Política ExtractVariables

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

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 usas esta política 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.

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
Extrae variables del parámetro de consulta (versión clásica de Edge) Extrae variables de un parámetro de consulta mediante la IU de Edge clásica.
Extrae variables de una carga útil de XML o JSON (Classic Edge) Extrae variables de una carga útil de XML o JSON con la IU clásica de Edge.

Ejemplos

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

GitHub

Estos vínculos apuntan a muestras de proxy de API en funcionamiento que puedes implementar y ejecutar en Edge. Usan ExtractVariables y se encuentran en el repositorio api-platform-samples de Apigee en GitHub. Los archivos README explican cómo se usa ExtractVariables en cada caso y cómo implementar y ejecutar cada muestra.

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://org1-test.apigee.net/svc1/accounts/12797282

Supongamos que la ruta base para el proxy de API es /svc1. Cuando Apigee Edge aplica el código de la política ExtractVariables anterior a esta solicitud entrante, establece la variable urirequest.id en 12797282. Después de que Apigee Edge ejecute la política, las políticas o los códigos 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 deAssignMessage incorpora el valor de esa variable en la carga útil de un nuevo mensaje de solicitud:

<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://org1-test.apigee.net/accounts/12797282?code=DBN88271

Cuando Apigee Edge aplica el código de la política ExtractVariables anterior a esta solicitud entrante, establece la variable queryinfo.dbncode en 88271. Después de que Apigee Edge ejecute la política, las políticas o los códigos 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 deAssignMessage 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>

Parámetros múltiples

<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 esta política para extraer el valor de varias instancias del parámetro de consulta “w”. 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.

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

GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago

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

Ahora puedes acceder a la variable queryinfo.firstWeather y queryinfo.secondWeather en el 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 Edge aplique el código de la política ExtractVariables anterior a este encabezado, establecerá la variable clientrequest.oauthtoken en 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>
<JSONPayload>$

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 Edge aplica el código de la política ExtractVariables anterior a este mensaje JSON, establece 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 deAssignMessage lo copia en un encabezado llamado “latitud” 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>
<XMLPayload>

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 Edge aplica el código de la política ExtractVariables anterior a este mensaje XML, establece tres variables: directionsresponse.travelmode, directionsresponse.duration y directionsresponse.timeunit. Todas las variables usan el mismo prefijo de variable de directionsresponse. El sufijo de estas variables se especifica de forma explícita con el atributo name del elemento <Variable>.

La variable directionsresponse.travelmode obtiene el valor DRIVING. La variable directionsresponse.duration obtiene el valor 19. La variable directionsresponse.timeunit obtiene el valor minutes.

Ahora puedes acceder a la variable directionresponse.travelmode en tu proxy. Por ejemplo, la siguiente política deAssignMessage 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. Luego, otras políticas y códigos pueden consumir esas variables para habilitar el comportamiento dinámico o enviar datos de la empresa a Analytics de la API de Edge.

Si deseas conocer cómo se puede usar ExtractVariables para compilar informes de Analytics basados en el contenido, consulta Analyze API message content using custom analytics.

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, con la política de registro de mensajes)
  • 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.

Coincidencias de rutas de acceso de URI, parámetros de consulta, encabezados, parámetros de formulario y variables

Cuando extraes información de una ruta de acceso de URI, los parámetros de consulta, los encabezados, los parámetros de forma y las variables, debes usar 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 establece en lo que aparece en el 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 en http://myCo.com/basepath/v1/a/b, la variable se configura como “b”.

Especifica varios patrones

Puedes especificar varios patrones para que coincidan, correspondientes a las etiquetas <Pattern>, en las que sucede lo siguiente:

  • Todos los patrones se prueban para detectar coincidencias.
  • Si ninguno de los patrones coincide, la política no hace nada y las variables no se crean.
  • 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 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 establece en “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 establece en “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>

Otra vez, expulsa un proxy de API con una ruta base de /basepath/v1 para la URL de la solicitud entrante:

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

…la variable urirequest.pathSeg1 se establece en “b” y la variable urirequest.pathSeg2 se establece 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 está configurada en "2". Si se omite el segundo parámetro de consulta de la solicitud, la variable urirequest.secondW estará 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”.

