Esta página foi traduzida pela API Cloud Translation.

Modelos de mensagens

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Este tópico aborda como usar modelos de mensagens em proxies de API e fornece uma referência de funções.

O que é um modelo de mensagem?

Um modelo de mensagem permite-lhe fazer a substituição de strings variáveis em determinados elementos de políticas e <TargetEndpoint>. Esta funcionalidade, quando suportada, permite-lhe preencher strings dinamicamente quando um proxy é executado.

Pode incluir qualquer combinação de referências de variáveis de fluxo e texto literal num modelo de mensagem. Os nomes das variáveis de fluxo têm de estar entre chavetas, enquanto qualquer texto que não esteja entre chavetas é apresentado como texto literal.

Consulte também Onde pode usar modelos de mensagens?

Exemplo

Por exemplo, a política AssignMessage permite-lhe usar um modelo de mensagem no elemento <Payload>:

<AssignMessage name="AM-set-payload-with-dynamic-content">
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

No exemplo acima, o valor da variável de fluxo user.name (entre chavetas) será avaliado e substituído na string de payload no momento da execução. Por exemplo, se user.name=jdoe, a mensagem resultante no payload será: You entered an invalid username: jdoe. Se não for possível resolver a variável, é gerada uma string vazia.

Exemplo

Quando uma quota é excedida, é uma boa prática devolver uma mensagem significativa ao autor da chamada. Este padrão é usado frequentemente com uma "regra de falha" para fornecer resultados que dão ao autor da chamada informações sobre a violação de quota. Na política AssignMessage seguinte, os modelos de mensagens são usados para preencher dinamicamente informações de quotas 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>
  </Set>
</AssignMessage>

Na política AssignMessage, os seguintes elementos no elemento <Set> suportam a utilização de modelos de mensagens:

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

Mais uma vez, tenha em atenção que as variáveis de fluxo num modelo de mensagem têm de estar entre chavetas.

Quando esta política é executada:

Os elementos <Header> recebem valores das variáveis de fluxo especificadas.
O payload inclui uma combinação de texto literal e variáveis (o client_id é preenchido dinamicamente).
O elemento <StatusCode> inclui apenas texto literal. No entanto, este elemento também suporta modelos de mensagens se quiser usá-los.

Exemplo

Numa definição de proxy <TargetEndpoint>, os elementos subordinados de <SSLInfo> suportam a utilização de modelos de mensagens. Seguindo o mesmo padrão usado nas políticas, as variáveis de fluxo entre chavetas 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 pode usar modelos de mensagens?

Os modelos de mensagens são suportados em várias políticas, bem como em determinados elementos usados na configuração TargetEndpoint.

Nota: também pode consultar a documentação de políticas para saber que política e <TargetEndpoint> elementos suportam modelos de mensagens.

Políticas que aceitam modelos de mensagens

A tabela seguinte indica as políticas e os elementos/elementos secundários suportados:

Política	Elementos/elementos secundários
Política AccessControl	`<SourceAddress>`, para o atributo `mask` e o endereço IP.
Política AssignMessage	`<Set>` elementos secundários: Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams `<Add>` elementos secundários: Headers, QueryParams, FormParams Elemento secundário `<AssignVariable>`: `<Template>`
Política de CORS	`<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<ExposeHeaders>`
Política ExtractVariables	`<JsonPath>` Nota: o modelo de mensagem não é aceite para `<XMLPath>`.
Política GenerateJWS Política VerifyJWS	`<Payload>` (apenas GenerateJWS policy) `<AdditionalHeaders><Claim>` * Estes elementos suportam o modelo de mensagem apenas quando type=map.
Política GenerateJWT Política VerifyJWT	`<AdditionalClaims><Claim>` `<AdditionalHeaders><Claim>` * Estes elementos suportam o modelo de mensagem apenas quando type=map.
Política HTTPModifier	`<Set>` elementos secundários: `<ContentType>` `<Verb>` `<Version>` `<Path>` `<StatusCode>` `<Headers>` `<QueryParams>` `<FormParams>` `<Add>` elementos secundários: `<Headers>` `<QueryParams>` `<FormParams>`
Política de MessageLogging	`<CloudLogging><Message>` `<Syslog><Message>` `<File><Message>`
Política de validação da OAS	`<OASResource>` elemento
Política RaiseFault	`<Set>` elementos: `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` `<Add>` elementos: `<FormParams>` `<Headers>` `<QueryParams>`
Política de SAMLAssertion	`<Template>` * Apenas quando a assinatura da política é `<GenerateSAMLAssertion>`
Política de textos destacados de serviços	`<Set>` elementos: `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` `<Add>` elementos: `<FormParams>` `<Headers>` `<QueryParams>` `<HTTPTargetConnection>/<URL>`: Consulte Modelos de URLs.

