Política ExtractVariables

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué

La política ExtractVariables extrae contenido de una solicitud o respuesta y establece el valor de una variable para ese contenido. Puedes extraer cualquier parte del mensaje, incluidos los encabezados, las rutas de URI, las cargas útiles de JSON/XML, los parámetros de formulario y los parámetros de búsqueda. La política funciona mediante la aplicación de un patrón de texto en el contenido del mensaje y, cuando se encuentra una coincidencia, se establece una variable con el contenido del mensaje especificado.

Aunque uses la política ExtractVariables a menudo para extraer información de una solicitud o mensaje de respuesta, también puedes usarla con el fin de extraer información de otras fuentes, incluidas las entidades creadas por la política AccessEntity, objetos XML o JSON.

Después de extraer el contenido del mensaje especificado, puedes hacer referencia a la variable en otras políticas como parte del procesamiento de una solicitud y una respuesta.

Nota sobre los textos destacados del Service: no es necesario que uses esta política para extraer variables de textos destacados del Service. La Política ServiceCallout tiene sus propias variables de solicitud y respuesta que puedes usar directamente, por ejemplo, en una política AssignMessage.

Esta política es una política extensible, y el uso de esta puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Videos

Nota: En los siguientes videos, se muestra el Editor de proxies clásico en la IU de Apigee. Apigee presenta una versión nueva del Editor de proxies, que tiene un diseño diferente al de la versión clásica que se muestra en los videos.

Mira los siguientes videos para obtener más información sobre la política ExtractVariables.

Video	Descripción
Extrae variables de la carga útil de XML	Extrae variables de una carga útil de XML con la política ExtractVariables.
Extrae variables de la carga útil de JSON	Extrae variables de una carga útil de JSON con la política ExtractVariables.
Extrae variables de los parámetros	Extrae variables de parámetros, como parámetros de búsqueda, encabezado, formulario o URI.
Extrae variables de parámetros de valores múltiples	Extrae variables de parámetros de valores múltiples

Ejemplos

En estas muestras de código de política, se ilustra cómo extraer variables de los siguientes tipos de artefactos:

URI

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Considera el código de política de muestra que aparece arriba. El elemento <URIPath> le indica a la política ExtractVariables que extraiga información de la ruta del URI. El elemento <Pattern> especifica el patrón que se aplicará a la ruta del URI. El patrón se trata como una plantilla simple, con las llaves que denotan la parte diversa de la ruta del URI.

El nombre de la variable que se establecerá se determina según el valor especificado en el elemento <VariablePrefix>, así como el valor encerrado entre llaves {} en el elemento <Pattern>. Los dos valores se unen mediante un punto intermedio, por lo que el nombre de una variable es urirequest.id. Si no hay un elemento <VariablePrefix>, el nombre de la variable es solo el valor entre llaves.

Considera el código de política de muestra anterior que funciona con la siguiente solicitud entrante:

GET http://example.com/svc1/accounts/12797282

Supongamos que la ruta base para el proxy de API es /svc1. Cuando Apigee aplica el código de política de extracción de variables anteriores a esta solicitud entrante, establece la variable urirequest.id en 12797282. Después de que Apigee ejecute la política, las políticas o el código posteriores en el flujo de procesamiento pueden hacer referencia a la variable llamada urirequest.id para obtener el valor de string 12797282.

Por ejemplo, la siguiente política AllocationMessage incorpora el valor de esa variable en la carga útil de un mensaje de solicitud nuevo:

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
  <DisplayName>AssignPayload</DisplayName>
    <Set>
      <Payload contentType="text/xml">
        <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
      </Payload>
    </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

Parámetros de consulta

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Considera el código de política de muestra anterior que funciona con la siguiente solicitud entrante:

GET http://example.com/accounts/12797282?code=DBN88271

Cuando Apigee aplica el código de política ExtractVariables antes mencionado en esta solicitud entrante, establece la variable queryinfo.dbncode en 88271. Después de que Apigee ejecute la política, las políticas o el código posteriores en el flujo de procesamiento pueden hacer referencia a la variable llamada queryinfo.dbncode para obtener el valor de string 88271.

Ahora puedes acceder a la variable queryinfo.dbncode en tu proxy. Por ejemplo, la siguiente política AssignMessage la copia en la carga útil de la solicitud:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Varios parámetros

