Construcción de expresiones JSONata para extraer y transformar datos

Para extraer y transformar datos de campos en el contexto de API cuando se utiliza la política Extraer con DataPower® API Gateway, debe proporcionar una expresión JSONata que defina los campos a extraer y transformar.

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