Política ExtractVariables

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

Consulta la documentación de Apigee Edge.

ícono de política

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.

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

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>

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.

Alcance

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

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 Configuración predeterminada Presence
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:

false 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.

false Obsoleto

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>
Configuración predeterminada

N/A

Si omites este elemento, se usa el valor del atributo name de la política.

Presence 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 Presence 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 true, se libera la memoria que usa el mensaje.

false

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 Presence Tipo
ignoreCase Especifica para ignorar mayúsculas y minúsculas cuando coincida el patrón.

false

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 Presence 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 Presence 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 Presence 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 Presence 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 Presence 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. Selecciona una opción:

  • string
  • booleano
  • número entero
  • 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.

<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 Presence 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.

false

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 Presence 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 Presence 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. Selecciona una opción:

  • string
  • booleano
  • número entero
  • 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.

<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

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa Corregir
steps.extractvariables.ExecutionFailed 500

Este error ocurre en los siguientes casos:

  • La carga útil de entrada (JSON, XML) está vacía.
  • La entrada (JSON, XML, etc.) pasada a la política no es válida o presenta errores de formato.
steps.extractvariables.ImmutableVariable 500 Una variable utilizada en la política es inmutable. La política no pudo establecer esta variable. N/A
steps.extractvariables.InvalidJSONPath 500 Este error se produce si se usa una ruta de acceso JSON no válida en el elemento JSONPath de la política. Por ejemplo, si una carga útil de JSON no tiene el objeto Name, pero especificas Name como la ruta de acceso en la política, se produce este error.
steps.extractvariables.JsonPathParsingFailure 500 Este error se produce cuando la política no puede analizar una ruta JSON ni extraer datos de la variable de flujo especificada en el elemento Source. Por lo general, esto sucede si la variable de flujo especificada en el elemento Source no existe en el flujo actual.
steps.extractvariables.SetVariableFailed 500 Este error se produce si la política no pudo establecer el valor en una variable. Esto ocurre si intentas asignar valores a múltiples variables cuyos nombres comienzan con las mismas palabras en un formato separado por puntos y comas.
steps.extractvariables.SourceMessageNotAvailable 500 Este error se produce si la variable mensaje especificada en el elemento Source de la política JSONThreatProtection es una de las siguientes opciones:
  • Fuera del alcance (no disponible en el flujo específico en el que se ejecuta la política)
  • No se puede resolver (no está definida)
steps.extractvariables.UnableToCast 500 Este error se produce si la política no pudo convertir el valor extraído en una variable. Por lo general, esto sucede si intentas establecer el valor de un tipo de datos como una variable de otro tipo de datos.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Causa Corregir
NothingToExtract Si la política no tiene ninguno de los elementos URIPath, QueryParam, Header, FormParam, XMLPayload o JSONPayload, la implementación del proxy de la API falla, no hay nada que extraer.
NONEmptyPrefixMappedToEmptyURI Este error se produce si la política tiene un prefijo definido en el elemento Namespace debajo del elemento XMLPayload, pero no se define un URI.
DuplicatePrefix Este error se produce si la política tiene el mismo prefijo definido más de una vez en el elemento Namespace debajo del elemento XMLPayload.
NoXPathsToEvaluate Si la política no tiene el elemento XPath dentro del elemento XMLPayload, entonces la implementación del proxy de API falla con este error.
EmptyXPathExpression Si la política tiene una expresión XPath vacía dentro del elemento XMLPayload, fallará la implementación del proxy de API.
NoJSONPathsToEvaluate Si la política no tiene el elemento JSONPath dentro del elemento JSONPayload, entonces la implementación del proxy de API falla con este error.
EmptyJSONPathExpression Si la política tiene una expresión XPath vacía dentro del elemento XMLPayload, fallará la implementación del proxy de API.
MissingName Si la política no tiene el atributo name en ninguno de los elementos de la política, como QueryParam, Header, FormParam o Variable, cuando sea necesario, la implementación del proxy de API falla.
PatternWithoutVariable Si la política no tiene una variable especificada en el elemento Pattern, la implementación del proxy de API fallará. El elemento Pattern requiere el nombre de la variable en la que se almacenarán los datos extraídos.
CannotBeConvertedToNodeset Si la política tiene una expresión XPath en la que el tipo Variable se define como nodeset, pero la expresión no se puede convertir en el conjunto de nodos, la implementación de la API de proxy falla.
JSONPathCompilationFailed La política no pudo compilar una ruta JSON especificada. N/A
InstantiationFailed No se pudo crear la instancia de la política. N/A
XPathCompilationFailed Si el prefijo o el valor usado en el elemento XPath no forma parte de los espacios de nombres declarados en la política, la implementación del proxy de API falla.
InvalidPattern Si la definición del elemento Pattern no es válida en ninguno de los elementos, como URIPath, QueryParam, Header, FormParam, XMLPayload o JSONPayload, dentro de la política, fallará la implementación del proxy de API.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. extractvariables.EV-ParseJsonResponse.failed = true

Ejemplo de respuesta de error

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

Ejemplo de regla de falla

<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

Temas relacionados

Referencia de las variables de flujo