<ExtractVariables name="ExtractVariables-2">
  <DisplayName>Extract a value from a query parameter</DisplayName>
  <Source>request</Source>
  <QueryParam name="w">
    <Pattern ignoreCase="true">{firstWeather}</Pattern>
  </QueryParam>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondWeather}</Pattern>
  </QueryParam>
  <VariablePrefix>queryinfo</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Supongamos que el diseño de tu API te permite especificar varios parámetros de búsqueda con el mismo nombre. Puedes usar una política de extracción de variables para extraer el valor de varias instancias del parámetro de consulta. Para hacer referencia a los parámetros de consulta con el mismo nombre en la política, usa índices en los que la primera instancia del parámetro de consulta no tenga índice, la segunda esté en el índice 2, la tercera en el índice 3, etcétera.

Considera el código de política de muestra anterior que funciona con la siguiente solicitud entrante:

GET http://example.com/weather?w=Boston&w=Chicago

Cuando Apigee aplica el código de política ExtractVariables de arriba a esta solicitud entrante, establece la variable queryinfo.firstWeather en Boston y la variable queryInfo.secondWeather en Chicago.

Ahora puedes acceder a las variables queryinfo.firstWeather y queryinfo.secondWeather en tu proxy. Por ejemplo, la siguiente política AssignMessage la copia en la carga útil de la solicitud:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
      <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Encabezados

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Supongamos que tu API usa tokens del portador de OAuth v2.0. Considera el código de política de muestra anterior que funciona con una solicitud que contiene un token de OAuth v2.0 que incluye un encabezado como este: Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

Como diseñador de API, supongamos que deseas usar el valor de token (pero no el encabezado completo) como una clave en la búsqueda en caché. Puedes usar el código de la política ExtractVariables que se encuentra arriba para extraer el token.

Cuando Apigee aplica el código de política ExtractVariables de arriba a este encabezado, configura la variable clientrequest.oauthtoken como TU08xptfFfeM7aS0xHqlxTgEAdAM.

Ahora puedes acceder a la variable clientrequest.oauthtoken en tu proxy. Por ejemplo, la siguiente política AssignMessage la copia en la carga útil de la solicitud:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetHeader</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

JSON

<ExtractVariables name="ExtractVariables-3">
  <Source>response</Source>
  <JSONPayload>
    <Variable name="latitude" type="float">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude" type="float">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
  <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

Considera la siguiente carga útil de respuesta de JSON:

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

Cuando Apigee aplica el código de política ExtractVariables que se muestra arriba en este mensaje JSON, configura dos variables: geocoderesponse.latitude y geocoderesponse.longitude. Ambas variables usan el mismo prefijo variable de geocoderesponse. El sufijo de estas variables se especifica de manera explícita con el atributo name del elemento <Variable>.

La variable geocoderesponse.latitude obtiene el valor 37.42291810. La variable geocoderesponse.longitude obtiene el valor -122.08542120.

Ahora puedes acceder a la variable geocoderesponse.latitude en tu proxy. Por ejemplo, la siguiente política de AssignMessage la copia en un encabezado llamado latitude en la respuesta:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

XML

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>

Considera la siguiente carga útil de respuesta XML:

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

Cuando Apigee aplica el código de política ExtractVariables que se muestra arriba en este mensaje XML, se establecen tres variables:

• directionsresponse.travelmode: Obtiene el valor DRIVING
• directionsresponse.duration: Obtiene el valor 19
• directionsresponse.timeunit: Obtiene el valor minutes

Todas las variables usan el mismo prefijo de variable directionsresponse. El sufijo de estas variables se especifica de manera explícita con el atributo name del elemento <Variable>.

Ahora puedes acceder a la variable directionresponse.travelmode en tu proxy. Por ejemplo, la siguiente política de AssignMessage la copia en un encabezado llamado tmode en la respuesta:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Nota: Configura Content-Type: Cuando se extraen variables de mensajes XML (incluido SOAP), la extracción de variables solo funciona cuando Content-Type se establece en el encabezado del mensaje (o en el encabezado SOAP); por ejemplo: application/xml.

Información acerca de la política ExtractVariables