`<TargetEndpoint>` elementos que aceitam modelos de mensagens

`<HTTPTargetConnection>` elementos	Elementos secundários que suportam modelos de mensagens
`<SSLInfo>`	`<Enabled>`, `<KeyAlias>`, `<KeyStore>`, `<TrustStore>`, `<ClientAuthEnabled>`, `<CLRStore>`
`<LocalTargetConnection>`	`<ApiProxy>`, `<ProxyEndpoint>`, `<Path>`
`<Path>`	N/A
`<URL>`	Sem elementos subordinados. Consulte a secção Modelos de URL para ver a utilização.

Sintaxe do modelo de mensagem

Esta secção explica as regras que tem de seguir para usar modelos de mensagens.

Use chavetas para denotar variáveis

Coloque os nomes das variáveis entre chavetas { }. Se a variável não existir, é devolvida uma string vazia na saída. No entanto, pode especificar valores predefinidos nos modelos de mensagens (valores que são substituídos se a variável não for resolvida). Consulte o artigo Definir valores predefinidos em modelos de mensagens.

Tenha em atenção que incluir toda a string do modelo de mensagem entre aspas é permitido, mas opcional. Por exemplo, os dois modelos de mensagens seguintes são equivalentes:

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

Não são permitidos espaços em expressões de funções

Não são permitidos espaços em nenhuma parte das expressões de funções de modelos de mensagens. Por exemplo:

Permitido:

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

Não permitido:

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

As funções aninhadas não são suportadas

A chamada de uma função dentro de outra função num modelo não é suportada. Por exemplo, não pode usar:

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

Inclua literais de strings em funções de modelos entre aspas simples

Quando fornecer literais de strings em funções, coloque-os entre aspas simples em vez de aspas duplas.

Por exemplo,

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

Evite usar carateres especiais em literais de strings

Evite carateres especiais, como ":", "/", "\", "<" ou ">", em literais de strings. Estes carateres podem causar erros. Se um literal de string exigir carateres especiais, atribua o valor a uma variável através de uma política de Python ou JavaScript e, em seguida, use a variável no modelo.

Definir valores predefinidos em modelos de mensagens

Se não for possível resolver uma variável baseada em modelos, o Apigee substitui-a por uma string vazia. No entanto, pode especificar um valor predefinido da seguinte forma:

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

No exemplo acima, se não for possível resolver a variável request.header.id, o respetivo valor é substituído por Unknown. Por exemplo:

Test message. id = Unknown

Modelos de URLs

O elemento URL suporta a utilização de modelos seguindo a mesma sintaxe que outros elementos.

Este exemplo mostra um URL criado com variáveis:

<URL>{targeturl}</URL>

Este exemplo mostra um valor predefinido para o protocolo:

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

Sintaxe antiga para payloads JSON

Nas versões do Apigee anteriores ao lançamento na nuvem 16.08.17, não podia usar chavetas para denotar referências de variáveis em payloads JSON. Nessas versões mais antigas, tinha de usar os atributos variablePrefix e variableSuffix para especificar carateres delimitadores e usá-los para incluir nomes de variáveis, da seguinte forma:

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

