Somente DataPower API Gateway

Construindo expressões JSONata para editar campos

Editar online

Para definir um campo para edição de dados ou remoção ao usar a política Redação com o DataPower® API Gateway, você fornece uma expressão JSONata que define o caminho para o campo que deseja editar ou remover.

Suporte a JSONata em API Connect

API Connect suporta o método ` v2.0 ` da especificação JSONata, com as seguintes limitações:

  • Se você usar uma expressão JSONata para extrair ou ocultar campos, as cópias vinculadas desses campos também serão afetadas pela política de extração ou ocultação, mesmo que os campos estejam em locais diferentes.
  • API Connect não suporta funções JSONata de ordem superior (funções que processam outras funções).
  • Se uma função JSONata suportada pelo API Connect chamar uma função de ordem superior como argumento, esse argumento não será suportado (devido à falta de suporte para funções de ordem superior).
  • As seguintes funções JSONata v2.0 não são suportadas:
    • $eval()
    • $sift()
    • $each()
    • $error()
    • $assert()
  • $fromMillis() é compatível com as seguintes restrições:
    • O $fromMillis() parâmetro aceita números no intervalo de -5364662400000 a 2903299199000.
      • Um valor menor que -5364662400000 é substituído por -5364662400000. Em outras palavras, o carimbo de data/hora é registrado como 1800-01-01T00:00:00Z.
      • Um valor maior que 2903299199000 utiliza 2903299199000. Em outras palavras, o carimbo de data/hora é registrado como 2261-12-31T23:59:59Z.
  • $now() é compatível com as seguintes restrições:
    • Os seguintes especificadores de componentes não são suportados:
      • W = Semana do ano
      • w = Semana do mês
      • X = Ano e número da semana ISO
      • x = Mês da numeração de semanas ISO
    • A representação de números por palavras não é suportada; portanto, os seguintes modificadores de apresentação não são suportados:
      • W = Palavra em maiúsculas (por exemplo: [YW] => DOIS MIL E VINTE E QUATRO)
      • w = Palavra em letras minúsculas (por exemplo: [Yw] => dois mil e vinte e quatro)
      • Ww = Palavra com letras maiúsculas no início (por exemplo: [YWw] => Dois Mil e Vinte e Quatro)
    • As mensagens de erro são genéricas.

A Tabela 1 lista as extensões funcionais que podem ser usadas com a notação padrão do JSONata. Cada extensão corresponde a uma parte do contexto da API.

Tabela 1. Extensões funcionais para o JSONata
Extensão Variável Descrição
$apiCtx() Acesso genérico a um contexto de API A $apiCtx() extensão oferece acesso genérico a um contexto de API.
  • Exemplo de campo de transformação em uma ação de extração:
    "$apiCtx().request.uri"
  • Exemplo de condição de um caso em uma ação de comutação:
    "$apiCtx().request.path = '/simple/apictx-function'"
$header(name) message.headers.name Cabeçalho da Mensagem
$httpVerb() request.verb Método HTTP da solicitação
$operationID() api.operation.id ID da operação
$operationPath() api.operation.path Caminho da operação
$queryParameter('name')
  • request.parameters.name.locations

    A palavra-chave suportada é query.

  • request.parameters.name.values
 Procura o índice de query em request.parameters.name.locations e retorna request.parameters.name.values[index], onde [index] é o valor de query em locais. Os valores de parâmetros não são decodificados por URL.
$statusCode() message.status.code Código de status
$storageType([arg]) variable.body

É possível especificar qualquer variável no contexto da API. Quando nenhuma variável é especificada, a variável padrão message.body é usada.

 Tipo de armazenamento da mensagem. Os valores suportados são binary, empty, graphql, json, streamou xml.
$urlParameter('name')
  • request.parameters.name.locations

    As palavras-chave suportadas são path e query

  • request.parameters.name.values
 Pesquisa o índice de path e query em request.parameters.name.locations e retorna uma única matriz que contém os query valores de path e de request.parameters.name.values. Quando a URL contém os valores de parâmetro de caminho e de consulta, a matriz inclui os valores de caminho primeiro, seguidos pelos valores de consulta. Os valores de cada tipo de parâmetro são incluídos na ordem em que são recebidos. Valores de parâmetros são URL decodificados.
Por exemplo, o seguinte URL URL contém tanto valores de caminho quanto de parâmetros de consulta.
http://example.com/petstore/cats/adopt?breed=Sphynx&breed=Siamese
A função ` URL$urlParameter('breed') ` retorna a seguinte matriz de valores.
[cats, adopt, Sphynx, Siamese]

Neste exemplo, a URL inclui um caminho de API que é configurado como /petstore/{breed}/{breed}, em que breed é configurado para ser um parâmetro de caminho do caminho da API. Como resultado, cats e adopt são incluídos na saída.
$xpath(path, xpathExpression) É possível especificar qualquer variável gravável no contexto de API. A xpathExpression deve ser uma sequência de caracteres literal. Permite o uso de expressões XPath. O exemplo a seguir especifica todos os elementos de preço na fonte.
$xpath($, '//price')

A Tabela 2 lista as extensões funcionais que você pode usar com as APIs d GraphQL.

