Esta página se ha traducido con Cloud Translation API.

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 proxies de API y se proporciona una referencia de funciones.

¿Qué es una plantilla de mensaje?

Una plantilla de mensaje te permite realizar una sustitución de cadenas de variables en determinados elementos de la política y de <TargetEndpoint>. Esta función, cuando está disponible, te permite rellenar cadenas 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 ir entre llaves, mientras que el texto que no esté entre llaves se mostrará 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 mensaje en el elemento <Payload>:

<AssignMessage name="AM-set-payload-with-dynamic-content">
  <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 se sustituirá en la cadena de carga útil en tiempo de ejecución. Por ejemplo, si user.name=jdoe, el mensaje resultante en la carga útil será: You entered an invalid username: jdoe. Si no se puede resolver la variable, se genera una cadena vacía.

Ejemplo

Cuando se supera una cuota, es recomendable devolver un mensaje significativo a la persona que llama. Este patrón se suele usar con una "regla de error" para proporcionar información al llamante sobre la infracción de la cuota. En la siguiente política AssignMessage, se usan plantillas de mensajes para rellenar información de 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 plantillas de mensajes:

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

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

Cuando se aplica esta política:

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

Ejemplo

En una definición de proxy <TargetEndpoint>, los elementos secundarios de <SSLInfo> admiten plantillas de mensajes. Siguiendo el mismo patrón que se usa en las políticas, las variables de flujo entre llaves se sustituyen 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 se admiten en varias políticas, así como en determinados elementos que se usan en la configuración de TargetEndpoint.

Nota: También puedes consultar la documentación de la política para saber qué política y qué elementos de <TargetEndpoint> admiten plantillas de mensajes.

Políticas que aceptan plantillas de mensajes

En la siguiente tabla se indican las políticas y los elementos o elementos secundarios que se admiten:

Política	Elementos o elementos secundarios
Política AccessControl	`<SourceAddress>`, para el atributo `mask` y la dirección IP.
Política AssignMessage	Elementos secundarios de `<Set>`: Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams y FormParams Elementos secundarios de `<Add>`: Headers, QueryParams y FormParams Elemento secundario `<AssignVariable>`: `<Template>`
Política de CORS	`<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<ExposeHeaders>`
Política ExtractVariables	`<JsonPath>` Nota: La plantilla de mensaje no se acepta para `<XMLPath>`.
Política GenerateJWS Política VerifyJWS	`<Payload>` (solo para la política GenerateJWS) `<AdditionalHeaders><Claim>` * Estos elementos solo admiten plantillas de mensaje cuando type=map.
Política GenerateJWT Política VerifyJWT	`<AdditionalClaims><Claim>` `<AdditionalHeaders><Claim>` * Estos elementos solo admiten plantillas de mensaje cuando type=map.
Política HTTPModifier	Elementos secundarios de `<Set>`: `<ContentType>` `<Verb>` `<Version>` `<Path>` `<StatusCode>` `<Headers>` `<QueryParams>` `<FormParams>` Elementos secundarios de `<Add>`: `<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 de SAMLAssertion	`<Template>` * Solo cuando la firma de la política sea `<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.

`<TargetEndpoint>` elementos 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 tiene elementos secundarios. Para saber cómo usarlas, consulta Plantillas de URL.

Sintaxis de plantilla de mensaje

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

Usar llaves para denotar variables

Incluya los nombres de las variables entre llaves { }. Si la variable no existe, se devuelve una cadena vacía en el resultado. Sin embargo, puede especificar valores predeterminados en las plantillas de mensajes (valores que se sustituyen si la variable no se resuelve). Consulta cómo definir valores predeterminados en plantillas de mensajes.

Ten en cuenta que se permite incluir toda la cadena de la plantilla de mensaje entre comillas, pero no es obligatorio. Por ejemplo, estas dos plantillas de mensaje 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 ninguna parte de las expresiones de funciones de las plantillas de mensaje. Por ejemplo:

Se permite:

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

No se permite:

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

No se admiten las funciones anidadas

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

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

Incluir literales de cadena entre comillas simples en funciones de plantilla

Cuando proporciones literales de cadena en funciones, inclúyelos entre comillas simples en lugar de comillas dobles.

Por ejemplo,

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

Evita usar caracteres especiales en literales de cadena

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

Definir valores predeterminados en plantillas de mensajes

Si no se puede resolver una variable de plantilla, Apigee sustituye una cadena 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 no se puede resolver la variable request.header.id, su valor se sustituye 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 creada 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 antigua de las cargas útiles de JSON

