Construcción de expresiones JSONata para redactar campos

Para definir un campo para redacción o eliminación al utilizar la política Redacción con DataPower® API Gateway, debe proporcionar una expresión JSONata que defina la vía de acceso al campo que desea redactar o eliminar.

Compatibilidad con JSONata en API Connect

API Connect admite v2.0 de la especificación JSONata, con las siguientes limitaciones:

Si utiliza una expresión JSONata para extraer o ocultar campos, las copias vinculadas de dichos campos también se verán afectadas por la política de extracción u ocultación, incluso si los campos se encuentran en ubicaciones diferentes.
API Connect no admite funciones JSONata de orden superior (funciones que procesan otras funciones).
Si una función de JSONata compatible con API Connect llama a una función de orden superior como argumento, dicho argumento no es compatible (debido a la falta de compatibilidad con las funciones de orden superior).
Las siguientes funciones de JSONata v2.0 no son compatibles:
- $eval()
- $sift()
- $each()
- $error()
- $assert()
$fromMillis() es compatible con las siguientes restricciones:
- El $fromMillis() parámetro admite números comprendidos entre -5364662400000 y 2903299199000.
  - Si el valor es inferior a -5364662400000, se utiliza -5364662400000. En otras palabras, indica que la marca de tiempo es « 1800-01-01T00:00:00Z ».
  - Si el valor es superior a 2903299199000, se utiliza 2903299199000. En otras palabras, indica que la marca de tiempo es « 2261-12-31T23:59:59Z ».
$now() es compatible con las siguientes restricciones:
- No se admiten los siguientes especificadores de componentes:
  - W = Semana del año
  - w = Semana del mes
  - X = Año de numeración de semanas ISO
  - x = Mes según la numeración de semanas ISO
- No se admite la representación de números en forma de palabras, por lo que tampoco se admiten los siguientes modificadores de presentación:
  - W = Palabra en mayúsculas (por ejemplo: [YW] => DOS MIL VEINTICUATRO)
  - w = Palabra en minúsculas (por ejemplo: [Yw] => dos mil veinticuatro)
  - Ww = Palabra con mayúscula inicial (por ejemplo: [YWw] => Dos mil veinticuatro)
- Los mensajes de error son genéricos.

En la tabla 1 se enumeran las extensiones funcionales que se pueden utilizar con la notación estándar de JSONata. Cada extensión corresponde a una parte del contexto de API.

Tabla 1. Ampliaciones funcionales de JSONata
Extensión	Variable	Descripción
`$apiCtx()`	Acceso genérico a un contexto de API	La `$apiCtx()` extensión permite acceder de forma genérica a un contexto de API. Ejemplo de campo de transformación en una acción de extracción: `"$apiCtx().request.uri"` Ejemplo de la situación de una caja en una acción de conmutación: `"$apiCtx().request.path = '/simple/apictx-function'"`
`$header(name)`	`message.headers.name`	Cabecera de mensaje
`$httpVerb()`	`request.verb`	Método HTTP de la solicitud
`$operationID()`	`api.operation.id`	ID de la operación
`$operationPath()`	`api.operation.path`	Vía de acceso de la operación
`$queryParameter('name')`	`request.parameters.name.locations` La palabra clave soportada es `query`. `request.parameters.name.values`	Busca el índice de `query` en `request.parameters.name.locations` y devuelve `request.parameters.name.values[index]`, donde `[index]` es el valor de `query` en las ubicaciones. Los valores de parámetro no se decodifican por URL.
`$statusCode()`	`message.status.code`	Código de estado
`$storageType([arg])`	`variable.body` Puede especificar cualquier variable en el contexto de la API. Si no se especifica ninguna variable, se utiliza la variable predeterminada `message.body`.	Tipo de almacenamiento del mensaje. Los valores soportados son `binary`, `empty`, `graphql`, `json`, `stream`o `xml`.
`$urlParameter('name')`	`request.parameters.name.locations` Las palabras clave soportadas son `path` y `query` `request.parameters.name.values`	Busca el índice de `path` y `query` en `request.parameters.name.locations` y devuelve una única matriz que contiene los valores `path` y `query` de `request.parameters.name.values`. Cuando el URL contiene valores de parámetro de vía de acceso y de consulta, la matriz incluye primero los valores de vía de acceso seguidos por los valores de consulta. Los valores de cada tipo de parámetro se añaden en el orden en que se reciben. Los valores de parámetro son decodificados por URL Por ejemplo, la siguiente URL contiene tanto valores de ruta como de parámetro de consulta. `http://example.com/petstore/cats/adopt?breed=Sphynx&breed=Siamese` La URL `$urlParameter('breed')` devuelve la siguiente matriz de valores. `[cats, adopt, Sphynx, Siamese]` En este ejemplo, el URL incluye una vía de acceso de API que se configura como `/petstore/{breed}/{breed}`, donde `breed` se configura como parámetro de vía de acceso de la vía de acceso de API. Como resultado, se incluyen `cats` y `adopt` en la salida.
`$xpath(path, xpathExpression)`	Puede especificar cualquier variable modificable en el contexto de la API. La `xpathExpression` debe ser una serie literal.	Permite el uso de expresiones XPath. El ejemplo siguiente especifica todos los elementos de precio en el origen. `$xpath($, '//price')`

