Transformer les données avec JSONata in Step Functions

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Vous JSONata bénéficiez ainsi d'un puissant langage de requête et d'expression open source pour sélectionner et transformer les données dans vos flux de travail. Pour une brève introduction et une JSONata référence complète, consultez la documentation JSONata .org.

La vidéo suivante décrit les variables et JSONata décrit Step Functions avec un exemple DynamoDB :

Vous devez accepter d'utiliser le langage de JSONata requête et de transformation pour les flux de travail existants. Lorsque vous créez un flux de travail dans la console, nous vous recommandons de choisir JSONata la machine QueryLanguage à états de niveau supérieur. Pour les flux de travail existants ou nouveaux qui l'utilisent JSONPath, la console fournit une option permettant de convertir les états individuels en JSONata.

Après la sélection JSONata, les champs de votre flux de travail seront réduits de cinq JSONPath champs (InputPathParametersResultSelector,ResultPath,, etOutputPath) à deux champs seulement : Arguments etOutput. De plus, vous n'utiliserez pas .$ les noms de clé des objets JSON.

Si vous débutez avec Step Functions, il vous suffit de savoir que les JSONata expressions utilisent la syntaxe suivante :

JSONata syntaxe : "{% <JSONata expression> %}"

Les exemples de code suivants montrent une conversion de JSONPath vers JSONata :

# Original sample using JSONPath
{
  "QueryLanguage": "JSONPath", // Set explicitly; could be set and inherited from top-level
  "Type": "Task",
  ...
  "Parameters": {
    "static": "Hello",
    "title.$": "$.title",
    "name.$": "$customerName",  // With $customerName declared as a variable
    "not-evaluated": "$customerName"
  }
}

# Sample after conversion to JSONata
{
  "QueryLanguage": "JSONata", // Set explicitly; could be set and inherited from top-level
  "Type": "Task",
  ...
  "Arguments": { // JSONata states do not have Parameters
    "static": "Hello",
    "title": "{% $states.input.title %}", 
    "name": "{% $customerName %}",   // With $customerName declared as a variable
    "not-evaluated": "$customerName"
  }
}

Compte tenu de l'entrée { "title" : "Doctor" } et de la variable customerName assignées"María", les deux machines d'état produiront le résultat JSON suivant :

{
  "static": "Hello",
  "title": "Doctor",
  "name": "María",
  "not-evaluated": "$customerName"
 }

Dans le schéma suivant, vous pouvez voir une représentation graphique montrant comment la conversion JSONPath (gauche) vers JSONata (droite) réduira la complexité des étapes dans vos machines d'état :

Vous pouvez (éventuellement) sélectionner et transformer les données de l'entrée d'état en arguments à envoyer à votre action intégrée. Avec JSONata, vous pouvez ensuite (éventuellement) sélectionner et transformer les résultats de l'action pour l'assignation aux variables et pour l'état Output.

Remarque : Les étapes d'assignation et de sortie se déroulent en parallèle. Si vous choisissez de transformer les données lors de l'attribution de variables, ces données transformées ne seront pas disponibles à l'étape Sortie. Vous devez réappliquer la JSONata transformation à l'étape Sortie.

QueryLanguage champ

Dans les définitions ASL de votre flux de travail, il existe un QueryLanguage champ au niveau supérieur d'une définition de machine à états et dans des états individuels. En définissant QueryLanguage des états individuels, vous pouvez les adopter progressivement JSONata dans une machine à états existante plutôt que de la mettre à niveau en une seule fois.

Le QueryLanguage champ peut être défini sur "JSONPath" ou"JSONata". Si le QueryLanguage champ de niveau supérieur est omis, sa valeur par défaut est. "JSONPath" Si un état contient un QueryLanguage champ au niveau de l'état, Step Functions utilisera la langue de requête spécifiée pour cet état. Si l'état ne contient aucun QueryLanguage champ, il utilisera la langue de requête spécifiée dans le QueryLanguage champ de niveau supérieur.

Écrire JSONata des expressions dans des chaînes JSON

Lorsqu'une chaîne contenant la valeur d'un champ ASL, d'un champ d'objet JSON ou d'un élément de tableau JSON est entourée de {% %} caractères, cette chaîne est évaluée comme JSONata suit. Notez que la chaîne doit {% commencer sans espaces de début et doit se terminer %} sans espaces de fin. L'ouverture ou la fermeture incorrectes de l'expression entraînera une erreur de validation.

Voici quelques exemples :