Los desarrolladores de API compilan proxies de API que se comportan de manera diferente según el contenido de los mensajes, incluidos los encabezados, las rutas de URI, las cargas útiles y los parámetros de búsqueda. Con frecuencia, el proxy extrae parte de este contenido para usarlo en una declaración de condición. Para hacerlo, usa la política ExtractVariables.

Cuando definas la política ExtractVariables, puedes elegir lo siguiente:

• Nombres de las variables que se establecerán
• Fuente de las variables
• Cuántas variables para extraer y establecer

Cuando se ejecuta, la política aplica un patrón de texto al contenido y, cuando se encuentra una coincidencia, se establece el valor de la variable designada con el contenido. Otras políticas y código pueden consumir esas variables para habilitar el comportamiento dinámico o enviar datos de la empresa a las estadísticas de la API de Apigee.

Advertencia: Apigee establece muchas variables de forma automática durante el procesamiento de solicitudes. Consulta la Referencia de variables de flujo. Usa la política ExtractVariables para configurar variables adicionales.

Permiso

Las variables establecidas con la política ExtractVariables tienen el permiso global. Es decir, después de que la política ExtractVariables define una variable nueva, puedes acceder a esa variable desde cualquier política o código en cualquier etapa del flujo (que se ejecuta después de la política ExtractVariables). Incluye lo siguiente:

• PreFlow: ProxyEndpoint y TargetEndpoint (solicitud y respuesta)
• PostFlow: ProxyEndpoint y TargetEndpoint (solicitud y respuesta)
• PostClientFlow: ProxyEndpoint (solo respuesta, mediante la política MessageLogging>)
• Flujos de error

Sugerencia: Si no ves la variable que se acaba de extraer en la herramienta de depuración intenta quitar el elemento <VariablePrefix> si lo agregaste. Para obtener más información, consulta este ExtractVariables que no se muestran en Trace.

Información acerca de la coincidencia y la creación de variables

La política ExtractVariables extrae información de una solicitud o respuesta y escribe esa información en una variable. Para cada tipo de información que puedes extraer, como la ruta de URI o los datos de XML, debes especificar el patrón que coincida y el nombre de la variable que se usa para almacenar la información extraída.

Sin embargo, la forma en que funciona la coincidencia de patrones depende de la fuente de la extracción. En las siguientes secciones, se describen las dos categorías básicas de información que puedes extraer.

Haz coincidir rutas de URI, parámetros de consulta, encabezados, parámetros de formularios y variables

Cuando extraes información de una ruta de URI, parámetros de búsqueda, encabezados, parámetros de formulario y variables, usas la etiqueta <Pattern> para especificar uno o más patrones que deben coincidir. Por ejemplo, en el siguiente ejemplo de política se muestra un solo patrón coincidente para la ruta del URI:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

En este ejemplo, la variable urirequest.pathSeg se configura como cualquier elemento que aparezca en proxy.pathsuffix después de /a/. Por ejemplo, supongamos que la ruta base para tu proxy de API es /basepath/v1. Con una solicitud entrante a http://myCo.com/basepath/v1/a/b, la variable se configura como b.

Especifica varios patrones

Puedes especificar varios patrones que deban coincidir, que correspondan a las etiquetas <Pattern>, en las que ocurra lo siguiente:

• Todos los patrones se prueban para detectar coincidencias.
• Si ninguno de los patrones coincide, la política no hace nada y no se crean las variables.
• Si hay más de un patrón que coincide, se usa el patrón con los segmentos de ruta de acceso más largos para la extracción.
• Si dos patrones coincidentes tienen los mismos segmentos de ruta de acceso más largos, el patrón especificado primero en la política se usa para la extracción.

En el siguiente ejemplo, crearás una política que contenga tres patrones coincidentes para la ruta del URI:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Supongamos que, para un proxy de API con una ruta base de /basepath/v1, la URL de la solicitud entrante al proxy de API es la siguiente:

http://myCo.com/basepath/v1/a/b

En este ejemplo, el primer patrón coincide con el URI y la variable urirequest.pathSeg se configura como b.

Si la URL de solicitud es la siguiente:

http://myCo.com/basepath/v1/a/b/c/d

…el tercer patrón coincide y la variable urirequest.pathSeg se configura como d.

