Esta página foi traduzida pela API Cloud Translation.

Modelos de mensagens

Esta é a documentação do Apigee Edge.
Acesse 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 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 AssignMessage, os seguintes elementos no elemento <Set> são compatíveis com os modelos de mensagens:

Header
QueryParam
FormParam
PayLoad
Versão
Verbo
Caminho
StatusCode
ReasonPhrase

Novamente, as variáveis de fluxo em um modelo de mensagem precisam ser incluídas entre chaves.

Quando esta política é executada:

Os elementos de cabeçalho recebem os valores das variáveis de fluxo especificadas.
O payload inclui uma combinação de texto e variáveis literais (o client_id é preenchido dinamicamente).
O StatusCode e o ReasonPhrase incluem apenas texto literal. No entanto, esses elementos também são compatíveis com modelos de mensagens 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 várias políticas, bem como com determinados elementos usados na configuração TargetEndpoint.

Políticas que aceitam modelos de mensagens

Policy	Elementos e elementos filhos compatíveis com modelos de mensagens
Política AccessControl	`<SourceAddress>`, para o atributo `mask` e o endereço IP.
Política AssignMessage	Elementos filhos de `<Set>`: Payload, ContentType, Verb, Versão, Caminho, StatusCode, ReasonPhrase, Cabeçalhos, QueryParams, FormParams Elementos filhos `<Add>`: cabeçalhos, QueryParams e FormParams Elemento filho `<AssignVariable>`: `<Template>`
Política ExtensionCallout	`<Input>`
Política ExtractVariables	`<JsonPath>` O modelo de mensagem não é aceito para `<XMLPath>`.
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.
Política GenerateJWT Política VerifyJWT	`<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, Versão, Caminho, StatusCode, ReasonPhrase, Cabeçalhos, QueryParams, FormParams Elementos `<Add>`: Cabeçalhos, QueryParams, FormParams
Política SAMLAssertion	`<Template>` * Somente quando a assinatura da política for `<GenerateSAMLAssertion>`
Política ServiceCallout	Elementos `<Set>`: Payload, ContentType, Verb, Versão, Caminho, StatusCode, ReasonPhrase, Cabeçalhos, QueryParams, FormParams Elementos `<Add>`: Cabeçalhos, QueryParams, FormParams `<HTTPTargetConnection>/<URL>`: a primeira parte da string precisa ser http ou https.

Elementos TargetEndpoint que aceitam modelos de mensagem

Elementos HTTPTargetConnection	Elementos filho compatíveis com modelos de mensagens
SSLInfo	Ativado, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection	ApiProxy, ProxyEndpoint
Caminho	N/D

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 com 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 antes da versão 16.08.17 do Cloud, não era possível use chaves para denotar referências de variáveis em payloads 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 que você use a sintaxe mais recente de chaves, a sintaxe 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 variáveis de string de formatação.

As funções do modelo de mensagens são descritas em detalhes na Referência da função do modelo de mensagens.

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

Veja a política de extração de variáveis que extrai as informações user_message em uma variável chamada standard.systemMessage:

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

Agora, veja uma política de atribuição de mensagens 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. Esta 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 faz o escape das aspas incorporadas, resultando em JSON válido, que é exatamente o que você quer:

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

Não é possível aninhar chamadas de função. Por exemplo, não é possível fazer o seguinte:

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

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 da string desse hash como um número hexadecimal.

Sintaxe

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

Função	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 valor 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)

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funções de string

Execute operações em strings em um modelo de mensagens.

Funções de codificação Base64

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

Sintaxe

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

Converte uma string em todas as letras maiúsculas ou minúsculas.

Sintaxe

Função	Descrição
`toUpperCase(string)`	Converta uma string em maiúsculas.
`toLowerCase(string)`	Converta uma string em 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 uma variável de fluxo de string.
start_index: o índice inicial na 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, suponhamos que essas variáveis de fluxo existam:

Nome da variável	Valor
`alpha`	ABCDEFGHIJKLMNOPQRSTUVWXYZ
`seven`	7

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

Expressão do modelo de mensagens	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 são substituídas.
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, suponhamos que essas variáveis de fluxo existam:

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

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

Expressão do modelo de mensagens	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 da 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 são substituídas.
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 escapam ou codificam caracteres especiais em uma string.

Sintaxe

Função	Descrição
escapeJSON(string)	As barras invertidas têm escapes entre aspas.
escapeXML(string)	Substitui colchetes angulares, apóstrofo, aspas duplas e "e" comercial pelas respectivas entidades XML. Use para documentos XML 1.0. Use escapeXML para documentos XML1.0 e escapeXML11 para documentos XML 1.1.
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 apóstrofo, colchetes angulares e "e" comercial.

Argumentos

string: a string de escape. 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". Depois, a função:

{escapeHTML(food)}

Resulta em:

"bread" & "butter"

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

Função	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 valores a seguir e suponha que o fuso horário local é 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

Função	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 da 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 Java SecureRandom.
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:

Função de união nula

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

Sintaxe

firstnonnull(var1,var_n)

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:

Modelo	Var1	Var2	Var3	Result
`{firstnonnull(var1,var2)}`	Não definido	`foo`	N/D	`foo`
`{firstnonnull(var1,var2)}`	`foo`	`bar`	N/D	`foo`
`{firstnonnull(var1,var2)}`	`foo`	Não definido	N/D	`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/D	N/A	`null`
`{firstnonnull(var1)}`	`foo`	N/A	N/A	`foo`
`{firstnonnull(var1,var2)}`	`""`	`bar`	N/D	`""`
`{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 variável ou string 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 AssignMessage, 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 esse 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']