Tous les champs ASL ne sont pas acceptés JSONata. Par exemple, Type le champ de chaque État doit être défini sur une chaîne constante. De même, le Resource champ de Task l'état doit être une chaîne constante. Le Items champ Map state acceptera un tableau JSON ou une JSONata expression qui doit être évaluée en tableau.

Variable réservée : $states

Step Functions définit une variable réservée unique appelée $states. Dans JSONata les états, les structures suivantes sont attribuées $states pour être utilisées dans les JSONata expressions :

# Reserved $states variable in JSONata states
$states = {
  "input":       // Original input to the state
  "result":      // API or sub-workflow's result (if successful)
  "errorOutput": // Error Output (only available in a Catch)
  "context":     // Context object
}

Lors de la saisie de l'état, Step Functions affecte l'état saisi à $states.input. La valeur de $states.input peut être utilisée dans tous les champs qui acceptent JSONata des expressions. $states.inputfait toujours référence à l'entrée d'état d'origine.

Pour TaskParallel, et Map déclare :

Toute tentative d'accès $states.result ou $states.errorOutput dans des champs et états où ils ne sont pas accessibles sera interceptée lors de la création, de la mise à jour ou de la validation de la machine à états.

L'$states.contextobjet fournit à vos flux de travail des informations sur leur exécution spécifiqueStartTime, telles que le jeton de tâche et la saisie initiale du flux de travail. Pour en savoir plus, consultez Accès aux données d'exécution depuis l'objet Context dans Step Functions .

Gestion des erreurs d'expression

Au moment de l'exécution, l'évaluation des JSONata expressions peut échouer pour diverses raisons, telles que :

Dans chaque cas, l'interpréteur lancera l'erreur :States.QueryEvaluationError. Vos états Task, Map et Parallel peuvent fournir un Catch champ pour détecter l'erreur et un Retry champ pour réessayer de corriger l'erreur.

Conversion JSONPath de JSONata

Les sections suivantes comparent et expliquent les différences entre le code écrit avec JSONPath et JSONata.

Plus de champs de chemin

L'ASL oblige les développeurs à utiliser des Path versions de champs, comme dansTimeoutSecondsPath, pour sélectionner une valeur à partir des données d'état lors de l'utilisation JSONPath. Lorsque vous utilisez JSONata, vous n'utilisez plus de Path champs car l'ASL interprétera automatiquement pour vous les JSONata expressions {% %} incluses dans des champs autres que Path, tels que. TimeoutSeconds

De même, l'Mapétat ItemsPath a été remplacé par le Items champ qui accepte un tableau JSON ou une JSONata expression qui doit être évaluée en tableau.

Objets JSON

ASL utilise le terme modèle de charge utile pour décrire un objet JSON qui peut contenir des JSONPath expressions Parameters et des valeurs de ResultSelector champ. ASL n'utilisera pas le terme modèle de charge utile JSONata car JSONata l'évaluation a lieu pour toutes les chaînes, qu'elles apparaissent seules ou dans un objet JSON ou un tableau JSON.

Plus rien. $

L'ASL vous oblige à ajouter « .$ » aux noms de champs dans les modèles de charge utile à utiliser JSONPath et aux fonctions intrinsèques. Lorsque vous spécifiez"QueryLanguage":"JSONata", vous n'utilisez plus la convention « .$ » pour les noms de champs d'objets JSON. Au lieu de cela, vous insérez les JSONata expressions dans des {% %} caractères. Vous utilisez la même convention pour tous les champs à valeur de chaîne, quelle que soit la profondeur d'imbrication de l'objet dans d'autres tableaux ou objets.

Arguments et champs de sortie

Lorsque le QueryLanguage est défini surJSONata, les anciens champs de traitement des E/S seront désactivés (InputPath, ParametersResultSelector, ResultPath etOutputPath) et la plupart des États recevront deux nouveaux champs : Arguments etOutput.

JSONata fournit un moyen plus simple d'effectuer des transformations d'E/S par rapport aux champs utilisés avec JSONPath. JSONatales fonctionnalités le rendent Arguments et sont Output plus performants que les cinq champs précédents avec JSONPath. Ces nouveaux noms de champs contribuent également à simplifier votre ASL et à clarifier le modèle de transmission et de renvoi de valeurs.

Les Output champs Arguments and (et d'autres champs similaires tels que ceux de Map l'étatItemSelector) accepteront soit un objet JSON tel que :

"Arguments": {
    "field1": 42, 
    "field2": "{% jsonata expression %}"
}