Embora a Apigee recomende que use a sintaxe de chavetas mais recente, a sintaxe mais antiga continua a funcionar.

Usar funções de modelos de mensagens

A Apigee fornece um conjunto de funções que pode usar em modelos de mensagens para aplicar escape, codificar, aplicar hash e formatar variáveis de string, conforme descrito abaixo.

Exemplo: toLowerCase()

Use a função integrada toLowerCase() para transformar uma variável de string em 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 respetivos carateres vão estar todos em minúsculas. Se foo.bar não for resolvido, o valor predefinido FOO é substituído e convertido em carateres em minúsculas. Por exemplo:

Test header: foo

Exemplo: escapeJSON()

Aqui está um exemplo de utilização interessante: suponhamos que a sua app de back-end devolve uma resposta JSON que contém carateres de escape válidos. Por exemplo:

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

Suponhamos que quer devolver esta mensagem ao autor da chamada cliente numa carga útil personalizada. A forma habitual de o fazer é extrair a mensagem do payload de resposta de destino e usar AssignMessage para a adicionar a uma resposta de proxy personalizada (ou seja, enviá-la de volta para o cliente).

Segue-se a política ExtractVariables que extrai as informações user_message para uma variável denominada standard.systemMessage:

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

Agora, segue-se uma política AssignMessage perfeitamente válida que adiciona a variável extraída ao payload de 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>response</AssignTo>
</AssignMessage>

Infelizmente, existe um problema. A política ExtractVariables removeu os carateres de aspas com escape em torno de parte da mensagem. Isto significa que a resposta devolvida ao cliente é JSON inválido. Isto não é claramente o que pretendia!

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

Para contornar este problema, pode modificar a política AssignMessage para usar uma função de modelo de mensagem que escape as aspas no JSON por si. Esta função, escapeJSON(), escapa a quaisquer aspas ou outros carateres especiais que ocorram numa 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>response</AssignTo>
</AssignMessage>

A função escapa às aspas incorporadas, o que resulta num JSON válido, que é exatamente o que pretendia:

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

Um modelo de mensagem é uma funcionalidade de substituição de strings dinâmicas que pode usar em determinadas políticas e em definições de <TargetEndpoint>. As funções de modelos de mensagens permitem-lhe realizar operações úteis, como hash, manipulação de strings, escape de carateres e outras, num modelo de mensagem.

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

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo>response</AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
   <Headers>
     <Header name="x-h1">Test header: Hello, {toLowerCase(user.name)}</Header>
   </Headers>
  </Set>
</AssignMessage>

Esta secção descreve as funções de modelos de mensagens, os respetivos argumentos e resultados. Este tópico pressupõe que conhece os modelos de mensagens e os contextos em que são usados.

Funções hash

Calcula um valor hash e devolve a representação de string desse hash.

Funções hash hexadecimais

Calcula um valor de hash e devolve a representação de 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 sobre o qual o algoritmo de hash é calculado. O argumento pode ser uma string literal (entre aspas simples) ou uma variável de fluxo de string.

Exemplos

Chamada de função:

sha256Hex('abc')

Resultado:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Chamada de função:

var str = 'abc';
sha256Hex(str)

Resultado:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funções hash Base64

Calcula um valor de hash e devolve a representação de string desse 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 selecionam um único argumento de string no qual o algoritmo hash é calculado. O argumento pode ser uma string literal (entre aspas simples) ou uma variável de fluxo de string.

Exemplos

Chamada de função:

sha256Base64('abc')

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Chamada de função:

var str = 'abc';
sha256Base64(str)

Resultado:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funções de string

Realize operações em strings num modelo de mensagem.

Funções de codificação Base64

Codifique e descodifique strings através do esquema de codificação Base64.

Sintaxe