En las versiones de Apigee anteriores a la versión 16.08.17 de Cloud, no podías usar llaves para indicar referencias de variables en cargas útiles JSON. En esas versiones anteriores, tenías que usar los atributos variablePrefix y variableSuffix para especificar los caracteres delimitadores y usarlos para envolver 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 más reciente con llaves, la sintaxis anterior sigue funcionando.

Usar funciones de plantillas de mensajes

Apigee proporciona un conjunto de funciones que puede usar en plantillas de mensajes para aplicar formato de escape, codificar, cifrar con hash y dar formato a variables de cadena, tal como se describe a continuación.

Ejemplo: toLowerCase()

Usa la función integrada 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 serán todos en minúsculas. Si foo.bar no se resuelve, se sustituye por el valor predeterminado FOO y se convierte a minúsculas. Por ejemplo:

Test header: foo

Ejemplo: escapeJSON()

Aquí tienes un caso práctico interesante: supongamos que tu 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 quieres devolver este mensaje al cliente que ha llamado 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).

Esta es 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í tienes una política AssignMessage perfectamente válida que añade 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>response</AssignTo>
</AssignMessage>

Lamentablemente, hay un problema. La política ExtractVariables ha eliminado los caracteres de comillas de escape de una parte del mensaje. Esto significa que la respuesta devuelta al cliente no es un JSON válido. Está claro que no es lo que querías.

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

Para solucionar este problema, puedes modificar la política AssignMessage para usar una función de plantilla de mensaje que escape las comillas del JSON. Esta función, escapeJSON(), escapa las comillas u otros caracteres especiales que se incluyan 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>response</AssignTo>
</AssignMessage>

La función escapa las comillas insertadas, lo que da como resultado un JSON válido, que es exactamente lo que querías:

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

Una plantilla de mensaje es una función de sustitución de cadenas dinámica que puedes usar en determinadas políticas y en definiciones de <TargetEndpoint>. Las funciones de las plantillas de mensajes te permiten realizar operaciones útiles, como cifrado hash, manipulación de cadenas y escape de caracteres, entre otras, en una plantilla de mensaje.

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>response</AssignTo>
  <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 las plantillas de mensajes, sus argumentos y sus resultados. En este tema se da por supuesto que conoces las plantillas de mensajes y los contextos en los que se utilizan.

Funciones hash

Calcula un valor de 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

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

Argumentos

string: Las funciones hash toman un único argumento de cadena sobre el que 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 de hash y devuelve la representación de cadena de ese hash como un valor codificado en Base64.

Sintaxis

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

Argumentos

string: las funciones de hash toman un único argumento de cadena sobre el que se calcula el algoritmo de 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

Realiza operaciones en cadenas de una plantilla de mensaje.

Funciones de codificación Base64

Codifica y decodifica cadenas mediante el esquema de codificación Base64.

Sintaxis

Función	Descripción
`encodeBase64(string)`	Codifica una cadena mediante la codificación Base64. Por ejemplo, `encodeBase64(value)`. Si `value` contiene `abc`, la función devuelve la cadena `YWJj`.
`decodeBase64(string)`	Decodifica una cadena codificada en Base64. Por ejemplo, `decodeBase64(value)` cuando `value` contiene `aGVsbG8sIHdvcmxk`, la función devuelve la cadena `hello, world`.

Argumentos

string: cadena que se va a 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 a mayúsculas o minúsculas.

Sintaxis

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

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 el 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 de 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

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

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

Estos son los resultados de las llamadas de función que usan estas variables:

Expresión de plantilla de mensaje	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`

Función Reemplazar todo

Aplica una expresión regular a una cadena y, en caso de que haya coincidencias, las sustituye por un valor de sustitución.

Sintaxis

replaceAll(string,regex,value)

Argumentos

string: una cadena literal (entre comillas simples) o una variable de flujo de cadena en la que se van a hacer las sustituciones.
regex expresión regular.
value: valor que se va a usar para sustituir todas las coincidencias de la expresión regular en la cadena.

Ejemplos

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

Nombre de 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 mensaje	Resultado
`{replaceAll(header,'9993','')}`	`Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-`
`{replaceAll(header,regex1,'')}`	`ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`
`{replaceAll(header,regex1,replacement)}`	`TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993`

Sustituir función First

Sustituye solo la primera aparición de la coincidencia de la 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 hacer sustituciones.
regex: una expresión regular.
value: el valor que se va a usar para sustituir las coincidencias de la expresión regular en la cadena.

Funciones de escape y codificación de caracteres

Funciones que escapan o codifican caracteres especiales en una cadena.

Sintaxis

Función	Descripción
`escapeJSON(string)`	Escapa las comillas dobles con una barra inversa.
`escapeXML(string)`	Sustituye los corchetes angulares, las comillas simples, las comillas dobles y las & por las entidades XML correspondientes. Se usa en documentos XML 1.0. Usa escapeXML para documentos XML 1.0 y escapeXML11 para documentos XML 1.1.
`escapeXML11(string)`	Funciona igual que escapeXML, pero para entidades XML v1.1. Consulta las notas de uso que se incluyen más abajo.
`encodeHTML(string)`	Codifica apóstrofos, corchetes angulares y el signo et (&).

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 determinados caracteres de control, pero no puede representar el byte nulo ni los puntos de código subrogados de Unicode sin emparejar, ni siquiera después de aplicarles un carácter de escape. La función escapeXML11() elimina los caracteres que no se ajustan a los siguientes intervalos:

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

La función escapeXML11() usa caracteres de escape en los siguientes intervalos:

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

Ejemplos

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

{escapeHTML(food)}

Resultados:

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

Funciones de formato de hora

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

Sintaxis

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

Argumentos

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

Ejemplos

Supongamos que se han asignado los siguientes valores y que la zona horaria local es la del 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:

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 ofrecen una alternativa al uso de la política HMAC para calcular un HMAC. Estas funciones son útiles cuando se realiza un cálculo HMAC en cascada, como cuando la salida de un HMAC se usa como clave para un segundo HMAC.

Sintaxis

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

Argumentos

key: (obligatorio) especifica la clave secreta, codificada como una cadena, que se usa para calcular el HMAC.
valueToSign (obligatorio) especifica el mensaje que se va a firmar. Debe ser una cadena.
keyencoding: (opcional) La cadena de clave secreta se decodificará según la codificación especificada. Valores válidos: hex, base16, base64, utf-8. Predeterminado: utf-8
outputencoding: (opcional) especifica el algoritmo de codificación que se va a usar en la salida. Valores válidos: hex, base16 y base64. El sistema no distingue entre mayúsculas y minúsculas. Por ejemplo, hex y base16 son sinónimos. Predeterminado: base64

Ejemplos

En este ejemplo se usa 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>

En este ejemplo se muestra cómo generar un HMAC en cascada que se puede usar con el proceso de firma AWS Signature versión 4. En el ejemplo se usa la política AssignMessage para generar los cinco niveles de HMAC en cascada que se utilizan para calcular una firma de AWS Signature versión 4:

<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 ejemplo:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Función Random Long Generator

Devuelve un entero largo aleatorio.

Sintaxis

randomLong(args)

Argumentos

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

Ejemplo

{randomLong()}

El resultado es algo parecido a lo siguiente:

5211338197474042880

Generador de texto de expresiones regulares

Genera una cadena 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 cadena de siete dígitos sin ceros:

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

Resultado de ejemplo:

Función de fusión nula

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

Sintaxis

firstnonnull(var1,var_n)

Argumento

var1: una variable de contexto.

var_n: una o varias variables de contexto. Puede asignar una cadena al argumento situado más a la derecha para proporcionar un valor alternativo (un valor que se asignará si no se ha asignado ninguno de los argumentos de la izquierda).

Ejemplos

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

Template	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 cadena que contenga XML.

datatype: (Opcional) Especifica el tipo de valor 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"

La función xpath() se usa en una política AssignMessage, como se indica a continuación:

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

Ejemplo 2: espacios de nombres XML

Para especificar un espacio de nombres, añade parámetros adicionales. Cada uno de ellos es una cadena con el siguiente formato: prefix:namespaceuri. Por ejemplo, una función xpath() que selecciona el elemento secundario de un cuerpo SOAP podría ser así:

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

Si quieres añadir más espacios de nombres, puedes incluir hasta 10 parámetros adicionales en la función xpath().

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

{xpath(xpathexpression,xml,ns1)}

Ejemplo 3: Especificar un tipo de retorno deseado

El tercer parámetro opcional que se transfiere a la función xpath() especifica el tipo de valor devuelto que se quiere obtener 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, invoca la función xpath() con un tercer parámetro que especifique el 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. Si no es así, se trata como el tipo de valor devuelto deseado. En este caso, si el tercer parámetro no es uno de los valores válidos (sin tener en cuenta las mayúsculas y minúsculas), la función xpath() devuelve un conjunto de nodos de forma predeterminada.

Función JSON Path

Evalúa una expresión JSON Path en una variable JSON.

Sintaxis

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

Argumentos

Obligatorio. json-path: (cadena) expresión de ruta JSON.
Obligatorio json-var: (cadena) una variable de flujo o una cadena que contenga JSON.
(Opcional) want-array: (Cadena) Si este parámetro se define como true y el conjunto de resultados es una matriz, se devuelven todos los elementos de la matriz. Si se asigna cualquier otro valor o se omite este parámetro, solo se devolverá el elemento cero de una matriz de resultados. Si el conjunto de resultados no es una matriz, se ignora este tercer parámetro, si está presente.

Puedes usar variables en cualquiera de los argumentos. Si usas cadenas fijas, inclúyelas entre comillas simples.

Ejemplo 1

Si esta es la plantilla de mensaje:

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

El valor devuelto de esta consulta jsonPath será una matriz que contenga un solo elemento. La función jsonPath de Apigee asume de forma predeterminada que quieres un solo valor para usarlo en la interpolación de cadenas. Por lo tanto, Apigee devuelve solo el elemento cero de la matriz. Para solicitar 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 de mensaje:

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

y the_json_variable contiene lo siguiente:

{
  "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"]

En este caso, el tercer parámetro de la función se ha definido como true, por lo que la función jsonPath devuelve la matriz completa, con la sintaxis de matriz JSON, en lugar del elemento cero.

Ejemplo 3

Si the_json_variable contiene lo siguiente:

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

y the_query contiene lo siguiente:

$.config.quota[?(@.operation=="ManageOrder")].appname

El resultado de la plantilla de mensaje: {jsonPath(the_query,the_json_variable,true)} es ["A","B"]

Si usas una variable para la consulta, podrás crear una consulta en tiempo de ejecución con datos dinámicos. Puedes hacerlo con el elemento <AssignVariable> de la política AssignMessage.

Por ejemplo, supongamos que la variable operationname contiene el valor ManageOrder. La siguiente política asignará a the_query la consulta que se muestra arriba.

<AssignMessage>
    <AssignVariable>
      <Name>the_query</Name>
      <Template>$.config.quota[?(@.operation=="{operationname}")].appname</Template>
    </AssignVariable>
  </AssignMessage>

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

¿Qué es una plantilla de mensaje?

Ejemplo

Ejemplo

Ejemplo

¿Dónde puedes usar plantillas de mensajes?

Políticas que aceptan plantillas de mensajes

<TargetEndpoint> elementos que aceptan plantillas de mensajes

Sintaxis de plantilla de mensaje

Usar llaves para denotar variables

No se permiten espacios en las expresiones de función

No se admiten las funciones anidadas

Incluir literales de cadena entre comillas simples en funciones de plantilla

Evita usar caracteres especiales en literales de cadena

Definir valores predeterminados en plantillas de mensajes

Plantillas de URL

Sintaxis antigua de las cargas útiles de JSON

Usar funciones de plantillas de mensajes

Ejemplo: toLowerCase()

Ejemplo: escapeJSON()

Funciones hash

Funciones hash hexadecimales

Sintaxis

Argumentos

Ejemplos

Funciones hash Base64

Sintaxis

Argumentos

Ejemplos

Funciones de cadena

Funciones de codificación Base64

Sintaxis

Argumentos

Ejemplo

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

Sintaxis

Argumentos

Ejemplo

Función de subcadena

Sintaxis

Argumentos

Ejemplos

Función Reemplazar todo

Sintaxis

Argumentos

Ejemplos

Sustituir función First

Sintaxis

Argumentos

Funciones de escape y codificación de caracteres

Sintaxis

Argumentos

Notas de uso

Ejemplos

Funciones de formato de hora

Sintaxis

Argumentos

Ejemplos

Funciones de cálculo de HMAC

Sintaxis

Argumentos

Ejemplos

Otras funciones

Crear función UUID

Sintaxis

Argumentos

Ejemplo

Función Random Long Generator

Sintaxis

Argumentos

Ejemplo

Generador de texto de expresiones regulares

Sintaxis

Argumento

Ejemplo

Función de fusión nula

Sintaxis

Argumento

Ejemplos

Función XPath

Plantillas de mensajes

`<TargetEndpoint>` elementos que aceptan plantillas de mensajes