Vous pouvez également utiliser une JSONata expression directement, par exemple :

"Output": "{% jsonata expression %}"

La sortie peut également accepter n'importe quel type de valeur JSON, par exemple :"Output":true,"Output":42.

Les Output champs Arguments et ne sont pris en charge que JSONata, par conséquent, il n'est pas possible de les utiliser avec les flux de travail qui utilisent JSONPath. À l'inverse,InputPath,Parameters,ResultSelector, ResultPathOutputPath, et JSONPath les autres champs ne sont pris en charge que dans JSONPath. Il n'est donc pas possible d'utiliser des champs basés sur des chemins lorsque vous les utilisez JSONata comme langage de flux de travail de haut niveau ou de requête d'état.

État du pass

L'état facultatif Result in a Pass était auparavant traité comme le résultat d'une tâche virtuelle. Une JSONata fois sélectionné comme langue de flux de travail ou de requête d'état, vous pouvez désormais utiliser le nouveau champ de sortie.

État du choix

Lors de l'utilisation JSONPath, les états de choix ont une entrée Variable et de nombreux chemins de comparaison, tels que les suivants NumericLessThanEqualsPath :

# JSONPath choice state sample, with Variable and comparison path
"Check Price": {
  "Type": "Choice",
  "Default": "Pause",
  "Choices": [
  {
    "Variable": "$.current_price.current_price",
    "NumericLessThanEqualsPath": "$.desired_price",
    "Next": "Send Notification"
  } ],
}

Avec JSONata, l'état de choix comporte un Condition endroit où vous pouvez utiliser une JSONata expression :

