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.
# Traitement des entrées et des sorties dans Step Functions
**Gestion de l'état à l'aide de variables et JSONata**
Step Functions a récemment ajouté des variables et JSONata permet de gérer l'état et de transformer les données.
Pour en savoir plus, consultez le billet de blog [Simplifier l'expérience des développeurs à l'aide de variables et JSONata ](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/) dans AWS Step Functions
Lorsqu'une exécution de Step Functions reçoit une entrée JSON, elle transmet ces données au premier état du flux de travail en tant qu'entrée.
Avec JSONata, vous pouvez récupérer les entrées d'état depuis`$states.input`. Les exécutions de vos machines à états fournissent également ces données d'entrée initiales dans le[Objet Contexte](input-output-contextobject.md). Vous pouvez récupérer l'entrée de la machine à états d'origine à tout moment de votre flux de travail à partir de`$states.context.Execution.Input`.
Lorsque les états sortent, leur sortie est disponible pour l'*état* suivant dans votre machine à états. Vos entrées d'état seront transmises en tant que sortie d'état par défaut, sauf si vous **modifiez** l'état de sortie. Pour les données dont vous pourriez avoir besoin ultérieurement, pensez à les stocker dans des variables. Pour plus d’informations, consultez [Transmission de données entre états à l'aide de variables](workflow-variables.md).
**QueryLanguage recommandation**
Pour les nouvelles machines à états, nous recommandons le langage de JSONata requête. Dans les machines d'état qui ne spécifient pas de langue de requête, la machine d'état utilise par défaut la valeur par défaut JSONPath pour des raisons de rétrocompatibilité. Vous devez choisir de l'utiliser JSONata pour vos machines d'État ou pour des États individuels.
**Traitement des entrées et des sorties avec JSONata**
JSONata Les expressions vous permettent de sélectionner et de transformer des données. Sur le `Arguments` terrain, vous pouvez personnaliser les données envoyées à l'action. Le résultat peut être transformé en sortie d'état personnalisée `Output` sur le terrain. Vous pouvez également stocker des données dans des variables `Assign` sur le terrain. Pour plus d'informations, consultez la section [Transformation des données avec JSONata](transforming-data.md).
Le schéma suivant montre comment les informations JSON passent par l'état d'une JSONata tâche.
![\[Diagram showing JSONata task state flow with input, arguments, output, and action components.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/vars-jsonata.png)
**Traitement des entrées et des sorties avec JSONPath**
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Pour les machines à états qui l'utilisent JSONPath, les champs suivants contrôlent le flux de données d'un état à l'`InputPath`autre :`Parameters`,`ResultSelector`,`ResultPath`, et`OutputPath`. Chaque JSONPath champ peut manipuler le JSON au fur et à mesure qu'il passe par chaque état de votre flux de travail.
JSONPath les champs peuvent utiliser [des chemins](amazon-states-language-paths.md) pour sélectionner des parties du JSON à partir de l'entrée ou du résultat. Un chemin est une chaîne, commençant par`$`, qui identifie les nœuds dans le texte JSON. Les chemins Step Functions utilisent [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)la syntaxe.
Le schéma suivant montre comment les informations JSON passent par l'état d'une JSONPath tâche. `InputPath`Sélectionne les parties de l'entrée JSON à transmettre à la tâche de l'`Task`état (par exemple, une AWS Lambda fonction). Vous pouvez ajuster les données qui sont envoyées à votre action `Parameters` sur le terrain. Ensuite`ResultSelector`, vous pouvez sélectionner des parties du résultat de l'action à reporter. `ResultPath`sélectionne ensuite la combinaison de l'entrée d'état et des résultats de la tâche à transmettre à la sortie. `OutputPath`peut filtrer la sortie JSON pour limiter davantage les informations transmises à la sortie.
![\[Ordre des filtres : InputPath, Paramètres ResultSelector, ResultPath, et OutputPath.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/vars-jsonpath.png)
**Topics**
+ [Transmission de données entre états à l'aide de variables](workflow-variables.md)
+ [Transformer les données avec JSONata in Step Functions](transforming-data.md)
+ [Accès aux données d'exécution depuis l'objet Context dans Step Functions](input-output-contextobject.md)
+ [Utiliser des JSONPath chemins](amazon-states-language-paths.md)
+ [Manipulation des paramètres dans les flux de travail Step Functions](input-output-inputpath-params.md)
+ [Exemple : manipulation de données d'état à l'aide de chemins dans les flux de travail Step Functions](input-output-example.md)
+ [Spécification de la sortie d'état à l'aide ResultPath de in Step Functions](input-output-resultpath.md)
+ [Mappez les champs d'entrée et de sortie d'état dans Step Functions](input-output-fields-dist-map.md)
# Transmission de données entre états à l'aide de variables
**Gestion de l'état avec des variables et JSONata**
Step Functions a récemment ajouté des variables et JSONata permet de gérer l'état et de transformer les données.
Pour en savoir plus, consultez le billet de blog [Simplifier l'expérience des développeurs à l'aide de variables et JSONata ](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/) dans AWS Step Functions
La vidéo suivante décrit les variables et JSONata décrit Step Functions avec un exemple DynamoDB :
Grâce aux variables et aux sorties d'état, vous pouvez transmettre des données entre les étapes de votre flux de travail.
À l'aide de variables de flux de travail, vous pouvez stocker des données dans une étape et les récupérer lors des étapes futures. Par exemple, vous pouvez stocker une réponse d'API contenant des données dont vous pourriez avoir besoin ultérieurement. Inversement, la sortie d'état ne peut être utilisée que comme entrée pour l'étape suivante.
## Vue d'ensemble conceptuelle des variables
Avec les variables de flux de travail, vous pouvez stocker des données pour vous y référer ultérieurement. Par exemple, l'étape 1 peut stocker le résultat d'une demande d'API afin qu'une partie de cette demande puisse être réutilisée ultérieurement à l'étape 5.
Dans le scénario suivant, la machine à états extrait les données d'une API une seule fois. À l'étape 1, le flux de travail stocke les données d'API renvoyées (jusqu'à 256 KiB par état) dans une variable « x » à utiliser lors des étapes ultérieures.
Sans variables, vous devez transmettre les données par le biais de la sortie de l'étape 1 à l'étape 2, puis de l'étape 3 à l'étape 4 pour les utiliser à l'étape 5. Et si ces étapes intermédiaires ne nécessitaient pas les données ? Transmettre des données d'un État à l'autre par le biais des sorties et des entrées représenterait un effort inutile.
Les variables vous permettent de stocker des données et de les utiliser à toute étape future. Vous pouvez également modifier, réorganiser ou ajouter des étapes sans perturber le flux de vos données. Compte tenu de la flexibilité des variables, il se peut que vous n'ayez besoin d'utiliser **Output** que pour renvoyer les données des sous-flux de travail Parallel et Map, et à la fin de l'exécution de votre machine à états.
![\[Diagram showing step 1 assigning a value to $x, used in step 5.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/vars-diag-opt1.png)
**États qui prennent en charge les variables**
Les types d'états suivants permettent `Assign` de déclarer et d'attribuer des valeurs aux variables : *Pass, Task, Map, Parallel, Choice, Wait.*
Pour définir une variable, fournissez un objet JSON avec les noms et les valeurs des variables :
```
"Assign": {
"productName": "product1",
"count" : 42,
"available" : true
}
```
Pour référencer une variable, ajoutez le signe dollar (`$`) au début de son nom, `$productName` par exemple.
## Variable réservée : \$1states
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.input`fait toujours référence à l'entrée d'état d'origine.
Pour `Task``Parallel`, et `Map` déclare :
+ **`$states.result`**fait référence au résultat brut de l'API ou du sous-flux de travail en cas de réussite.
+ **`$states.errorOutput`**fait référence au résultat d'erreur en cas d'échec de l'API ou du sous-flux de travail.
`$states.errorOutput`peut être utilisé `Catch` sur le terrain `Assign` ou`Output`.
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.context`objet fournit à vos flux de travail des informations sur leur exécution spécifique`StartTime`, telles que le jeton de tâche et la saisie initiale du flux de travail. Pour en savoir plus, veuillez consulter la section [Accès aux données d'exécution depuis l'objet Context dans Step Functions](input-output-contextobject.md).
## Syntaxe des noms de variables
Les noms de variables suivent les règles relatives aux identificateurs Unicode, telles que décrites dans l'[annexe \$131 de la norme Unicode®](https://unicode.org/reports/tr31/). Le premier caractère du nom d'une variable doit être un caractère Unicode ID\$1Start, et le second caractère et les suivants doivent être des caractères Unicode ID\$1Continue. La longueur maximale d'un nom de variable est de 80.
La convention de nom de variable est similaire aux règles applicables JavaScript aux autres langages de programmation.
## Champ d'application variable
Les flux de travail Step Functions évitent les conditions de course associées à des variables en utilisant une portée locale au *flux de travail*.
La portée locale du flux de travail inclut tous les états du champ States d'une machine à **états**, mais pas les états des états Parallel ou Map. Les états compris dans les états Parallel ou Map peuvent faire référence à des variables de portée externes, mais ils créent et gèrent leurs propres variables et valeurs locales au flux de travail.
`Parallel`les branches et `Map` les itérations peuvent accéder aux valeurs des variables depuis **des étendues externes**, mais elles n'ont pas accès aux valeurs des variables provenant d'autres branches ou itérations simultanées. Lors de la gestion des erreurs, le `Assign` champ d'un `Catch` peut attribuer des valeurs aux variables de la portée externe, c'est-à-dire de la portée dans laquelle l' Parallel/Map état existe.
Exception : **les états des cartes distribuées** ne peuvent actuellement pas faire référence à des variables dans des étendues externes.
Une variable existe dans une portée si un état de la portée lui attribue une valeur. Pour éviter les erreurs courantes, une variable affectée dans une étendue interne ne peut pas porter le même nom qu'une variable affectée dans une étendue externe. Par exemple, si la portée de niveau supérieur assigne une valeur à une variable appelée`myVariable`, aucune autre portée (à l'intérieur d'un`Map`,`Parallel`) ne peut également l'attribuer`myVariable`.
L'accès aux variables dépend de la portée actuelle. Les états Parallel et Map ont leur propre portée, mais peuvent accéder à des variables situées dans des étendues externes.
Lorsqu'un état parallèle ou cartographique se termine, toutes leurs variables deviennent hors de portée et cessent d'être accessibles. Utilisez le **champ Sortie** pour transmettre des données à partir de branches parallèles et d'itérations cartographiques.
## Attribuer un champ en ASL
Le `Assign` champ en ASL est utilisé pour attribuer des valeurs à une ou plusieurs variables. Le `Assign` champ est disponible au niveau supérieur de chaque État (sauf `Succeed` et`Fail`), dans les règles de l'`Choice`État et dans `Catch` les champs intérieurs. Par exemple :
```
# Example of Assign with JSONata
"Store inputs": {
"Type": "Pass",
"Next": "Get Current Price",
"Comment": "Store the input desired price into a variable: $desiredPrice",
"Assign": {
"desiredPrice": "{% $states.input.desired_price %}",
"maximumWait": "{% $states.input.max_days %}"
}
},
```
Le `Assign` champ accepte un objet JSON. Chaque champ de niveau supérieur nomme une variable à attribuer. Dans les exemples précédents, les noms des variables sont `desiredPrice` et`maximumWait`. Lors de l'utilisation JSONata, `{% ... %}` indique une JSONata expression qui peut contenir des variables ou des expressions plus complexes. Pour plus d'informations sur JSONata les expressions, consultez la [documentation JSONata .org](https://docs.jsonata.org/overview.html).
Lors de l'utilisation **JSONata**comme langage de requête, le schéma suivant montre comment les champs **Assign** et **Output** sont traités en parallèle. Notez l'implication : l'*attribution de valeurs variables n'affectera pas l'état de sortie*.
![\[Diagram showing a comparison of JSONPath and JSONata flow.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/vars-jsonata.png)
L' JSONata exemple suivant effectue une extraction `order.product` à partir de l'entrée d'état. La variable `currentPrice` est définie sur une valeur issue du résultat de la tâche.
```
# Example of Task with JSONata assignment from result
{
"Type": "Task",
...
"Assign": {
"product": "{% $states.input.order.product %}",
"currentPrice": "{% $states.result.Payload.current_price %}"
},
"Next": "the next state"
}
```
Remarque : Vous **ne pouvez pas** attribuer de valeur à une partie d'une variable. Par exemple, vous pouvez`"Assign":{"x":42}`, mais vous ne pouvez pas `"Assign":{"x.y":42}` ou`"Assign":{"x[2]":42}`.
## Ordre d'évaluation dans un champ d'attribution
Toutes les références de variables dans les états Step Functions utilisent les valeurs telles qu'elles étaient lors de la **saisie de l'état**.
Le fait précédent est important pour comprendre comment le `Assign` champ attribue des valeurs à une ou plusieurs variables. Les nouvelles valeurs sont d'abord calculées, puis Step Functions affecte les nouvelles valeurs aux variables. Les nouvelles valeurs des variables seront disponibles à partir de l'état **suivant**. Par exemple, considérez le `Assign` champ suivant :
```
# Starting values: $x=3, $a=6
"Assign": {
"x": "{% $a %}",
"nextX": "{% $x %}"
}
# Ending values: $x=6, $nextX=3
```
Dans l'exemple précédent, la variable `x` est à la fois affectée et référencée.
N'oubliez pas que toutes les expressions sont d'***abord évaluées***, puis que les assignations sont effectuées. Et les nouvelles valeurs attribuées seront disponibles dans l'état **suivant**.
Passons en revue l'exemple en détail. Supposons que dans un état précédent, `$x` on lui a attribué une valeur de trois (3) et `$a` une valeur de six (6). Les étapes suivantes décrivent le processus :
1. Toutes les expressions sont évaluées en utilisant les valeurs **actuelles** de toutes les variables.
L'expression `"{% $a %}"` sera évaluée à 6 et `"{% $x %}"` sera évaluée à 3.
1. Ensuite, les tâches sont effectuées :
`$x`se verra attribuer la valeur six (6)
`$nextX`se verront attribuer trois (3)
Remarque : S'il n'`$x`avait pas été attribué auparavant, l'exemple **échouerait car il ne** `$x` serait *pas défini*.
En résumé, Step Functions évalue **toutes les** expressions, puis effectue des assignations. L'ordre dans lequel les variables apparaissent dans le `Assign` champ **n'a pas** d'importance.
## Limites
La taille maximale d'une variable est de 256 Ko, pour les flux de travail standard et express.
La taille maximale combinée pour toutes les variables d'un même `Assign` champ est également de 256 Ko. Par exemple, vous pouvez affecter X et Y à 128 Ko, mais vous ne pouvez pas attribuer X et Y à 256 Ko dans le même `Assign` champ.
La taille totale de toutes les variables stockées ne peut pas dépasser 10 Mo par exécution.
## Utilisation de variables dans JSONPath les états
Les variables sont également disponibles dans les états qui utilisent JSONPath leur langage de requête.
Vous pouvez référencer une variable dans n'importe quel champ qui accepte une JSONpath expression (`$.`ou une `$$.` syntaxe), à l'exception de `ResultPath` celle qui spécifie un emplacement dans la saisie d'état pour injecter le résultat de l'état. Les variables ne peuvent pas être utilisées dans`ResultPath`.
Dans JSONPath, le `$` symbole fait référence à la valeur « actuelle » et `$$` représente l'objet Context de l'état. JSONPath les expressions peuvent commencer par « `$.` as in `$.customer.name` ». Vous pouvez accéder au contexte avec `$$.` as in`$$.Execution.Id`.
Pour référencer une variable, vous devez également utiliser le `$` symbole devant le nom d'une variable, par exemple, `$x` ou`$order.numItems`.
Dans ** JSONPath**les champs qui acceptent des fonctions intrinsèques, des variables peuvent être utilisées dans les arguments, par exemple`States.Format('The order number is {}', $order.number)`.
Le schéma suivant illustre comment l'étape d'attribution d'une **JSONPath**tâche se produit en même temps que ResultSelector :
![\[Logical diagram of a state that uses JSONPath query language.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/vars-jsonpath.png)
**Affectation de variables dans JSONPath**
JSONPath les affectations de variables se comportent de la même manière que les modèles de charge utile. Les champs qui se terminent par `.$` indiquent que la valeur est une JSONPath expression que Step Functions évalue à une valeur lors de l'exécution de State Machine (par exemple : `$.order..product` et`$.order.total`).
```
# Example of Assign with JSONPath
{
"Type": "Task",
...
"Assign": {
"products.$": "$.order..product",
"orderTotal.$": "$.order.total"
},
"Next": "the next state"
}
```
Pour JSONPath les états, la valeur de `$` dans un `Assign` champ dépend du type d'état. Dans `Task,``Map`, `Parallel` states, `$` fait référence au résultat de l'API/du sous-flux de travail. Dans `Choice` et `Wait` état, `$` fait référence à l'*entrée effective*, qui est la valeur après avoir `InputPath` été appliquée à l'entrée d'état. Car`Pass`, `$` fait référence au résultat, qu'il soit généré par le `Result` champ ou par `Parameters` les champs `InputPath` /.
L' JSONPath exemple suivant affecte un objet JSON à la `details` variable, le résultat de l' JSONPath expression `$.result.code` à `resultCode` et le résultat de l' JSONPath expression `States.Format('Hello {}', $customer.name)` à`message`. S'il était dans un `Task` état, alors `$` dans `$.order.items` et `$.result.code` fait référence au résultat de l'API. La `startTime` variable est affectée à une valeur provenant de l'objet Context,`$$.Execution.StartTime`.
```
"Assign": {
"details": {
"status": "SUCCESS",
"lineItems.$": "$.order.items"
},
"resultCode.$": "$.result.code",
"message.$": "States.Format('Hello {}', $customer.name)",
"startTime.$": "$$.Execution.StartTime"
}
```
# Transformer les données avec JSONata in Step Functions
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](https://docs.jsonata.org/overview.html).
**JSONata Version prise en charge**
Step Functions supporte JSONata la version 2.0.6.
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 (`InputPath``Parameters``ResultSelector`,`ResultPath`,, et`OutputPath`) à deux champs seulement : `Arguments` et`Output`. 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 :** `"{% %}"`
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 :
![\[Schéma qui compare les champs dans JSONPath et JSONata les états.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/compare-jsonpath-jsonata.png)
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.
![\[Schéma logique d'un état utilisant un langage de JSONata requête.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/vars-jsonata.png)
## 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 :
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `"Arguments" : {"field1" : "{% $name %}"}`dans un `Task` État
+ `"Items": [1, "{% $two %}", 3]`dans un `Map` État
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` d'état acceptera un tableau JSON, un objet JSON ou une JSONata expression qui doit être évaluée en tableau ou en objet.
## Variable réservée : \$1states
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.input`fait toujours référence à l'entrée d'état d'origine.
Pour `Task``Parallel`, et `Map` déclare :
+ **`$states.result`**fait référence au résultat brut de l'API ou du sous-flux de travail en cas de réussite.
+ **`$states.errorOutput`**fait référence au résultat d'erreur en cas d'échec de l'API ou du sous-flux de travail.
`$states.errorOutput`peut être utilisé `Catch` sur le terrain `Assign` ou`Output`.
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.context`objet fournit à vos flux de travail des informations sur leur exécution spécifique`StartTime`, 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](input-output-contextobject.md).
## Gestion des erreurs d'expression
Au moment de l'exécution, l'évaluation des JSONata expressions peut échouer pour diverses raisons, telles que :
+ **Erreur de type** : une expression, telle que`{% $x + $y %}`, échouera si elle `$x` n'`$y`est pas un nombre.
+ **Incompatibilité de type** : une expression peut être d'un type que le champ n'acceptera pas. Par exemple, le champ `TimeoutSeconds` nécessite une entrée numérique, de sorte que l'expression `{% $timeout %}` échouera si elle `$timeout` renvoie une chaîne.
+ **Valeur hors plage** : une expression qui produit une valeur située en dehors de la plage acceptable pour un champ échouera. Par exemple, une expression telle que `{% $evaluatesToNegativeNumber %}` échouera dans le `TimeoutSeconds` champ.
+ **Impossible de renvoyer un résultat** : le JSON ne peut pas représenter une expression de valeur non définie. L'expression `{% $data.thisFieldDoesNotExist %}` provoquerait donc une erreur.
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 de JSONPath vers 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 dans`TimeoutSecondsPath`, 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`
+ JSONPath exemple d'héritage : `"TimeoutSecondsPath": "$timeout"`
+ JSONata : `"TimeoutSeconds": "{% $timeout %}"`
De même, l'`Map`état `ItemsPath` a été remplacé par le `Items` champ qui accepte un tableau JSON, un objet JSON ou une JSONata expression qui doit être évaluée en tableau ou en objet.
### 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. \$1
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` paramètre est défini sur`JSONata`, les anciens champs de I/O traitement seront désactivés (`InputPath``Parameters`,`ResultSelector`, `ResultPath` et`OutputPath`) et la plupart des États recevront deux nouveaux champs : `Arguments` et`Output`.
JSONata fournit un moyen plus simple d'effectuer I/O des transformations 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'état`ItemSelector`) 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`, `ResultPath``OutputPath`, 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 de passage
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
}
```
![\[Capture d'écran montrant l'entrée et la sortie d'un état testé.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/jsonata-basic-io.png)
### Exemple : Filtrer avec JSONata
Vous pouvez filtrer vos données à l'aide des [opérateurs JSONata Path](https://docs.jsonata.org/path-operators). 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"
}
]
}
```
![\[Exemple de sortie pour les JSONata expressions en cours de test.\]](http://docs.aws.amazon.com/fr_fr/step-functions/latest/dg/images/test-state-jsonata.png)
## 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.
**\$1partition -** 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) %}"
}
```
**\$1range** - 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) %}"
}
```
**\$1hash** - 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) %}"
}
```
**\$1random** - 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 [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)n'accepte pas de valeur initiale.
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**\$1uuid** - 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() %}"
}
```
**\$1parse** - 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'`$eval`est pas prise en charge dans les flux de travail Step Functions.
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```
# Accès aux données d'exécution depuis l'objet Context dans Step Functions
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
L'objet Context est une structure JSON interne disponible lors d'une exécution et contenant des informations sur votre machine à états et sur l'exécution. Le contexte fournit à vos flux de travail des informations sur leur exécution spécifique. Vos flux de travail peuvent faire référence à l'objet Context dans une JSONata expression avec`$states.context`.
## Accès à l'objet Context
**Pour accéder à l'objet Context dans JSONata**
Pour accéder à l'objet Context dans JSONata les états, `$states.context` utilisez-le dans une JSONata expression.
```
{
"ExecutionID" : "{% $states.context.Execution.Id %}"
}
```
**Pour accéder à l'objet Context dans JSONPath**
Pour accéder à l'objet Context dans JSONPath, vous devez d'abord l'ajouter `.$` à la fin de la clé pour indiquer que la valeur est un chemin. Ajoutez ensuite la valeur avec `$$.` pour sélectionner un nœud dans l'objet Context.
```
{
"ExecutionID.$": "$$.Execution.Id"
}
```
JSONPath les états peuvent faire référence au contexte (`$$.`) à partir des JSONPath champs suivants :
+ `InputPath`
+ `OutputPath`
+ `ItemsPath`(dans les états de la carte)
+ `Variable`(dans les États de Choice)
+ `ResultSelector`
+ `Parameters`
+ Opérateurs de comparaison de variables à variables
## Champs d'objets contextuels
L'objet Context inclut des informations sur la machine à états, l'état, l'exécution et la tâche. L'objet Context JSON inclut des nœuds pour chaque type de données au format suivant :
```
{
"Execution": {
"Id": "String",
"Input": {},
"Name": "String",
"RoleArn": "String",
"StartTime": "Format: ISO 8601",
"RedriveCount": Number,
"RedriveTime": "Format: ISO 8601"
},
"State": {
"EnteredTime": "Format: ISO 8601",
"Name": "String",
"RetryCount": Number
},
"StateMachine": {
"Id": "String",
"Name": "String"
},
"Task": {
"Token": "String"
}
}
```
Lors d'une exécution, l'objet Context est renseigné avec les données pertinentes.
Parfois, de nouveaux champs sont ajoutés au contexte. Si vous traitez directement le contexte JSON, nous vous recommandons de créer un code capable de gérer facilement les nouveaux champs inconnus. Par exemple, si vous utilisez la bibliothèque Jackson pour désamorcer le code JSON, nous vous recommandons de définir la `FAIL_ON_UNKNOWN_PROPERTIES` valeur `false` dans votre `ObjectMapper` pour éviter un. `UnrecognizedPropertyException`
`RedriveTime`L'objet de contexte n'est disponible que si vous avez redriven une exécution. Si c'est le cas [redriven a Map Run](redrive-map-run.md), l'objet de `RedriveTime` contexte n'est disponible que pour les flux de travail enfants de type Standard. Pour un redriven Map Run avec des flux de travail enfants de type Express, `RedriveTime` ce n'est pas disponible.
Le contenu d'une exécution en cours inclut des informations spécifiques au format suivant :
```
{
"Execution": {
"Id": "arn:aws:states:region:123456789012:execution:stateMachineName:executionName",
"Input": {
"key": "value"
},
"Name": "executionName",
"RoleArn": "arn:aws:iam::123456789012:role...",
"StartTime": "2025-08-27T10:04:42Z"
},
"State": {
"EnteredTime": "2025-08-27T10:04:42.001Z",
"Name": "Test",
"RetryCount": 3
},
"StateMachine": {
"Id": "arn:aws:states:region:123456789012:stateMachine:stateMachineName",
"Name": "stateMachineName"
},
"Task": {
"Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
}
}
```
**Format d'horodatage avec des fractions de secondes**
Step Functions suit la ISO8601 spécification qui indique que la sortie peut être de zéro, trois, six ou neuf chiffres selon les besoins. Lorsqu'un horodatage ne comporte aucune fraction de seconde, Step Functions supprime les zéros suivants au lieu de compléter la sortie.
Si vous créez du code qui utilise les horodatages de Step Functions, votre code doit être capable de traiter un nombre variable de fractions de secondes.
## Données d'objets contextuels pour les états de la carte
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Lors du traitement d'un [`Map`état](state-map.md), le contexte contient également `Index``Value`, et`Source`.
Pour chaque itération d'`Map`état, `Index` contient le numéro d'index de l'élément du tableau en cours de traitement, `Value` contient l'élément du tableau en cours de traitement et `Source` sera le chiffre InputType de`CSV`, `JSON``JSONL`, ou`PARQUET`.
Dans un `Map` état, l'objet Context inclut les données suivantes :
```
"Map": {
"Item": {
"Index" : Number,
"Key" : "String", // Only valid for JSON objects
"Value" : "String",
"Source": "String"
}
}
```
Ils ne sont disponibles que dans un `Map` état et peuvent être spécifiés dans le `ItemSelector (Carte)` champ.
**Note**
Vous devez définir les paramètres à partir de l'objet Context dans le `ItemSelector` bloc de `Map` l'état principal, et non dans les états inclus dans la `ItemProcessor` section.
Étant donné qu'une machine à états utilise un **JSONPath**`Map`état, vous pouvez injecter des informations à partir de l'objet Context comme suit.
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex.$": "$$.Map.Item.Index",
"ContextValue.$": "$$.Map.Item.Value",
"ContextSource.$": "$$.Map.Item.Source"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
En effet JSONata, les informations contextuelles supplémentaires sur l'état de la carte sont accessibles à partir de la `$states.context` variable :
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex": "{% $states.context.Map.Item.Index %}",
"ContextValue": "{% $states.context.Map.Item.Value %}",
"ContextSource": "{% $states.context.Map.Item.Source %}"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Si vous exécutez la machine d'état précédente avec l'entrée suivante, les éléments `Index` et `Value` sont insérés dans la sortie.
```
[
{
"who": "bob"
},
{
"who": "meg"
},
{
"who": "joe"
}
]
```
Le résultat de l'exécution renvoie les valeurs de `Index` et `Value` les éléments pour chacune des trois itérations, comme suit :
```
[
{
"ContextIndex": 0,
"ContextValue": {
"who": "bob"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 1,
"ContextValue": {
"who": "meg"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 2,
"ContextValue": {
"who": "joe"
},
"ContextSource" : "STATE_DATA"
}
]
```
Notez que ce `$states.context.Map.Item.Source` sera l'un des suivants :
+ Pour la saisie de l'état, la valeur sera : `STATE_DATA`
+ Pour `Amazon S3 LIST_OBJECTS_V2` with`Transformation=NONE`, la valeur indiquera l'URI S3 du compartiment. Par exemple : `S3://bucket-name`.
+ Pour tous les autres types d'entrée, la valeur sera l'URI Amazon S3. Par exemple : `S3://bucket-name/object-key`.
# Utiliser des JSONPath chemins
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Dans l'Amazon States Language, un *chemin* est une chaîne commençant par `$` laquelle vous pouvez identifier les composants dans le texte JSON. Les chemins suivent [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)la syntaxe, qui n'est disponible que lorsque le `QueryLanguage` paramètre est défini sur JSONPath. Vous pouvez spécifier un chemin pour accéder à des sous-ensembles de l'entrée lors de la spécification des valeurs pour `InputPath`, `ResultPath` et `OutputPath`.
Vous devez utiliser la notation entre crochets si le nom de votre champ contient un caractère qui n'est pas inclus dans la `member-name-shorthand` définition de la règle [JsonPath ABNF](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf). Par conséquent, pour coder des caractères spéciaux, tels que les signes de ponctuation (sauf`_`), vous devez utiliser la notation entre crochets. Par exemple, `$.abc.['def ghi']`.
## Chemins de référence
Un *chemin de référence* est un chemin dont la syntaxe est limitée de telle sorte qu'elle ne peut identifier qu'un seul nœud dans une structure JSON :
+ Vous pouvez accéder aux champs des objets uniquement en utilisant la notation point (`.`) et crochet (`[ ]`).
+ Les fonctions telles que `length()` ne sont pas prises en charge.
+ Les opérateurs lexicaux, qui ne sont pas symboliques, par exemple, `subsetof` ne sont pas pris en charge.
+ Le filtrage par expression régulière ou par référence à une autre valeur dans la structure JSON n'est pas pris en charge.
+ Les opérateurs`@`, `,``:`, et ne `?` sont pas pris en charge
Par exemple, les données d'entrée d'état contiennent les valeurs suivantes :
```
{
"foo": 123,
"bar": ["a", "b", "c"],
"car": {
"cdr": true
}
}
```
Dans ce cas, les chemins de référence suivants renverraient :
```
$.foo => 123
$.bar => ["a", "b", "c"]
$.car.cdr => true
```
Certains états utilisent des chemins d'accès et des chemins de référence pour contrôler le flux d'une machine d'état ou configurer les paramètres ou les options d'un état. Pour plus d'informations, voir [Modélisation du traitement des chemins d'entrée et de sortie du flux de travail avec un simulateur de flux de données](https://aws.amazon.com/blogs/compute/modeling-workflow-input-output-path-processing-with-data-flow-simulator/) et [Utilisation JSONPath efficace dans AWS Step Functions](https://aws.amazon.com/blogs/compute/using-jsonpath-effectively-in-aws-step-functions/).
### Aplatir un tableau de tableaux
Si l'[État du flux de travail cartographique](state-map.md)état [État du flux de travail parallèle](state-parallel.md) ou de vos machines d'état renvoie un tableau de tableaux, vous pouvez les transformer en tableau plat avec le [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) champ. Vous pouvez inclure ce champ dans la définition de l'état parallèle ou de l'état cartographique pour manipuler le résultat de ces états.
Pour aplatir les tableaux, utilisez la syntaxe : `[*]` dans le `ResultSelector` champ, comme indiqué dans l'exemple suivant.
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
Pour des exemples illustrant comment aplatir un tableau, reportez-vous à l'*étape 3* des didacticiels suivants :
+ [Traitement de données par lots avec une fonction Lambda dans Step Functions](tutorial-itembatcher-param-task.md)
+ [Traitement d'éléments individuels avec une fonction Lambda dans Step Functions](tutorial-itembatcher-single-item-process.md)
# Manipulation des paramètres dans les flux de travail Step Functions
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Les `ResultSelector` champs`InputPath`, `Parameters` et permettent de manipuler le JSON au fur et à mesure qu'il se déplace dans votre flux de travail. `InputPath`peut limiter l'entrée transmise en filtrant la notation JSON à l'aide d'un chemin (voir[Utiliser des JSONPath chemins](amazon-states-language-paths.md)). Avec le `Parameters` champ, vous pouvez transmettre une collection de paires clé-valeur, en utilisant soit des valeurs statiques, soit des sélections provenant de l'entrée à l'aide d'un chemin.
Le `ResultSelector` champ permet de manipuler le résultat de l'état avant `ResultPath` son application.
AWS Step Functionsapplique d'abord `InputPath` le champ, puis le `Parameters` champ. Vous pouvez d'abord filtrer vos données d'entrée brutes que vous souhaitez à l'aide de `InputPath`, puis appliquer `Parameters` pour manipuler davantage cette entrée, ou pour ajouter de nouvelles valeurs. Vous pouvez ensuite utiliser le `ResultSelector` champ pour manipuler la sortie de l'état avant `ResultPath` son application.
## InputPath
Utilisez `InputPath` pour sélectionner une partie de l'entrée de l'état.
Par exemple, si l'entrée de votre état comprend les éléments suivants :
```
{
"comment": "Example for InputPath.",
"dataset1": {
"val1": 1,
"val2": 2,
"val3": 3
},
"dataset2": {
"val1": "a",
"val2": "b",
"val3": "c"
}
}
```
Vous pouvez appliquer le `InputPath`.
```
"InputPath": "$.dataset2",
```
Avec le précédent `InputPath`, ce qui suit est le JSON transmis en tant qu'entrée.
```
{
"val1": "a",
"val2": "b",
"val3": "c"
}
```
**Note**
Un chemin peut produire une sélection de valeurs. Prenez l’exemple de code suivant.
```
{ "a": [1, 2, 3, 4] }
```
Si vous appliquez le chemin `$.a[0:2]`, le résultat est le suivant :
```
[ 1, 2 ]
```
## Parameters
Cette section décrit les différentes manières d'utiliser le champ Paramètres.
### Paires clé-valeur
Utilisez le `Parameters` champ pour créer une collection de paires clé-valeur qui sont transmises en entrée. Les valeurs de chacune peuvent être soit des valeurs statiques que vous incluez dans la définition de votre machine à états, soit sélectionnées dans l'entrée ou dans l'objet Context avec un chemin. Pour les paires clé-valeur dans lesquelles la valeur est sélectionnée à l'aide d'un chemin, le nom de clé doit se terminer par `.$`.
Par exemple, supposons que vous fournissiez les entrées suivantes.
```
{
"comment": "Example for Parameters.",
"product": {
"details": {
"color": "blue",
"size": "small",
"material": "cotton"
},
"availability": "in stock",
"sku": "2317",
"cost": "$23"
}
}
```
Pour sélectionner certaines informations, vous pouvez spécifier ces paramètres dans la définition de votre machine d'état.
```
"Parameters": {
"comment": "Selecting what I care about.",
"MyDetails": {
"size.$": "$.product.details.size",
"exists.$": "$.product.availability",
"StaticValue": "foo"
}
},
```
Soit les entrées précédentes et le champ `Parameters`, il s'agit du JSON qui est transmis.
```
{
"comment": "Selecting what I care about.",
"MyDetails": {
"size": "small",
"exists": "in stock",
"StaticValue": "foo"
}
},
```
Outre l'entrée, vous pouvez accéder à un objet JSON spécial, appelé objet Context. L'objet Context inclut des informations sur l'exécution de votre machine à états. Consultez [Accès aux données d'exécution depuis l'objet Context dans Step Functions](input-output-contextobject.md).
### Ressources connectées
Le champ `Parameters` peut également transmettre des informations aux ressources connectées. Par exemple, si l'état de votre tâche orchestre une AWS Batch tâche, vous pouvez transmettre les paramètres d'API pertinents directement aux actions d'API de ce service. Pour en savoir plus, consultez :
+ [Transmission de paramètres à une API de service dans Step Functions](connect-parameters.md)
+ [Intégration des services ](integrate-services.md)
### Amazon S3
Si les données de la fonction Lambda que vous transmettez entre les états peuvent atteindre plus de 262 144 octets, nous vous recommandons d'utiliser Amazon S3 pour stocker les données et d'implémenter l'une des méthodes suivantes :
+ Utilisez l'*état de la carte distribuée* dans votre flux de travail afin que l'`Map`état puisse lire les entrées directement depuis les sources de données Amazon S3. Pour de plus amples informations, veuillez consulter [Mode distribué](state-map-distributed.md).
+ Analysez le nom Amazon Resource (ARN) du bucket dans le `Payload` paramètre pour obtenir le nom du bucket et la valeur clé. Pour de plus amples informations, veuillez consulter [Utiliser Amazon S3 ARNs au lieu de transmettre des charges utiles importantes dans Step Functions](sfn-best-practices.md#avoid-exec-failures).
Vous pouvez également ajuster votre implémentation pour transmettre des charges utiles plus faibles lors de vos exécutions.
## ResultSelector
Utilisez le `ResultSelector` champ pour manipuler le résultat d'un état avant qu'`ResultPath`il ne soit appliqué. Le `ResultSelector` champ vous permet de créer une collection de paires clé-valeur, dont les valeurs sont statiques ou sélectionnées à partir du résultat de l'état. À l'aide du `ResultSelector` champ, vous pouvez choisir les parties du résultat d'un état que vous souhaitez transmettre au `ResultPath` champ.
**Note**
Avec le `ResultPath` champ, vous pouvez ajouter la sortie du `ResultSelector` champ à l'entrée d'origine.
`ResultSelector`est un champ facultatif dans les états suivants :
+ [État du flux de travail cartographique](state-map.md)
+ [État du flux de travail des tâches](state-task.md)
+ [État du flux de travail parallèle](state-parallel.md)
Par exemple, les intégrations du service Step Functions renvoient des métadonnées en plus de la charge utile contenue dans le résultat. `ResultSelector`peut sélectionner des parties du résultat et les fusionner avec l'entrée d'état avec`ResultPath`. Dans cet exemple, nous voulons sélectionner uniquement le `resourceType` et`ClusterId`, puis le fusionner avec l'entrée d'état d'un Amazon EMR CreateCluster.sync. Compte tenu de ce qui suit :
```
{
"resourceType": "elasticmapreduce",
"resource": "createCluster.sync",
"output": {
"SdkHttpMetadata": {
"HttpHeaders": {
"Content-Length": "1112",
"Content-Type": "application/x-amz-JSON-1.1",
"Date": "Mon, 25 Nov 2019 19:41:29 GMT",
"x-amzn-RequestId": "1234-5678-9012"
},
"HttpStatusCode": 200
},
"SdkResponseMetadata": {
"RequestId": "1234-5678-9012"
},
"ClusterId": "AKIAIOSFODNN7EXAMPLE"
}
}
```
Vous pouvez ensuite sélectionner `resourceType` et `ClusterId` en utilisant `ResultSelector` :
```
"Create Cluster": {
"Type": "Task",
"Resource": "arn:aws:states:::elasticmapreduce:createCluster.sync",
"Parameters": {
},
"ResultSelector": {
"ClusterId.$": "$.output.ClusterId",
"ResourceType.$": "$.resourceType"
},
"ResultPath": "$.EMROutput",
"Next": "Next Step"
}
```
Avec l'entrée donnée, l'utilisation `ResultSelector` produit :
```
{
"OtherDataFromInput": {},
"EMROutput": {
"ClusterId": "AKIAIOSFODNN7EXAMPLE",
"ResourceType": "elasticmapreduce",
}
}
```
### Aplatir un tableau de tableaux
Si l'[État du flux de travail cartographique](state-map.md)état [État du flux de travail parallèle](state-parallel.md) ou de vos machines d'état renvoie un tableau de tableaux, vous pouvez les transformer en tableau plat avec le [ResultSelector](#input-output-resultselector) champ. Vous pouvez inclure ce champ dans la définition de l'état parallèle ou de l'état cartographique pour manipuler le résultat de ces états.
Pour aplatir les tableaux, utilisez la syntaxe : `[*]` dans le `ResultSelector` champ, comme indiqué dans l'exemple suivant.
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
Pour des exemples illustrant comment aplatir un tableau, reportez-vous à l'*étape 3* des didacticiels suivants :
+ [Traitement de données par lots avec une fonction Lambda dans Step Functions](tutorial-itembatcher-param-task.md)
+ [Traitement d'éléments individuels avec une fonction Lambda dans Step Functions](tutorial-itembatcher-single-item-process.md)
# Exemple : manipulation de données d'état à l'aide de chemins dans les flux de travail Step Functions
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états à l'aide de variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Cette rubrique contient des exemples de manipulation du JSON d'entrée et de sortie d'état à l'aide des OutputPath champs InputPath ResultPath, et.
Tout état autre qu'un [État du flux de travail défaillant](state-fail.md) état ou un [État du flux de travail réussi](state-succeed.md) état peut inclure les champs de traitement d'entrée et de sortie, tels que `InputPath``ResultPath`, ou`OutputPath`. De plus, les [État du flux de travail choisi](state-choice.md) états [État du flux de travail en attente](state-wait.md) et ne prennent pas en charge le `ResultPath` champ. Avec ces champs, vous pouvez utiliser a [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)pour filtrer les données JSON au fur et à mesure qu'elles se déplacent dans votre flux de travail.
Vous pouvez également utiliser le `Parameters` champ pour manipuler les données JSON au fur et à mesure qu'elles se déplacent dans votre flux de travail. Pour obtenir des informations sur l'utilisation d'`Parameters`, veuillez consulter [Manipulation des paramètres dans les flux de travail Step Functions](input-output-inputpath-params.md).
Par exemple, commencez par la AWS Lambda fonction et la machine à états décrites dans le [Création d'une machine d'état Step Functions utilisant Lambda](tutorial-creating-lambda-state-machine.md) didacticiel. Modifiez la machine d'état afin qu'elle comprenne les éléments `InputPath`, `ResultPath` et `OutputPath` suivants.
```
{
"Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:HelloFunction",
"InputPath": "$.lambda",
"ResultPath": "$.data.lambdaresult",
"OutputPath": "$.data",
"End": true
}
}
}
```
Commencez une exécution avec l'entrée suivante.
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
Supposons que les `extra` nœuds `comment` et peuvent être supprimés, mais que vous souhaitez inclure le résultat de la fonction Lambda et conserver les informations dans `data` le nœud.
Dans la machine d'état mise à jour, l'état `Task` est modifié pour traiter l'entrée pour la tâche.
```
"InputPath": "$.lambda",
```
Cette ligne dans la définition de la machine d'état limite l'entrée de tâche au nœud `lambda` de l'entrée d'état uniquement. La fonction Lambda reçoit uniquement l'objet JSON `{"who": "AWS Step Functions"}` en entrée.
```
"ResultPath": "$.data.lambdaresult",
```
Cela `ResultPath` indique à la machine à états d'insérer le résultat de la fonction Lambda dans un nœud nommé`lambdaresult`, en tant qu'enfant du `data` nœud dans l'entrée de la machine à états d'origine. Comme vous n'effectuez aucune autre manipulation sur l'entrée d'origine et sur le résultat en utilisant`OutputPath`, la sortie de l'état inclut désormais le résultat de la fonction Lambda avec l'entrée d'origine.
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
Mais notre objectif était de ne conserver que le `data` nœud et d'inclure le résultat de la fonction Lambda. `OutputPath`filtre ce JSON combiné avant de le transmettre à la sortie d'état.
```
"OutputPath": "$.data",
```
Ainsi, seul le nœud `data` de l'entrée d'origine est sélectionné (y compris l'enfant `lambdaresult` inséré par `ResultPath`) comme devant être transmis à la sortie. La sortie de l'état est filtrée sur ce qui suit.
```
{
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
}
```
Dans cet état `Task` :
1. `InputPath`envoie uniquement le `lambda` nœud de l'entrée à la fonction Lambda.
1. `ResultPath` insère le résultat en tant qu'enfant du nœud `data` dans l'entrée d'origine.
1. `OutputPath`filtre l'entrée d'état (qui inclut désormais le résultat de la fonction Lambda) afin qu'elle ne transmette que le `data` nœud à la sortie d'état.
**Example pour manipuler l'entrée, le résultat et la sortie finale de la machine à états d'origine en utilisant JsonPath**
Prenons l'exemple de la machine d'État suivante qui vérifie l'identité et l'adresse d'un demandeur d'assurance.
Pour voir l'exemple complet, consultez [How to use JSON Path in Step Functions](https://github.com/aws-samples/serverless-account-signup-service).
```
{
"Comment": "Sample state machine to verify an applicant's ID and address",
"StartAt": "Verify info",
"States": {
"Verify info": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "Verify identity",
"States": {
"Verify identity": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-identity:$LATEST"
},
"End": true
}
}
},
{
"StartAt": "Verify address",
"States": {
"Verify address": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-address:$LATEST"
},
"End": true
}
}
}
]
}
}
}
```
Si vous exécutez cette machine à états en utilisant l'entrée suivante, l'exécution échoue car les fonctions Lambda qui effectuent la vérification attendent uniquement les données à vérifier en entrée. Par conséquent, vous devez spécifier les nœuds qui contiennent les informations à vérifier à l'aide d'une méthode appropriée JsonPath.
```
{
"data": {
"firstname": "Jane",
"lastname": "Doe",
"identity": {
"email": "jdoe@example.com",
"ssn": "123-45-6789"
},
"address": {
"street": "123 Main St",
"city": "Columbus",
"state": "OH",
"zip": "43219"
},
"interests": [
{
"category": "home",
"type": "own",
"yearBuilt": 2004
},
{
"category": "boat",
"type": "snowmobile",
"yearBuilt": 2020
},
{
"category": "auto",
"type": "RV",
"yearBuilt": 2015
},
]
}
}
```
Pour spécifier le nœud que la fonction `check-identity` Lambda doit utiliser, utilisez le `InputPath` champ comme suit :
```
"InputPath": "$.data.identity"
```
Et pour spécifier le nœud que la fonction `check-address` Lambda doit utiliser, utilisez le `InputPath` champ comme suit :
```
"InputPath": "$.data.address"
```
Maintenant, si vous souhaitez enregistrer le résultat de la vérification dans l'entrée de la machine à états d'origine, utilisez le `ResultPath` champ comme suit :
```
"ResultPath": "$.results"
```
Toutefois, si vous n'avez besoin que des résultats d'identité et de vérification et que vous supprimez l'entrée d'origine, utilisez le `OutputPath` champ comme suit :
```
"OutputPath": "$.results"
```
Pour de plus amples informations, veuillez consulter [Traitement des entrées et des sorties dans Step Functions](concepts-input-output-filtering.md).
## Filtrer la sortie d'état à l'aide OutputPath
`OutputPath`Vous pouvez sélectionner une partie de l'état de sortie à passer à l'état suivant. Cette approche vous permet de filtrer les informations indésirables et de ne transmettre que la partie du JSON dont vous avez besoin.
Si vous ne spécifiez pas une valeur `OutputPath`, la valeur par défaut est `$`. Cela transmet la totalité du nœud JSON (déterminé par l'état d'entrée, la tâche et les résultats `ResultPath`) à l'état suivant.
# Spécification de la sortie d'état à l'aide ResultPath de in Step Functions
**Gestion de l'état et transformation des données**
Cette page fait référence à JSONPath. Step Functions a récemment ajouté des variables et JSONata permet de gérer l'état et de transformer les données.
Découvrez comment [transmettre des données avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
La sortie d'un état peut être une copie de son entrée, le résultat qu'il génère (par exemple, la sortie d'une fonction Lambda pour l'état d'une `Task`) ou une combinaison de l'entrée et du résultat. Utilisez `ResultPath` pour contrôler les combinaisons de ces stratégies transmises à la sortie de l'état.
Les types d'état suivants peuvent générer un résultat et peuvent inclure `ResultPath:`
+ [Passer l'état du flux de travail](state-pass.md)
+ [État du flux de travail des tâches](state-task.md)
+ [État du flux de travail parallèle](state-parallel.md)
+ [État du flux de travail cartographique](state-map.md)
Utilisez `ResultPath` pour combiner un résultat de tâche avec une entrée de tâche ou pour sélectionner l'une de ces règles. Le chemin que vous fournissez à `ResultPath` détermine quelles informations sont transmises à la sortie.
**Note**
`ResultPath`est limité à l'utilisation de [chemins de référence](amazon-states-language-paths.md#amazon-states-language-reference-paths), qui limitent la portée, de sorte que le chemin ne doit identifier qu'un seul nœud en JSON. Voir [Chemins de référence](amazon-states-language-paths.md#amazon-states-language-reference-paths) dans le document [Langage des états d'Amazon](concepts-amazon-states-language.md).
## ResultPath À utiliser pour remplacer l'entrée par le résultat de la tâche
Si vous ne spécifiez pas a`ResultPath`, le comportement par défaut est le même que`"ResultPath": "$"`. L'état remplacera l'intégralité de l'entrée d'état par le résultat de la tâche.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$"
# Task result
"Hello, Step Functions!"
# State Output
"Hello, Step Functions!"
```
**Note**
`ResultPath` est utilisé pour inclure du contenu issu du résultat avec les données d'entrée, avant de les transmettre à la sortie. Mais, si `ResultPath` ce n'est pas spécifié, l'action par défaut consiste à remplacer l'intégralité de l'entrée.
## Ignorer le résultat et conserver l'entrée d'origine
Si vous réglez `ResultPath` sur`null`, l'état transmettra l'**entrée d'origine** à la sortie. La charge utile d'entrée de l'état sera copiée directement sur la sortie, sans tenir compte du résultat de la tâche.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": null
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
```
## ResultPath À utiliser pour inclure le résultat dans l'entrée
Si vous spécifiez un chemin pour ResultPath, la sortie d'état combinera l'entrée d'état et le résultat de la tâche :
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.taskresult"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions",
"taskresult" : "Hello, Step Functions!"
}
```
Vous pouvez également insérer le résultat dans un nœud enfant de l'entrée. Définissez `ResultPath` comme suit.
```
"ResultPath": "$.strings.lambdaresult"
```
Compte tenu des informations suivantes :
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz"
},
"who": "AWS Step Functions"
}
```
Le résultat de la tâche serait inséré en tant qu'enfant du `strings` nœud dans l'entrée.
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz",
"lambdaresult": "Hello, Step Functions!"
},
"who": "AWS Step Functions"
}
```
La sortie de l'état inclut désormais le JSON d'entrée d'origine avec le résultat sous forme d'un nœud enfant.
## ResultPath À utiliser pour mettre à jour un nœud dans l'entrée avec le résultat
Si vous spécifiez un nœud existant pour ResultPath, le résultat de la tâche remplacera ce nœud existant :
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.comment"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "Hello, Step Functions!",
"details": "Default example",
"who" : "Step Functions"
}
```
## ResultPath À utiliser pour inclure à la fois une erreur et une entrée dans un `Catch`
Dans certains cas, il se peut que vous souhaitiez conserver l'entrée d'origine avec l'erreur. Utilisez `ResultPath` dans un champ `Catch` pour inclure l'erreur avec l'entrée d'origine, au lieu de la remplacer :
```
"Catch": [{
"ErrorEquals": ["States.ALL"],
"Next": "NextTask",
"ResultPath": "$.error"
}]
```
Si l'instruction `Catch` précédente intercepte une erreur, elle inclut le résultat dans un nœud `error` avec l'entrée d'état. Par exemple, pour l'entrée suivante :
```
{"foo": "bar"}
```
La sortie de l'état lors de l'interception de l'erreur est :
```
{
"foo": "bar",
"error": {
"Error": "Error here"
}
}
```
Pour plus d'informations sur la gestion des erreurs, voir :
+ [Gestion des erreurs dans les flux de travail Step Functions](concepts-error-handling.md)
+ [Gestion des conditions d'erreur dans une machine à états Step Functions](tutorial-handling-error-conditions.md)
# Mappez les champs d'entrée et de sortie d'état dans Step Functions
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Les états de la carte sont itérés sur un ensemble d'éléments d'un jeu de données. Voici des exemples d'ensembles de données :
+ Tableaux JSON et objets des états précédents.
+ Fichiers de données individuels stockés dans Amazon S3 dans des formats tels que : JSON, JSONL, CSV, fichiers Parquet.
+ Des références à plusieurs objets, tels que les manifestes Athena et les fichiers d'inventaire Amazon S3
Une carte répète une série d'étapes pour chaque élément du jeu de données. Vous pouvez configurer l'entrée qu'il `Map state` reçoit et la sortie générée par la carte à l'aide de diverses options de configuration. Step Functions applique chaque option dans *l'état de votre carte distribuée* dans l'ordre indiqué dans la liste suivante. Selon votre cas d'utilisation, il se peut que vous n'ayez pas besoin d'appliquer tous les champs.
1. [ItemReader (Carte)](input-output-itemreader.md)- utilisé pour lire vos éléments de données
1. [ItemsPath (Carte, JSONPath uniquement)](input-output-itemspath.md)ou **Items (JSONata)** - facultatif ; utilisé pour spécifier des éléments dans votre ensemble de données
1. [ItemSelector (Carte)](input-output-itemselector.md)- facultatif ; utilisé pour sélectionner et modifier des éléments de l'ensemble de données
1. [ItemBatcher (Carte)](input-output-itembatcher.md)- utilisé pour traiter des groupes d'éléments lors du traitement de grands ensembles d'articles
1. [ResultWriter (Carte)](input-output-resultwriter.md)- fournit des options pour la sortie de résultats à partir de flux de travail secondaires
# ItemReader (Carte)
Le `ItemReader` champ est un objet JSON qui spécifie un ensemble de données et son emplacement. *L'état d'une carte distribuée* utilise ce jeu de données comme entrée.
L'exemple suivant montre la syntaxe du `ItemReader` champ dans un flux de travail **JSONPathbasé**, pour un ensemble de données dans un fichier délimité par du texte stocké dans un compartiment Amazon S3.
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csvDataset/ratings.csv",
"VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
}
}
```
Dans le flux de travail **JSONatabasé sur** le suivant, notez qu'`Parameters`il est remplacé par **Arguments**.
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Arguments": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csvDataset/ratings.csv"
"VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
}
}
```
## Contenu du ItemReader champ
Le contenu du `ItemReader` champ varie en fonction de votre jeu de données. Par exemple, si votre ensemble de données est un tableau JSON transmis lors d'une étape précédente du flux de travail, le `ItemReader` champ est omis. Si votre ensemble de données est une source de données Amazon S3, ce champ contient les sous-champs suivants.
**`Resource`**
L'action d'intégration de l'API Amazon S3 que Step Functions utilisera, telle que `arn:aws:states:::s3:getObject`
**`Arguments (JSONata) or Parameters (JSONPath)`**
Objet JSON qui spécifie le nom du compartiment Amazon S3 et la clé d'objet dans lesquels l'ensemble de données est stocké.
Si le contrôle de version est activé sur le compartiment, vous pouvez également fournir la version de l'objet Amazon S3.
**`ReaderConfig`**
Un objet JSON qui spécifie les détails suivants :
+ `InputType`
Accepte l'une des valeurs suivantes :`CSV`,`JSON`,`JSONL`,`PARQUET`,`MANIFEST`.
Spécifie le type de source de données Amazon S3, tel qu'un fichier délimité par du texte (`CSV`), un objet, un fichier JSON, des lignes JSON, un fichier Parquet, un manifeste Athena ou une liste d'inventaire Amazon S3. Dans Workflow Studio, vous pouvez sélectionner un type d'entrée à partir de la **source d'éléments S3**.
La plupart des types d'entrée qui utilisent la `S3GetObject` récupération prennent également en charge `VersionId` les champs `ExpectedBucketOwner` et les champs dans leurs paramètres. Les fichiers Parquet sont la seule exception qui ne soit pas prise en charge`VersionId`.
Les fichiers d'entrée prennent en charge les types de compression externes suivants : GZIP, ZSTD.
Exemples de noms de fichiers : `myObject.jsonl.gz` et`myObject.csv.zstd`.
Remarque : Les fichiers Parquet sont un type de fichier binaire compressé en interne. Les compressions GZIP, ZSTD et Snappy sont prises en charge.
+ `Transformation`
*Facultatif*. La valeur sera soit `NONE` ou soit`LOAD_AND_FLATTEN`.
Si elle n'est pas spécifiée, elle `NONE` sera prise en compte. Lorsque ce paramètre est défini sur`LOAD_AND_FLATTEN`, vous devez également définir`InputType`.
Comportement par défaut, la carte itère sur les **objets de métadonnées** renvoyés par les appels à`S3:ListObjectsV2`. Lorsqu'il est défini sur`LOAD_AND_FLATTEN`, la carte lit et traite les **objets de données** réels référencés dans la liste des résultats.
+ `ManifestType`
*Facultatif*. La valeur sera soit `ATHENA_DATA` ou soit`S3_INVENTORY`.
Remarque : Si ce paramètre est défini sur`S3_INVENTORY`, vous **ne devez pas** également le spécifier `InputType` car le type est supposé être`CSV`.
+ `CSVDelimiter`
Vous pouvez spécifier ce champ quand `InputType` est `CSV` ou`MANIFEST`.
Accepte l'une des valeurs suivantes : `COMMA` (par défaut)`PIPE`,`SEMICOLON`,`SPACE`,`TAB`.
**Note**
Ce `CSVDelimiter` champ `ItemReader` permet de traiter des fichiers délimités par des caractères autres que des virgules. Les références aux « fichiers CSV » incluent également les fichiers qui utilisent des délimiteurs alternatifs spécifiés par le `CSVDelimiter` champ.
+ `CSVHeaderLocation`
Vous pouvez spécifier ce champ quand `InputType` est `CSV` ou`MANIFEST`.
Accepte l'une des valeurs suivantes pour spécifier l'emplacement de l'en-tête de colonne :
+ `FIRST_ROW`— Utilisez cette option si la première ligne du fichier est l'en-tête.
+ `GIVEN`— Utilisez cette option pour spécifier l'en-tête dans la définition de la machine à états.
Par exemple, si votre fichier contient les données suivantes.
```
1,307,3.5,1256677221
1,481,3.5,1256677456
1,1091,1.5,1256677471
...
```
Vous pouvez fournir le tableau JSON suivant sous forme d'en-tête CSV :
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "GIVEN",
"CSVHeaders": [
"userId",
"movieId",
"rating",
"timestamp"
]
}
}
```
**Taille de l'en-tête CSV**
Step Functions prend en charge des en-têtes allant jusqu'à 10 KiB pour les fichiers délimités par du texte.
+ `ItemsPointer`
*Facultatif*. Vous pouvez spécifier ce champ à `InputType` quel moment`JSON`.
`ItemsPointer`utilise JSONPointer la syntaxe pour sélectionner un tableau ou un objet spécifique imbriqué dans votre fichier JSON. JSONPointer est une syntaxe standardisée conçue exclusivement pour la navigation et le référencement d'emplacements dans des documents JSON.
JSONPointer la syntaxe utilise des barres obliques (/) pour séparer chaque niveau d'imbrication, les indices des tableaux étant représentés sous forme de nombres sans crochets. Par exemple :
+ `/Data/Contents`- fait référence au tableau Contents dans l'objet Data
+ `/Data/Contents/0`- référence le premier élément du tableau Contents
La position de départ du tableau cible doit se situer dans les 16 premiers Mo du fichier JSON, et le JSONPointer chemin doit comporter moins de 2 000 caractères.
Par exemple, si votre fichier JSON contient :
```
{"data": {"items": [{"id": 1}, {"id": 2}]}}
```
Vous devez spécifier `"ItemsPointer": "/data/items"` de traiter le tableau d'éléments.
+ `MaxItems`
Par défaut, l'`Map`état itère sur tous les éléments de l'ensemble de données spécifié. En configurant`MaxItems`, vous pouvez limiter le nombre d'éléments de données transmis à l'`Map`état. Par exemple, si vous fournissez un fichier délimité par du texte contenant 1 000 lignes et que vous définissez une limite de 100 lignes, l'interpréteur *ne transmet que* 100 lignes à l'*état Carte distribuée*. L'`Map`état traite les éléments dans un ordre séquentiel, en commençant après la ligne d'en-tête.
Pour les **JSONPath**flux de travail, vous pouvez utiliser `MaxItemsPath` un *chemin de référence vers* une paire clé-valeur dans l'entrée d'état qui se résout en un entier. Notez que vous pouvez spécifier l'un `MaxItems` ou l'autre`MaxItemsPath`, mais pas **les deux**.
**Note**
Vous pouvez définir une limite maximale de 100 000 000 après laquelle il `Distributed Map` arrête de lire des éléments.
**Exigences relatives au compte et à la région**
Vos compartiments Amazon S3 doivent se trouver dans le même emplacement Compte AWS Région AWS que votre machine d'état.
Notez que même si votre machine d'état peut accéder à des fichiers dans des compartiments situés dans différents Comptes AWS compartiments se trouvant dans le même emplacement Région AWS, Step Functions prend uniquement en charge la mise en liste des objets dans les compartiments Amazon S3 qui se trouvent à la *fois* dans la même Compte AWS machine Région AWS que la machine à états.
## Traitement des ensembles de données imbriqués (mis à jour le 11 septembre 2025)
Avec le nouveau `Transformation` paramètre, vous pouvez spécifier une valeur de `LOAD_AND_FLATTEN` et la carte lira les objets de données **réels** référencés dans la liste des résultats d'un appel à`S3:ListObjectsV2`.
Avant cette version, vous deviez créer des cartes distribuées imbriquées pour **récupérer** les métadonnées, puis **traiter** les données réelles. La première carte passerait en revue les **métadonnées** renvoyées par les flux de travail enfants `S3:ListObjectsV2` et invoquerait ces derniers. Une autre carte au sein de chaque machine à états fils lirait les **données réelles** provenant de fichiers individuels. Avec l'option de transformation, vous pouvez effectuer les deux étapes en même temps.
Imaginez que vous souhaitiez effectuer un audit quotidien sur les 24 derniers fichiers journaux que votre système produit toutes les heures et stocke dans Amazon S3. L'état de votre carte distribuée peut répertorier les fichiers journaux`S3:ListObjectsV2`, puis effectuer une itération sur les *métadonnées* de chaque objet, ou il peut désormais charger et analyser les objets de **données réels** stockés dans votre compartiment Amazon S3.
L'utilisation de `LOAD_AND_FLATTEN` cette option permet d'augmenter l'évolutivité, de réduire le nombre d'exécutions de carte ouvertes et de traiter plusieurs objets simultanément. Les tâches Athena et Amazon EMR génèrent généralement des résultats qui peuvent être traités avec la nouvelle configuration.
Voici un exemple des paramètres d'une `ItemReader` définition :
```
{
"QueryLanguage": "JSONata",
"States": {
...
"Map": {
...
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"ReaderConfig": {
// InputType is required if Transformation is LOAD_AND_FLATTEN.
"InputType": "CSV | JSON | JSONL | PARQUET",
// Transformation is OPTIONAL and defaults to NONE if not present
"Transformation": "NONE | LOAD_AND_FLATTEN"
},
"Arguments": {
"Bucket": "amzn-s3-demo-bucket1",
"Prefix": "{% $states.input.PrefixKey %}"
}
},
...
}
}
```
## Exemples de jeux de données
Vous pouvez définir l'une des options suivantes comme jeu de données :
+ [Données JSON d'une étape précédente](#itemsource-json-array)
+ [Liste des objets Amazon S3](#itemsource-example-s3-object-data)
+ [Objets Amazon S3 transformés par LOAD\$1AND\$1FLATTEN](#itemsource-example-s3-object-data-flatten)
+ [Fichier JSON dans un compartiment Amazon S3](#itemsource-example-json-data)
+ [Fichier JSON Lines dans un compartiment Amazon S3](#itemsource-example-json-lines-data)
+ [Fichier CSV dans un compartiment Amazon S3](#itemsource-example-csv-data)
+ [Fichier Parquet dans un compartiment Amazon S3](#itemsource-example-parquet-data)
+ [Manifeste d'Athéna (traitement de plusieurs éléments)](#itemsource-example-athena-manifest-data)
+ [Inventaire Amazon S3 (traitement de plusieurs articles)](#itemsource-example-s3-inventory)
**Note**
Step Functions a besoin des autorisations appropriées pour accéder aux ensembles de données Amazon S3 que vous utilisez. Pour plus d'informations sur les politiques IAM relatives aux ensembles de données, consultez. [Recommandations de politique IAM pour les ensembles de données](#itemreader-iam-policies)
### Données JSON d'une étape précédente
*L'état d'une carte distribuée* peut accepter une entrée JSON transmise depuis une étape précédente du flux de travail.
L'entrée peut être un tableau JSON, un objet JSON ou un tableau au sein d'un nœud d'un objet JSON.
Step Functions itérera directement sur les éléments d'un tableau ou sur les paires clé-valeur d'un objet JSON.
Pour sélectionner un nœud spécifique contenant un tableau ou un objet JSON imbriqué à partir de l'entrée, vous pouvez utiliser le `ItemsPath (Carte, JSONPath uniquement)` ou utiliser une JSONata expression dans le `Items` champ pour les JSONata états.
Pour traiter des éléments individuels, l'*état de la carte distribuée lance l'*exécution d'un flux de travail secondaire pour chaque élément. Les onglets suivants présentent des exemples d'entrée transmise à l'`Map`état et d'entrée correspondante à l'exécution d'un flux de travail enfant.
**Note**
Le `ItemReader` champ n'est pas nécessaire lorsque votre ensemble de données est constitué de données JSON issues d'une étape précédente.
------
#### [ Input passed to the Map state ]
Considérez le tableau JSON suivant de trois éléments.
```
"facts": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "mostly-true",
"statement_date": "5/18/2016",
"statement_source": "news"
}
]
```
------
#### [ Input passed to a child workflow execution ]
L'*état de la carte distribuée* lance trois exécutions de flux de travail secondaires. Chaque exécution reçoit un élément de tableau en entrée. L'exemple suivant montre l'entrée reçue par l'exécution d'un flux de travail enfant.
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Liste des objets Amazon S3
*L'état d'une carte distribuée* peut être itéré sur les objets stockés dans un compartiment Amazon S3. Lorsque l'exécution du flux de travail atteint `Map` cet état, Step Functions invoque l'action API [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html), qui renvoie un tableau des **métadonnées de l'objet** Amazon S3. Dans ce tableau, chaque élément contient des données, telles que **ETag**et **Key**, pour les données réellement stockées dans le compartiment.
Pour traiter les éléments individuels du tableau, l'*état de la carte distribuée lance l'*exécution d'un flux de travail enfant. Supposons, par exemple, que votre compartiment Amazon S3 contienne 100 images. Ensuite, le tableau renvoyé après avoir appelé l'action d'`ListObjectsV2`API contient 100 éléments de métadonnées. L'*état de la carte distribuée* lance ensuite 100 exécutions de flux de travail secondaires pour traiter chaque élément.
**Pour traiter des objets de données directement, sans flux de travail imbriqués, vous pouvez choisir l'option de transformation LOAD\$1AND\$1FLATTEN pour traiter directement les éléments.**
**Note**
Step Functions inclura également un élément pour chaque **dossier** créé dans le compartiment Amazon S3 à l'aide de la **console** Amazon S3. Les éléments du dossier entraînent le lancement d'exécutions supplémentaires de flux de travail secondaires.
Pour éviter de créer des exécutions de flux de travail secondaires supplémentaires pour chaque dossier, nous vous recommandons d'utiliser le AWS CLI pour créer des dossiers. Pour plus d'informations, consultez la section [Commandes Amazon S3 de haut niveau](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-buckets-creating) dans le *guide de AWS Command Line Interface l'utilisateur*.
Step Functions a besoin des autorisations appropriées pour accéder aux ensembles de données Amazon S3 que vous utilisez. Pour plus d'informations sur les politiques IAM relatives aux ensembles de données, consultez. [Recommandations de politique IAM pour les ensembles de données](#itemreader-iam-policies)
Les onglets suivants présentent des exemples de syntaxe de `ItemReader` champ et d'entrée transmise à l'exécution d'un flux de travail enfant pour cet ensemble de données.
------
#### [ ItemReader syntax ]
Dans cet exemple, vous avez organisé vos données, qui incluent des images, des fichiers JSON et des objets, dans un préfixe nommé `processData` dans un compartiment Amazon S3 nommé`amzn-s3-demo-bucket`.
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Prefix": "processData"
}
}
```
------
#### [ Input passed to a child workflow execution ]
L'*état de la carte distribuée* lance autant d'exécutions de flux de travail enfants que le nombre d'éléments de métadonnées présents dans le compartiment Amazon S3. L'exemple suivant montre l'entrée reçue par l'exécution d'un flux de travail enfant.
```
{
"Etag": "\"05704fbdccb224cb01c59005bebbad28\"",
"Key": "processData/images/n02085620_1073.jpg",
"LastModified": 1668699881,
"Size": 34910,
"StorageClass": "STANDARD"
}
```
------
### Objets Amazon S3 transformés par `LOAD_AND_FLATTEN`
Grâce à la prise en charge améliorée de S3 ListObjects V2 en tant que source d'entrée dans Distributed Map, vos machines d'état peuvent lire et traiter directement plusieurs **objets de données** à partir de compartiments Amazon S3, éliminant ainsi le besoin de cartes imbriquées pour traiter les métadonnées \$1
Avec `LOAD_AND_FLATTEN` cette option, votre machine à états effectuera les opérations suivantes :
+ Lisez le **contenu réel** de chaque objet répertorié par l'`ListObjectsV2`appel Amazon S3.
+ Analysez le contenu en fonction de InputType (CSV, JSON, JSONL, Parquet).
+ Créez des éléments à partir du contenu du fichier (lignes/enregistrements) plutôt que des métadonnées.
Avec l'option de transformation, vous n'avez plus besoin de cartes distribuées imbriquées pour traiter les métadonnées. L'utilisation de l'option LOAD\$1AND\$1FLATTEN augmente l'évolutivité, réduit le nombre d'exécutions cartographiques actives et traite plusieurs objets simultanément.
La configuration suivante indique le réglage d'un `ItemReader` :
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"ReaderConfig": {
"InputType": "JSON",
"Transformation": "LOAD_AND_FLATTEN"
},
"Arguments": {
"Bucket": "S3_BUCKET_NAME",
"Prefix": "S3_BUCKET_PREFIX"
}
}
```
**Recommandation de préfixe de compartiment**
Nous vous recommandons d'ajouter une barre oblique à votre préfixe. Par exemple, si vous sélectionnez des données avec un préfixe de`folder1`, votre machine à états traitera à la fois `folder1/myData.csv` et`folder10/myData.csv`. L'utilisation ne `folder1/` traitera strictement qu'un seul dossier.
### Fichier JSON dans un compartiment Amazon S3
*L'état d'une carte distribuée* peut accepter un fichier JSON stocké dans un compartiment Amazon S3 en tant que jeu de données. Le fichier JSON doit contenir un tableau ou un objet JSON.
Lorsque l'exécution du flux de travail atteint `Map` cet état, Step Functions invoque l'action [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API pour récupérer le fichier JSON spécifié.
Si le fichier JSON contient une structure d'objet imbriquée, vous pouvez sélectionner le nœud spécifique avec votre ensemble de données avec un`ItemsPointer`. Par exemple, la configuration suivante permet d'extraire une liste imbriquée de *produits phares* en *stock*.
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "JSON",
"ItemsPointer": "/inventory/products/featured"
},
"Arguments": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "nested-data-file.json"
}
}
```
L'`Map`état itère ensuite sur chaque élément du tableau et lance l'exécution d'un flux de travail secondaire pour chaque élément. Par exemple, si votre fichier JSON contient 1 000 éléments de tableau, l'`Map`état lance 1 000 exécutions de flux de travail enfants.
**Note**
L'entrée d'exécution utilisée pour démarrer l'exécution d'un flux de travail enfant ne peut pas dépasser 256 KiB. Step Functions permet toutefois de lire un élément d'une taille maximale de 8 Mo à partir d'un fichier délimité par du texte, d'un fichier JSON ou d'un fichier JSON Lines si vous appliquez ensuite le `ItemSelector` champ facultatif pour réduire la taille de l'élément.
Step Functions prend en charge 10 Go comme taille maximale d'un fichier individuel dans Amazon S3.
Step Functions a besoin des autorisations appropriées pour accéder aux ensembles de données Amazon S3 que vous utilisez. Pour plus d'informations sur les politiques IAM relatives aux ensembles de données, consultez. [Recommandations de politique IAM pour les ensembles de données](#itemreader-iam-policies)
Les onglets suivants présentent des exemples de syntaxe de `ItemReader` champ et d'entrée transmise à l'exécution d'un flux de travail enfant pour cet ensemble de données.
Pour cet exemple, imaginez que vous avez un fichier JSON nommé`factcheck.json`. Vous avez stocké ce fichier dans un préfixe nommé `jsonDataset` dans un compartiment Amazon S3. Voici un exemple de jeu de données JSON.
```
[
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "mostly-true",
"statement_date": "5/18/2016",
"statement_source": "news"
},
...
]
```
------
#### [ ItemReader syntax ]
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "JSON"
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "jsonDataset/factcheck.json"
}
}
```
------
#### [ Input to a child workflow execution ]
L'*état de la carte distribuée* lance autant d'exécutions de flux de travail enfants que le nombre d'éléments de tableau présents dans le fichier JSON. L'exemple suivant montre l'entrée reçue par l'exécution d'un flux de travail enfant.
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Fichier JSON Lines dans un compartiment Amazon S3
*L'état d'une carte distribuée* peut accepter un fichier JSON Lines stocké dans un compartiment Amazon S3 en tant que jeu de données.
**Note**
L'entrée d'exécution utilisée pour démarrer l'exécution d'un flux de travail enfant ne peut pas dépasser 256 KiB. Step Functions permet toutefois de lire un élément d'une taille maximale de 8 Mo à partir d'un fichier délimité par du texte, d'un fichier JSON ou d'un fichier JSON Lines si vous appliquez ensuite le `ItemSelector` champ facultatif pour réduire la taille de l'élément.
Step Functions prend en charge 10 Go comme taille maximale d'un fichier individuel dans Amazon S3.
Step Functions a besoin des autorisations appropriées pour accéder aux ensembles de données Amazon S3 que vous utilisez. Pour plus d'informations sur les politiques IAM relatives aux ensembles de données, consultez. [Recommandations de politique IAM pour les ensembles de données](#itemreader-iam-policies)
Les onglets suivants présentent des exemples de syntaxe de `ItemReader` champ et d'entrée transmise à l'exécution d'un flux de travail enfant pour cet ensemble de données.
Pour cet exemple, imaginez que vous avez un fichier JSON Lines nommé`factcheck.jsonl`. Vous avez stocké ce fichier dans un préfixe nommé `jsonlDataset` dans un compartiment Amazon S3. Voici un exemple du contenu du fichier.
```
{"verdict": "true", "statement_date": "6/11/2008", "statement_source": "speech"}
{"verdict": "false", "statement_date": "6/7/2022", "statement_source": "television"}
{"verdict": "mostly-true", "statement_date": "5/18/2016", "statement_source": "news"}
```
------
#### [ ItemReader syntax ]
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "JSONL"
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "jsonlDataset/factcheck.jsonl"
}
}
```
------
#### [ Input to a child workflow execution ]
L'*état Distributed Map* lance autant d'exécutions de flux de travail enfants que le nombre de lignes présentes dans le fichier JSONL. L'exemple suivant montre l'entrée reçue par l'exécution d'un flux de travail enfant.
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Fichier CSV dans un compartiment Amazon S3
**Note**
Ce `CSVDelimiter` champ `ItemReader` permet de traiter des fichiers délimités par des caractères autres que des virgules. Les références aux « fichiers CSV » incluent également les fichiers qui utilisent des délimiteurs alternatifs spécifiés par le `CSVDelimiter` champ.
*L'état d'une carte distribuée* peut accepter un fichier délimité par du texte stocké dans un compartiment Amazon S3 en tant que jeu de données. Si vous utilisez un fichier délimité par du texte comme ensemble de données, vous devez spécifier un en-tête de colonne. Pour plus d'informations sur la manière de spécifier un en-tête, consultez[Contenu du ItemReader champ](#itemreader-field-contents).
Step Functions analyse les fichiers délimités par du texte selon les règles suivantes :
+ Le délimiteur qui sépare les champs est spécifié par `CSVDelimiter` in *ReaderConfig*. Le délimiteur est défini par défaut sur. `COMMA`
+ **Les nouvelles lignes sont un séparateur qui sépare les enregistrements.**
+ Les champs sont traités comme des chaînes. Pour les conversions de type de données, utilisez la fonction `States.StringToJson` intrinsèque dans[ItemSelector (Carte)](input-output-itemselector.md).
+ Les guillemets doubles (» «) ne sont pas obligatoires pour entourer les chaînes. Toutefois, les chaînes placées entre guillemets doubles peuvent contenir des virgules et des nouvelles lignes sans agir comme des délimiteurs d'enregistrement.
+ Vous pouvez conserver les guillemets doubles en les répétant.
+ Les barres obliques inverses (\$1) constituent un autre moyen d'échapper aux caractères spéciaux. Les barres obliques inverses ne fonctionnent qu'avec les autres barres obliques inverses, les guillemets doubles et le séparateur de champs configuré tel que la virgule ou le tube. Une barre oblique inversée suivie de tout autre caractère est supprimée silencieusement.
+ Vous pouvez conserver les barres obliques inverses en les répétant. Par exemple :
```
path,size
C:\\Program Files\\MyApp.exe,6534512
```
+ Les barres obliques inverses qui échappent aux guillemets doubles (`\"`) ne fonctionnent que lorsqu'elles sont incluses par paires. Nous vous recommandons donc d'éviter les guillemets doubles en les répétant :. `""`
+ Si le nombre de champs d'une ligne est **inférieur** au nombre de champs de l'en-tête, Step Functions fournit des **chaînes vides** pour les valeurs manquantes.
+ Si le nombre de champs d'une ligne est **supérieur** au nombre de champs de l'en-tête, Step Functions **ignore** les champs supplémentaires.
Pour plus d'informations sur la façon dont Step Functions analyse un fichier délimité par du texte, consultez. [Example of parsing an input CSV file](example-csv-parse-dist-map.md#example-csv-parse)
Lorsque l'exécution du flux de travail atteint `Map` cet état, Step Functions invoque l'action [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API pour récupérer le fichier spécifié. L'`Map`état itère ensuite sur chaque ligne du fichier et lance l'exécution d'un flux de travail enfant pour traiter les éléments de chaque ligne. Supposons, par exemple, que vous fournissiez un fichier délimité par du texte contenant 100 lignes en entrée. Ensuite, l'interpréteur passe chaque ligne à l'`Map`état. L'`Map`état traite les éléments par ordre de série, en commençant après la ligne d'en-tête.
**Note**
L'entrée d'exécution utilisée pour démarrer l'exécution d'un flux de travail enfant ne peut pas dépasser 256 KiB. Step Functions permet toutefois de lire un élément d'une taille maximale de 8 Mo à partir d'un fichier délimité par du texte, d'un fichier JSON ou d'un fichier JSON Lines si vous appliquez ensuite le `ItemSelector` champ facultatif pour réduire la taille de l'élément.
Step Functions prend en charge 10 Go comme taille maximale d'un fichier individuel dans Amazon S3.
Step Functions a besoin des autorisations appropriées pour accéder aux ensembles de données Amazon S3 que vous utilisez. Pour plus d'informations sur les politiques IAM relatives aux ensembles de données, consultez. [Recommandations de politique IAM pour les ensembles de données](#itemreader-iam-policies)
Les onglets suivants présentent des exemples de syntaxe de `ItemReader` champ et d'entrée transmise à l'exécution d'un flux de travail enfant pour cet ensemble de données.
------
#### [ ItemReader syntax ]
Supposons, par exemple, que vous ayez un fichier CSV nommé`ratings.csv`. Vous avez ensuite stocké ce fichier dans un préfixe nommé `csvDataset` dans un compartiment Amazon S3.
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW",
"CSVDelimiter": "PIPE"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csvDataset/ratings.csv"
}
}
```
------
#### [ Input to a child workflow execution ]
L'*état de la carte distribuée* lance autant d'exécutions de flux de travail enfants que le nombre de lignes présentes dans le fichier CSV, à l'exception de la ligne d'en-tête, si elle se trouve dans le fichier. L'exemple suivant montre l'entrée reçue par l'exécution d'un flux de travail enfant.
```
{
"rating": "3.5",
"movieId": "307",
"userId": "1",
"timestamp": "1256677221"
}
```
------
### Fichier Parquet dans un compartiment Amazon S3
Les fichiers Parquet peuvent être utilisés comme source d'entrée. Les fichiers Apache Parquet stockés dans Amazon S3 permettent un traitement efficace des données en colonnes à grande échelle.
Lorsque vous utilisez des fichiers Parquet, les conditions suivantes s'appliquent :
+ 256 Mo est la taille maximale du groupe de lignes et 5 Mo est la taille maximale du pied de page. Si vous fournissez des fichiers d'entrée qui dépassent l'une ou l'autre de ces limites, votre machine d'état renverra une erreur d'exécution.
+ Le `VersionId` champ **n'est pas** pris en charge pour`InputType=Parquet`.
+ Les compressions de données internes GZIP, ZSTD et Snappy sont prises en charge de manière native. Aucune extension de nom de fichier n'est nécessaire.
Voici un exemple de configuration ASL pour `InputType` set to Parquet :
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "PARQUET"
},
"Arguments": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "my-parquet-data-file-1.parquet"
}
}
```
**Traitement des tâches à grande échelle**
Pour les travaux à très grande échelle, Step Functions utilisera de nombreux lecteurs d'entrée. Les lecteurs entrelacent leur traitement, ce qui peut amener certains lecteurs à faire une pause tandis que d'autres progressent. Une progression intermittente est un comportement attendu à grande échelle.
### Manifeste d'Athéna (traitement de plusieurs éléments)
Vous pouvez utiliser les fichiers manifestes d'Athena, générés à partir des résultats des `UNLOAD` requêtes, pour spécifier la **source** des fichiers de données pour l'état de votre carte. Vous avez réglé `ManifestType` sur`ATHENA_DATA`, et `InputType` sur l'un ou `CSV` l'autre`JSONL`, ou`Parquet`.
Lors de l'exécution d'une `UNLOAD` requête, Athena génère un fichier manifeste de données en plus des objets de données réels. Le fichier manifeste fournit une liste CSV structurée des fichiers de données. Le manifeste et les fichiers de données sont enregistrés dans l'emplacement des résultats de votre requête Athena dans Amazon S3.
```
UNLOAD () TO 'S3_URI_FOR_STORING_DATA_OBJECT' WITH (format = 'JSON')
```
Aperçu conceptuel du processus, en bref :
1. Sélectionnez vos données dans une table à l'aide d'une `UNLOAD` requête dans Athena.
1. Athena générera un fichier manifeste (CSV) et les objets de données dans Amazon S3.
1. Configurez Step Functions pour lire le fichier manifeste et traiter les entrées.
La fonctionnalité peut traiter les formats de sortie CSV, JSONL et Parquet d'Athena. Tous les objets référencés dans un seul fichier manifeste doivent avoir le même InputType format. Notez que les objets CSV exportés par une `UNLOAD` requête n'incluent **pas** d'en-tête dans la première ligne. Vérifiez `CSVHeaderLocation` si vous devez fournir des en-têtes de colonne.
Le contexte de la carte inclura également un `$states.context.Map.Item.Source` afin que vous puissiez personnaliser le traitement en fonction de la source des données.
Voici un exemple de configuration d'un fichier `ItemReader` configuré pour utiliser un manifeste Athena :
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"ManifestType": "ATHENA_DATA",
"InputType": "CSV | JSONL | PARQUET"
},
"Arguments": {
"Bucket": "",
"Key": "-manifest.csv"
}
}
```
**Utilisation du modèle de manifeste Athena dans Workflow Studio**
Un scénario courant de traitement des données applique une carte aux données provenant d'une requête Athena UNLOAD. La carte invoque une fonction Lambda pour traiter chaque élément décrit dans le manifeste d'Athena. Step Functions Workflow Studio fournit un modèle prêt à l'emploi qui combine tous ces composants dans un bloc que vous pouvez faire glisser sur le canevas de votre machine à états.
### Inventaire S3 (traitement de plusieurs articles)
Un *état de carte distribuée* peut accepter un fichier manifeste d'inventaire Amazon S3 stocké dans un compartiment Amazon S3 en tant que jeu de données.
Lorsque l'exécution du flux de travail atteint son `Map` état, Step Functions invoque l'action [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API pour récupérer le fichier manifeste d'inventaire Amazon S3 spécifié.
Par défaut, l'`Map`état effectue ensuite une itération sur les **objets** de l'inventaire pour renvoyer un tableau de métadonnées des objets d'inventaire Amazon S3.
Si vous spécifiez ManifestType S3\$1INVENTORY, cela InputType ne peut pas être spécifié.
**Note**
Step Functions prend en charge 10 Go comme taille maximale d'un fichier individuel dans un rapport d'inventaire Amazon S3 après décompression. Step Functions peut toutefois traiter plus de 10 Go si la taille de chaque fichier est inférieure à 10 Go.
Step Functions a besoin des autorisations appropriées pour accéder aux ensembles de données Amazon S3 que vous utilisez. Pour plus d'informations sur les politiques IAM relatives aux ensembles de données, consultez. [Recommandations de politique IAM pour les ensembles de données](#itemreader-iam-policies)
Voici un exemple de fichier d'inventaire au format CSV. Ce fichier inclut les objets nommés `csvDataset` et`imageDataset`, qui sont stockés dans un compartiment Amazon S3 nommé`amzn-s3-demo-source-bucket`.
```
"amzn-s3-demo-source-bucket","csvDataset/","0","2022-11-16T00:27:19.000Z"
"amzn-s3-demo-source-bucket","csvDataset/titles.csv","3399671","2022-11-16T00:29:32.000Z"
"amzn-s3-demo-source-bucket","imageDataset/","0","2022-11-15T20:00:44.000Z"
"amzn-s3-demo-source-bucket","imageDataset/n02085620_10074.jpg","27034","2022-11-15T20:02:16.000Z"
...
```
**Important**
Step Functions ne prend pas en charge un rapport d'inventaire Amazon S3 défini par l'utilisateur sous forme de jeu de données.
Le format de sortie de votre rapport d'inventaire Amazon S3 doit être CSV.
Pour plus d'informations sur les inventaires Amazon S3 et sur la façon de les configurer, consultez [Amazon S3 Inventory](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html).
L'exemple suivant de fichier manifeste d'inventaire Amazon S3 montre les en-têtes CSV pour les métadonnées des objets d'inventaire.
```
{
"sourceBucket" : "amzn-s3-demo-source-bucket",
"destinationBucket" : "arn:aws:s3:::amzn-s3-demo-inventory",
"version" : "2016-11-30",
"creationTimestamp" : "1668560400000",
"fileFormat" : "CSV",
"fileSchema" : "Bucket, Key, Size, LastModifiedDate",
"files" : [ {
"key" : "amzn-s3-demo-bucket/destination-prefix/data/20e55de8-9c21-45d4-99b9-46c732000228.csv.gz",
"size" : 7300,
"MD5checksum" : "a7ff4a1d4164c3cd55851055ec8f6b20"
} ]
}
```
Les onglets suivants présentent des exemples de syntaxe de `ItemReader` champ et d'entrée transmise à l'exécution d'un flux de travail enfant pour cet ensemble de données.
------
#### [ ItemReader syntax ]
```
"ItemReader": {
"ReaderConfig": {
"InputType": "MANIFEST"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Key": "destination-prefix/amzn-s3-demo-bucket/config-id/YYYY-MM-DDTHH-MMZ/manifest.json"
}
}
```
------
#### [ Input to a child workflow execution ]
```
{
"LastModifiedDate": "2022-11-16T00:29:32.000Z",
"Bucket": "amzn-s3-demo-source-bucket",
"Size": "3399671",
"Key": "csvDataset/titles.csv"
}
```
Selon les champs que vous avez sélectionnés lors de la configuration du rapport d'inventaire Amazon S3, le contenu de votre `manifest.json` fichier peut être différent de celui de l'exemple.
------
## Recommandations de politique IAM pour les ensembles de données
Lorsque vous créez des flux de travail avec la console Step Functions, Step Functions peut générer automatiquement des politiques IAM en fonction des ressources figurant dans votre définition de flux de travail. Les politiques générées incluent le minimum de privilèges nécessaires pour permettre au rôle de machine d'état d'invoquer l'action d'`[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)`API pour l'*état de la carte distribuée* et les AWS ressources d'accès, telles que les buckets et les objets Amazon S3, ainsi que les fonctions Lambda.
Nous vous recommandons de n'inclure que les autorisations nécessaires dans vos politiques IAM. Par exemple, si votre flux de travail inclut un `Map` état en mode distribué, limitez vos politiques au compartiment et au dossier Amazon S3 spécifiques qui contiennent vos données.
**Important**
Si vous spécifiez un compartiment et un objet Amazon S3, ou un préfixe, avec un [chemin de référence vers](amazon-states-language-paths.md#amazon-states-language-reference-paths) une paire clé-valeur existante dans l'entrée d'*état de votre carte distribuée*, assurez-vous de mettre à jour les politiques IAM pour votre flux de travail. Élargissez les politiques jusqu'au bucket et aux noms d'objets auxquels le chemin aboutit au moment de l'exécution.
Les exemples suivants présentent des techniques permettant d'accorder le minimum de privilèges requis pour accéder à vos ensembles de données Amazon S3 à l'aide des actions [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) et [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API.
**Example condition utilisant un objet Amazon S3 comme ensemble de données**
La condition suivante accorde le moins de privilèges pour accéder aux objets d'un `processImages` dossier d'un compartiment Amazon S3.
```
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ],
"Condition": {
"StringLike": {
"s3:prefix": [ "processImages" ]
}
}
```
**Example utilisation d'un fichier CSV en tant que jeu de données**
L'exemple suivant montre les actions requises pour accéder à un fichier CSV nommé`ratings.csv`.
```
"Action": [ "s3:GetObject" ],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/csvDataset/ratings.csv"
]
```
**Example utilisation d'un inventaire Amazon S3 en tant que jeu de données**
Vous trouverez ci-dessous des exemples de ressources pour un manifeste d'inventaire Amazon S3 et des fichiers de données.
```
"Resource": [
"arn:aws:s3:::myPrefix/amzn-s3-demo-bucket/myConfig-id/YYYY-MM-DDTHH-MMZ/manifest.json",
"arn:aws:s3:::myPrefix/amzn-s3-demo-bucket/myConfig-id/data/*"
]
```
**Example utilisation de la ListObjects V2 pour se limiter à un préfixe de dossier**
Lors de l'utilisation de la [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html), deux politiques seront générées. L'une est nécessaire pour permettre de **répertorier** le contenu du compartiment (`ListBucket`) et une autre politique autorisera la **récupération d'objets** dans le compartiment (`GetObject`).
Vous trouverez ci-dessous des exemples d'actions, de ressources et de conditions :
```
"Action": [ "s3:ListBucket" ],
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ],
"Condition": {
"StringLike": {
"s3:prefix": [ "/path/to/your/json/" ]
}
}
```
```
"Action": [ "s3:GetObject" ],
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/path/to/your/json/*" ]
```
Notez que cela ne `GetObject` sera pas délimité et que vous utiliserez un caractère générique (`*`) pour l'objet.
# ItemsPath (Carte, JSONPath uniquement)
**Gestion de l'état et transformation des données**
Cette page fait référence à JSONPath. Step Functions a récemment ajouté des variables et JSONata permet de gérer l'état et de transformer les données.
Découvrez comment [transmettre des données avec des variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Dans les états JSONPath basés, utilisez le `ItemsPath` champ pour sélectionner un tableau ou un objet dans une entrée JSON fournie à un `Map` état. Par défaut, l'`Map`état est défini `ItemsPath` sur`$`, ce qui sélectionne l'intégralité de l'entrée.
+ Si l'entrée de l'`Map`état est un tableau JSON, il exécute une itération pour chaque élément du tableau, en transmettant cet élément à l'itération en tant qu'entrée
+ Si l'entrée de l'`Map`état est un objet JSON, il exécute une itération pour chaque paire clé-valeur de l'objet, en transmettant la paire à l'itération en entrée
**Note**
Vous ne pouvez l'utiliser `ItemsPath` dans l'*état de carte distribuée* que si vous utilisez une entrée JSON transmise depuis un état précédent dans le flux de travail.
La valeur de `ItemsPath` doit être un [chemin de référence](amazon-states-language-paths.md#amazon-states-language-reference-paths), et ce chemin doit être évalué comme un tableau ou un objet JSON. Par exemple, imaginons l’entrée d’un état `Map` qui inclut deux tableaux, comme dans l'exemple suivant.
```
{
"ThingsPiratesSay": [
{
"say": "Avast!"
},
{
"say": "Yar!"
},
{
"say": "Walk the Plank!"
}
],
"ThingsGiantsSay": [
{
"say": "Fee!"
},
{
"say": "Fi!"
},
{
"say": "Fo!"
},
{
"say": "Fum!"
}
]
}
```
Dans ce cas, vous pouvez spécifier le tableau à utiliser pour les itérations `Map` d'états en le sélectionnant avec`ItemsPath`. La définition de machine à états suivante spécifie le `ThingsPiratesSay` tableau dans l'entrée à l'`ItemsPath`aide de .Il exécute ensuite une itération de l'état de `SayWord` passe pour chaque élément du `ThingsPiratesSay` tableau.
```
{
"StartAt": "PiratesSay",
"States": {
"PiratesSay": {
"Type": "Map",
"ItemsPath": "$.ThingsPiratesSay",
"ItemProcessor": {
"StartAt": "SayWord",
"States": {
"SayWord": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Pour les objets JSON imbriqués, vous pouvez `ItemsPath` les utiliser pour sélectionner un objet spécifique dans l'entrée. Tenez compte de l'entrée suivante avec des données de configuration imbriquées :
```
{
"environment": "production",
"servers": {
"web": {
"server1": {"port": 80, "status": "active"},
"server2": {"port": 8080, "status": "inactive"}
},
"database": {
"primary": {"host": "db1.example.com", "port": 5432},
"replica": {"host": "db2.example.com", "port": 5432}
}
}
}
```
Pour effectuer une itération sur l'objet du serveur Web, vous devez définir ce qui suit `ItemsPath` : `$.servers.web`
```
{
"StartAt": "ProcessWebServers",
"States": {
"ProcessWebServers": {
"Type": "Map",
"ItemsPath": "$.servers.web",
"ItemProcessor": {
"StartAt": "CheckServer",
"States": {
"CheckServer": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Lors du traitement de l'entrée, l'`Map`état s'applique `ItemsPath` ensuite [`InputPath`](input-output-inputpath-params.md#input-output-inputpath). Il agit sur l'entrée effective de l'état après avoir `InputPath` filtré l'entrée.
Pour plus d'informations sur les états `Map`, consultez les sections suivantes.
+ [État de mappage](state-map.md)
+ [Modes de traitement de l'état des cartes](state-map.md#concepts-map-process-modes)
+ [Répéter les actions avec Inline Map](tutorial-map-inline.md)
+ [Traitement d'entrée et de sortie d'`Map`état en ligne](state-map-inline.md#inline-map-state-output)
# ItemSelector (Carte)
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états à l'aide de variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Par défaut, l'entrée effective pour l'`Map`état est l'ensemble des éléments de données individuels présents dans l'entrée d'état brute. Ce `ItemSelector` champ vous permet de remplacer les valeurs des éléments de données avant qu'elles ne soient transmises à l'`Map`État.
Pour remplacer les valeurs, spécifiez une entrée JSON valide contenant une collection de paires clé-valeur. Les paires peuvent être des valeurs statiques fournies dans la définition de votre machine à états, des valeurs sélectionnées à partir de l'entrée d'état à l'aide d'un [chemin](amazon-states-language-paths.md) ou des valeurs accessibles depuis l'[objet Context](input-output-contextobject.md).
Si vous spécifiez des paires clé-valeur à l'aide d'un chemin ou d'un objet de contexte, le nom de la clé doit se terminer par. `.$`
**Note**
Le `ItemSelector` champ remplace le `Parameters` champ au sein de l'`Map`État. Si vous utilisez le `Parameters` champ dans les définitions de votre `Map` état pour créer des entrées personnalisées, nous vous recommandons de le remplacer par`ItemSelector`.
Vous pouvez spécifier le `ItemSelector` champ à la fois dans un état de *carte intégrée et dans un état* de *carte distribuée*.
Par exemple, considérez l'entrée JSON suivante qui contient un tableau de trois éléments dans le `imageData` nœud. Pour chaque *itération d'`Map`état*, un élément de tableau est transmis à l'itération en entrée.
```
[
{
"resize": "true",
"format": "jpg"
},
{
"resize": "false",
"format": "png"
},
{
"resize": "true",
"format": "jpg"
}
]
```
À l'aide de `ItemSelector` ce champ, vous pouvez définir une entrée JSON personnalisée pour remplacer l'entrée d'origine, comme indiqué dans l'exemple suivant. Step Functions transmet ensuite cette entrée personnalisée à chaque *itération `Map` d'état*. L'entrée personnalisée contient une valeur statique `size` et la valeur des données d'un objet Context pour `Map` l'état. L'objet `$$.Map.Item.Value` Context contient la valeur de chaque élément de données individuel.
```
{
"ItemSelector": {
"size": 10,
"value.$": "$$.Map.Item.Value"
}
}
```
L'exemple suivant montre l'entrée reçue par une itération de l'état de la *carte intégrée* :
```
{
"size": 10,
"value": {
"resize": "true",
"format": "jpg"
}
}
```
**Astuce**
Pour un exemple complet d'*état de carte distribuée* utilisant le `ItemSelector` champ, consultez[Copier un CSV à grande échelle à l'aide d'une carte](tutorial-map-distributed.md).
# ItemBatcher (Carte)
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états à l'aide de variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Le `ItemBatcher` champ est un objet JSON qui indique de traiter un groupe d'éléments dans le cadre d'une exécution de flux de travail enfant unique. Utilisez le traitement par lots lors du traitement de fichiers CSV ou de tableaux JSON volumineux, ou de grands ensembles d'objets Amazon S3.
L'exemple suivant montre la syntaxe du `ItemBatcher` champ. Dans la syntaxe suivante, le nombre maximum d'éléments que chaque exécution de flux de travail enfant doit traiter est fixé à 100.
```
{
"ItemBatcher": {
"MaxItemsPerBatch": 100
}
}
```
Par défaut, chaque élément d'un ensemble de données est transmis en tant qu'entrée à des exécutions de flux de travail enfants individuelles. Supposons, par exemple, que vous spécifiez un fichier JSON en entrée contenant le tableau suivant :
```
[
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "true",
"statement_date": "5/18/2016",
"statement_source": "news"
},
...
]
```
Pour l'entrée donnée, chaque exécution de flux de travail enfant reçoit un élément de tableau en entrée. L'exemple suivant montre l'entrée d'une exécution de flux de travail enfant :
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
Pour optimiser les performances et le coût de votre tâche de traitement, sélectionnez une taille de lot qui équilibre le nombre d'articles par rapport au temps de traitement des articles. Si vous utilisez le traitement par lots, Step Functions ajoute les éléments à un tableau d'**éléments**. Il transmet ensuite le tableau en entrée à chaque exécution du flux de travail enfant. L'exemple suivant montre un lot de deux éléments transmis en entrée à l'exécution d'un flux de travail enfant :
```
{
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
}
]
}
```
**Astuce**
Pour en savoir plus sur l'utilisation du `ItemBatcher` champ dans vos flux de travail, essayez les didacticiels et ateliers suivants :
[Traitement d'un lot complet de données dans une fonction Lambda](tutorial-itembatcher-param-task.md)
[Itérer sur les éléments d'un lot dans le cadre d'exécutions de flux de travail secondaires](tutorial-itembatcher-single-item-process.md)
[Carte distribuée et ressources connexes](https://catalog.workshops.aws/stepfunctions/use-cases/distributed-map) dans *The AWS Step Functions Workshop*
**Contents**
+ [Champs pour spécifier le traitement par lots d'articles](#input-output-itembatcher-subfields)
## Champs pour spécifier le traitement par lots d'articles
Pour regrouper des articles, spécifiez le nombre maximum d'articles à regrouper, la taille maximale du lot, ou les deux. Vous devez spécifier l'une de ces valeurs pour les articles par lots.
**Nombre maximum d'articles par lot**
Spécifie le nombre maximum d'éléments traités par chaque exécution de flux de travail enfant. L'interpréteur limite le nombre d'éléments groupés dans le `Items` tableau à cette valeur. Si vous spécifiez à la fois un numéro de lot et une taille, l'interpréteur réduit le nombre d'articles dans un lot pour éviter de dépasser la limite de taille de lot spécifiée.
Si vous ne spécifiez pas cette valeur mais que vous fournissez une valeur pour la taille de lot maximale, Step Functions traite autant d'éléments que possible lors de chaque exécution du flux de travail enfant sans dépasser la taille de lot maximale en octets.
Par exemple, imaginez que vous exécutiez une exécution avec un fichier JSON d'entrée contenant 1 130 nœuds. Si vous spécifiez une valeur maximale de 100 articles pour chaque lot, Step Functions crée 12 lots. Parmi ceux-ci, 11 lots contiennent 100 articles chacun, tandis que le douzième lot contient les 30 articles restants.
Vous pouvez également spécifier le nombre maximum d'éléments pour chaque lot comme [chemin de référence vers](amazon-states-language-paths.md#amazon-states-language-reference-paths) une paire clé-valeur existante dans l'entrée d'*état de votre carte distribuée*. Ce chemin doit être résolu en un entier positif.
Par exemple, avec les données d'entrée suivantes :
```
{
"maxBatchItems": 500
}
```
Vous pouvez spécifier le nombre maximum d'articles à regrouper en utilisant un chemin de référence (**JSONPath uniquement**) comme suit :
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxItemsPerBatchPath": "$.maxBatchItems"
}
...
...
}
}
```
Pour les états **JSONatabasés**, vous pouvez également fournir une JSONata expression dont le résultat est un entier positif.
Vous pouvez spécifier le `MaxItemsPerBatch` ou le `MaxItemsPerBatchPath (JSONPath only)` sous-champ, mais pas les deux.
**Nombre maximal de KiB par lot**
Spécifie la taille maximale d'un lot en octets, jusqu'à 256 KiB. Si vous spécifiez à la fois un numéro de lot et une taille maximum, Step Functions réduit le nombre d'articles dans un lot pour éviter de dépasser la limite de taille de lot spécifiée.
Vous pouvez également spécifier la taille de lot maximale comme [chemin de référence vers](amazon-states-language-paths.md#amazon-states-language-reference-paths) une paire clé-valeur existante dans l'entrée d'*état de votre carte distribuée*. Ce chemin doit être résolu en un entier positif.
Si vous utilisez le traitement par lots et que vous ne spécifiez pas de taille de lot maximale, l'interpréteur traite autant d'éléments qu'il peut traiter jusqu'à 256 KiB lors de chaque exécution de flux de travail enfant.
Par exemple, avec les données d'entrée suivantes :
```
{
"batchSize": 131072
}
```
Vous pouvez spécifier la taille de lot maximale à l'aide d'un chemin de référence comme suit :
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxInputBytesPerBatchPath": "$.batchSize"
}
...
...
}
}
```
Pour les états **JSONatabasés**, vous pouvez également fournir une JSONata expression dont le résultat est un entier positif.
Vous pouvez spécifier le sous-champ `MaxInputBytesPerBatch` ou le `MaxInputBytesPerBatchPath` (JSONPath seul) sous-champ, mais pas les deux.
**Saisie par lots**
Vous pouvez également éventuellement spécifier une entrée JSON fixe à inclure dans chaque lot transmis à chaque exécution de flux de travail enfant. Step Functions fusionne cette entrée avec celle de chaque exécution de flux de travail enfant individuelle. Par exemple, étant donné la saisie fixe suivante d'une date de vérification des faits sur un tableau d'éléments :
```
"ItemBatcher": {
"BatchInput": {
"factCheck": "December 2022"
}
}
```
Chaque exécution d'un flux de travail enfant reçoit les informations suivantes en entrée :
```
{
"BatchInput": {
"factCheck": "December 2022"
},
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
...
]
}
```
Pour les états **JSONatabasés**, vous pouvez fournir des JSONata expressions directement ou utiliser des JSONata expressions dans des objets ou des tableaux JSON. BatchInput
# ResultWriter (Carte)
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états à l'aide de variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Le `ResultWriter` champ est un objet JSON qui fournit des options pour les résultats de sortie des exécutions de flux de travail enfants lancées par un état de carte distribuée. Vous pouvez spécifier différentes options de formatage pour les résultats de sortie ainsi que l'emplacement Amazon S3 où les stocker si vous choisissez de les exporter. Step Functions n'exporte pas ces résultats par défaut.
**Topics**
+ [Contenu du ResultWriter champ](#input-output-resultwriter-field-contents)
+ [Exemples](#input-output-resultwriter-examples)
+ [Exportation vers Amazon S3](#input-output-resultwriter-exporting-to-S3)
+ [Politiques IAM pour ResultWriter](#resultwriter-iam-policies)
## Contenu du ResultWriter champ
Le `ResultWriter` champ contient les sous-champs suivants. Le choix des champs détermine le format de la sortie et détermine si elle est exportée vers Amazon S3.
**`ResultWriter`**
Un objet JSON qui spécifie les détails suivants :
+ `Resource`
L'action d'API Amazon S3 invoquée par Step Functions pour exporter les résultats de l'exécution.
+ `Parameters`
Objet JSON qui spécifie le nom du compartiment Amazon S3 et le préfixe qui stocke le résultat de l'exécution.
+ `WriterConfig`
Ce champ permet de configurer les options suivantes.
+ `Transformation`
+ `NONE`- renvoie la sortie des exécutions du flux de travail enfant inchangée, en plus des métadonnées du flux de travail. Par défaut lors de l'exportation des résultats d'exécution du flux de travail enfant vers Amazon S3, cette valeur n'`WriterConfig`est pas spécifiée.
+ `COMPACT`- renvoie le résultat des exécutions du flux de travail enfant. Par défaut, lorsqu'`ResultWriter`il n'est pas spécifié.
+ `FLATTEN`- renvoie le résultat des exécutions du flux de travail enfant. Si l'exécution d'un flux de travail enfant renvoie un tableau, cette option aplatit le tableau avant de renvoyer le résultat dans une sortie d'état ou d'écrire le résultat dans un objet Amazon S3.
**Note**
Si l'exécution d'un flux de travail enfant échoue, Step Functions renvoie le résultat d'exécution inchangé. Les résultats seraient équivalents à un réglage `Transformation` sur`NONE`.
+ `OutputType`
+ `JSON`- formate les résultats sous forme de tableau JSON.
+ `JSONL`- formate les résultats sous forme de lignes JSON.
**Combinaisons de champs obligatoires**
Le `ResultWriter` champ ne peut pas être vide. Vous devez spécifier l'un de ces ensembles de sous-champs.
+ `WriterConfig`- pour prévisualiser la sortie formatée, sans enregistrer les résultats sur Amazon S3.
+ `Resource`et `Parameters` - pour enregistrer les résultats sur Amazon S3 sans mise en forme supplémentaire.
+ Les trois champs :`WriterConfig`, `Resource` et `Parameters` - pour formater la sortie et l'enregistrer sur Amazon S3.
## Exemples de configurations et résultats de transformation
Les rubriques suivantes présentent les paramètres de configuration possibles `ResultWriter` et des exemples de résultats traités à partir des différentes options de transformation.
+ [ResultWriter configurations](#input-output-resultwriter-example-configurations)
+ [Transformations](#input-output-resultwriter-example-transformations)
### Exemples de ResultWriter configurations
Les exemples suivants illustrent les configurations avec les combinaisons possibles des trois champs :`WriterConfig`, `Resources` et`Parameters`.
**Seuls les appareils privés *WriterConfig***
Cet exemple configure la manière dont la sortie d'état est présentée dans l'aperçu, avec le format de sortie et la transformation spécifiés dans le `WriterConfig` champ. Inexistants `Resource` et `Parameters` les champs, qui auraient fourni les spécifications du compartiment Amazon S3, impliquent la ressource de *sortie de l'état*. Les résultats sont transmis à l'état suivant.
```
"ResultWriter": {
"WriterConfig": {
"Transformation": "FLATTEN",
"OutputType": "JSON"
}
}
```
***Ressources* et *paramètres* uniquement**
Cet exemple exporte la sortie d'état vers le compartiment Amazon S3 spécifié, sans le formatage et la transformation supplémentaires que le `WriterConfig` champ inexistant aurait spécifiés.
```
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
```
**Les trois champs : *WriterConfig**Ressources* et *paramètres***
Cet exemple met en forme la sortie d'état conformément aux spécifications du `WriterConfig` champ. Il l'exporte également vers un compartiment Amazon S3 conformément aux spécifications des `Parameters` champs `Resource` et.
```
"ResultWriter": {
"WriterConfig": {
"Transformation": "FLATTEN",
"OutputType": "JSON"
},
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
```
### Exemples de transformations
Pour ces exemples, supposons que chaque exécution d'un flux de travail enfant renvoie une sortie, qui est un tableau d'objets.
```
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
}
]
```
Ces exemples montrent la sortie formatée pour différentes `Transformation` valeurs, avec `OutputType` of`JSON`.
**Transformation AUCUNE**
Il s'agit d'un exemple du résultat traité lorsque vous utilisez la `NONE` transformation. La sortie est inchangée et inclut les métadonnées du flux de travail.
```
[
{
"ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:da4e9fc7-abab-3b27-9a77-a277e463b709",
"Input": ...,
"InputDetails": {
"Included": true
},
"Name": "da4e9fc7-abab-3b27-9a77-a277e463b709",
"Output": "[{\"customer_id\":\"145538\",\"order_id\":\"100000\"},{\"customer_id\":\"898037\",\"order_id\":\"100001\"}]",
"OutputDetails": {
"Included": true
},
"RedriveCount": 0,
"RedriveStatus": "NOT_REDRIVABLE",
"RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven",
"StartDate": "2025-02-04T01:49:50.099Z",
"StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders",
"Status": "SUCCEEDED",
"StopDate": "2025-02-04T01:49:50.163Z"
},
...
{
"ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a",
"Input": ...,
"InputDetails": {
"Included": true
},
"Name": "f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a",
"Output": "[{\"customer_id\":\"169881\",\"order_id\":\"100005\"},{\"customer_id\":\"797471\",\"order_id\":\"100006\"}]",
"OutputDetails": {
"Included": true
},
"RedriveCount": 0,
"RedriveStatus": "NOT_REDRIVABLE",
"RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven",
"StartDate": "2025-02-04T01:49:50.135Z",
"StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders",
"Status": "SUCCEEDED",
"StopDate": "2025-02-04T01:49:50.227Z"
}
]
```
**Transformation COMPACT**
Il s'agit d'un exemple du résultat traité lorsque vous utilisez la `COMPACT` transformation. Notez qu'il s'agit de la sortie combinée des exécutions du flux de travail enfant avec la structure de tableau d'origine.
```
[
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
}
],
...,
[
{
"customer_id": "169881",
"order_id": "100005"
},
{
"customer_id": "797471",
"order_id": "100006"
}
]
]
```
**Transformation APLATIR**
Il s'agit d'un exemple du résultat traité lorsque vous utilisez la `FLATTEN` transformation. Notez qu'il s'agit de la sortie combinée des tableaux d'exécutions de flux de travail enfants aplatie en un seul tableau.
```
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
},
...
{
"customer_id": "169881",
"order_id": "100005"
},
{
"customer_id": "797471",
"order_id": "100006"
}
]
```
## Exportation vers Amazon S3
**Important**
Assurez-vous que le compartiment Amazon S3 que vous utilisez pour exporter les résultats d'un Map Run se trouve sous le même Compte AWS emplacement Région AWS que votre machine d'état. Sinon, l'exécution de votre machine d'état échouera avec l'`States.ResultWriterFailed`erreur.
L'exportation des résultats vers un compartiment Amazon S3 est utile si la taille de votre charge utile en sortie dépasse 256 KiB. Step Functions consolide toutes les données d'exécution du flux de travail enfant, telles que les entrées et sorties d'exécution, l'ARN et le statut d'exécution. Il exporte ensuite les exécutions avec le même statut vers leurs fichiers respectifs à l'emplacement Amazon S3 spécifié.
L'exemple suivant, utilisant **JSONPath**, montre la syntaxe du `ResultWriter` champ avec `Parameters` pour exporter les résultats de l'exécution du flux de travail enfant. Dans cet exemple, vous stockez les résultats dans un compartiment nommé `amzn-s3-demo-destination-bucket` dans un préfixe appelé`csvProcessJobs`.
```
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
```
Pour **JSONata**les États, `Parameters` sera remplacé par`Arguments`.
```
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Arguments": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
```
**Astuce**
Dans Workflow Studio, vous pouvez exporter les résultats d'exécution du flux de travail enfant en sélectionnant **Exporter les résultats de l'état de la carte vers Amazon S3**. Indiquez ensuite le nom du compartiment Amazon S3 et le préfixe vers lesquels vous souhaitez exporter les résultats.
Step Functions a besoin des autorisations appropriées pour accéder au bucket et au dossier dans lesquels vous souhaitez exporter les résultats. Pour plus d'informations sur la politique IAM requise, consultez[Politiques IAM pour ResultWriter](#resultwriter-iam-policies).
Si vous exportez les résultats de l'exécution du flux de travail enfant, l'exécution de *l'état de la carte distribuée* renvoie l'ARN Map Run et les données relatives au lieu d'exportation Amazon S3 au format suivant :
```
{
"MapRunArn": "arn:aws:states:us-east-2:account-id:mapRun:csvProcess/Map:ad9b5f27-090b-3ac6-9beb-243cd77144a7",
"ResultWriterDetails": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Key": "csvProcessJobs/ad9b5f27-090b-3ac6-9beb-243cd77144a7/manifest.json"
}
}
```
Step Functions exporte les exécutions avec le même statut vers leurs fichiers respectifs. Par exemple, si les exécutions du flux de travail de votre enfant se sont soldées par 500 résultats réussis et 200 échecs, Step Functions crée deux fichiers à l'emplacement Amazon S3 spécifié pour les résultats de réussite et d'échec. Dans cet exemple, le fichier de résultats de réussite contient les 500 résultats de réussite, tandis que le fichier de résultats d'échec contient les 200 résultats d'échec.
Pour une tentative d'exécution donnée, Step Functions crée les fichiers suivants dans l'emplacement Amazon S3 spécifié en fonction du résultat de votre exécution :
+ `manifest.json`— Contient les métadonnées Map Run, telles que l'emplacement d'exportation, l'ARN Map Run et des informations sur les fichiers de résultats.
Si vous avez [redriven](redrive-map-run.md)un Map Run, le `manifest.json` fichier contient des références à toutes les exécutions de flux de travail enfant réussies lors de toutes les tentatives d'exécution d'un Map Run. Toutefois, ce fichier contient des références aux exécutions échouées ou en attente pour une exécution spécifiqueredrive.
+ `SUCCEEDED_n.json`— Contient les données consolidées pour toutes les exécutions réussies de flux de travail pour enfants. *n* représente le numéro d'index du fichier. Le numéro d'index commence à 0. Par exemple, `SUCCEEDED_1.json`.
+ `FAILED_n.json`— Contient les données consolidées pour toutes les exécutions de flux de travail enfants ayant échoué, expiré ou abandonné. Utilisez ce fichier pour effectuer une restauration après un échec d'exécution. *n* représente l'index du fichier. Le numéro d'index commence à 0. Par exemple, `FAILED_1.json`.
+ `PENDING_n.json`— Contient les données consolidées pour toutes les exécutions de flux de travail enfants qui n'ont pas été démarrées en raison de l'échec ou de l'abandon du Map Run. *n* représente l'index du fichier. Le numéro d'index commence à 0. Par exemple, `PENDING_1.json`.
Step Functions prend en charge des fichiers de résultats individuels d'une capacité maximale de 5 Go. Si la taille d'un fichier dépasse 5 Go, Step Functions crée un autre fichier pour écrire les résultats d'exécution restants et ajoute un numéro d'index au nom du fichier. Par exemple, si la taille du `SUCCEEDED_0.json` fichier dépasse 5 Go, Step Functions crée un `SUCCEEDED_1.json` fichier pour enregistrer les résultats restants.
Si vous n'avez pas spécifié d'exporter les résultats de l'exécution du flux de travail enfant, l'exécution de la machine d'état renvoie un tableau des résultats d'exécution du flux de travail enfant, comme indiqué dans l'exemple suivant :
```
[
{
"statusCode": 200,
"inputReceived": {
"show_id": "s1",
"release_year": "2020",
"rating": "PG-13",
"type": "Movie"
}
},
{
"statusCode": 200,
"inputReceived": {
"show_id": "s2",
"release_year": "2021",
"rating": "TV-MA",
"type": "TV Show"
}
},
...
]
```
**Note**
Si la taille de sortie renvoyée dépasse 256 KiB, l'exécution de la machine à états échoue et renvoie une `States.DataLimitExceeded` erreur.
## Politiques IAM pour ResultWriter
Lorsque vous créez des flux de travail avec la console Step Functions, Step Functions peut générer automatiquement des politiques IAM en fonction des ressources figurant dans votre définition de flux de travail. Les politiques générées incluent le minimum de privilèges nécessaires pour permettre au rôle de machine d'état d'invoquer l'action d'`[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)`API pour l'*état de la carte distribuée* et les AWS ressources d'accès, telles que les buckets et les objets Amazon S3, ainsi que les fonctions Lambda.
Nous vous recommandons de n'inclure que les autorisations nécessaires dans vos politiques IAM. Par exemple, si votre flux de travail inclut un `Map` état en mode distribué, limitez vos politiques au compartiment et au dossier Amazon S3 spécifiques qui contiennent vos données.
**Important**
Si vous spécifiez un compartiment et un objet Amazon S3, ou un préfixe, avec un [chemin de référence vers](amazon-states-language-paths.md#amazon-states-language-reference-paths) une paire clé-valeur existante dans l'entrée d'*état de votre carte distribuée*, assurez-vous de mettre à jour les politiques IAM pour votre flux de travail. Élargissez les politiques jusqu'au bucket et aux noms d'objets auxquels le chemin aboutit au moment de l'exécution.
L'exemple de politique IAM suivant accorde le minimum de privilèges requis pour écrire les résultats de l'exécution du flux de travail de votre enfant dans un dossier nommé *csvJobs* dans un compartiment Amazon S3 à l'aide de l'action `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)` API.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-destination-bucket/csvJobs/*"
]
}
]
}
```
Si le compartiment Amazon S3 dans lequel vous écrivez le résultat de l'exécution du flux de travail enfant est chiffré à l'aide d'une AWS Key Management Service (AWS KMS) clé, vous devez inclure les AWS KMS autorisations nécessaires dans votre politique IAM. Pour de plus amples informations, veuillez consulter [Autorisations IAM pour le compartiment Amazon S3 AWS KMS key chiffré](iam-policies-eg-dist-map.md#multiupload-dmap-result-policy).
# Comment Step Functions analyse les fichiers CSV d'entrée
**Gestion de l'état et transformation des données**
Découvrez comment [transmettre des données entre états à l'aide de variables](workflow-variables.md) et [transformer des données avec JSONata](transforming-data.md).
Step Functions analyse les fichiers délimités par du texte selon les règles suivantes :
+ Le délimiteur qui sépare les champs est spécifié par `CSVDelimiter` in *ReaderConfig*. Le délimiteur est défini par défaut sur. `COMMA`
+ **Les nouvelles lignes sont un séparateur qui sépare les enregistrements.**
+ Les champs sont traités comme des chaînes. Pour les conversions de type de données, utilisez la fonction `States.StringToJson` intrinsèque dans[ItemSelector (Carte)](input-output-itemselector.md).
+ Les guillemets doubles (» «) ne sont pas obligatoires pour entourer les chaînes. Toutefois, les chaînes placées entre guillemets doubles peuvent contenir des virgules et des nouvelles lignes sans agir comme des délimiteurs d'enregistrement.
+ Vous pouvez conserver les guillemets doubles en les répétant.
+ Les barres obliques inverses (\$1) constituent un autre moyen d'échapper aux caractères spéciaux. Les barres obliques inverses ne fonctionnent qu'avec les autres barres obliques inverses, les guillemets doubles et le séparateur de champs configuré tel que la virgule ou le tube. Une barre oblique inverse suivie de tout autre caractère est supprimée silencieusement.
+ Vous pouvez conserver les barres obliques inverses en les répétant. Par exemple :
```
path,size
C:\\Program Files\\MyApp.exe,6534512
```
+ Les barres obliques inverses qui échappent aux guillemets doubles (`\"`) ne fonctionnent que lorsqu'elles sont incluses par paires. Nous vous recommandons donc d'éviter les guillemets doubles en les répétant :. `""`
+ Si le nombre de champs d'une ligne est **inférieur** au nombre de champs de l'en-tête, Step Functions fournit des **chaînes vides** pour les valeurs manquantes.
+ Si le nombre de champs d'une ligne est **supérieur** au nombre de champs de l'en-tête, Step Functions **ignore** les champs supplémentaires.
**Exemple d'analyse d'un fichier CSV d'entrée**
Supposons que vous ayez fourni un fichier CSV nommé `myCSVInput.csv` contenant une ligne en entrée. Vous avez ensuite stocké ce fichier dans un compartiment Amazon S3 nommé`amzn-s3-demo-bucket`. Le fichier CSV est le suivant.
```
abc,123,"This string contains commas, a double quotation marks (""), and a newline (
)",{""MyKey"":""MyValue""},"[1,2,3]"
```
La machine à états suivante lit ce fichier CSV et l'utilise [ItemSelector (Carte)](input-output-itemselector.md) pour convertir les types de données de certains champs.
```
{
"StartAt": "Map",
"States": {
"Map": {
"Type": "Map",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "STANDARD"
},
"StartAt": "Pass",
"States": {
"Pass": {
"Type": "Pass",
"End": true
}
}
},
"End": true,
"Label": "Map",
"MaxConcurrency": 1000,
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "GIVEN",
"CSVHeaders": [
"MyLetters",
"MyNumbers",
"MyString",
"MyObject",
"MyArray"
]
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "myCSVInput.csv"
}
},
"ItemSelector": {
"MyLetters.$": "$$.Map.Item.Value.MyLetters",
"MyNumbers.$": "States.StringToJson($$.Map.Item.Value.MyNumbers)",
"MyString.$": "$$.Map.Item.Value.MyString",
"MyObject.$": "States.StringToJson($$.Map.Item.Value.MyObject)",
"MyArray.$": "States.StringToJson($$.Map.Item.Value.MyArray)"
}
}
}
}
```
Lorsque vous exécutez cette machine à états, elle produit le résultat suivant.
```
[
{
"MyNumbers": 123,
"MyObject": {
"MyKey": "MyValue"
},
"MyString": "This string contains commas, a double quote (\"), and a newline (\n)",
"MyLetters": "abc",
"MyArray": [
1,
2,
3
]
}
]
```