Plantillas de mensajes

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

Consulta la documentación de Apigee Edge.

En este tema, se explica cómo usar plantillas de mensajes en los proxies de API y se proporciona una referencia de función.

¿Qué es una plantilla de mensaje?

Una plantilla de mensajes te permite realizar una sustitución de string variable en ciertos elementos de políticas y <TargetEndpoint>. Esta función, cuando se admite, te permite propagar strings de forma dinámica cuando se ejecuta un proxy.

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

Consulta también ¿Dónde puedes usar las plantillas de mensajes?

Ejemplo

Por ejemplo, la política AssignMessage te permite usar una plantilla de mensajes 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 (en llaves) se evaluará y sustituirá a la string de carga útil en el entorno de ejecución. Por ejemplo, si user.name=jdoe, el resultado del mensaje resultante en la carga útil será You entered an invalid username: jdoe. Si la variable no se puede resolver, se genera una string vacía.

Ejemplo

Cuando se supera una cuota, se recomienda mostrar un mensaje significativo al emisor. Por lo general, este patrón se usa con una “regla de falla” que proporciona un resultado para darle al emisor información sobre el incumplimiento de cuota. En la siguiente política AssignMessage, las plantillas de mensajes se usan para propagar la información de la cuota de forma dinámica 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 las plantillas de mensajes:

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

Otra vez, ten en cuenta que las variables de flujo en una plantilla de mensaje deben incluirse entre llaves.

Cuando se ejecuta esta política, sucede lo siguiente:

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

Ejemplo

En una definición de proxy <TargetEndpoint>, los elementos secundarios de <SSLInfo> admiten las plantillas de mensajes. Si se sigue el mismo patrón usado en las políticas, las variables de flujo en llaves se reemplazan cuando se ejecuta 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 usar plantillas de mensajes?

Las plantillas de mensajes son compatibles con varias políticas y ciertos elementos que se usan en la configuración de TargetEndpoint.

Nota: También puedes consultar la documentación de la política para obtener información sobre qué política y elementos de <TargetEndpoint> son compatibles con las plantillas de mensajes.

Políticas que aceptan plantillas de mensajes

En la siguiente tabla, se enumeran las políticas y los elementos compatibles, y los elementos secundarios:

Política	Elementos secundarios y elementos
Política AccessControl	`<SourceAddress>` para el atributo `mask` y la dirección IP
Política AssignMessage	Elementos secundarios `<Set>`: Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams Elementos secundarios `<Add>`: encabezados, QueryParams, FormParams Elemento secundario `<AssignVariable>`: `<Template>`
Política de CORS	`<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<ExposeHeaders>`
Política ExtractVariables	`<JsonPath>` Nota: La plantilla de mensajes no se acepta para `<XMLPath>`.
Política GenerateJWS Política VerifyJWS	`<Payload>` (solo política GenerateJWS) `<AdditionalHeaders><Claim>` * Estos elementos admiten la plantilla de mensajes solo cuando type=map.
Política GenerateJWT Política VerifyJWT	`<AdditionalClaims><Claim>` `<AdditionalHeaders><Claim>` * Estos elementos admiten la plantilla de mensajes solo cuando type=map.
Política HTTPModifier	`<Set>`Elementos secundarios: `<ContentType>` `<Verb>` `<Version>` `<Path>` `<StatusCode>` `<Headers>` `<QueryParams>` `<FormParams>` `<Add>`Elementos secundarios: `<Headers>` `<QueryParams>` `<FormParams>`
Política MessageLogging	`<CloudLogging><Message>` `<Syslog><Message>` `<File><Message>`
Política OASValidation	Elemento `<OASResource>`
Política RaiseFault	Elementos `<Set>`: `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` Elementos `<Add>`: `<FormParams>` `<Headers>` `<QueryParams>`
Política SAMLAssertion	`<Template>` * Solo cuando la firma de la política es `<GenerateSAMLAssertion>`
Política ServiceCallout	Elementos `<Set>`: `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` Elementos `<Add>`: `<FormParams>` `<Headers>` `<QueryParams>` `<HTTPTargetConnection>/<URL>`: Consulta Plantillas de URL.

Elementos `<TargetEndpoint>` que aceptan plantillas de mensajes