Especifica patrones con muchas variables

Puedes especificar múltiples variables en el patrón coincidente. Por ejemplo, especifica un patrón coincidente con dos variables:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Si se asume que un proxy de API con una ruta base de /basepath/v1 para la URL de solicitud entrante:

http://myCo.com/basepath/v1/a/b/c/d

…la variable urirequest.pathSeg1 se configura como b y la variable urirequest.pathSeg2 está configurada en d.

Haz coincidir varias instancias en el patrón

También puede hacer coincidir patrones cuando hay varias instancias de un elemento con el mismo nombre. Por ejemplo, puedes realizar una solicitud que contenga varios parámetros de búsqueda o varios encabezados con el mismo nombre. La siguiente solicitud contiene dos parámetros de búsqueda llamados “w”:

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

Para hacer referencia a estos parámetros de consulta en la política ExtractVariables, usa índices, en los que la primera instancia del parámetro de consulta no tiene índice, la segunda está en el índice 2, la tercera en el índice 3, etcétera. Por ejemplo, la siguiente política extrae el valor del segundo parámetro de consulta llamado “w” en la solicitud:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondW}</Pattern>
  </QueryParam>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

La variable urirequest.secondW se configura como “2”. Si el segundo parámetro de búsqueda se omite de la solicitud, la variable urirequest.secondW está vacía. Usa la indexación cuando haya varios elementos con el mismo nombre en la solicitud.

Usa caracteres especiales en el patrón

Cuando se hacen coincidir las rutas de URI, puedes usar los caracteres comodín “*” y “**” en el patrón, en el que se ilustra lo siguiente:

• “*” busca cualquier segmento de la ruta
• “**” coincide con varios segmentos de la ruta de acceso

Por ejemplo, puedes especificar patrones para el elemento <URIPath> como se muestra a continuación:

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

El primer patrón coincide con solicitudes con sufijos de ruta (la parte de la ruta del URI que sigue a la ruta base), como “/a/b/c”, “/a/foo/bar”, etc. El segundo patrón coincide con cualquier cantidad de segmentos de la ruta después de “/a/”, como “/a/foo/bar/baz/c”, así como “/a/b/c” y “/a/foo/bar”.

Cuando se especifican patrones para consultar parámetros, encabezados y parámetros de formulario, el carácter “*” indica que coincide con cualquier cantidad de caracteres. Por ejemplo, cuando coincide un encabezado, especifica el patrón de la siguiente manera:

*;charset={encoding}

Este patrón coincide con los valores “text/xml;charset=UTF-16” y “application/xml;charset=ASCII”.

