Modelos de mensagens

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Este tópico mostra como usar modelos de mensagens nos proxies de API e fornece uma referência de função.

O que é um modelo de mensagens?

Um modelo de mensagem permite que você realize a substituição de strings variáveis em determinados elementos de política e TargetEndpoint. Com esse recurso, quando compatível, é possível preencher strings dinamicamente quando um proxy é executado.

É possível incluir qualquer combinação de referências de variáveis de fluxo e texto literal em um modelo de mensagem. Os nomes das variáveis de fluxo precisam ser colocados entre chaves, enquanto qualquer texto sem chaves é a saída como texto literal.

Consulte também Onde é possível usar os modelos de mensagens?.

Exemplo

Por exemplo, a política "Atribuir mensagem" permite que você use um modelo de mensagem no 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>

No exemplo acima, o valor da variável de fluxo user.name (em chaves) será avaliado e substituído na string de payload no ambiente de execução. Por exemplo, se user.name=jdoe, a saída de mensagem resultante no payload será: You entered an invalid username: jdoe. Se a variável não puder ser resolvida, uma string vazia será gerada.

Exemplo

Quando uma cota é excedida, é uma boa prática retornar uma mensagem significativa para o autor da chamada. Esse padrão é comumente usado com uma "regra de falha" para fornecer uma saída às informações do autor da chamada sobre a violação da cota. Na seguinte política "Atribuir mensagem", os modelos de mensagem são usados para preencher informações de cota dinamicamente em vários 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>

Na política AttributionMessage, os seguintes elementos no elemento <Set> são compatíveis com os modelos de mensagens:

  • Cabeçalho
  • QueryParam
  • FormParam
  • PayLoad
  • Versão
  • Verbo
  • Caminho
  • StatusCode
  • ReasonPhrase

Vale lembrar que as variáveis de fluxo em um modelo de mensagem precisam estar entre chaves.

Quando esta política é executada:

  • Os elementos Header recebem valores das variáveis de fluxo especificadas.
  • O payload inclui uma mistura de texto literal e variáveis (o client_id é preenchido dinamicamente).
  • StatusCode e Reasonphrase incluem apenas texto literal. No entanto, esses elementos também são compatíveis com modelos de mensagem, se você quiser usá-los.

Exemplo

Em uma definição de proxy TargetEndpoint, os elementos filhos de <SSLInfo> são compatíveis com os modelos de mensagens. Seguindo o mesmo padrão usado nas políticas, as variáveis de fluxo nas chaves são substituídas quando o proxy é executado.

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

Onde é possível usar modelos de mensagens?

Os modelos de mensagens são compatíveis com diversas políticas, bem como com determinados elementos usados na configuração TargetEndpoint.

Políticas que aceitam modelos de mensagens

Política Elementos e elementos filhos compatíveis com modelos de mensagem
Política AccessControl <SourceAddress>, para o atributo mask e o endereço IP.
Política AssignMessage Elementos filhos de <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonExpression, Headers, QueryParams, FormParams

Elementos filhos do <Add>: Headers, QueryParams, FormParams

Elemento filho <AssignVariable>: <Template>

Política ExtensionCallout <Input>
Política ExtractVariables <JsonPath>
Política GenerateJWS
Política VerifyJWS
<Payload> (somente política GenerateJWS)

<AdditionalHeaders><Claim>

* Esses elementos são compatíveis com modelos de mensagem somente quando type=map.

GenerateJWT política
Verificar política JWT
<AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* Esses elementos são compatíveis com modelos de mensagem somente quando type=map.

Política LDAP <SearchQuery>
Política MessageLogging <Syslog><Message>

<File><Message>

Política OASValidation Elemento <OASResource>
Política RaiseFault Elementos <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, Reasonphrase, Headers, QueryParams, FormParams

Elementos <Add>: Headers, QueryParams, FormParams

Política SAMLAssertion <Template>

* Somente quando a assinatura da política for <GenerateSAMLAssertion>

Política ServiceCallout Elementos <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonExpression, /Headers, QueryParams, FormParams

