Contenu du ItemReader champ Traitement des ensembles de données imbriqués (mis à jour le 11 septembre 2025)Exemples de jeux de données Recommandations de politique IAM pour les ensembles de données

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'Parametersil 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 chargeVersionId.

Les fichiers d'entrée prennent en charge les types de compression externes suivants : GZIP, ZSTD.

Exemples de noms de fichiers : myObject.jsonl.gz etmyObject.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 soitLOAD_AND_FLATTEN.

Si elle n'est pas spécifiée, elle NONE sera prise en compte. Lorsque ce paramètre est défini surLOAD_AND_FLATTEN, vous devez également définirInputType.

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 surLOAD_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 soitS3_INVENTORY.

Remarque : Si ce paramètre est défini surS3_INVENTORY, vous ne devez pas également le spécifier InputType car le type est supposé êtreCSV.
CSVDelimiter

Vous pouvez spécifier ce champ quand InputType est CSV ouMANIFEST.

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 ouMANIFEST.

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.
MaxItems

Par défaut, l'Mapétat itère sur tous les éléments de l'ensemble de données spécifié. En configurantMaxItems, 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 JSONPathflux 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'autreMaxItemsPath, 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 journauxS3: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
Liste des objets Amazon S3
Objets Amazon S3 transformés par LOAD_AND_FLATTEN
Fichier JSON dans un compartiment Amazon S3
Fichier JSON Lines dans un compartiment Amazon S3
Fichier CSV dans un compartiment Amazon S3
Fichier Parquet dans un compartiment Amazon S3
Manifeste d'Athéna (traitement de plusieurs éléments)
Inventaire Amazon S3 (traitement de plusieurs articles)

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

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 à partir d'un objet JSON, 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.

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, 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 ETaget 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'ListObjectsV2API 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_AND_FLATTEN 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 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

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.

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 !

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'ListObjectsV2appel 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_AND_FLATTEN 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 concernant le préfixe du 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 defolder1, votre machine à états traitera à la fois folder1/myData.csv etfolder10/myData.csv. L'utilisation ne folder1/ traitera strictement qu'un seul dossier.

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 GetObjectAPI 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 unItemsPointer. 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

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"
  },
  ...
]

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

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"}

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, consultezContenu du ItemReader champ.

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 dansItemSelector (Carte).
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 (\) 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. Exemples :
```
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

Lorsque l'exécution du flux de travail atteint Map cet état, Step Functions invoque l'action GetObjectAPI 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

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.

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 pourInputType=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.

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 surATHENA_DATA, et InputType sur l'un ou CSV l'autreJSONL, ouParquet.

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 (<YOUR_SELECT_QUERY>) TO 'S3_URI_FOR_STORING_DATA_OBJECT' WITH (format = 'JSON')

Aperçu conceptuel du processus, en bref :

Sélectionnez vos données dans une table à l'aide d'une UNLOAD requête dans Athena.
Athena générera un fichier manifeste (CSV) et les objets de données dans Amazon S3.
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": "<S3_BUCKET_NAME>",
      "Key": "<S3_KEY_PREFIX><QUERY_ID>-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.

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 GetObjectAPI 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_INVENTORY, 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

Voici un exemple de fichier d'inventaire au format CSV. Ce fichier inclut les objets nommés csvDataset etimageDataset, 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.

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.

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'StartExecutionAPI 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 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 et GetObjectAPI.

Exemple 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" ]
   }
}

Exemple 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"
   ]

Exemple 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/*"
   ]

Exemple utilisation de la ListObjects V2 pour se limiter à un préfixe de dossier

Lors de l'utilisation de la ListObjectsV2, 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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Configuration de l'état de la carte

ItemsPath (JSONPath)

ItemReader (Carte)

Contenu du ItemReader champ

Note

Taille de l'en-tête CSV

Note

Exigences relatives au compte et à la région

Traitement des ensembles de données imbriqués (mis à jour le 11 septembre 2025)

Exemples de jeux de données

Note

Note

Note

Recommandation concernant le préfixe du compartiment

Note

Note

Note

Note

Traitement des tâches à grande échelle

Utilisation du modèle de manifeste Athena dans Workflow Studio

Note

Important

Recommandations de politique IAM pour les ensembles de données

Important

Exemple condition utilisant un objet Amazon S3 comme ensemble de données

Exemple utilisation d'un fichier CSV en tant que jeu de données

Exemple utilisation d'un inventaire Amazon S3 en tant que jeu de données

Exemple utilisation de la ListObjects V2 pour se limiter à un préfixe de dossier