Plantillas de mensajes

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Esta página se aplica a Apigee y Apigee híbrido .

Ver la documentación de Apigee Edge .

Este tema analiza cómo utilizar plantillas de mensajes en servidores proxy de API y proporciona una referencia de funciones.

¿Qué es una plantilla de mensaje?

Una plantilla de mensaje permite sustituir cadenas variables en ciertas políticas y elementos <TargetEndpoint> . Esta función, cuando es compatible, permite rellenar cadenas dinámicamente al ejecutar un proxy.

Puede incluir cualquier combinación de referencias a variables de flujo y texto literal en una plantilla de mensaje. Los nombres de las variables de flujo deben ir entre llaves, y el texto que no esté entre llaves se muestra como texto literal.

Ver también ¿Dónde puedes utilizar plantillas de mensajes?

Ejemplo

Por ejemplo, la política AssignMessage le permite utilizar una plantilla de mensaje dentro del elemento <Payload> :

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

En el ejemplo anterior, el valor de la variable de flujo user.name (entre llaves) se evaluará y sustituirá en la cadena de carga útil durante la ejecución. Por ejemplo, si user.name=jdoe , el mensaje resultante en la carga útil será: You entered an invalid username: jdoe . Si la variable no se puede resolver, se mostrará una cadena vacía.

Ejemplo

Cuando se excede una cuota, es recomendable devolver un mensaje significativo al emisor. Este patrón se usa comúnmente con una "regla de fallo" para proporcionar información al emisor sobre la violación de la cuota. En la siguiente política AssignMessage , se utilizan plantillas de mensaje para rellenar dinámicamente la información de cuota en varios elementos XML:

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
  </Set>
</AssignMessage>

En la política AssignMessage , los siguientes elementos del elemento <Set> admiten la creación de plantillas de mensajes:

• <Header>
• <QueryParam>
• <FormParam>
• <PayLoad>
• <Version>
• <Verb>
• <Path>
• <StatusCode>

Nuevamente, tenga en cuenta que las variables de flujo en una plantilla de mensaje deben estar entre llaves .

Cuando se ejecuta esta política:

• Los elementos <Header> reciben valores de las variables de flujo especificadas.
• La carga útil incluye una combinación de texto literal y variables (el client_id se completa de forma dinámica).
• El <StatusCode> solo incluye texto literal; sin embargo, este elemento también admite la creación de plantillas de mensajes si desea utilizarlas.

Ejemplo

En una definición de proxy <TargetEndpoint> , los elementos secundarios de <SSLInfo> admiten la creación de plantillas de mensajes. Siguiendo el mismo patrón utilizado en las políticas, las variables de flujo entre llaves se reemplazan al ejecutarse el proxy.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

¿Dónde puedes utilizar plantillas de mensajes?

Las plantillas de mensajes son compatibles con varias políticas , así como con ciertos elementos utilizados en la configuración de TargetEndpoint .

Políticas que aceptan plantillas de mensajes

La siguiente tabla enumera las políticas y qué elementos/elementos secundarios son compatibles:

Elementos <TargetEndpoint> que aceptan plantillas de mensajes

Sintaxis de la plantilla de mensaje

Esta sección explica las reglas que debes seguir para utilizar plantillas de mensajes.

Utilice llaves para indicar variables

Encierre los nombres de las variables entre llaves { } . Si la variable no existe, se devuelve una cadena vacía en la salida; sin embargo, puede especificar valores predeterminados en las plantillas de mensajes (valores que se sustituyen si la variable no está resuelta). Consulte Establecer valores predeterminados en las plantillas de mensajes .

Tenga en cuenta que se permite escribir toda la cadena de plantilla de mensaje entre comillas, pero es opcional. Por ejemplo, las dos plantillas de mensaje siguientes son equivalentes:

<Set>
  <Headers>
    <Header name="x-h1">"Hello {user.name}"</Header>
    <Header name="x-h1">Hello {user.name}</Header>
  </Headers>
</Set>

No se permiten espacios en las expresiones de función.

No se permiten espacios en las expresiones de función de plantilla de mensaje. Por ejemplo:

Permitido:

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

No permitido:

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

No se admiten funciones anidadas

No se permite llamar a una función dentro de otra función en una plantilla. Por ejemplo, no se puede usar:

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

Encierre los literales de cadena en funciones de plantilla entre comillas simples

Al proporcionar literales de cadena en funciones, enciérrelos entre comillas simples en lugar de comillas dobles.