Elementos `<HTTPTargetConnection>`	Elementos secundarios que admiten plantillas de mensajes
`<SSLInfo>`	`<Enabled>`, `<KeyAlias>`, `<KeyStore>`, `<TrustStore>`, `<ClientAuthEnabled>`, `<CLRStore>`
`<LocalTargetConnection>`	`<ApiProxy>`, `<ProxyEndpoint>`, `<Path>`
`<Path>`	N/A
`<URL>`	No hay elementos secundarios. Consulta Plantillas de URL para usarlas.

Sintaxis de la plantilla de mensajes

En esta sección, se explican las reglas que debe seguir para usar las plantillas de mensajes.

Usa llaves para denotar variables

Encierra los nombres de las variables entre llaves { }. Si la variable no existe, se muestra una string vacía en el resultado. Sin embargo, puedes especificar valores predeterminados en las plantillas de mensajes (valores que se sustituyen si la variable no se resuelve). Consulta Establece valores predeterminados en las plantillas de mensajes.

Tenga en cuenta que puedes incluir toda la string de plantilla de mensaje entre comillas, pero es opcional. Por ejemplo, las siguientes dos plantillas de mensajes 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 las funciones

No se permiten espacios en las expresiones de las funciones de las plantillas de mensajes. Por ejemplo:

Permitido:

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

No permitido:

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

No se admiten las funciones anidadas.

No se admite llamar a una función dentro de otra función en una plantilla. Por ejemplo, no puedes usar .

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

Encierra literales de strings en funciones de plantillas entre comillas simples

Cuando proporciones literales de string en funciones, los encierra entre comillas simples en lugar de comillas dobles.

Por ejemplo:

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

Evita usar caracteres especiales en literales de string

Evita los caracteres especiales, como ":", "/", "\", "<" o ">", en los literales de string. Estos caracteres pueden causar errores. Si un literal de string requiere caracteres especiales, asigna el valor a una variable mediante una política de Python o JavaScript y, luego, usa la variable en la plantilla.

Establece valores predeterminados en las plantillas de mensajes

Si no se puede resolver una variable con plantilla, Apigee sustituye una string vacía. Sin embargo, puedes especificar un valor predeterminado de la siguiente manera:

<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, el valor se reemplaza por Unknown. Por ejemplo:

Test message. id = Unknown

Plantillas de URL

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

En este ejemplo, se muestra una URL construida con variables:

<URL>{targeturl}</URL>

En este ejemplo, se muestra un valor predeterminado para el protocolo:

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

Sintaxis heredada para cargas útiles JSON

En las versiones de Apigee antes de la versión 16.08.17 de Cloud, no puedes usar llaves para denotar referencias de variables en las cargas útiles de JSON. En esas versiones anteriores, necesitabas usar los atributos variablePrefix y variableSuffix para especificar los caracteres delimitadores y usarlos a fin de encerrar los nombres de las variables de la siguiente manera:

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

Aunque Apigee recomienda que uses la sintaxis entre llaves más reciente, la sintaxis anterior seguirá funcionando.

Usa funciones de plantilla de mensajes

Apigee proporciona un conjunto de funciones que puedes usar dentro de plantillas de mensajes para escapar a variables de string, codificarlas, generar hash y darles formato, como se describe a continuación.

Ejemplo: toLowerCase()

Usa la función integrada toLowerCase() para transformar una variable de string en 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, todos sus caracteres aparecerán en minúsculas. Si no se resuelve foo.bar, se sustituye el valor predeterminado FOO y se convierte en caracteres en minúscula. Por ejemplo:

Test header: foo

Ejemplo: escapeJSON()

Este es un caso de uso interesante: supongamos que tu app de backend muestra una respuesta JSON que contiene caracteres de escape válidos. Por ejemplo:

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

Luego, supongamos que deseas mostrar este mensaje al emisor del cliente 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 agregarlo a una respuesta de proxy personalizada (es decir, enviarla de vuelta al cliente).

Esta es la política de ExtractVariables que extrae la información de 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>

Esta es una política AssignMessage válida en el que se agrega la variable extraída a la carga útil de la 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 quitó los caracteres de comillas alrededor del escape del mensaje. Esto significa que la respuesta que se muestra al cliente no es válida para JSON. Esto no es lo que pretendías.

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