En la tabla 2 se enumeran las extensiones funcionales que se pueden utilizar con las API de GraphQL.

Tabla 2. Ampliaciones funcionales de JSONata para « GraphQL »
Extensión	Variable	Descripción
`$gqlActiveOperation([graphql_message])`	`message.body`	Obtiene la operación activa encontrada en el mensaje GraphQL especificado. El `operationName` debe ser el mismo que el nombre de la operación activa.
`$gqlAlias(graphql_field_node)`	`message.body`	Obtiene el alias de un nodo de campo GraphQL .
`$gqlFragments([graphql_message])`	`message.body`	Obtiene los fragmentos encontrados en el mensaje GraphQL especificado.
`$gqlName([graphql_node])`	`message.body`	Obtiene el nombre de nodo. Para las operaciones, el nombre de nodo es `operationName`. Para campos, definiciones de fragmentos, argumentos y otros elementos, el nombre de nodo es el nombre del elemento. De forma predeterminada, se recupera el `operationName` de `message.body` .
`$gqlOperations([graphql_message])`	`message.body`	Obtiene las operaciones encontradas en el mensaje GraphQL especificado.
`$gqlType([graphql_node])`	`message.body`	El tipo de operación de la operación activa se recupera para los tipos de consulta Consulta, Mutación y Suscripción.

Además de las extensiones funcionales, puedes utilizar los siguientes operadores:

Puede utilizar el operador de navegación & (concatenación).

Puede utilizar los siguientes operadores numéricos JSONata:

+ (adición)
- (resta)
* (multiplicación)
/ (división)
% (módulo)

Puede utilizar los siguientes operadores de comparación de JSONata para valores de número o cadenas:

=
!=
<
>
<=
>=

También puede utilizar los siguientes operadores y expresiones.

Paréntesis para convertir una secuencia en una matriz, especificar prioridad de operador o calcular expresiones complejas en un valor de contexto.
Rangos de matriz y expresiones de predicado.
Caracteres comodín de asterisco único (*) y asterisco doble (**).

Los elementos siguientes de una consulta GraphQL se pueden exponer en notación JSONata utilizando la sintaxis que se muestra.

query
Toda la consulta GraphQL incluyendo operaciones y fragmentos.
operationName
Para una operación anónima, operationName puede estar vacío.
~fragmentSpreadName
on~typeCondition
~~fragmentDefinitionName

Puedes definir la ruta utilizando cualquiera de las siguientes opciones:

Utilizar una expresión JSONata
Utilizar la extensión JSONata de $xpath()

Utilización de una expresión JSONata

La vía de acceso especificada por la expresión JSONata es relativa a cualquier valor especificado para la propiedad root de la política Redaction . Si la propiedad root no tiene ningún valor o está ausente, inicie la expresión con la vía de acceso de contenido absoluta. Si la propiedad root tiene un valor, puede iniciar la expresión con $ para utilizar la vía de acceso de root directamente, o puede proporcionar una subvía de acceso relativa a la vía de acceso root .

Nota: Si utilizas una expresión JSONata para ocultar campos y existen copias vinculadas de un campo en diferentes ubicaciones, la política de ocultación puede provocar que se oculte el contenido de todos los campos vinculados.

Las expresiones JSONata se pueden utilizar con contenido que esté en formato JSON o XML.

Ejemplo 1

Si la propiedad root de la política Redaction no tiene ningún valor o está ausente, utilice la expresión siguiente para redactar o eliminar todas las apariciones del campo price en los datos de solicitud y respuesta:

message.body.**.price

Ejemplo 2

Si la propiedad root de la política Redaction tiene el valor log.request_body, utilice la expresión siguiente para redactar o eliminar todas las apariciones del campo price , específicamente dentro de un elemento item , en la carga útil de solicitud registrada:

$.item.price

Ejemplo 3

Si la propiedad root de la política Redaction tiene el valor log, utilice la expresión siguiente para redactar o eliminar todas las apariciones del campo price en la carga útil de respuesta registrada:

response_body.**.price

El comodín descendiente ** recorre todos los descendientes de todos los niveles jerárquicos.

Utilización de la extensión de JSONata `$xpath()`

La función $xpath() tiene el formato siguiente:

$xpath(content_path, xpath_expression)

donde:

vía_acceso_contenido es la vía de acceso al contenido que incluye el campo que desea redactar o eliminar.
expresión_xpath es la expresión XPath que define el campo que desea redactar o eliminar.

La vía_acceso_contenido es relativa a cualquier valor especificado para la propiedad root de la política Redaction . Si la propiedad root no tiene ningún valor o está ausente, especifique la vía de acceso de contenido absoluta. Si la propiedad root tiene un valor, puede proporcionar el valor $ para que el parámetro vía_acceso_contenido utilice directamente la vía de acceso root, o bien puede proporcionar una subvía de acceso relativa a la vía de acceso root.

La función $xpath() sólo puede utilizarse con contenido que esté en formato XML.