Estás viendo la documentación de Apigee Edge.
Ve a la
Documentación de Apigee X. información
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. Cuando se admite, esta función te permite propagar cadenas de forma dinámica cuando se ejecuta un proxy.
En una plantilla de mensaje, puedes incluir cualquier combinación de referencias de variables de flujo y texto literal. Los nombres de las variables de flujo se deben colocar 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 de asignar mensaje 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) será
se evalúa y se sustituye en la cadena de carga útil en el entorno de ejecución. Por ejemplo, si user.name=jdoe
,
entonces, el resultado del mensaje 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. Esta
el patrón se usa comúnmente con una “regla de falla” para proporcionar un resultado y brindar información al emisor
sobre la infracción de la cuota. En la siguiente política de Asignar mensajes, se usan plantillas de mensajes
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> <ReasonPhrase>Quota Exceeded</ReasonPhrase> </Set> </AssignMessage>
En la políticaAssignMessage, los siguientes elementos en <Set>
Plantillas de mensajes de compatibilidad con elementos:
- Header
- QueryParam
- FormParam
- PayLoad
- Versión
- Verbo
- Ruta
- StatusCode
- ReasonPhrase
Una vez más, ten en cuenta que las variables de flujo en una plantilla de mensaje deben estar entre llaves.
Cuando se ejecuta esta política, sucede lo siguiente:
- Los elementos de encabezado reciben valores de las variables de flujo especificadas.
- La carga útil incluye una combinación de texto literal y variables (el
client_id
se propaga de forma dinámica). - Los estados StatusCode y ReasonPhrase solo incluyen texto literal; sin embargo, estos elementos también admiten plantillas de mensajes si deseas usarlos.
Ejemplo
En una definición de TargetEndpoint del proxy, los elementos secundarios de <SSLInfo>
admiten plantillas de mensajes. Siguiendo el mismo patrón utilizado en las políticas, las variables de flujo entre 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.
Políticas que aceptan plantillas de mensajes
Policy | Elementos y elementos secundarios que admiten plantillas de mensajes |
---|---|
Política AccessControl | <SourceAddress> para el atributo mask y la dirección IP |
Política AssignMessage | Elementos secundarios <Set> : carga útil, ContentType, verbo, versión, ruta de acceso, StatusCode, ReasonPhrase, Headers, QueryParams, FormParamsElementos secundarios
Elemento secundario |
Política ExtensionCallout |
<Input> |
Política ExtractVariables | <JsonPath> |
Política de GenerateJWS Política VerifyJWS |
<Payload> (solo política GenerateJWS)
* Estos elementos admiten la plantilla de mensajes solo cuando type=map. |
Política de GenerateJWT Política VerifyJWT |
<AdditionalClaims><Claim>
* Estos elementos admiten la plantilla de mensajes solo cuando type=map. |
Política de LDAP | <SearchQuery> |
Política MessageLogging | <Syslog><Message>
|
Política OASValidation | Elemento
|
Política RaiseFault | Elementos <Set> : carga útil, ContentType, verbo, versión, ruta de acceso, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Elementos |
Política SAMLAssertion | <Template>
* Solo cuando la firma de la política es |
Política ServiceCallout | Elementos <Set> : carga útil, ContentType, verbo, versión, ruta de acceso, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Elementos
|
Elementos de TargetEndpoint que aceptan plantillas de mensajes
Elementos de HTTPTargetConnection | Elementos secundarios que admiten plantillas de mensajes |
---|---|
SSLInfo | Enabled, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled y CLRStore |
LocalTargetConnection | ApiProxy y ProxyEndpoint |
Ruta | N/A |
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, aparecerá una se muestra una cadena vacía en el resultado; Sin embargo, puedes especificar valores predeterminados en los mensajes plantillas (valores que se sustituyen si la variable no está resuelta). Consulta Establecer valores predeterminados en plantillas de mensajes.
Tenga en cuenta que puedes incluir toda la string de plantilla de mensaje entre comillas, pero es opcional. Por ejemplo, las dos plantillas de mensajes siguientes son equivalentes:
<Set> <Headers> <Header name="x-h1">"Hello {user.name}"</Header> <Header name="x-h1">Hello {user.name}</Header> </Headers> </Set>
Establece valores predeterminados en las planillas de mensajes
Si una variable con plantilla no se puede resolver, Edge 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 no se puede resolver la variable request.header.id
, entonces su valor
se reemplaza por Unknown
. Por ejemplo:
Test message. id = Unknown
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 )}
Sintaxis heredada para cargas útiles JSON
En las versiones de Edge anteriores a la actualización 16.08.17 de Cloud, no
Usa llaves para denotar referencias variables dentro de 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
Edge proporciona un conjunto de funciones que se pueden usar en las plantillas de mensajes y dar formato a las variables de cadena.
Las funciones de la plantilla de mensajes se describen en detalle en la referencia de las funciones de las plantillas de mensajes.
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 Asignar mensaje para agregarlo a una respuesta de proxy personalizada (es decir, enviarla de vuelta al cliente).
Esta es la política Extraer variables 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>
Ahora, esta es una política de asignación de mensajes válida que agrega la variable extraída a la carga útil 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>
Se produjo un problema. La política Extraer variables quitó los caracteres de escape que rodean parte del mensaje. Esto significa que la respuesta que se muestra al cliente no es un JSON válido. Esto no es lo que pretendías.
{ "systemMessage": "Invalid value for "logonId" check your input." }
Para solucionar este problema, puedes modificar la política de Asignar mensajes para usar una función de plantilla de mensajes que escape las comillas dentro del archivo JSON. Esta función, escapeJSON()
, escapa de las comillas y 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 las comillas incorporadas, lo que da como resultado un JSON válido, que es exactamente lo que querías:
{ "systemMessage": "Invalid value for \"logonId\" check your input.", }
Un mensaje plantilla es una función de sustitución dinámica de cadenas que puedes usar en ciertas políticas y en las definiciones de TargetEndpoint. Las funciones de plantillas de mensajes te permiten realizar operaciones útiles como el hashing, la manipulación de cadenas, el escape de caracteres y otros elementos dentro de una plantilla de mensaje.
Por ejemplo, en la siguiente políticaAssignMessage, se usa la función toLowerCase()
en un
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 este tema, se describen las funciones de las plantillas de mensajes, sus argumentos y resultados. En este tema, se supone que que conozcas mensajes plantillas 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 hash toman un solo argumento de string en el que se calcula el algoritmo hash. El argumento puede ser un literal de string 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 hash toman un solo argumento de string en el que se calcula el algoritmo hash. El argumento puede ser un literal de string 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: String que se codifica o decodifica. Puede ser un literal de string 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 cadena en mayúsculas. |
toLowerCase(string)
|
Convierte una cadena en minúsculas. |
Argumentos
string: String que se va a convertir. Puede ser un literal de string 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 variable literal o una variable de flujo de string.
- start_index: es el índice de inicio de la string.
- end_index: (Opcional) El índice de fin en la string. 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: literal de string 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 o variable de flujo de string en la que se realizan los reemplazos.
- regex: una expresión regular.
- valor: valor que se usa para reemplazar coincidencias de regex dentro de 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(cadena) | Reemplaza los corchetes angulares, el apóstrofo, las comillas dobles y el signo de unión por las entidades XML respectivas. Úsalo para documentos XML 1.0.
. |
escapeXML11(cadena) | 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. |
codificaHTML(string) | Codifica apóstrofos, corchetes y ets. |
Argumentos
string: string que se va a escapar. Puede ser un literal de string 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 de Unicode no sincronizados, incluso después de escapar. La función escapeXML11() quita los caracteres que no caben 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)}
Resultados de:
"bread" & "butter"
Funciones de formato de tiempo
Muestra una representación de string de la hora, con formato en la zona horaria local o en UTC.
Sintaxis
Función | Descripción |
---|---|
timeFormat(format,str)
|
Muestra la fecha con el formato de la zona horaria local. |
timeFormatMs(format,str)
|
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 con formato de fecha y hora. Puede ser un literal de string o una variable de string.
- str: una variable de flujo de string o 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:
- 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
ybase64
. Los valores no distinguen mayúsculas de minúsculas,hex
ybase16
son sinónimos. Configuración predeterminada:base64
Función | Resultado |
---|---|
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
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 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
{random()}
da como resultado algo como esto:
5211338197474042880
Generador de textos de regex
Genera una string de texto que coincida con una expresión regular determinada.
Sintaxis
xeger(regex)
Argumento
regex: expresión regular.
Ejemplo
En este ejemplo, se genera una string de siete dígitos sin ceros:
xeger('[1-9]{7}')
Resultado de ejemplo:
9857253
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,varn)
Argumento
var1: Es una variable de contexto.
varn: 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: expresión XPath.
xml_string: es una string de flujo o una string que contiene XML.
datatype: (opcional) especifica el tipo de datos que se devuelve. Puede ser conjunto de nodos, nodo, número, booleano, cadena. 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
Si solo deseas obtener el valor del nodo, usa la función text()
, de la siguiente manera:
<AssignMessage> <AssignVariable> <Name>extracted_tag</Name> <Template>{xpath('/tag/tagid/text()',xml)}</Template> </AssignVariable> </AssignMessage>
Como resultado de esta operación, la variable de contexto extracted_tag
se configura como 250397
.
Si se seleccionan varios nodos, el resultado de xpath()
es todos los valores de la selección, concatenados con una coma.
Ejemplo 3: 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()
.
Puedes especificar una expresión de XPath simple como una string entre comillas simples:
{xpath('/tag/tagid/text()',xml)}
Si la expresión de XPath incluye prefijos de espacio de nombres (y dos puntos), entonces debes asignar esa expresión XPath a una variable y especificar el nombre de la variable directamente en lugar de la expresión.
{xpath(xpathexpression,xml,ns1)}
Ejemplo 4: 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']