Para solucionar este problema, puedes modificar la política AssignMessage a fin de usar una función de plantilla de mensajes que escape las comillas dentro del JSON por ti. Esta función, escapeJSON(), escapa todas las comillas y otros caracteres especiales que ocurren dentro de 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 las comillas incorporadas y da como resultado un valor JSON válido, que es lo que deseas:

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

Una plantilla de mensajes es una función de sustitución de string dinámica que puedes usar en ciertas políticas y en definiciones de <TargetEndpoint>. Las funciones de la plantilla de mensajes te permiten realizar operaciones útiles, como hash, manipulación de strings, escape de caracteres y otras dentro de una plantilla de mensajes.

Por ejemplo, en la siguiente política AssignMessage, la función toLowerCase() se usa 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>

En esta sección, se describen las funciones de la plantilla de mensajes, sus argumentos y los resultados. En este tema, se supone que estás familiarizado con las plantillas de mensajes y los contextos en los que se usan.

Funciones de generación de hash

Calcula un valor de hash y muestra la representación de la string de ese hash.

Funciones de hash hexadecimal

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

Sintaxis

Función	Descripción
`md5Hex(string)`	Calcula un hash MD5 expresado como un número hexadecimal.
`sha1Hex(string)`	Calcula un hash SHA1 expresado como número hexadecimal.
`sha256Hex(string)`	Calcula un hash SHA256 expresado como número hexadecimal.
`sha384Hex(string)`	Calcula un hash SHA384 expresado como número hexadecimal.
`sha512Hex(string)`	Calcula un hash SHA512 expresado como número hexadecimal.

Argumentos

string: Las funciones de hash toman un solo argumento de string en el que se calcula el algoritmo de hash. El argumento puede ser un literal de string (entre comillas simples) o una variable de flujo de string.

Ejemplos

Llamada a función:

sha256Hex('abc')

Resultado:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Llamada a función:

var str = 'abc';
sha256Hex(str)

Resultado:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funciones de hash en base64

Calcula un valor de hash y muestra la representación de string de ese hash como un valor con codificación base64.

Sintaxis

Función	Descripción
`md5Base64(string)`	Calcula un hash MD5 expresado como un valor con codificación base64.
`sha1Base64(string)`	Calcula un hash SHA1 expresado como valor codificado en Base64.
`sha256Base64(string)`	Calcula un hash SHA256 expresado como valor codificado en Base64.
`sha384Base64(string)`	Calcula un hash SHA384 expresado como un valor con codificación base64.
`sha512Base64(string)`	Calcula un hash SHA512 expresado como valor codificado en Base64.

Argumentos

string: las funciones de hash toman un solo argumento de string en el que se calcula el algoritmo de hash. El argumento puede ser un literal de string (entre comillas simples) o una variable de flujo de string.

Ejemplos

Llamada a función:

sha256Base64('abc')

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Llamada a función:

var str = 'abc';
sha256Base64(str)

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funciones de string

Realiza operaciones en strings dentro de una plantilla de mensajes.

Funciones de codificación en base64

Codifica y decodifica strings con el esquema de codificación en Base64.

Sintaxis

Función	Descripción
`encodeBase64(string)`	Codifica una string con codificación base64. Por ejemplo: `encodeBase64(value)`, cuando `value` contiene `abc`, la función muestra la string: `YWJj`
`decodeBase64(string)`	Decodifica una string codificada en base64. Por ejemplo: `decodeBase64(value)` cuando `value` contiene `aGVsbG8sIHdvcmxk`, la función muestra la string `hello, world`.

Argumentos

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

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 string a todas letras mayúsculas o todas minúsculas.

Sintaxis

Función	Descripción
`toUpperCase(string)`	Convierte una string en mayúsculas.
`toLowerCase(string)`	Convierte una string en minúsculas.

Argumentos

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

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 substring

Muestra los caracteres entre el índice inicial y el final de la string especificada.

Sintaxis

substring(str,start_index,end_index)

Argumentos

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

Ejemplos

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

Nombre de la variable	Valor
`alpha`	ABCDEFGHIJKLMNOPQRSTUVWXYZ
`seven`	7

Estos son los resultados de las llamadas a funciones que usan estas variables:

Expresión de plantilla de mensajes	Resultado
`{substring(alpha,22)}`	`WXYZ`
`hello {substring(alpha,22)}`	`hello WXYZ`
`{substring(alpha,-4)}`	`WXYZ`
`{substring(alpha,-8,-4)}`	`STUV`
`{substring(alpha,0,10)}`	`ABCDEFGHIJ`
`{substring(alpha,0,seven)}`	`ABCDEFG`

Reemplaza todas las funciones

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

Sintaxis

replaceAll(string,regex,value)

Argumentos

string: string literal (entre comillas simples) o variable de flujo de string en la que se realizan los reemplazos.
regex: una expresión regular.
valor: valor que reemplaza todas las coincidencias de regex dentro de la string.

Ejemplos

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

Nombre de la variable	Valor
`header`	`Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`
`regex1`	`"^Bearer "`
`replacement`	`"TOKEN: "`

Estos son los resultados de las llamadas a funciones que usan estas variables:

Expresión de plantilla de mensajes	Resultado
`{replaceAll(header,'9993','')}`	`Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-`
`{replaceAll(header,regex1,'')}`	`ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`
`{replaceAll(header,regex1,replacement)}`	`TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`

Reemplaza la primera función

Reemplaza solo la primera instancia de la coincidencia con la expresión regular especificada en la string.

Sintaxis

replaceFirst(string,regex,value)

Argumentos

string: literal de string (entre comillas simples) o variable de flujo de string en la que se realizan los reemplazos.
regex: una expresión regular.
value: Es el valor que se usa para reemplazar coincidencias de regex en la string.

Funciones de codificación y escape de caracteres

Funciones que escapan o codifican caracteres especiales en una string.

Sintaxis

Función	Descripción
`escapeJSON(string)`	Backslash-escapes double-quotes.
`escapeXML(string)`	Reemplaza corchetes angulares, apóstrofos, comillas dobles y signos de unión por las entidades XML respectivas. Úsalo para documentos XML 1.0. Usa escapeXML para los documentos XML1.0 y escapeXML11 para los documentos XML 1.1 .
`escapeXML11(string)`	Funciona de la misma manera que escapeXML, pero para las entidades XML versión 1.1. Consulta las notas de uso que aparecen a continuación.
`encodeHTML(string)`	Codifica apóstrofos, corchetes y ets.

Argumentos

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

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 subrogados Unicode únicos, incluso después del escape. La función escapeXML11() quita los caracteres que no entran en los siguientes rangos:

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

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

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

Ejemplos

Supongamos que existe una variable de flujo llamada food con el siguiente valor "bread" & "butter". Luego, la función:

{escapeHTML(food)}

Se produce el siguiente resultado:

&quot;bread&quot; &amp; &quot;butter&quot;

Funciones de formato de tiempo

Muestra una representación de cadena de la hora con formato UTC.

Sintaxis

Función	Descripción
`timeFormat(format,str)`	Muestra la fecha en formato UTC. `DEPRECATED`: Muestra la fecha con el formato de la zona horaria local.
`timeFormatMs(format,str)`	Muestra la fecha en formato UTC. `DEPRECATED`: Muestra la fecha con el formato de la zona horaria local.
`timeFormatUTC(format,str)`	Muestra la fecha en formato UTC.
`timeFormatUTCMs(format,str)`	Muestra la fecha en formato UTC.

Argumentos

format: una string de formato de fecha y hora. Puede ser una string literal (entre comillas simples) o una variable de string. Usa una variable en lugar de un literal cuando el formato incluya dos puntos. Consulta la nota anterior en esta sección.
str: una string o una variable de flujo de string que contiene un valor de tiempo. El valor puede estar en segundos desde el ciclo de entrenamiento o milisegundos para timeFormatMs.

Ejemplos

Supón los siguientes valores y supón 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 muestran los siguientes resultados:

Función	Salida
`timeFormatMs(fmt1,epoch_time_ms)`	`2017-05-09`
`timeFormat(fmt1,epoch_time)`	`2017-05-09`
`timeFormat(fmt2,epoch_time)`	`2017-05-09 21:24:26`
`timeFormat(fmt3,epoch_time)`	`20170509212426`
`timeFormatUTC(fmt1,epoch_time)`	`2017-05-10`
`timeFormatUTC(fmt2,epoch_time)`	`2017-05-10 04:24:26`
`timeFormatUTC(fmt3,epoch_time)`	`20170510042426`

Funciones de cálculo de HMAC