Função	Descrição
`encodeBase64(string)`	Codifica uma string através da codificação Base64. Por exemplo: `encodeBase64(value)`, quando `value` contém `abc`, a função devolve a string: `YWJj`
`decodeBase64(string)`	Descodifica uma string codificada em Base64. Por exemplo: `decodeBase64(value)` quando `value` contém `aGVsbG8sIHdvcmxk`, a função devolve a string `hello, world`.

Argumentos

string: a string a codificar ou descodificar. Pode ser uma string literal (delimitada por aspas simples) 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 maiúsculas/minúsculas

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

Sintaxe

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

Argumentos

string: a string a converter. Pode ser uma string literal (delimitada por aspas simples) 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

Devolve os carateres entre o índice inicial e final da string especificada.

Sintaxe

substring(str,start_index,end_index)

Argumentos

str: uma string literal (entre aspas simples) 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 é o fim da string.

Exemplos

Para os exemplos seguintes, suponha que estas variáveis de fluxo existem:

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

Seguem-se os resultados das chamadas de funções que usam estas variáveis:

Expressão do modelo de mensagem	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`

Função Substituir tudo

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

Sintaxe

replaceAll(string,regex,value)

Argumentos

string: uma string literal (entre aspas simples) ou uma variável de fluxo de string na qual fazer substituições.
regex: uma expressão regular.
valor: o valor para substituir todas as correspondências de regex na string.

Exemplos

Para os exemplos seguintes, suponha que estas variáveis de fluxo existem:

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

Seguem-se os resultados das chamadas de funções que usam estas variáveis:

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

Função Replace First

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 (entre aspas simples) ou uma variável de fluxo de string na qual fazer substituições.
regex: uma expressão regular.
value: o valor para substituir as correspondências de regex na string.

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

Funções que escapam ou codificam carateres especiais numa string.

Sintaxe

Função	Descrição
`escapeJSON(string)`	Usa a barra invertida para escapar às aspas duplas.
`escapeXML(string)`	Substitui os sinais de maior e menor, o apóstrofo, as aspas duplas e os sinais de "e comercial" pelas respetivas entidades XML. Use para documentos XML 1.0. Use escapeXML para documentos XML 1.0 e escapeXML11 para documentos XML 1.1.
`escapeXML11(string)`	Funciona da mesma forma que escapeXML, mas para entidades XML v1.1. Consulte as notas de utilização abaixo.
`encodeHTML(string)`	Codifica o apóstrofe, os sinais de maior e menor, e o "E" comercial.

Argumentos

string: a string a escapar. Pode ser uma string literal (delimitada por aspas simples) ou uma variável de fluxo de string.

Notas de utilização

O XML 1.1 pode representar determinados carateres de controlo, mas não pode representar o byte nulo nem os pontos de código substitutos Unicode não emparelhados, mesmo após a fuga. A função escapeXML11() remove os carateres que não se enquadram nos seguintes intervalos:

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

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

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

Exemplos

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

{escapeHTML(food)}

Resultados em:

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

Funções de formato de hora

Devolve uma representação de string da hora, formatada em UTC.

Sintaxe

Função	Descrição
`timeFormat(format,str)`	Devolve a data formatada em UTC. `DEPRECATED`: devolve a data formatada no fuso horário local.
`timeFormatMs(format,str)`	Devolve a data formatada em UTC. `DEPRECATED`: devolve a data formatada no fuso horário local.
`timeFormatUTC(format,str)`	Devolve a data formatada em UTC.
`timeFormatUTCMs(format,str)`	Devolve a data formatada em UTC.

Argumentos

format: uma string de formato de data/hora. Pode ser uma string literal (delimitada por aspas simples) ou uma variável de string. Use uma variável em vez de um literal quando o formato incluir dois pontos. Consulte a nota anterior nesta secção.
str: uma string ou uma variável de fluxo de strings que contém um valor de tempo. O valor pode estar em segundos desde epoch ou milissegundos desde epoch para timeFormatMs.

Exemplos

Suponha os seguintes valores e que o fuso horário local é o do 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 devolvem os seguintes resultados:

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

Funções de cálculo de HMAC

As funções de cálculo de HMAC oferecem uma alternativa à utilização da política de HMAC para calcular um HMAC. As funções são úteis quando realiza 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 hash SHA-224.
`hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica um HMAC com a função hash SHA-256.
`hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica um HMAC com a função hash SHA-384.
`hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica um HMAC com a função hash SHA-512.
`hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica um HMAC com a função hash MD5.
`hmacSha1(key,valueToSign[,keyencoding[,outputencoding]])`	Codifica um HMAC com o algoritmo de encriptação 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 assinar. Deve ser uma string.
keyencoding: (opcional) a string da chave secreta é descodificada de acordo com esta codificação especificada. Valores válidos: hex, base16, base64, utf-8. Predefinição: utf-8
outputencoding: (opcional) especifica o algoritmo de codificação a usar para a saída. Valores válidos: hex, base16, base64. Os valores não são sensíveis a maiúsculas e minúsculas; hex e base16 são sinónimos. Predefiniçã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 da assinatura AWS 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 v4 da AWS:

<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

Função CREATE_UUID

Gera e devolve um UUID.

Sintaxe

createUuid()

Argumentos

Nenhum.

Exemplo

{createUuid()}

Resultado de exemplo:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Função de gerador longo aleatório

Devolve um número inteiro longo aleatório.

Sintaxe

randomLong(args)

Argumentos

Se não forem especificados argumentos, a função devolve um número inteiro longo aleatório, calculado pela classe Java SecureRandom.
Se estiver presente um argumento, é tratado como o valor mínimo do cálculo.
Se estiver presente um segundo argumento, é tratado como o valor máximo do cálculo.

Exemplo

{randomLong()}

Resulta em algo semelhante ao seguinte:

5211338197474042880

Gerador de texto de regex

Gere uma sequência de texto que corresponda 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 coalescência nula

A função firstnonnull() devolve o valor do argumento mais à esquerda que não seja nulo.

Sintaxe

firstnonnull(var1,var_n)

Argumento

var1: uma variável de contexto.

var_n: uma ou mais variáveis de contexto. Pode definir o argumento mais à direita como uma string para fornecer um valor alternativo (um valor que é definido se nenhum dos argumentos à esquerda estiver definido).

Exemplos

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

Modelo	Var1	Var2	Var3	Resultado
`{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 variável de fluxo ou uma string que contém XML.

datatype: (Opcional) Especifica o tipo de retorno pretendido da consulta. Os valores válidos são nodeset, node, number, boolean ou string. O valor predefinido é nodeset. Normalmente, a predefinição é a escolha certa.

Exemplo 1

Suponhamos que estas variáveis de contexto definem 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"

A função xpath() é usada numa política AssignMessage, da seguinte forma:

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

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

Exemplo 2: espaços de nomes XML

Para especificar um espaço de nomes, acrescente parâmetros adicionais, cada um deles uma string semelhante a prefix:namespaceuri. Por exemplo, uma função xpath() que seleciona o elemento secundário de um corpo SOAP pode ser semelhante a esta:

<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 espaços de nomes adicionais, pode adicionar até 10 parâmetros à função xpath().

Em vez de especificar expressões XPath com carateres especiais como um literal de string, use uma variável para incluir essa string na função. Consulte o artigo Evite usar carateres especiais em literais de strings para ver detalhes.

{xpath(xpathexpression,xml,ns1)}

Exemplo 3: especificar um tipo de devolução pretendido

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

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

count(//Record/Fields/Pair)

Esta consulta válida devolve um valor booleano:

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

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

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

Se o terceiro parâmetro contiver dois pontos, é interpretado como um argumento de espaço de nomes. Caso contrário, é tratado como o tipo de retorno desejado. Neste caso, se o terceiro parâmetro não for um dos valores válidos (ignorando a capitalização), a função xpath() devolve por predefinição um conjunto de nós.

Função JSON Path

Avalia uma expressão JSON Path em relação a uma variável JSON.

Sintaxe

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

Argumentos

(Obrigatório) json-path: (String) Uma expressão JSON Path.
(Obrigatório) json-var: (string) Uma variável de fluxo ou uma string que contém JSON.
(Opcional) want-array: (string) se este parâmetro estiver definido como true e se o conjunto de resultados for uma matriz, são devolvidos todos os elementos da matriz. Se for definido para qualquer outro valor ou se este parâmetro for omitido, é devolvido apenas o elemento zero de uma matriz de conjunto de resultados. Se o conjunto de resultados não for uma matriz, então este terceiro parâmetro, se estiver presente, é ignorado.

Pode usar variáveis para qualquer um dos argumentos. Se usar strings fixas, coloque-as entre aspas simples.

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 contém:

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

O valor de retorno desta consulta jsonPath é uma matriz que contém um único elemento. Por predefinição, a função jsonPath no Apigee assume que quer um único valor para utilização na interpolação de strings. Por conseguinte, o Apigee devolve apenas o elemento zero da matriz. Para pedir a matriz completa, chame a função com true como o terceiro parâmetro, conforme mostrado no exemplo seguinte.

Exemplo 2

Se este for o modelo de mensagem:

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

e the_json_variable contém:

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

Neste caso, o terceiro parâmetro da função está definido como true. Por conseguinte, a função jsonPath devolve a matriz completa, na sintaxe de matriz JSON, em vez do elemento zero.

Exemplo 3

Se the_json_variable contiver:

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

e the_query contém:

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

O resultado do modelo de mensagem: {jsonPath(the_query,the_json_variable,true)} é ["A","B"]

A utilização de uma variável para a consulta permite-lhe criar uma consulta no tempo de execução, usando dados dinâmicos. Pode fazê-lo com o elemento <AssignVariable> na política AssignMessage.

Por exemplo, supondo que a variável operationname contém o valor ManageOrder, a seguinte política define the_query para a consulta mostrada acima.

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

Modelos de mensagens Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O que é um modelo de mensagem?

Exemplo

Exemplo

Exemplo

Onde pode usar modelos de mensagens?

Políticas que aceitam modelos de mensagens

<TargetEndpoint> elementos que aceitam modelos de mensagens

Sintaxe do modelo de mensagem

Use chavetas para denotar variáveis

Não são permitidos espaços em expressões de funções

As funções aninhadas não são suportadas

Inclua literais de strings em funções de modelos entre aspas simples

Evite usar carateres especiais em literais de strings

Definir valores predefinidos em modelos de mensagens

Modelos de URLs

Sintaxe antiga para payloads JSON

Usar funções de modelos de mensagens

Exemplo: toLowerCase()

Exemplo: escapeJSON()

Funções hash

Funções hash hexadecimais

Sintaxe

Argumentos

Exemplos

Funções hash Base64

Sintaxe

Argumentos

Exemplos

Funções de string

Funções de codificação Base64

Sintaxe

Argumentos

Exemplo

Funções de conversão de maiúsculas/minúsculas

Sintaxe

Argumentos

Exemplo

Função substring

Sintaxe

Argumentos

Exemplos

Função Substituir tudo

Sintaxe

Argumentos

Exemplos

Função Replace First

Sintaxe

Argumentos

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

Sintaxe

Argumentos

Notas de utilização

Exemplos

Funções de formato de hora

Sintaxe

Argumentos

Exemplos

Funções de cálculo de HMAC

Sintaxe

Argumentos

Exemplos

Outras funções

Função CREATE_UUID

Sintaxe

Argumentos

Exemplo

Função de gerador longo aleatório

Sintaxe

Argumentos

Exemplo

Gerador de texto de regex

Sintaxe

Argumento

Exemplo

Função de coalescência nula

Sintaxe

Argumento

Exemplos

Função XPath

Modelos de mensagens

`<TargetEndpoint>` elementos que aceitam modelos de mensagens