Tabela 2. Extensões funcionais para o JSONata para o ` GraphQL `
Extensão Variável Descrição
$gqlActiveOperation([graphql_message]) message.body Obtém a operação ativa localizada na mensagem GraphQL especificada O operationName deve ser igual ao nome da operação ativa.
$gqlAlias(graphql_field_node) message.body Obtém o alias de um nó do campo GraphQL .
$gqlFragments([graphql_message]) message.body Obtém os fragmentos localizados na mensagem GraphQL especificada..
$gqlName([graphql_node]) message.body Obtém o nome do nó.. Para operações, o nome do nó é operationName. Para campos, definições de fragmentos, argumentos e outros elementos, o nome do nó é o nome do elemento. Por padrão, operationName de message.body é recuperado.
$gqlOperations([graphql_message]) message.body Obtém as operações localizadas na mensagem GraphQL especificada..
$gqlType([graphql_node]) message.body O tipo de operação da operação ativa é recuperado para tipos de consulta Consulta, Mutação e Assinatura.
Além das extensões funcionais, você pode usar os seguintes operadores:
  • Você pode usar o operador de & navegação (concatenação).

É possível usar os operadores numéricos JSONata a seguir:

  • + (adição)
  • - (subtração).
  • * (multiplicação)
  • / (divisão)
  • % (modulo)

É possível usar os operadores de comparação JSONata a seguir para valores ou sequências numéricas:

  • =
  • !=
  • <
  • >
  • <=
  • >=
Também é possível usar os seguintes operadores e expressões.
  • Parênteses para converter uma seqüência em uma matriz, especificar precedência do operador ou calcular expressões complexas em um valor de contexto.
  • Intervalos de matrizes e expressões de predicado
  • Caracteres curinga asterisco único (*) e asterisco duplo (**).
Os seguintes elementos de uma consulta GraphQL podem ser expostos na notação JSONata usando a sintaxe mostrada.
  • query

    A consulta GraphQL inteira incluindo operações e fragmentos.

  • operationName

    Para uma operação anônima, o operationName pode estar vazio

  • ~fragmentSpreadName
  • on~typeCondition
  • ~~fragmentDefinitionName

Você pode definir o caminho usando qualquer uma das seguintes opções:

Usando uma expressão JSONata

O caminho especificado pela expressão JSONata é relativo a qualquer valor especificado para a propriedade root da política Redação . Se a propriedade root não tiver valor ou estiver ausente, inicie a expressão com o caminho de conteúdo absoluto. Se a propriedade root tiver um valor, será possível começar a expressão com $ para usar o caminho root diretamente ou fornecer um subcaminho relativo ao caminho root.

Observação: Se você usar uma expressão JSONata para ocultar campos e houver cópias vinculadas de um campo em diferentes locais, a política de ocultação poderá fazer com que o conteúdo de todos os campos vinculados seja ocultado.

É possível usar as expressões JSONata com conteúdo no formato JSON ou XML.

Exemplo 1
Se a propriedade root da política Redação não tiver valor ou estiver ausente, use a expressão a seguir para editar ou remover todas as ocorrências do campo price nos dados de solicitação e resposta:
message.body.**.price
Exemplo 2
Se a propriedade root da política Redaction tiver o valor log.request_body, use a expressão a seguir para editar ou remover todas as ocorrências do campo price , especificamente dentro de um elemento item , na carga útil da solicitação registrada:
$.item.price
Exemplo 3
Se a propriedade root da política Redação tiver o valor log, use a expressão a seguir para editar ou remover todas as ocorrências do campo price na carga útil de resposta registrada:
response_body.**.price

O curinga descendente ** atravessa todos os descendentes em todos os níveis hierárquicos.

Usando a extensão JSONata $xpath()

A função $xpath() tem o formato a seguir:
$xpath(content_path, xpath_expression)
em que:
  • content_path é o caminho para o conteúdo que contém o campo que você deseja editar ou remover.
  • xpath_expression é a expressão XPath que define o campo que você deseja editar ou remover.

O content_path é relativo a qualquer valor especificado para a propriedade root da política Redação . Se a propriedade root não tiver valor ou estiver ausente, forneça o caminho de conteúdo absoluto. Se a propriedade root tiver um valor, será possível fornecer o valor $ para o parâmetro content_path para usar o caminho root diretamente ou fornecer um subcaminho relativo ao caminho root.

A função $xpath() pode ser usada apenas com conteúdo que está no formato XML.

Exemplo 1
Se a propriedade root da política Redação não tiver valor ou estiver ausente, use a expressão a seguir para editar ou remover todas as ocorrências do campo price nos dados de solicitação e resposta:
$xpath(message.body, '//price')
Exemplo 2
Se a propriedade root da política Redaction tiver o valor log.request_body, use a expressão a seguir para editar ou remover todas as ocorrências do campo price , especificamente dentro de um elemento item , na carga útil da solicitação registrada:
$xpath($, 'item/price')
Exemplo 3
Se a propriedade root da política Redação tiver o valor log, use a expressão a seguir para editar ou remover todas as ocorrências do campo price na carga útil de resposta registrada:
$xpath(response_body, '//price')

A expressão // no segundo parâmetro seleciona todas as ocorrências em qualquer lugar do conteúdo.