Elementos <Add>: Headers, QueryParams, FormParams

<HTTPTargetConnection>/<URL>: a primeira parte da string precisa ser http ou https.

Elementos TargetEndpoint que aceitam modelos de mensagem

Elementos HTTPTargetConnection Elementos filhos compatíveis com modelos de mensagem
SSLInfo Ativado, Alias de chave, keystore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection ApiProxy e ProxyEndpoint
Caminho N/A

Sintaxe do modelo de mensagens

Esta seção explica as regras que você precisa seguir para usar modelos de mensagens.

Use chaves para denotar variáveis

Coloque nomes de variáveis entre chaves { }. Se a variável não existir, uma string vazia será retornada na saída. No entanto, é possível especificar valores padrão em modelos de mensagens (valores que são substituídos se a variável não for resolvida). Consulte Como configurar valores padrão em modelos de mensagens.

É permitido colocar toda a string do modelo de mensagem entre aspas, mas é opcional. Por exemplo, os dois modelos de mensagens a seguir são equivalentes:

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

Como definir valores padrão em modelos de mensagens

Se uma variável de modelo não puder ser resolvida, o Edge vai substituir uma string vazia. No entanto, é possível especificar um valor padrão da seguinte maneira:

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

No exemplo acima, se a variável request.header.id não puder ser resolvida, seu valor será substituído por Unknown. Exemplo:

Test message. id = Unknown

Espaços não são permitidos em expressões de funções

Os espaços não são permitidos em nenhum lugar nas expressões de funções de modelos de mensagem. Exemplo:

Permitido:

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

Não permitido:

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

Sintaxe legada para payloads JSON

Nas versões do Edge anteriores à versão 16.08.17 do Cloud, não é possível usar chaves para denotar referências de variáveis nos payloads do JSON. Nessas versões mais antigas, você precisava usar os atributos variablePrefix e variableSuffix para especificar caracteres delimitadores e usá-los para agrupar nomes de variáveis, como:

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

Embora a Apigee recomende a sintaxe mais recente, a mais antiga ainda funciona.

Como usar funções de modelo de mensagens

O Edge oferece um conjunto de funções que podem ser usadas em modelos de mensagens para escapar, codificar, gerar hash e formatar variáveis de string.

As funções de modelo de mensagem são descritas em detalhes em Referência de função de modelo de mensagem.

Exemplo: toLowerCase()

Use a função toLowerCase() integrada para transformar uma variável de string em letras 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>

Se a variável de fluxo foo.bar for resolvida, os caracteres terão letras minúsculas. Se foo.bar não for resolvido, o valor padrão FOO será substituído e convertido em caracteres minúsculos. Exemplo:

Test header: foo

Exemplo: escapeJSON()

Veja um caso de uso interessante: digamos que seu app de back-end retorne uma resposta JSON que contenha caracteres de escape válidos. Exemplo:

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

Digamos que você queira retornar essa mensagem ao autor da chamada em um payload personalizado. A maneira comum de fazer isso é extrair a mensagem do payload da resposta de destino e usar a opção Atribuir mensagem a uma resposta de proxy personalizada (ou seja, enviá-la de volta ao cliente).

Confira a política "Extrair variáveis" que extrai as informações do user_message para uma variável com o nome standard.systemMessage:

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