# Choice state after JSONata conversion
"Check Price": {
  "Type": "Choice",
  "Default": "Pause"
  "Choices": [
    {
      "Condition": "{% $current_price <= $states.input.desired_priced %}",
      "Next": "Send Notification"
    } ]
    

Remarque : Les variables et les champs de comparaison ne sont disponibles que pour JSONPath. La condition n'est disponible que pour JSONata.

JSONata exemples

Les exemples suivants peuvent être créés dans Workflow Studio à des fins d'expérimentation JSONata. Vous pouvez créer et exécuter les machines à états, ou utiliser l'état Test pour transmettre des données et même modifier la définition des machines à états.

Exemple : entrée et sortie

Cet exemple montre comment $states.input utiliser l'entrée d'état et le Output champ pour spécifier l'état de sortie lorsque vous optez pour JSONata.

{
  "Comment": "Input and Output example using JSONata",
  "QueryLanguage": "JSONata",
  "StartAt": "Basic Input and Output",
  "States": {
    "Basic Input and Output": {
      "QueryLanguage": "JSONata",
      "Type": "Succeed",
      "Output": {
        "lastName": "{% 'Last=>' & $states.input.customer.lastName %}",
        "orderValue": "{% $states.input.order.total %}"
      }
    }
  }
}

Lorsque le flux de travail est exécuté avec les informations suivantes en entrée :

{
  "customer": {
    "firstName": "Martha",
    "lastName": "Rivera"
  },
  "order": {
    "items": 7,
    "total": 27.91
  }
}

L'état du test ou l'exécution de la machine à états renverra la sortie JSON suivante :

{
  "lastName": "Last=>Rivera",
  "orderValue": 27.91
}

Exemple : Filtrer avec JSONata

Vous pouvez filtrer vos données à l'aide des opérateurs JSONata Path. Imaginons, par exemple, que vous ayez une liste de produits à saisir et que vous ne vouliez traiter que des produits ne contenant aucune calorie. Vous pouvez créer une définition de machine à états avec l'ASL suivante et tester l'FilterDietProductsétat avec l'exemple d'entrée qui suit.

Définition de la machine à états pour le filtrage avec JSONata

{
  "Comment": "Filter products using JSONata",
  "QueryLanguage": "JSONata",
  "StartAt": "FilterDietProducts",
  "States": {
    "FilterDietProducts": {
      "Type": "Pass",
      "Output": {
        "dietProducts": "{% $states.input.products[calories=0] %}"
      },
      "End": true
    }
  }
}

Exemple d'entrée pour le test

{
  "products": [
    {
      "calories": 140,
      "flavour": "Cola",
      "name": "Product-1"
    },
    {
      "calories": 0,
      "flavour": "Cola",
      "name": "Product-2"
    },
    {
      "calories": 160,
      "flavour": "Orange",
      "name": "Product-3"
    },
    {
      "calories": 100,
      "flavour": "Orange",
      "name": "Product-4"
    },
    {
      "calories": 0,
      "flavour": "Lime",
      "name": "Product-5"
    }
  ]
}

Résultat du test de l'étape dans votre machine à états

{
    "dietProducts": [
        {
            "calories": 0,
            "flavour": "Cola",
            "name": "Product-2"
        },
        {
            "calories": 0,
            "flavour": "Lime",
            "name": "Product-5"
        }
    ]
}

JSONata fonctions fournies par Step Functions

JSONata contient des bibliothèques de fonctions pour les fonctions String, Numeric, Aggregation, Boolean, Array, Object, Date/Time et High Order. Step Functions fournit des JSONata fonctions supplémentaires que vous pouvez utiliser dans vos JSONata expressions. Ces fonctions intégrées remplacent les fonctions intrinsèques de Step Functions. Les fonctions intrinsèques ne sont disponibles que dans les états qui utilisent le langage de JSONPath requête.

Remarque : JSONata les fonctions intégrées qui nécessitent des valeurs entières comme paramètres arrondiront automatiquement les nombres non entiers fournis.

$partition - JSONata équivalent d'une fonction States.ArrayPartition intrinsèque pour partitionner un grand tableau.

Le premier paramètre est le tableau à partitionner, le second est un entier représentant la taille du bloc. La valeur de retour sera un tableau bidimensionnel. L'interpréteur découpe le tableau d'entrée en plusieurs tableaux de la taille spécifiée par la taille du morceau. La longueur du dernier segment de tableau peut être inférieure à la longueur des fragments de tableau précédents si le nombre d'éléments restants dans le tableau est inférieur à la taille du morceau.

"Assign": {
  "arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}

$range - JSONata équivalent d'une fonction States.ArrayRange intrinsèque pour générer un tableau de valeurs.

Cette fonction prend trois arguments. Le premier argument est un entier représentant le premier élément du nouveau tableau, le deuxième argument est un entier représentant le dernier élément du nouveau tableau, et le troisième argument est l'entier de valeur delta pour les éléments du nouveau tableau. La valeur de retour est un tableau nouvellement généré de valeurs allant du premier argument de la fonction au deuxième argument de la fonction, les éléments intermédiaires étant ajustés par le delta. La valeur delta peut être positive ou négative, ce qui augmentera ou diminuera chaque élément depuis le dernier jusqu'à ce que la valeur finale soit atteinte ou dépassée.

"Assign": {
  "arrayRange": "{% $range(0, 10, 2) %}"
}

$hash - JSONata équivalent de la fonction States.Hash intrinsèque pour calculer la valeur de hachage d'une entrée donnée.

Cette fonction prend deux arguments. Le premier argument est la chaîne source à hacher. Le deuxième argument est une chaîne représentant l'algorithme de hachage utilisé pour le calcul du hachage. L'algorithme de hachage doit prendre l'une des valeurs suivantes :"MD5",,"SHA-1", "SHA-256""SHA-384","SHA-512". La valeur renvoyée est une chaîne du hachage calculé des données.

Cette fonction a été créée car elle JSONata ne prend pas en charge nativement la possibilité de calculer des hachages.

"Assign": {
  "myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}

$random - JSONata équivalent de la fonction States.MathRandom intrinsèque pour renvoyer un nombre aléatoire n où0 ≤ n < 1.

La fonction prend un argument entier facultatif représentant la valeur initiale de la fonction aléatoire. Si vous utilisez cette fonction avec la même valeur initiale, elle renvoie un nombre identique.

Cette fonction surchargée a été créée parce que la JSONata fonction intégrée $randomn'accepte pas de valeur initiale.

"Assign": {
   "randNoSeed": "{% $random() %}",
   "randSeeded": "{% $random($states.input.seed) %}"
}

$uuid - JSONata version de la fonction intrinsèque. States.UUID

La fonction ne prend aucun argument. Cette fonction renvoie un UUID v4.

Cette fonction a été créée car elle JSONata ne prend pas en charge nativement la possibilité de générer UUIDs.

"Assign": {
  "uniqueId": "{% $uuid() %}"
}

$parse - JSONata fonction pour désérialiser les chaînes JSON.

La fonction prend un JSON sous forme de chaîne comme seul argument.

JSONata prend en charge cette fonctionnalité via $eval ; toutefois, elle n'$evalest pas prise en charge dans les flux de travail Step Functions.

"Assign": {
  "deserializedPayload": "{% $parse($states.input.json_string) %}"
}