Modelos de mensagens

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

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 <TargetEndpoint> e políticas. Com esse recurso, quando compatível, é possível preencher strings dinamicamente quando um proxy for 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 é processado como texto literal.

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

Exemplo

Por exemplo, a política AssignMessage 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 (entre chaves) é 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", que fornece uma saída ao autor da chamada com informações sobre a violação da cota. Na política AssignMessage a seguir, 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>
  </Set>
</AssignMessage>

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

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

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

Quando esta política é executada:

• os elementos <Header> recebem os 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 <StatusCode> inclui apenas texto literal. No entanto, esse elemento também é compatível com os modelos de mensagem, se você quiser usá-lo.

Exemplo

Em uma definição de proxy <TargetEndpoint>, os elementos filhos de <SSLInfo> são compatíveis com modelos de mensagens. Seguindo o mesmo padrão usado nas políticas, as variáveis de fluxo entre 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 de TargetEndpoint.

Políticas que aceitam modelos de mensagens

A tabela a seguir lista as políticas e quais elementos/elementos filhos são compatíveis:

Elementos <TargetEndpoint> que aceitam modelos de mensagem

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>

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. 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 compatíveis

Não é possível chamar uma função dentro de outra função em um modelo. Por exemplo, não é possível usar:

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

Coloque literais de string em funções de modelo entre aspas simples

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

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

Evite usar caracteres especiais em literais de string

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

Como definir valores padrão em modelos de mensagem

Se uma variável de modelo não puder ser resolvida, a Apigee 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, o valor dela será substituído por Unknown. Por exemplo:

Test message. id = Unknown

Modelos de URL

O elemento URL é compatível com modelos que seguem a mesma sintaxe de outros elementos.

Este exemplo mostra um URL criado usando variáveis:

<URL>{targeturl}</URL>

Este exemplo mostra um valor padrão para o protocolo:

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

Sintaxe legada para payloads JSON

Nas versões da Apigee antes da versão 16.08.17, não era possível usar chaves para denotar referências de variável nos 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 continua funcionando.

Como usar funções de modelo de mensagens

A Apigee fornece um conjunto de funções que podem ser usadas nos modelos de mensagem para escapar, codificar, gerar hash e formatar variáveis de string, conforme descrito abaixo.

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. Por exemplo:

Test header: foo

Exemplo: escapeJSON()

Veja um caso de uso interessante: digamos que um app de back-end retorne uma resposta JSON que contenha caracteres de escape válidos. Por 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 AssignMessage para adicioná-la a uma resposta de proxy personalizada (ou seja, enviá-la de volta ao cliente).

Esta é a política ExtractVariables 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 AssignMessage 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 ExtractVariables removeu os caracteres de escape entre aspas de parte da mensagem. Isso significa que a resposta retornada ao cliente é um 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 AssignMessage para usar uma função de modelo de mensagens que faça o escape das aspas no JSON. Essa função, escapeJSON(), insere 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 um JSON válido, que é exatamente o que você quer:

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

Um modelo de mensagem é um recurso dinâmico de substituição de strings que pode ser usado em determinadas políticas e em definições <TargetEndpoint>. As funções do modelo de mensagens permitem executar operações úteis, como hash, manipulação de string, escape de caracteres, entre 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>

Nesta seção, 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 da string desse hash como um número hexadecimal.

Sintaxe

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 (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 de hash base64

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

Sintaxe

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 (entre aspas simples) 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

Argumentos

string: a string a ser codificada ou decodificada. Pode ser uma string literal (entre 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 caso

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

Sintaxe

Argumentos

string: a string a ser convertida. Pode ser uma string literal (entre 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

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

Sintaxe

substring(str,start_index,end_index)

Argumentos

• str: uma string literal (entre aspas) ou 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:

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

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 (entre aspas simples) ou variável de fluxo de string em que as substituições são 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, suponhamos que essas variáveis de fluxo existam:

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

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 (entre aspas simples) ou variável de fluxo de string em que as substituições são feitas.
• regex: uma expressão regular.
• value: o valor que 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

Argumentos

string: a string a ser escapada. Pode ser uma string literal (entre aspas simples) ou uma variável de fluxo de string.

Observações sobre uso

O XML 1.1 pode representar determinados 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:

"bread" & "butter"

Funções de formato de hora

Retorna uma representação em string do horário, formatada em UTC.

Sintaxe

Argumentos

• format: uma string de formato de data/hora. Pode ser uma string literal (entre aspas simples) ou uma variável de string. Use uma variável em vez de um literal quando o formato incluir dois pontos. Veja a observação anterior nesta seção.
• str: uma string ou variável de fluxo de string contendo um valor de horário. 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çõ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

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

Nenhuma.

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

{randomLong()}

Resulta em algo parecido com isto:

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.

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

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 string que contém XML.

datatype: (opcional) especifica o tipo de retorno pretendido para a consulta. Os valores válidos são nodeset, node, number, boolean, ou string. O valor padrão é nodeset. 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: 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().

Em vez de especificar expressões XPath com caracteres especiais como um literal de string, use uma variável para incluí-la na função. Consulte Evite usar caracteres especiais em literais de string para ver mais detalhes.

{xpath(xpathexpression,xml,ns1)}

Exemplo 3: 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']