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.

Soporte de JSONata en API Connect

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

Si utiliza una expresión JSONata para extraer o redactar campos, las copias enlazadas en software del campo también se ven afectadas por la política Extraer o Redacción, incluso si los campos existen en ubicaciones diferentes.
API Connect no da soporte a las funciones JSONata de orden superior (funciones que procesan otras funciones).
Si una función JSONata soportada por API Connect llama a una función de orden superior como argumento, dicho argumento no está soportado (debido a la falta de soporte para funciones de orden superior).
Las siguientes funciones de JSONata v2.0 no están soportadas:
- $eval()
- $sift()
- $each()
- $error()
- $assert()
$fromMillis() está soportado con las restricciones siguientes:
- El parámetro $fromMillis() ' admite números en el rango -5364662400000 - 2903299199000.
  - Un valor inferior a -5364662400000 utiliza -5364662400000. En otras palabras, informa de la marca de tiempo como 1800-01-01T00:00:00Z.
  - Un valor superior a 2903299199000 utiliza 2903299199000. En otras palabras, informa de la marca de tiempo como 2261-12-31T23:59:59Z.
$now() está soportado con las restricciones siguientes:
- Los siguientes especificadores de componente no están soportados:
  - W = Semana del año
  - w = Semana en mes
  - X = año de numeración semanal ISO
  - x = mes de numeración de semana ISO
- No se da soporte a la representación de números como palabras, por lo que no se da soporte a los modificadores de presentación siguientes:
  - W = Palabra en mayúsculas (por ejemplo: [YW] = > TWO THOUSAND AND TWENTY-FOUR)
  - w = Palabra en minúsculas (por ejemplo: [Yw] = > dos mil y veinticuatro)
  - Ww = Palabra de caso de título (por ejemplo: [YWw] = > Dos mil y veinticuatro)
- Los mensajes de error son genéricos.

La Tabla 1 lista las extensiones funcionales que puede utilizar con la notación JSONata estándar. Cada extensión corresponde a una parte del contexto de API.

Tabla 1. Extensiones funcionales para JSONata
Extensión	Variable	Descripción
`$apiCtx()`	Acceso genérico a un contexto de API	La extensión `$apiCtx()` proporciona acceso genérico a un contexto de API. Campo de transformación de ejemplo en una acción de extracción: `"$apiCtx().request.uri"` Condición de ejemplo de un caso 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')`

La Tabla 2 lista las extensiones funcionales que puede utilizar con las API de GraphQL .

Tabla 2. Extensiones funcionales a 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, puede utilizar los operadores siguientes:

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