{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

Evite utilizar caracteres especiales en literales de cadena

Evite caracteres especiales, como ':', '/', '\', '<' o ">', en literales de cadena. Estos caracteres pueden causar errores. Si un literal de cadena requiere caracteres especiales, asigne el valor a una variable mediante una política de Python o JavaScript y luego use la variable en la plantilla.

Establecer valores predeterminados en las plantillas de mensajes

Si no se puede resolver una variable de plantilla, Apigee la sustituye por una cadena vacía. Sin embargo, puede especificar un valor predeterminado como se indica a continuación:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

En el ejemplo anterior, si la variable request.header.id no se puede resolver, su valor se reemplaza por Unknown . Por ejemplo:

Test message. id = Unknown

Plantillas de URL

El elemento URL admite plantillas que siguen la misma sintaxis que otros elementos.

Este ejemplo muestra una URL construida utilizando variables:

<URL>{targeturl}</URL>

Este ejemplo muestra un valor predeterminado para el protocolo:

<URL>{protocol:https}://{site:google.com}/path</URL>

Sintaxis heredada para cargas útiles JSON

En versiones de Apigee anteriores a la versión 16.08.17 de Cloud , no se podían usar llaves para indicar referencias a variables dentro de las cargas útiles JSON. En esas versiones anteriores, era necesario usar los atributos variablePrefix y variableSuffix para especificar caracteres delimitadores y usarlos para encapsular los nombres de las variables, como se muestra a continuación:

<Set>
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
    {"name":"foo","type":"@variable_name#"}
  </Payload>
</Set>

Aunque Apigee recomienda que utilice la sintaxis de llaves más nueva, la sintaxis anterior aún funciona.

Uso de funciones de plantilla de mensajes

Apigee proporciona un conjunto de funciones que puedes usar dentro de las plantillas de mensajes para escapar, codificar, aplicar hash y formatear variables de cadena, como se describe a continuación.

Ejemplo: toLowerCase()

Utilice la función incorporada toLowerCase() para transformar una variable de cadena a minúsculas:

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo createNew="false" type="response"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header>
    </Headers>
  </Set>
</AssignMessage>

Si la variable de flujo foo.bar se resuelve, sus caracteres estarán en minúsculas. Si foo.bar no se resuelve, se sustituye el valor predeterminado FOO y se convierte a minúsculas. Por ejemplo:

Test header: foo

Ejemplo: escapeJSON()

Aquí hay un caso práctico interesante: Supongamos que su aplicación backend devuelve una respuesta JSON que contiene caracteres de escape válidos. Por ejemplo:

{
  "code": "INVALID",
  "user_message": "Invalid value for \"logonId\" check your input."
}

Supongamos que desea devolver este mensaje al cliente que llama en una carga útil personalizada. La forma habitual de hacerlo es extraer el mensaje de la carga útil de la respuesta de destino y usar AssignMessage para añadirlo a una respuesta de proxy personalizada (es decir, enviarlo de vuelta al cliente).

Aquí está la política ExtractVariables que extrae la información user_message en una variable llamada standard.systemMessage :

<ExtractVariables name="EV-BackendErrorResponse">
  <DisplayName>EV-BackendErrorResponse</DisplayName>
  <JSONPayload>
    <Variable name="standard.systemMessage">
      <JSONPath>$.user_message</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Ahora, aquí hay una política AssignMessage perfectamente válida que agrega la variable extraída a la carga de respuesta (la respuesta del proxy):

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{standard.systemMessage}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Lamentablemente, hay un problema. La política ExtractVariables eliminó las comillas de escape que rodeaban parte del mensaje. Esto significa que la respuesta devuelta al cliente es un JSON no válido. ¡Esto claramente no es lo que pretendías!

{
  "systemMessage": "Invalid value for "logonId" check your input."
}

Para solucionar este problema, puede modificar la política AssignMessage para usar una función de plantilla de mensaje que escape las comillas dentro del JSON. Esta función, escapeJSON() , escapa las comillas u otros caracteres especiales que aparecen en una expresión JSON:

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{escapeJSON(standard.systemMessage)}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

La función escapa de las comillas integradas, lo que da como resultado un JSON válido, que es exactamente lo que deseaba:

{
  "systemMessage": "Invalid value for \"logonId\" check your input.",
}

Una plantilla de mensaje es una función de sustitución dinámica de cadenas que se puede usar en ciertas políticas y en las definiciones de <TargetEndpoint> . Las funciones de plantilla de mensaje permiten realizar operaciones útiles como hash, manipulación de cadenas, escape de caracteres y otras dentro de una plantilla de mensaje.

Por ejemplo, en la siguiente política AssignMessage, la función toLowerCase() se utiliza en una plantilla de mensaje:

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo createNew="false" type="response"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
   <Headers>
     <Header name="x-h1">Test header: {Hello,toLowerCase(user.name)}</Header>
   </Headers>
  </Set>
</AssignMessage>

Esta sección describe las funciones de las plantillas de mensajes, sus argumentos y resultados. Se asume que está familiarizado con las plantillas de mensajes y los contextos en los que se utilizan.

Funciones hash

Calcula un valor hash y devuelve la representación de cadena de ese hash.

Funciones hash hexadecimales

Calcula un valor hash y devuelve la representación de cadena de ese hash como un número hexadecimal.

Sintaxis

Argumentos

string : Las funciones hash toman un único argumento de cadena sobre el cual se calcula el algoritmo hash. El argumento puede ser una cadena literal ( entre comillas simples ) o una variable de flujo de cadena.

Ejemplos

Llamada de función:

sha256Hex('abc')

Resultado:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Llamada de función:

var str = 'abc';
sha256Hex(str)

Resultado:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funciones hash Base64

Calcula un valor hash y devuelve la representación de cadena de ese hash como un valor codificado en Base64.

Sintaxis

Argumentos

string : Las funciones hash toman un único argumento de cadena sobre el cual se calcula el algoritmo hash. El argumento puede ser una cadena literal ( entre comillas simples ) o una variable de flujo de cadena.

Ejemplos

Llamada de función:

sha256Base64('abc')

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Llamada de función:

var str = 'abc';
sha256Base64(str)

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funciones de cadena

Realizar operaciones en cadenas dentro de una plantilla de mensaje.

Funciones de codificación Base64

Codifique y decodifica cadenas utilizando el esquema de codificación Base64.

Sintaxis

Argumentos

string : La cadena que se codificará o decodificará. Puede ser una cadena literal ( entre comillas simples ) o una variable de flujo de cadena.

Ejemplo

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

Funciones de conversión de mayúsculas y minúsculas

Convierte una cadena en letras mayúsculas o minúsculas.

Sintaxis

Argumentos

string : La cadena que se va a convertir. Puede ser una cadena literal ( entre comillas simples ) o una variable de flujo de cadena.

Ejemplo

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

Función de subcadena

Devuelve los caracteres entre el índice inicial y final de la cadena especificada.

Sintaxis

substring(str,start_index,end_index)

Argumentos

• str : una cadena literal ( entre comillas simples ) o una variable de flujo de cadena.
• start_index : El índice inicial en la cadena.
• end_index : (Opcional) El índice final de la cadena. Si no se proporciona, el índice final es el final de la cadena.

Ejemplos

Para los siguientes ejemplos, supongamos que existen estas variables de flujo:

Aquí se muestran los resultados de las llamadas de funciones que utilizan estas variables:

Función Reemplazar todo

Aplica una expresión regular a una cadena y, para cualquier coincidencia, reemplaza la coincidencia con un valor de reemplazo.

Sintaxis

replaceAll(string,regex,value)

Argumentos

• cadena : una cadena literal ( entre comillas simples ) o una variable de flujo de cadena en la que se realizarán reemplazos.
• regex - Una expresión regular.
• valor : el valor que se utilizará para reemplazar todas las coincidencias de expresiones regulares dentro de la cadena.

Ejemplos

Para los siguientes ejemplos, supongamos que existen estas variables de flujo:

Aquí se muestran los resultados de las llamadas de funciones que utilizan estas variables:

Función Reemplazar Primero

Reemplaza solo la primera ocurrencia de la coincidencia de expresión regular especificada en la cadena.

Sintaxis

replaceFirst(string,regex,value)

Argumentos

• string : una cadena literal ( entre comillas simples ) o una variable de flujo de cadena en la que se realizarán reemplazos.
• regex : Una expresión regular.
• value : el valor que se utilizará para reemplazar las coincidencias de expresiones regulares dentro de la cadena.

Funciones de escape y codificación de caracteres

Funciones que escapan o codifican caracteres especiales en una cadena.

Sintaxis

Argumentos

string : La cadena que se va a escapar. Puede ser una cadena literal ( entre comillas simples ) o una variable de flujo de cadena.

Notas de uso

XML 1.1 puede representar ciertos caracteres de control, pero no puede representar el byte nulo ni los puntos de código sustitutos Unicode no emparejados, incluso después de escapar. La función escapeXML11() elimina los caracteres que no encajan en los siguientes rangos:

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

La función escapeXML11() escapa caracteres en los siguientes rangos:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

Ejemplos

Supongamos que existe una variable de flujo llamada comida con este valor: "bread" & "butter" . Entonces, la función:

{escapeHTML(food)}

Resultados en:

"bread" & "butter"

Funciones de formato de hora

Devuelve una representación de cadena de la hora, formateada en UTC.

Sintaxis

Argumentos

• format : Una cadena con formato de fecha y hora. Puede ser una cadena literal ( entre comillas simples ) o una variable de cadena. Use una variable en lugar de un literal cuando el formato incluya dos puntos. Consulte la nota anterior en esta sección.
• str : Una variable de cadena o de flujo de cadena que contiene un valor de tiempo. El valor puede expresarse en segundos o milisegundos desde la época para timeFormatMs.

Ejemplos

Suponga los siguientes valores y suponga que la zona horaria local es el Pacífico:

• epoch_time_ms = 1494390266000
• epoch_time = 1494390266
• fmt1 = yyyy-MM-dd
• fmt2 = yyyy-MM-dd HH-mm-ss
• fmt3 = yyyyMMddHHmmss

Las funciones devuelven los siguientes resultados:

Funciones de cálculo de HMAC

Las funciones de cálculo de HMAC ofrecen una alternativa al uso de la política HMAC para calcular un HMAC. Estas funciones son útiles al realizar cálculos de HMAC en cascada, como cuando la salida de un HMAC se utiliza como clave para un segundo HMAC.

Sintaxis

Argumentos

• clave - (Obligatorio) Especifica la clave secreta, codificada como una cadena, utilizada para calcular el HMAC.
• valueToSign - (Obligatorio) Especifica el mensaje a firmar. Debe ser una cadena.
• Codificación de clave : (Opcional) La cadena de clave secreta se decodificará según la codificación especificada. Valores válidos: hex , base16 , base64 y utf-8 . Predeterminado: utf-8
• outputencoding - (Opcional) Especifica el algoritmo de codificación que se usará para la salida. Valores válidos: hex , base16 , base64 . Los valores no distinguen entre mayúsculas y minúsculas; hex y base16 son sinónimos. Predeterminado: base64

Ejemplos

Este ejemplo utiliza la política AssignMessage para calcular un HMAC-256 y asignarlo a una variable de flujo:

<AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

Este ejemplo ilustra cómo generar un HMAC en cascada que se puede usar con el proceso de firma de AWS Signature v4 . El ejemplo utiliza la política AssignMessage para generar los cinco niveles de HMAC en cascada que se utilizan para calcular una firma para AWS Signature v4:

<AssignMessage name='AM-HMAC-AWS-1'>
  <!-- 1 -->
  <AssignVariable>
    <Name>DateValue</Name>
    <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template>
  </AssignVariable>
  <!-- 2 -->
  <AssignVariable>
    <Name>FirstKey</Name>
    <Template>AWS4{private.secret_aws_access_key}</Template>
  </AssignVariable>
  <!-- 3 -->
  <AssignVariable>
    <Name>DateKey</Name>
    <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template>
  </AssignVariable>
  <!-- 4 -->
  <AssignVariable>
    <Name>DateRegionKey</Name>
    <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 5 -->
  <AssignVariable>
    <Name>DateRegionServiceKey</Name>
    <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 6 -->
  <AssignVariable>
    <Name>SigningKey</Name>
    <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template>
  </AssignVariable>
  <!-- 7 -->
  <AssignVariable>
    <Name>aws4_hmac_value</Name>
    <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template>
  </AssignVariable>
</AssignMessage>

Otras funciones

Crear función UUID

Genera y devuelve un UUID.

Sintaxis

createUuid()

Argumentos

Ninguno.

Ejemplo

{createUuid()}

Resultado de muestra:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Función de generador de números largos aleatorios

Devuelve un entero largo aleatorio.

Sintaxis

randomLong(args)

Argumentos

• Si no se especifican argumentos, la función devuelve un entero largo aleatorio, tal como lo calcula la clase Java SecureRandom.
• Si hay un argumento, se trata como el valor mínimo del cálculo.
• Si hay un segundo argumento, se trata como el valor máximo del cálculo.

Ejemplo

{randomLong()}

El resultado es algo como esto:

5211338197474042880

Generador de texto de expresiones regulares

Generar una cadena de texto que coincida con una expresión regular dada.

Sintaxis

xeger(regex)

Argumento

regex : Una expresión regular.

Ejemplo

Este ejemplo genera una cadena de siete dígitos sin ceros:

xeger( '[1-9]{7}' )

Ejemplo de resultado:

9857253

Función de coalescencia nula

La función firstnonnull() devuelve el valor del argumento no nulo más a la izquierda.

Sintaxis

firstnonnull(var1,varn)

Argumento

var1 : Una variable de contexto.

var n : Una o más variables de contexto. Puede asignar una cadena al argumento situado más a la derecha para proporcionar un valor de reserva (un valor que se establecerá si no se establece ninguno de los argumentos de la izquierda).

Ejemplos

La siguiente tabla ilustra cómo utilizar la función:

Función XPath

Aplica una expresión XPath a una variable XML.

Sintaxis

xpath(xpath_expression,xml_string[,datatype])

Argumentos

xpath_expression : Una expresión XPath.

xml_string : una variable de flujo o cadena que contiene XML.

datatype : (Opcional) Especifica el tipo de retorno deseado de la consulta. Los valores válidos son nodeset , node , number , boolean o string . El valor predeterminado es nodeset . El valor predeterminado suele ser la opción correcta.

Ejemplo 1

Supongamos que estas variables de contexto definen una cadena XML y una expresión XPath:

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

Y la función xpath() se utiliza en una política AssignMessage, de la siguiente manera:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage>

La función devuelve el valor <tagid>250397</tagid> . Este valor se coloca en la variable de contexto denominada extracted_tag .

Ejemplo 2: espacios de nombres XML

Para especificar un espacio de nombres, añada parámetros adicionales, cada uno una cadena similar prefix:namespaceuri . Por ejemplo, una función xpath() que selecciona el elemento secundario de un cuerpo SOAP podría ser similar a esto:

<AssignMessage>
  <AssignVariable>
    <Name>soapns</Name>
    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>xpathexpression</Name>
    <Value>/soap:Envelope/soap:Body/*</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>extracted_element</Name>
    <Template>{xpath(xpathexpression,xml,soapns)}</Template>
  </AssignVariable>
</AssignMessage>

Para espacios de nombres adicionales, puede agregar hasta 10 parámetros adicionales a la función xpath() .

En lugar de especificar una expresión XPath con caracteres especiales como literal de cadena, utilice una variable para incluir esa cadena en la función. Consulte "Evitar el uso de caracteres especiales en literales de cadena" para obtener más información.

{xpath(xpathexpression,xml,ns1)}

Ejemplo 3: Especificación de un tipo de retorno deseado

El tercer parámetro opcional pasado a la función xpath() especifica el tipo de retorno deseado de la consulta.

Algunas consultas XPath pueden devolver valores numéricos o booleanos. Por ejemplo, la función count() devuelve un número. Esta es una consulta XPath válida:

count(//Record/Fields/Pair)

Esta consulta válida devuelve un valor booleano:

count(//Record/Fields/Pair)>0

En esos casos, invoque la función xpath() con un tercer parámetro que especifique ese tipo:

{xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}

Si el tercer parámetro contiene dos puntos, se interpreta como un argumento de espacio de nombres. De lo contrario, se trata como el tipo de retorno deseado. En este caso, si el tercer parámetro no es uno de los valores válidos (sin distinguir entre mayúsculas y minúsculas), la función xpath() devuelve un conjunto de nodos por defecto.

Función de ruta JSON

Aplica una expresión de ruta JSON a una variable JSON.

Sintaxis

jsonPath(json-path,json-var,want-array)

Argumentos

• (Obligatorio) json-path : (Cadena) Una expresión de ruta JSON.
• (Obligatorio) json-var : (Cadena) Una variable de flujo o cadena que contiene JSON.
• (Opcional) want-array : (Cadena) Si este parámetro se establece en 'true' y el conjunto de resultados es un array, se devuelven todos los elementos del array. Si se establece en cualquier otro valor o se omite este parámetro, solo se devuelve el elemento cero del array del conjunto de resultados. Si el conjunto de resultados no es un array, este tercer parámetro, si está presente, se ignora.

Ejemplo 1

Si esta es la plantilla del mensaje:

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

y the_json_variable contiene:

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
} 

El resultado de la función es:

The address is 1060 West Addison Street

Tenga en cuenta que, en este caso, el conjunto de resultados es un solo elemento (no un array de elementos). Si el conjunto de resultados fuera un array, solo se devolvería el elemento cero del array. Para devolver el array completo, llame a la función con 'true' como tercer parámetro, como se muestra en el siguiente ejemplo.

Ejemplo 2

Si esta es la plantilla del mensaje:

{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

y the_json_variable contiene:

{
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
} 

El resultado de la función es:

['A','B']