Si el valor que se pasa a la política ExtractVariables contiene un carácter especial, como “{”, usa el carácter “%” para escapar. En el siguiente ejemplo, se escapan los caracteres “{” y “}” en el patrón porque se usan como caracteres literales en el valor del parámetro de consulta:

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

En este ejemplo, el patrón coincide con el valor “{user} Steve”, pero no con el valor “user Steve”.

Haz coincidir JSON y XML

Cuando extraes datos de JSON y XML, debes especificar una o más etiquetas <Variable> en la política. La etiqueta <Variable> especifica el nombre de la variable de destino en la que se almacena la información extraída, y la JsonPath (JSON) o XPATH (XML) para la información extraída.

Se evalúan todas las etiquetas <Variable> en la política para que puedas propagar múltiples variables desde una sola política. Si la etiqueta <Variable> no se evalúa como un campo válido en JSON o XML, no se crea la variable correspondiente.

En el siguiente ejemplo, se muestra una política ExtractVariables que propaga dos variables del cuerpo JSON de una respuesta:

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

Escribe en la misma variable en varios lugares

Ten cuidado cuando elijas los nombres de variables que deseas configurar. La política se ejecuta de forma secuencial desde el primer patrón de extracción hasta el último. Si la política escribe un valor en la misma variable desde varios lugares, la última escritura en la política determina el valor de la variable. (puede ser lo que desees).

Por ejemplo, si deseas extraer un valor de token que se puede pasar en un parámetro de búsqueda o en un encabezado, como se muestra a continuación:

<!-- If token only in query param, the query param determines the value.
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>

<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

Controla lo que sucede cuando no se produce ninguna coincidencia

Si el patrón no coincide, entonces no se crea la variable correspondiente. Por lo tanto, si otra política hace referencia a la variable, puede provocar un error.

Una opción es configurar <IgnoreUnresolvedVariables> como verdadero en una política que hace referencia a la variable para tratar cualquier variable sin resolver como una string vacía (nula):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Referencia del elemento

La referencia del elemento describe los elementos y atributos de la política ExtractVariables.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName> 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

Atributos <ExtractVariables>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo	Descripción	Predeterminado	Presencia
name	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	falso	Opcional
enabled	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	falso	Obsoleta

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presencia	Opcional
Tipo	String

Elemento <Source>

Especifica la variable que se analizará (opcional). El valor predeterminado de <Source> es message. El valor message es sensible al contexto. En un flujo de solicitud, message se resuelve en el mensaje de solicitud. En un flujo de respuesta, message se resuelve en el mensaje de respuesta.

Si bien con frecuencia usas esta política para extraer información de una solicitud o mensaje de respuesta, puedes usarla con el fin de extraer información de cualquier variable. Por ejemplo, puedes usarla para extraer información de una entidad creada por la política AccessEntity, a partir de los datos que muestra la política ServiceCallout, o bien extraer información de un objeto XML o JSON.

Si no se puede resolver <Source> o se resuelve como un tipo que no es de mensaje, la política no responderá.

<Source clearPayload="true|false">request</Source>

Predeterminado:	mensaje
Presencia:	Opcional
Tipo:	String

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
clearPayload	Configúralo como true si quieres borrar la carga útil especificada en <Source> después de extraer datos. Usa la opción <clearPayload> solo si el mensaje de origen no es necesario después de que se ejecute ExtractVariables. Si se configura como verdadero, se libera la memoria que usa el mensaje.	falso	Opcional	Booleano

Elemento <VariablePrefix>

El nombre completo de la variable se crea mediante la unión de <VariablePrefix>, un punto y el nombre que defines entre {llaves} en el elemento <Pattern> o el elemento <Variable>. Por ejemplo, myprefix.id, myprefix.dbncode o myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

Por ejemplo, supongamos que el valor del nombre es “usuario”.

• Si no se especifica <VariablePrefix>, los valores extraídos se asignan a una variable llamada user.
• Si se especifica <VariablePrefix> como myprefix, los valores extraídos se asignan a una variable llamada myprefix.user.

Predeterminado:	N/A
Presencia:	Opcional
Tipo:	String

Elemento <IgnoreUnresolvedVariables>

Configúralo como true para tratar cualquier variable no recuperable como una string vacía (null) (opcional). Configúralo como false si deseas que la política genere un error cuando no se pueda resolver ninguna variable referenciada.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Predeterminado:	Falso
Presencia:	Opcional
Tipo:	Booleano

Elemento <URIPath>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Extrae un valor del proxy.pathsuffix de un mensaje fuente request. La ruta que se aplica al patrón es el proxy.pathsuffix, que no incluye la ruta base para el proxy de API. Si el mensaje fuente se resuelve en un tipo de mensaje de response, este elemento no realiza ninguna acción.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

Es posible usar varios elementos <Pattern>:

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
ignoreCase	Especifica para ignorar mayúsculas y minúsculas cuando coincida el patrón.	falso	Opcional	Booleano

Elemento <QueryParam>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Extrae un valor del parámetro de búsqueda especificado de un mensaje fuente request. Si el mensaje fuente se resuelve en un tipo de mensaje de response, este elemento no realiza ninguna acción.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

Si varios parámetros de búsqueda tienen el mismo nombre, usa índices para hacer referencia a los parámetros:

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
name	Especifica el nombre del parámetro de búsqueda. Si varios parámetros de búsqueda tienen el mismo nombre, usa la referencia indexada, en la que la primera instancia del parámetro de búsqueda no tiene índice, la segunda está en el índice 2, la tercera en el índice 3, etcétera.	N/A	Obligatorio	String

Elemento <Header>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Extrae un valor del encabezado HTTP especificado del mensaje request o response especificado. Si varios encabezados tienen el mismo nombre, sus valores se almacenan en un arreglo.

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

Si varios encabezados tienen el mismo nombre, usa índices para hacer referencia a encabezados individuales en el array:

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

O haz lo siguiente para enumerar todos los encabezados del array:

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
name	Especifica el nombre del encabezado del que se extrae el valor. Si varios encabezados tienen el mismo nombre, usa la referencia indexada, en la que la primera instancia del encabezado no tiene índice, la segunda está en el índice 2, la tercera en el índice 3, etcétera. Usa .values para obtener todos los encabezados del arreglo.	N/A	Obligatorio	String

Elemento <FormParam>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Extrae un valor del parámetro de formulario especificado del mensaje request o response especificado. Los parámetros de forma solo se pueden extraer cuando el encabezado Content-Type del mensaje especificado es application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
name	El nombre del parámetro del formulario desde el que se extrae el valor.	N/A	Obligatorio	String

Elemento <Variable>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Especifica el nombre de una variable desde la que se extrae un valor.

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

Para extraer dos valores de la variable, haz lo siguiente:

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
name	El nombre de la variable desde la que se extrae el valor.	N/A	Obligatorio	String

Elemento <JSONPayload>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Especifica el mensaje con formato JSON a partir del cual se extraerá el valor de la variable. La extracción de JSON solo se realiza cuando el encabezado Content-Type del mensaje es application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Elemento <JSONPayload>/<Variable>

(Obligatorio en el elemento JSONPayload). Especifica la variable a la que se asigna el valor extraído. Puedes incluir varias etiquetas <Variable> en el elemento <JSONPayload> para propagar múltiples variables.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>

Predeterminado:	N/A
Presencia:	Obligatorio en el elemento JSONPayload.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
name	Especifica el nombre de la variable a la que se asignará el valor extraído.	name	Obligatorio	String
tipo	Especifica el tipo de datos del valor de la variable.	N/A	Opcional	String. Seleccionar una opción: string Booleano integer long float double nodeset (muestra un fragmento JSON)

Elemento <JSONPayload>/<Variable>/<JSONPath>

(Obligatorio en el elemento JSONPayload:Variable). Especifica la ruta JSON que se usó para extraer un valor de un mensaje con formato JSON.

Nota:El elemento <JSONPath> admite la función de sustitución dinámica de string llamada plantillas de mensajes.

<Variable name="name">
  <JSONPath>$.rss.channel.title</JSONPath>
</Variable>

Predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	String

Elemento <XMLPayload>

(Opcional, pero consulta la fila Presencia en la tabla que aparece a continuación para obtener más información). Especifica el mensaje con formato XML del que se extraerá el valor de la variable. Las cargas útiles XML se extraen solo cuando el encabezado Content-Type del mensaje es text/xml, application/xml o application/*+xml.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
    <Namespace prefix="apigee">http://www.apigee.com</Namespace>
    <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
    <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>

Predeterminado:	N/A
Presencia:	Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
stopPayloadProcessing	Configúralo como true para detener la evaluación de XPath después de que se propague una variable. Esto significa que la política solo propaga una variable única.	falso	Opcional	Booleano

Elemento <XMLPayload>/<Namespaces>

Especifica el espacio de nombres que se usará en la evaluación de XPath (opcional). Si usas espacios de nombres en tus expresiones de XPath, debes declararlos aquí, como se muestra en el siguiente ejemplo.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

Si no usas espacios de nombres en tus expresiones de XPath, puedes omitir o comentar el elemento <Namespaces>, como se muestra a continuación:

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>

Predeterminado:	N/A
Presencia:	Opcional
Tipo:	String

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
prefix	Prefijo del espacio de nombres.	N/A	Obligatorio	String

Elemento <XMLPayload>/<Variable>

Especifica la variable a la que se asignará el valor extraído (opcional).

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

Predeterminado:	N/A
Presencia:	Opcional
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia	Tipo
name	Especifica el nombre de la variable a la que se asignará el valor extraído.	name	Obligatorio	String
tipo	Especifica el tipo de datos del valor de la variable.	Booleano	Opcional	String. Seleccionar una opción: string Booleano integer long float double nodeset (muestra un fragmento XML)

Elemento <XMLPayload>/<Variable>/<XPath>

(Obligatorio en el elemento XMLPayload:Variable). Especifica la XPath definida para la variable. Solo se admiten expresiones de XPath 1.0.

El elemento <XPath> no admite plantillas de mensajes.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

Ejemplo con un espacio de nombres. Si usas espacios de nombres en tus expresiones de XPath, debes declarar los espacios de nombres en la sección <XMLPayload><Namespaces> de la política.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

Predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	String

Nota: Usar parent, ancestor, following y preceding en las expresiones XPath no es compatible con Apigee. Para obtener los mismos resultados que coincidan, prueba la coincidencia o el nombre de nodo explícito del nodo. Por ejemplo:

• <XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
  obtiene el valor de foo_attribute.
• <XPath>/Attributes/Attribute[4]/Value</XPath>
  obtiene el valor del cuarto atributo.

Referencia de errores

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.extractvariables.ExecutionFailed	500	This error occurs when: The input payload (JSON, XML) is empty. The input (JSON, XML, etc) passed to the policy is invalid or malformed.
steps.extractvariables.ImmutableVariable	500	A variable used in the policy is immutable. The policy was unable to set this variable.	N/A
steps.extractvariables.InvalidJSONPath	500	This error occurs if an invalid JSON path is used in the JSONPath element of the policy. For example, if a JSON payload does not have the object Name, but you specify Name as the path in the policy, then this error occurs.
steps.extractvariables.JsonPathParsingFailure	500	This error occurs when the policy is unable to parse a JSON path and extract data from the flow variable specified in Source element. Typically this happens if the flow variable specified in the Source element does not exist in the current flow.
steps.extractvariables.SetVariableFailed	500	This error occurs if the policy could not set the value to a variable. The error generally happens if you try to assign values to multiple variables whose names start with the same words in a nested dot-separated format.
steps.extractvariables.SourceMessageNotAvailable	500	This error occurs if the message variable specified in the Source element of the policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)
steps.extractvariables.UnableToCast	500	This error occurs if the policy was unable to cast the extracted value to a variable. Typically this happens if you attempt to set the value of one data type to a variable of another data type.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

Error name	Cause	Fix
NothingToExtract	If the policy does not have any of the elements URIPath, QueryParam, Header, FormParam, XMLPayload, or JSONPayload, the deployment of the API Proxy fails, because there's nothing to extract.
NONEmptyPrefixMappedToEmptyURI	This error occurs if the policy has a prefix defined in the Namespace element under the XMLPayload element, but no URI is defined.
DuplicatePrefix	This error occurs if the policy has the same prefix defined more than once in the Namespace element under the XMLPayload element.
NoXPathsToEvaluate	If the policy does not have the XPath element within the XMLPayload element, then the deployment of the API proxy fails with this error. If you want to extract variables from an XML Payload, then an XPath child element must be specified.
EmptyXPathExpression	If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
NoJSONPathsToEvaluate	If the policy does not have the JSONPath element within the JSONPayload element, then the deployment of the API proxy fails with this error.
EmptyJSONPathExpression	If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
MissingName	If the policy does not have the name attribute in any of the policy elements like QueryParam, Header, FormParam or Variable, where it is required, then the deployment of the API proxy fails.
PatternWithoutVariable	If the policy does not have a variable specified within the Pattern element, then the deployment of the API proxy fails. The Pattern element requires the name of the variable in which extracted data will be stored.
CannotBeConvertedToNodeset	If the policy has an XPath expression where the Variable type is defined as nodeset, but the expression cannot be converted to nodeset, then the deployment of the API proxy fails.
JSONPathCompilationFailed	The policy could not compile a specified JSON Path.	N/A
InstantiationFailed	The policy could not be instantiated.	N/A
XPathCompilationFailed	If the prefix or the value used in the XPath element is not part of any of the declared namespaces in the policy, then the deployment of the API proxy fails.
InvalidPattern	If the Pattern element definition is invalid in any of the elements like URIPath, QueryParam, Header, FormParam, XMLPayload or JSONPayload within the policy, then the deployment of the API proxy fails. The Pattern element is considered invalid if it doesn't include a variable. For more information about pattern matching, see About matching and variable creation.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	extractvariables.EV-ParseJsonResponse.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

Example fault rule

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

Esquemas

Muestra: Consulta nuestros repositorios de GitHub para ver los esquemas más recientes.

Temas relacionados

Referencia de las variables de flujo