Hacer coincidir con JSON y XML

Cuando extraigas 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) de la información extraída.

Se evalúan todas las etiquetas <Variable> de la política para que puedas propagar muchas 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>Extract Variables 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 Predeterminada 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.

No disponible Obligatorias
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.

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 Funciones obsoletas

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

No disponible

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

Presencia Opcional
Tipo Cadena

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 Service Featured o para 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: Cadena

Atributos

Atributo Descripción Predeterminada Presencia Tipo
clearPayload

Configúralo como true si deseas borrar la carga útil especificada en <Source> después de extraer datos de ella.

Usa la opción <clearPayload> solo si el mensaje de origen no es necesario después de que se ejecuta ExtractVariables. Si se establece en true, se libera la memoria usada por el mensaje.

false

Opcional Booleano

Elemento <VariablePrefix>

Opcional: Se crea el nombre completo de la variable si se une el <VariablePrefix>, un punto y el nombre que defines entre {llaves} en el elemento <Pattern> o <Variable>. Por ejemplo, myprefix.id, myprefix.dbncode o myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

Por ejemplo, supongamos que el valor de name es "user".

  • 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: No disponible
Presencia: Opcional
Tipo: Cadena

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

Si una referencia de XPath no se resuelve en un <XMLPayload>, la política arroja el siguiente error:

{
   "fault":{
      "faultstring":"Unresolved xpath path in policy policy_name.",
      "detail":{
         "errorcode":"steps.extractvariables.InvalidXPath"
      }
   }
}

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 de proxy.pathsuffix de un mensaje de origen de 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 de origen se resuelve en un tipo de mensaje response, este elemento no hace nada.

<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: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia 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 consulta especificado de un mensaje de origen de request. Si el mensaje fuente se resuelve en un tipo de mensaje response, este elemento no hace nada.

<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: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada 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.

No disponible

Obligatorias Cadena

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 en el 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: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada 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.

No disponible

Obligatorias Cadena

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: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia Tipo
name El nombre del parámetro del formulario desde el que se extrae el valor.

No disponible

Obligatorias Cadena

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: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia Tipo
name El nombre de la variable desde la que se extrae el valor.

No disponible

Obligatorias Cadena

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 JSON se realiza solo cuando el encabezado Content-Type del mensaje es application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>
Predeterminado: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

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 distintas variables.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>
Predeterminado: No disponible
Presencia: Obligatorio en el elemento JSONPayload.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia Tipo
name

Especifica el nombre de la variable a la que se asignará el valor extraído.

name

Obligatorio Cadena
tipo Especifica el tipo de datos del valor de la variable. No disponible Opcional

String. Seleccionar una opción:

  • cadena
  • boolean
  • 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.

<Variable name="name">
   <JSONPath>$.rss.channel.title</JSONPath>
</Variable>
Predeterminado: No disponible
Presencia: Obligatorias
Tipo: Cadena

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: No disponible
Presencia: Opcional. Sin embargo, debes incluir al menos uno de los siguientes: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada 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.

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: No disponible
Presencia: Opcional
Tipo: Cadena

Atributos

Atributo Descripción Predeterminada Presencia Tipo
prefix

Prefijo del espacio de nombres.

No disponible

Obligatorias Cadena

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: No disponible
Presencia: Opcional
Tipo: No disponible

Atributos

Atributo Descripción Predeterminada Presencia Tipo
name

Especifica el nombre de la variable a la que se asignará el valor extraído.

name

Obligatorio Cadena
tipo Especifica el tipo de datos del valor de la variable. Booleano Opcional

String. Seleccionar una opción:

  • cadena
  • boolean
  • 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.

<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 declararlos en la sección <XMLPayload><Namespaces> de la política.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>
Predeterminado: No disponible
Presencia: Obligatorias
Tipo: Cadena

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge 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.
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 de mensaje especificada en el elemento Source de la política tiene las siguientes características:
  • 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.
InstantiationFailed No se pudo crear la instancia de la política.
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

Analiza el contenido de mensajes de API mediante estadísticas personalizadas

Referencia de variables