Confira uma política "Atribuir mensagem" perfeitamente válida que adiciona a variável extraída ao payload da resposta (a resposta do 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>


Ocorreu um problema. A política "Variáveis de extração" removeu os caracteres de escape antes da parte da mensagem. Isso significa que a resposta retornada ao cliente é JSON inválido. Não era a nossa intenção.

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

Para contornar esse problema, modifique a política "Atribuir mensagem" para usar uma função de modelo de mensagens que faça o escape das aspas no JSON. Essa função, escapeJSON(), faz o escape de todas as aspas ou outros caracteres especiais que ocorrem em uma expressão 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>


A função escapa das aspas incorporadas, resultando em um JSON válido, que é exatamente o que você queria:

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

Um modelo de mensagens é um recurso de substituição de string dinâmica que pode ser usado em determinadas políticas e em definições de TargetEndpoint. As funções do modelo de mensagens permitem executar operações úteis, como hash, manipulação de string, escape de caracteres e outros em um modelo de mensagem.

Por exemplo, na seguinte política AssignMessage, a função toLowerCase() é usada em um modelo de mensagem:

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

Neste tópico, descrevemos as funções do modelo de mensagem, os argumentos e as saídas. Neste tópico, você precisa estar familiarizado com os modelos de mensagens e os contextos em que são usados.

Funções de hash

Calcular um valor de hash e retornar a representação de string desse hash.

Funções de hash hexadecimal

Calcule um valor de hash e retorne a representação em string desse hash como um número hexadecimal.

Sintaxe

Function Descrição
md5Hex(string) Calcula um hash MD5 expresso como um número hexadecimal.
sha1Hex(string) Calcula um hash SHA1 expresso como um número hexadecimal.
sha256Hex(string) Calcula um hash SHA256 expresso como um número hexadecimal.
sha384Hex(string) Calcula um hash SHA384 expresso como um número hexadecimal.
sha512Hex(string) Calcula um hash SHA512 expresso como um número hexadecimal.

Argumentos

string: as funções de hash usam um único argumento de string em que o algoritmo de hash é calculado. O argumento pode ser uma string literal ou uma variável de fluxo de strings.

Exemplos

Chamada de função

sha256Hex('abc')

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Chamada de função

var str = 'abc';
sha256Hex(str)

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funções de hash base64

Calcular um valor de hash e retornar a representação da string dessa hash como um valor codificado em Base64.

Sintaxe

Function Descrição
md5Base64(string) Calcula um hash MD5 expresso como um valor codificado em Base64.
sha1Base64(string) Calcula um hash SHA1 expresso como um valor codificado em Base64.
sha256Base64(string) Calcula um hash SHA256 expresso como um valor codificado em Base64.
sha384Base64(string) Calcula um hash SHA384 expresso como um valuer codificado em Base64.
sha512Base64(string) Calcula um hash SHA512 expresso como um valor codificado em Base64.

Argumentos

string: as funções de hash usam um único argumento de string em que o algoritmo de hash é calculado. O argumento pode ser uma string literal ou uma variável de fluxo de string.

Exemplos

Chamada de função

sha256Base64('abc')

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Chamada de função

var str = 'abc';
sha256Base64(str)

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funções de string

Executa operações em strings dentro de um modelo de mensagem.

Funções de codificação Base64

Codifique e decodifique strings usando o esquema de codificação Base64.

Sintaxe

Function Descrição
encodeBase64(string) Codifica uma string usando a codificação Base64. Por exemplo: encodeBase64(value), quando value contém abc, a função retorna a string: YWJj
decodeBase64(string) Decodifica uma string codificada em Base64. Por exemplo: decodeBase64(value), quando value contém aGVsbG8sIHdvcmxk, a função retorna a string: hello, world.

Argumentos

string: a string a ser codificada ou decodificada. Pode ser uma string literal ou uma variável de fluxo de string.

Exemplo

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

Funções de conversão de caso

Converta uma string em letras maiúsculas ou minúsculas.

Sintaxe

Function Descrição
toUpperCase(string) Converte uma string em letras maiúsculas.
toLowerCase(string) Converte uma string em letras minúsculas.


Argumentos

string: a string a ser convertida. Pode ser uma string literal ou uma variável de fluxo de string.

Exemplo

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

Função substring

Retorna os caracteres entre o índice inicial e final da string especificada.

Sintaxe

substring(str,start_index,end_index)

Argumentos

  • str: uma string literal ou variável de fluxo de string.
  • start_index: o índice inicial da string.
  • end_index (opcional) o índice final na string. Se não for fornecido, o índice final será o final da string.

Exemplos

Para os exemplos a seguir, suponha que essas variáveis de fluxo existam:

Nome da variável Valor
alpha ABCDEFGHIJKLMNOPQRSTUVWXYZ
seven 7


Confira os resultados de chamadas de função que usam essas variáveis:

Expressão de modelo de mensagem Result
{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

Substituir todas as funções

Aplica uma expressão regular a uma string e, para qualquer correspondência, substitui a correspondência por um valor de substituição.

Sintaxe

replaceAll(string,regex,value)

Argumentos

  • string: uma string literal ou variável de fluxo de string em que as substituições precisam ser feitas.
  • regex: uma expressão regular.
  • value: o valor para substituir todas as correspondências de regex dentro da string.

Exemplos

Para os exemplos a seguir, suponha que estas variáveis de fluxo existam:

Nome da variável Valor
header Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1 "^Bearer "
replacement "TOKEN: "

Confira os resultados de chamadas de função que usam essas variáveis:

Expressão de modelo de mensagem Result
{replaceAll(header,"9993",'')} Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')} ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)} TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

Substituir primeira função

Substitui apenas a primeira ocorrência da correspondência de expressão regular especificada na string.

Sintaxe

replaceFirst(string,regex,value)

Argumentos

  • string: uma string literal ou variável de fluxo de string em que as substituições precisam ser feitas.
  • regex: uma expressão regular.
  • value: o valor para substituir as correspondências de regex dentro da string.

Funções de codificação e de escape de caracteres

Funções que codificam ou escaparam caracteres especiais em uma string.

Sintaxe

Function Descrição
escapeJSON(string) Barra invertida com escape de aspas duplas.
escapeXML(string) Substitui colchetes angulares, apóstrofo, aspas duplas e "e" comercial pelas respectivas entidades XML. Use para documentos XML 1.0.

escapeXML11(string) Funciona da mesma forma que o escapeXML, mas para entidades XML v1.1. Consulte as "Observações sobre o uso" abaixo.
encodeHTML(string) Codifica o apóstrofo, os sinais de "menor que" e o "e" comercial.

Argumentos

string: a string em que o escape será realizado. Pode ser uma string literal ou uma variável de fluxo de string.

Observações sobre uso

O XML 1.1 pode representar certos caracteres de controle, mas não pode representar o byte nulo ou os codepoints alternativos Unicode despareados, mesmo após o escape. A função escapeXML11() remove caracteres que não se encaixam nos seguintes intervalos:

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

A função escapeXML11() escapa caracteres nos seguintes intervalos:

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

Exemplos

Suponha que exista uma variável de fluxo chamada food com este valor: "bread" & "butter". Em seguida, a função:

{escapeHTML(food)}

resulta em:

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

Funções de formato de hora

Retorna uma representação em string do horário, formatado no fuso horário local ou em UTC.

Sintaxe

Function Descrição
timeFormat(format,str) Retorna a data formatada no fuso horário local.
timeFormatMs(format,str) Retorna a data formatada no fuso horário local.
timeFormatUTC(format,str) Retorna a data formatada em UTC.
timeFormatUTCMs(format,str) Retorna a data formatada em UTC.

Argumentos

  • format: uma string de formato de data/hora. Pode ser uma string literal ou uma variável de string.
  • str uma string ou variável de fluxo de string contendo um valor de tempo. O valor pode ser em seconds-since-epoch ou milliseconds-since-epoch para timeFormatMs.

Exemplos

Considere os seguintes valores e suponha que o fuso horário local seja o Pacífico:

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

As funções retornam os seguintes resultados:

    Função Saída
    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

    Funções de cálculo de HMAC

    As funções de cálculo de HMAC oferecem uma alternativa ao uso da política HMAC para calcular um HMAC. As funções são úteis ao executar um cálculo HMAC em cascata, como quando a saída de um HMAC é usada como a chave para um segundo HMAC.

    Sintaxe

    Function Descrição
    hmacSha224(key,valueToSign[,keyencoding[,outputencoding]]) Calcula um HMAC com a função de hash SHA-224.
    hmacSha256(key,valueToSign[,keyencoding[,outputencoding]]) Codifica um HMAC com a função de hash SHA-256.
    hmacSha384(key,valueToSign[,keyencoding[,outputencoding]]) Codifica um HMAC com a função de hash SHA-384.
    hmacSha512(key,valueToSign[,keyencoding[,outputencoding]]) Codifica um HMAC com a função de hash SHA-512.
    hmacMd5(key,valueToSign[,keyencoding[,outputencoding]]) Codifica um HMAC com a função de hash MD5.
    hmacSha1(key, valueToSign [,keyencoding[,outputencoding]]) Codifica um HMAC com o algoritmo de criptografia SHA-1.

    Argumentos

    • key: (obrigatório) especifica a chave secreta, codificada como uma string, usada para calcular o HMAC.
    • valueToSign: (obrigatório) especifica a mensagem a ser assinada. Precisa ser uma string.
    • keyencoding: (opcional) a string da chave secreta será decodificada de acordo com essa codificação especificada. Valores válidos: hex, base16, base64 e utf-8 Padrão: utf-8
    • outputencoding: (opcional) especifica o algoritmo de codificação a ser usado para a saída. Valores válidos: hex, base16, base64. Os valores não diferenciam maiúsculas de minúsculas. Portanto, hex e base16 são sinônimos. Padrão: base64

    Exemplos

    Este exemplo usa a política AssignMessage para calcular um HMAC-256 e atribuí-lo a uma variável de fluxo:

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

    Este exemplo ilustra como gerar um HMAC em cascata que pode ser usado com o processo de assinatura AWS Signing v4. O exemplo usa a política AssignMessage para gerar os cinco níveis de HMAC em cascata usados para calcular uma assinatura para a assinatura da AWS 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>
    

    Outras funções

    Criar função UUID

    Gerar e retornar um UUID.

    Sintaxe

    createUuid()
    

    Argumentos

    Nenhum.

    Exemplo

    {createUuid()}

    Resultado de amostra:

    ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8
    

    Função Gerador de longo aleatório

    Retorna um número inteiro longo aleatório.

    Sintaxe

    randomLong(args)
    

    Argumentos

    • Se nenhum argumento for especificado, a função retornará um número inteiro longo aleatório, conforme calculado pela classe SecureRandom do Java.
    • Se houver um argumento, ele será tratado como o valor mínimo do cálculo.
    • Se um segundo argumento estiver presente, ele será tratado como o valor máximo do cálculo.

    Exemplo

    {random()}
    

    resulta em algo assim:

    5211338197474042880
    

    Gerador de texto regex

    Gera uma string de texto que corresponde a uma determinada expressão regular.

    Sintaxe

    xeger(regex)
    

    Argumento

    regex: uma expressão regular.

    Exemplo

    Este exemplo gera uma string de sete dígitos sem zeros:

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

    Exemplo de resultado:

    9857253
    

    Função de união nula

    A função firstnonnull() retorna o valor do argumento mais à esquerda e não nulo.

    Sintaxe

    firstnonnull(var1,varn)
    

    Argumento

    var1: uma variável de contexto.

    var n uma ou mais variáveis de contexto. É possível definir o argumento mais à direita como uma string para fornecer um valor substituto, que será definido se nenhum dos argumentos à esquerda estiver definido.

    Exemplos

    A tabela a seguir ilustra como usar a função:

    Template Var1 Var2 Var3 Result
    {firstnonnull(var1,var2)} Não definido foo N/A foo
    {firstnonnull(var1,var2)} foo bar N/A foo
    {firstnonnull(var1,var2)} foo Não definido N/A foo
    {firstnonnull(var1,var2,var3)} foo bar baz foo
    {firstnonnull(var1,var2,var3)} Não definido bar baz bar
    {firstnonnull(var1,var2,var3)} Não definido Não definido baz baz
    {firstnonnull(var1,var2,var3)} Não definido Não definido Não definido null
    {firstnonnull(var1)} Não definido 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

    Função XPath

    Aplica uma expressão XPath a uma variável XML.

    Sintaxe

    xpath(xpath_expression,xml_string,[datatype])
    

    Argumentos

    xpath_expression: uma expressão XPath.

    xml_string: uma string ou variável de fluxo que contém XML.

    datatype: (opcional) especifica o tipo de retorno desejado para a consulta. Ele pode ser conjunto de nós, nó, número, booleano, string. O padrão é conjunto de nós. O padrão é a escolha certa.

    Exemplo 1

    Suponha que essas variáveis de contexto definam uma string XML e uma expressão XPath:

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

    E a função xpath() é usada em uma política AttributionMessage, da seguinte maneira:

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

    A função retorna o valor <tagid>250397</tagid>. Esse valor é colocado na variável de contexto denominada extracted_tag.

    Exemplo 2

    Se você quiser apenas o valor do nó, use a função text() da seguinte maneira:

    <AssignMessage>
      <AssignVariable>
        <Name>extracted_tag</Name>
        <Template>{xpath('/tag/tagid/text()',xml)}</Template>
      </AssignVariable>
    </AssignMessage>

    Como resultado dessa operação, a variável de contexto extracted_tag é definida como 250397.

    Se vários nós forem selecionados, o resultado de xpath() será todos os valores da seleção, concatenados com uma vírgula.

    Exemplo 3: namespaces XML

    Para especificar um namespace, anexe mais parâmetros, cada um com uma string semelhante a prefix:namespaceuri. Por exemplo, uma função xpath() que seleciona o elemento filho de um corpo SOAP pode ser assim:

    <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 namespaces adicionais, é possível adicionar até 10 parâmetros extras à função xpath().

    É possível especificar uma expressão XPath simples como uma string entre aspas simples:

    {xpath('/tag/tagid/text()',xml)}

    Se a expressão XPath incluir prefixos de namespace (e dois pontos), você precisará atribuir essa expressão XPath a uma variável e especificar o nome da variável diretamente em vez da expressão.

    {xpath(xpathexpression,xml,ns1)}

    Exemplo 4: como especificar um tipo de retorno pretendido

    O terceiro parâmetro opcional transmitido para a função xpath() especifica o tipo de retorno pretendido da consulta.

    Algumas consultas XPath podem retornar valores numéricos ou booleanos. Por exemplo, a função count() retorna um número. Esta é uma consulta XPath válida:

    count(//Record/Fields/Pair)
    

    Esta consulta válida retorna um booleano:

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

    Nesses casos, invoque a função xpath() com um terceiro parâmetro especificando o tipo:

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

    Se o terceiro parâmetro contiver dois pontos, ele será interpretado como um argumento de namespace. Caso contrário, ele será tratado como o tipo de retorno pretendido. Nesse caso, se o terceiro parâmetro não for um dos valores válidos (ignorando maiúsculas e minúsculas), a função xpath() retornará um conjunto de nós por padrão.

    Função de caminho JSON

    Aplica uma expressão de caminho JSON a uma variável JSON.

    Sintaxe

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

    Argumentos

    • json-path (obrigatório): (string) uma expressão de caminho JSON.
    • json-var (obrigatório): (string) uma variável de fluxo ou string que contém JSON.
    • want-array (obrigatório): (string) se esse parâmetro for definido como 'true' e o conjunto de resultados for uma matriz, todos os elementos da matriz serão retornados. Se definido como qualquer outro valor ou se esse parâmetro for omitido, somente o elemento zero de uma matriz de conjunto de resultados será retornado. Se o conjunto de resultados não for uma matriz, esse terceiro parâmetro, se presente, será ignorado.

    Exemplo 1

    Se este for o modelo de mensagem:

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

    e the_json_variable contiver:

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

    O resultado da função é:

    The address is 1060 West Addison Street

    Nesse caso, o conjunto de resultados é um único elemento (não uma matriz de elementos). Se o conjunto de resultados fosse uma matriz, apenas o elemento zero da matriz seria retornado. Para retornar a matriz completa, chame a função com 'true' como o terceiro parâmetro, como mostra o exemplo a seguir.

    Exemplo 2

    Se este for o modelo de mensagem:

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

    e the_json_variable contiver:

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

    O resultado da função é:

    ['A','B']