Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de Apigee Edge.
Qué
La política ExtractVariables extrae contenido de una solicitud o respuesta y establece el valor de una variable para ese contenido. Puedes extraer cualquier parte del mensaje, incluidos los encabezados, las rutas de URI, las cargas útiles de JSON/XML, los parámetros de formulario y los parámetros de búsqueda. La política funciona mediante la aplicación de un patrón de texto en el contenido del mensaje y, cuando se encuentra una coincidencia, se establece una variable con el contenido del mensaje especificado.
Aunque uses la política ExtractVariables a menudo para extraer información de una solicitud o mensaje de respuesta, también puedes usarla con el fin de extraer información de otras fuentes, incluidas las entidades creadas por la política AccessEntity, objetos XML o JSON.
Después de extraer el contenido del mensaje especificado, puedes hacer referencia a la variable en otras políticas como parte del procesamiento de una solicitud y una respuesta.
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 valorDRIVING
directionsresponse.duration
: Obtiene el valor19
directionsresponse.timeunit
: Obtiene el valorminutes
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 De forma opcional, usa el elemento |
N/A | Obligatorio |
continueOnError |
Configúralo como Configúralo como |
false | Opcional |
enabled |
Configúralo como Configúralo como |
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 |
---|---|
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 Usa la opción |
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 llamadauser
. - Si se especifica
<VariablePrefix>
como myprefix, los valores extraídos se asignan a una variable llamadamyprefix.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:
|
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 |
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:
|
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:
|
build |
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. |
build |
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. |
build |
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. | build |
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:
|
build |
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. | build |
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. |
build |
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. |
build |
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 . |
build |
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.
|
build |
EmptyXPathExpression |
Si la política tiene una expresión XPath vacía dentro del elemento XMLPayload , fallará la implementación del proxy de API. |
build |
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. |
build |
EmptyJSONPathExpression |
Si la política tiene una expresión XPath vacía dentro del elemento XMLPayload , fallará la implementación del proxy de API. |
build |
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. |
build |
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. |
build |
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. |
build |
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. |
build |
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.
|
build |
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