Las funciones de cálculo de HMAC proporcionan una alternativa al uso de la política HMAC para calcular un HMAC. Las funciones son útiles cuando se realiza un cálculo en HMAC en cascada, como cuando el resultado de un HMAC se usa como clave para un segundo HMAC.

Sintaxis

Función	Descripción
`hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])`	Calcula una HMAC con la función de hash SHA-224.
`hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica una HMAC con la función hash SHA-256.
`hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica una HMAC con la función hash SHA-384.
`hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica una HMAC con la función hash SHA-512.
`hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica una HMAC con la función de hash MD5.
`hmacSha1(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica una HMAC con el algoritmo de encriptación SHA-1.

Argumentos

key: (obligatorio) Especifica la clave secreta, codificada como una string, que se usa para calcular la HMAC.
valueToSign: Especifica el mensaje que se firmará (obligatorio). Debe ser una string.
keyencoding - (opcional) La string de clave secreta se decodificará de acuerdo con esta codificación especificada. Valores válidos: hex, base16, base64, utf-8. Valor predeterminado: utf-8
outputencoding: Especifica el algoritmo de codificación que se usará para el resultado (opcional). Valores válidos: hex, base16 y base64. Los valores no distinguen mayúsculas de minúsculas, hex y base16 son sinónimos. Configuración predeterminada: base64

Ejemplos

En este ejemplo, se usa la política AssignMessage para calcular una HMAC-256 y asignarla 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>

En este ejemplo, se ilustra cómo generar una HMAC en cascada que se puede usar con el proceso de firma de AWS Signature v4. En el ejemplo, se usa la política AssignMessage para generar los cinco niveles de HMAC en cascada que se usan a fin de 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 funciones UUID

Genera y muestra un UUID.

Sintaxis

createUuid()

Argumentos

Ninguno

Ejemplo

{createUuid()}

Resultado de muestra:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Función del generador largo aleatorio

Muestra un número entero largo aleatorio.

Sintaxis

randomLong(args)

Argumentos

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

Ejemplo

{randomLong()}

Da un resultado similar al siguiente:

5211338197474042880

Generador de textos de regex

Genera una string de texto que coincida con una expresión regular determinada.

Sintaxis

xeger(regex)

Argumento

regex: una expresión regular.

Ejemplo

En este ejemplo, se genera una string de siete dígitos sin ceros:

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

Resultado de ejemplo:

Función de fusión nula

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

Sintaxis

firstnonnull(var1,var_n)

Argumento

var1: Una variable de contexto.

var_n: Una o más variables de contexto. Puedes configurar el argumento más a la derecha para establecer una string como valor de resguardo (un valor que se establecerá si no se estableció ninguno de los argumentos de la izquierda).

Ejemplos

En la siguiente tabla, se ilustra cómo usar la función:

Plantilla	Var1	Var2	Var3	Resultado
`{firstnonnull(var1,var2)}`	Sin establecer	`foo`	N/A	`foo`
`{firstnonnull(var1,var2)}`	`foo`	`bar`	N/A	`foo`
`{firstnonnull(var1,var2)}`	`foo`	Sin establecer	N/A	`foo`
`{firstnonnull(var1,var2,var3)}`	`foo`	`bar`	`baz`	`foo`
`{firstnonnull(var1,var2,var3)}`	Sin establecer	`bar`	`baz`	`bar`
`{firstnonnull(var1,var2,var3)}`	Sin establecer	Sin establecer	`baz`	`baz`
`{firstnonnull(var1,var2,var3)}`	Sin establecer	Sin establecer	Sin establecer	`null`
`{firstnonnull(var1)}`	Sin establecer	N/A	N/A	`null`
`{firstnonnull(var1)}`	`foo`	N/A	N/A	`foo`
`{firstnonnull(var1,var2)}`	`""`	`bar`	N/A	`""`
`{firstnonnull(var1,var2,'fallback value')}`	`null`	`null`	`fallback value`	`fallback value`

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 una string que contiene XML.

datatype: Especifica el tipo de datos que se muestra deseado de la consulta (opcional). Los valores válidos son nodeset, node, number, boolean o string. El valor predeterminado es nodeset. La opción predeterminada suele ser la correcta.

Ejemplo 1

Supongamos que estas variables de contexto definen una string 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 usa 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 muestra el valor <tagid>250397</tagid>. Este valor se coloca en la variable de contexto llamada extracted_tag.

Ejemplo 2: Espacios de nombres en formato XML

Para especificar un espacio de nombres, agrega parámetros adicionales, cada uno de los cuales tendrá una string similar a prefix:namespaceuri. Por ejemplo, una función xpath() que selecciona el elemento secundario de un cuerpo de SOAP podría tener el siguiente aspecto:

<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, puedes agregar hasta 10 parámetros adicionales a la función xpath().

En lugar de especificar una expresión XPath con caracteres especiales como un literal de string, usa una variable para incluir esa string en la función. Consulta Evita usar caracteres especiales en literales de string para obtener más detalles.

{xpath(xpathexpression,xml,ns1)}

Ejemplo 3: especifica un tipo de resultado deseado

El tercer parámetro opcional que se pasa a la función xpath() especifica el tipo de datos que se desea que muestre la consulta.

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

count(//Record/Fields/Pair)

Esta consulta válida muestra un valor booleano:

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

En esos casos, invoca 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 datos que se muestra. En este caso, si el tercer parámetro no es uno de los valores válidos (si se ignora el caso), la función xpath() muestra de forma predeterminada un conjunto de nodos.

Función de ruta JSON

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

Sintaxis

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

Argumentos

json-path (obligatorio): (string) una expresión de ruta de acceso JSON.
json-var (obligatorio): (string) una variable de flujo o string que contiene JSON.
want-array (opcional): (string) Si este parámetro se establece en 'true' y el conjunto de resultados es un array, se muestran todos los elementos del array. Si se establece en cualquier otro valor o si se omite este parámetro, solo se muestra el elemento cero de un array de resultados. Si el conjunto de resultados no es un array, se ignora este tercer parámetro, si está presente.

Ejemplo 1

Si esta es la plantilla del mensaje, ten en cuenta lo siguiente:

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

y the_json_variable contiene lo siguiente:

{
  "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 el siguiente:

The address is 1060 West Addison Street

Ten 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 mostraría el cero elemento del array. Para mostrar el array completo, llama 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, ten en cuenta lo siguiente:

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

y the_json_variable contiene lo siguiente:

{
  "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 el siguiente:

['A','B']

Plantillas de mensajes

¿Qué es una plantilla de mensaje?

Ejemplo

Ejemplo

Ejemplo

¿Dónde puedes usar plantillas de mensajes?

Políticas que aceptan plantillas de mensajes

Elementos <TargetEndpoint> que aceptan plantillas de mensajes

Sintaxis de la plantilla de mensajes

Usa llaves para denotar variables

No se permiten espacios en las expresiones de las funciones

No se admiten las funciones anidadas.

Encierra literales de strings en funciones de plantillas entre comillas simples

Evita usar caracteres especiales en literales de string

Establece valores predeterminados en las plantillas de mensajes

Plantillas de URL

Sintaxis heredada para cargas útiles JSON

Usa funciones de plantilla de mensajes

Ejemplo: toLowerCase()

Ejemplo: escapeJSON()

Funciones de generación de hash

Funciones de hash hexadecimal

Sintaxis

Argumentos

Ejemplos

Funciones de hash en base64

Sintaxis

Argumentos

Ejemplos

Funciones de string

Funciones de codificación en base64

Sintaxis

Argumentos

Ejemplo

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

Sintaxis

Argumentos

Ejemplo

Función substring

Sintaxis

Argumentos

Ejemplos

Reemplaza todas las funciones

Sintaxis

Argumentos

Ejemplos

Reemplaza la primera función

Sintaxis

Argumentos

Funciones de codificación y escape de caracteres

Sintaxis

Argumentos

Notas de uso

Ejemplos

Funciones de formato de tiempo

Sintaxis

Argumentos

Ejemplos

Funciones de cálculo de HMAC

Sintaxis

Argumentos

Ejemplos

Otras funciones

Crear funciones UUID

Sintaxis

Argumentos

Ejemplo

Función del generador largo aleatorio

Sintaxis

Argumentos

Ejemplo

Generador de textos de regex

Sintaxis

Argumento

Ejemplo

Función de fusión nula

Sintaxis

Argumento

Ejemplos

Función XPath

Elementos `<TargetEndpoint>` que aceptan plantillas de mensajes