ItemReader - AWS Step Functions
Contenuto del ItemReader campoEsempi di set di datiPolitiche IAM per set di dati

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

ItemReader

IlItemReaderfield è un oggetto JSON, che specifica un set di dati e la sua posizione. UNStato della mappa distribuitautilizza questo set di dati come input. L'esempio seguente mostra la sintassi dellaItemReadercampo se il tuo set di dati è un file CSV archiviato in un bucket Amazon S3.

"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
        "Bucket": "myBucket",
        "Key": "csvDataset/ratings.csv"
    }
}
Suggerimento

In Workflow Studio, specifichi il set di dati e la sua posizione nelFonte dell'articolocampo.

Contenuto del ItemReader campo

A seconda del set di dati, il contenuto delItemReaderil campo varia. Ad esempio, se il set di dati è un array JSON passato da una fase precedente del flusso di lavoro,ItemReaderil campo è omesso. Se il set di dati è un'origine dati Amazon S3, questo campo contiene i seguenti sottocampi.

ReaderConfig

Un oggetto JSON che specifica i seguenti dettagli:

  • InputType

    Speciifica il tipo di origine dati Amazon S3, ad esempio file CSV, oggetto, file JSON o un elenco di inventario Amazon S3. In Workflow Studio, puoi selezionare un tipo di input dalFonte dell'articolo Amazon S3elenco a discesa sotto ilFonte dell'articolocampo.

  • CSVHeaderLocation

    Nota

    È necessario specificare questo campo solo se si utilizza un file CSV come set di dati.

    Accetta uno dei seguenti valori per specificare la posizione dell'intestazione della colonna:

    Importante

    Attualmente, Step Functions supporta intestazioni CSV fino a 10 KB.

    • FIRST_ROW— Usa questa opzione se la prima riga del file è l'intestazione.

    • GIVEN— Utilizzate questa opzione per specificare l'intestazione all'interno della definizione della macchina a stati. Ad esempio, se il file CSV contiene i seguenti dati.

      1,307,3.5,1256677221
1,481,3.5,1256677456
1,1091,1.5,1256677471
...

      Fornisci il seguente array JSON come intestazione CSV.

      "ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "GIVEN",
        "CSVHeaders": [
            "userId",
            "movieId",
            "rating",
            "timestamp"
        ]
    }
}
    Suggerimento

    In Workflow Studio, puoi trovare questa opzione inConfigurazione aggiuntivanelFonte dell'articolocampo.

  • MaxItems

    Limita il numero di elementi di dati trasmessi aMapstato. Ad esempio, supponiamo di fornire un file CSV contenente 1000 righe e di specificare un limite di 100. Quindi, l'interprete passasolomancano 100 righe alMapstato. LaMapstate elabora gli elementi in ordine sequenziale, a partire dalla riga di intestazione.

    Per impostazione predefinita,Maplo stato itera su tutti gli elementi del set di dati specificato.

    Nota

    Attualmente, è possibile specificare un limite fino a 100.000.000. IlStato della mappa distribuitainterrompe la lettura degli elementi che superano questo limite.

    Suggerimento

    In Workflow Studio, puoi trovare questa opzione inConfigurazione aggiuntivanelFonte dell'articolocampo.

    In alternativa, è possibile specificare unpercorso di riferimentoa una coppia chiave-valore esistente nelstato della mappa distribuitainput. Questo percorso deve risolversi in un numero intero positivo. Specificate il percorso di riferimento nelMaxItemsPathsottocampo.

    Importante

    È possibile specificare una delleMaxItemsoMaxItemsPathsottocampo, ma non entrambi.

Resource

L'azione dell'API Amazon S3 che Step Functions deve richiamare a seconda del set di dati specificato.

Parameters

Un oggetto JSON che specifica il nome del bucket Amazon S3 e la chiave dell'oggetto in cui è archiviato il set di dati.

Importante

Assicurati che i tuoi bucket Amazon S3 siano sotto gli stessiAccount AWSeRegione AWScome la tua macchina di stato.

Esempi di set di dati

È possibile specificare una delle seguenti opzioni come set di dati:

Importante

Step Functions necessita di autorizzazioni appropriate per accedere ai set di dati Amazon S3 che utilizzi. Per informazioni sulle politiche IAM per i set di dati, consultaPolitiche IAM per set di dati.

UNStato della mappa distribuitapuò accettare un input JSON della fase precedente nel flusso di lavoro. Questo input deve essere un array o deve contenere un array all'interno di un nodo specifico. Per selezionare un nodo che contiene l'array, è possibile utilizzareItemsPathcampo.

Per elaborare i singoli elementi dell'array,Stato della mappa distribuitaavvia l'esecuzione di un workflow secondario per ogni elemento dell'array. Le schede seguenti mostrano esempi dell'input passato aMapstato e l'input corrispondente all'esecuzione di un workflow secondario.

Nota

Step Functions ometteItemReadercampo quando il set di dati è un array JSON di un passaggio precedente.

Input passed to the Map state

Considera il seguente array JSON di tre elementi.

"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

LaStato della mappa distribuitaavvia tre esecuzioni di workflow secondarie. Ogni esecuzione riceve un elemento dell'array come input. L'esempio seguente mostra l'input ricevuto dall'esecuzione di un workflow secondario.

{
  "verdict": "true",
  "statement_date": "6/11/2008",
  "statement_source": "speech"
}

UNStato della mappa distribuitapuò iterare sugli oggetti archiviati in un bucket Amazon S3. Quando l'esecuzione del flusso di lavoro raggiunge ilMapstate, Step Functions invoca ilListObjectsV2Azione API, che restituisce un array di metadati degli oggetti Amazon S3. In questo array, ogni elemento contiene dati, comeETageChiave, per i dati memorizzati nel bucket.

Per elaborare singoli elementi dell'array,Stato della mappa distribuitaavvia l'esecuzione di un workflow secondario. Ad esempio, supponiamo che il bucket Amazon S3 contenga 100 immagini. Quindi, l'array è tornato dopo aver richiamato ilListObjectsV2L'azione API contiene 100 elementi. IlStato della mappa distribuitaavvia quindi 100 esecuzioni di workflow secondarie per elaborare ogni elemento dell'array.

Nota

  • Attualmente, Step Functions include anche un elemento per ogni cartella creata in un bucket Amazon S3 utilizzando la console Amazon S3. Ciò si traduce in un'esecuzione aggiuntiva del flusso di lavoro secondario avviata daStato della mappa distribuita. Per evitare di creare un'esecuzione aggiuntiva del flusso di lavoro secondario per la cartella, si consiglia di utilizzare ilAWS CLIper creare cartelle. Per ulteriori informazioni, consulta la paginaComandi Amazon S3 di alto livellonelAWS Command Line InterfaceGuida per l'utente.

  • Step Functions necessita di autorizzazioni appropriate per accedere ai set di dati Amazon S3 che utilizzi. Per informazioni sulle politiche IAM per i set di dati, consultaPolitiche IAM per set di dati.

Le schede seguenti mostrano esempi diItemReaderla sintassi del campo e l'input passato all'esecuzione di un workflow secondario per questo set di dati.

ItemReader syntax

In questo esempio, hai organizzato i dati, che includono immagini, file JSON e oggetti, all'interno di un prefisso denominatoprocessDatain un bucket Amazon S3 denominatomyBucket.

"ItemReader": {
    "Resource": "arn:aws:states:::s3:listObjectsV2",
    "Parameters": {
        "Bucket": "myBucket",
        "Prefix": "processData"
    }
}
Input passed to a child workflow execution

LaStato della mappa distribuitaavvia tante esecuzioni di workflow secondarie quanti sono gli elementi presenti nel bucket Amazon S3. L'esempio seguente mostra l'input ricevuto dall'esecuzione di un flusso di lavoro secondario.

{
  "Etag": "\"05704fbdccb224cb01c59005bebbad28\"",
  "Key": "processData/images/n02085620_1073.jpg",
  "LastModified": 1668699881,
  "Size": 34910,
  "StorageClass": "STANDARD"
}

UNStato della mappa distribuitaè in grado di accettare un file JSON archiviato in un bucket Amazon S3 come set di dati. Il file JSON deve contenere un array.

Quando l'esecuzione del flusso di lavoro raggiunge ilMapstate, Step Functions invoca ilGetObjectAzione API per recuperare il file JSON specificato. IlMapstate esegue quindi un'iterazione su ogni elemento dell'array e avvia un'esecuzione del flusso di lavoro secondario per ogni elemento. Ad esempio, se il file JSON contiene 1000 elementi dell'array,Mapstate avvia 1000 esecuzioni di workflow secondarie.

Nota

  • L'input di esecuzione utilizzato per avviare l'esecuzione di un workflow secondario non può superare i 256 KB. Tuttavia, Step Functions supporta la lettura di un elemento fino a 8 MB da un file CSV o JSON se poi si applica l'opzioneItemSelectorcampo per ridurre le dimensioni dell'articolo.

  • Attualmente, Step Functions supporta 10 GB come dimensione massima di un singolo file in un report di inventario Amazon S3. Tuttavia, Step Functions può elaborare più di 10 GB se ogni singolo file è inferiore a 10 GB.

  • Step Functions necessita di autorizzazioni appropriate per accedere ai set di dati Amazon S3 che utilizzi. Per informazioni sulle politiche IAM per i set di dati, consultaPolitiche IAM per set di dati.

Le schede seguenti mostrano esempi diItemReaderla sintassi del campo e l'input passato all'esecuzione di un workflow secondario per questo set di dati.

In questo esempio, immagina di avere un file JSON di nomefactcheck.json. Hai memorizzato questo file all'interno di un prefisso denominatojsonDatasetin un bucket Amazon S3. Di seguito è riportato un esempio del set di dati 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": "myBucket",
        "Key": "jsonDataset/factcheck.json"
    }
}
Input to a child workflow execution

LaStato della mappa distribuitaavvia tante esecuzioni di workflow secondarie quanti sono gli elementi dell'array presenti nel file JSON. L'esempio seguente mostra l'input ricevuto dall'esecuzione di un workflow secondario.

{
  "verdict": "true",
  "statement_date": "6/11/2008",
  "statement_source": "speech"
}

UNStato della mappa distribuitaè in grado di accettare un file CSV archiviato in un bucket Amazon S3 come set di dati. Se utilizzi un file CSV come set di dati, devi specificare un'intestazione di colonna CSV. Per informazioni su come specificare un'intestazione CSV, consultaContenuto del ItemReader campo.

Poiché non esiste un formato standardizzato per creare e gestire i dati nei file CSV, Step Functions analizza i file CSV in base alle seguenti regole:

  • Le virgole (,) sono un delimitatore che separa i singoli campi.

  • Le newline sono un delimitatore che separa i singoli record.

  • I campi vengono trattati come stringhe. Per le conversioni dei tipi di dati, usaStates.StringToJsonfunzione intrinseca inItemSelector.

  • Le virgolette doppie (» «) non sono necessarie per racchiudere le stringhe. Tuttavia, le stringhe racchiuse tra virgolette doppie possono contenere virgole e nuove righe senza che funzionino come delimitatori.

  • Evita le virgolette doppie ripetendole.

  • Se il numero di campi in una riga è inferiore al numero di campi nell'intestazione, Step Functions fornisce stringhe vuote per i valori mancanti.

  • Se il numero di campi in una riga è superiore al numero di campi nell'intestazione, Step Functions salta i campi aggiuntivi.

Per ulteriori informazioni su come Step Functions analizza un file CSV, vedere la.Example of parsing an input CSV file.

Quando l'esecuzione del flusso di lavoro raggiunge ilMapstate, Step Functions invoca ilGetObjectAzione API per recuperare il file CSV specificato. IlMapstate esegue quindi un'iterazione su ogni riga del file CSV e avvia un'esecuzione del flusso di lavoro secondario per elaborare gli elementi di ogni riga. Ad esempio, supponiamo di fornire un file CSV che contiene 100 righe come input. Quindi, l'interprete passa ogni riga alMapstato. LaMapstate elabora gli elementi in ordine seriale, a partire dalla riga di intestazione.

Nota

  • L'input di esecuzione utilizzato per avviare l'esecuzione di un workflow secondario non può superare i 256 KB. Tuttavia, Step Functions supporta la lettura di un elemento fino a 8 MB da un file CSV o JSON se poi si applica l'opzioneItemSelectorcampo per ridurre le dimensioni dell'articolo.

  • Attualmente, Step Functions supporta 10 GB come dimensione massima di un singolo file in un report di inventario Amazon S3. Tuttavia, Step Functions può elaborare più di 10 GB se ogni singolo file è inferiore a 10 GB.

  • Step Functions necessita di autorizzazioni appropriate per accedere ai set di dati Amazon S3 che utilizzi. Per informazioni sulle politiche IAM per i set di dati, consultaPolitiche IAM per set di dati.

Le schede seguenti mostrano esempi diItemReaderla sintassi del campo e l'input passato all'esecuzione di un workflow secondario per questo set di dati.

ItemReader syntax

Ad esempio, supponiamo di avere un file CSV di nomeratings.csv. Quindi, hai memorizzato questo file all'interno di un prefisso denominatocsvDatasetin un bucket Amazon S3.

{
  "ItemReader": {
    "ReaderConfig": {
      "InputType": "CSV",
      "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
      "Bucket": "myBucket",
      "Key": "csvDataset/ratings.csv"
    }
  }
}
Input to a child workflow execution

IlStato della mappa distribuitaavvia tante esecuzioni di workflow secondarie quante sono le righe presenti nel file CSV, esclusa la riga di intestazione, se presente nel file. L'esempio seguente mostra l'input ricevuto dall'esecuzione di un workflow secondario.

{
  "rating": "3.5",
  "movieId": "307",
  "userId": "1",
  "timestamp": "1256677221"
}

UNStato della mappa distribuitaè in grado di accettare un file di inventario Amazon S3 che è archiviato in un bucket Amazon S3 come set di dati.

Quando l'esecuzione del flusso di lavoro raggiunge ilMapstate, Step Functions invoca ilGetObjectAzione API per recuperare il file manifesto dell'inventario Amazon S3 specificato. IlMapstate esegue quindi un'iterazione sugli oggetti nell'inventario per restituire una serie di metadati degli oggetti di inventario Amazon S3.

Nota

  • Attualmente, Step Functions supporta 10 GB come dimensione massima di un singolo file in un report di inventario Amazon S3. Tuttavia, Step Functions può elaborare più di 10 GB se ogni singolo file è inferiore a 10 GB.

  • Step Functions necessita di autorizzazioni appropriate per accedere ai set di dati Amazon S3 che utilizzi. Per informazioni sulle politiche IAM per i set di dati, consultaPolitiche IAM per set di dati.

Di seguito è riportato un esempio di modello di inventario in formato CSV. Questo file include gli oggetti denominaticsvDataseteimageDataset, che sono archiviati in un bucket Amazon S3 denominatosourceBucket.

"sourceBucket","csvDataset/","0","2022-11-16T00:27:19.000Z"
"sourceBucket","csvDataset/titles.csv","3399671","2022-11-16T00:29:32.000Z"
"sourceBucket","imageDataset/","0","2022-11-15T20:00:44.000Z"
"sourceBucket","imageDataset/n02085620_10074.jpg","27034","2022-11-15T20:02:16.000Z"
...
Importante

Attualmente, Step Functions non supporta i report di inventario Amazon S3 definiti dall'utente come set di dati. È inoltre necessario assicurarsi che il formato di output del report di inventario di Amazon S3 sia CSV. Per ulteriori informazioni sugli inventari Amazon S3 e su come configurarli, consulta la.Inventario Amazon S3nelGuida per l'utente di Amazon S3.

Il seguente esempio di file manifesto dell'inventario mostra le intestazioni CSV per i metadati degli oggetti di inventario.

{
  "sourceBucket" : "sourceBucket",
  "destinationBucket" : "arn:aws:s3:::inventory",
  "version" : "2016-11-30",
  "creationTimestamp" : "1668560400000",
  "fileFormat" : "CSV",
  "fileSchema" : "Bucket, Key, Size, LastModifiedDate",
  "files" : [ {
    "key" : "source-bucket/destination-prefix/data/20e55de8-9c21-45d4-99b9-46c732000228.csv.gz",
    "size" : 7300,
    "MD5checksum" : "a7ff4a1d4164c3cd55851055ec8f6b20"
  } ]
}

Le schede seguenti mostrano esempi diItemReaderla sintassi del campo e l'input passato all'esecuzione di un workflow secondario per questo set di dati.

ItemReader syntax
{
  "ItemReader": {
    "ReaderConfig": {
      "InputType": "MANIFEST"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
      "Bucket": "destinationBucket",
      "Key": "destination-prefix/source-bucket/config-ID/YYYY-MM-DDTHH-MMZ/manifest.json"
    }
  }
}
Input to a child workflow execution
{
  "LastModifiedDate": "2022-11-16T00:29:32.000Z",
  "Bucket": "sourceBucket",
  "Size": "3399671",
  "Key": "csvDataset/titles.csv"
}

A seconda dei campi selezionati durante la configurazione del report sull'inventario di Amazon S3, il contenuto delmanifest.jsonil file può variare rispetto all'esempio mostrato.

Politiche IAM per set di dati

Quando crei flussi di lavoro con la console Step Functions, Step Functions può generare automaticamente policy IAM basate sulle risorse nella definizione del flusso di lavoro. Queste politiche includono i privilegi minimi necessari per consentire al ruolo della macchina a stati di richiamare ilStartExecutionAzione API perStato della mappa distribuita. Queste politiche includono anche i privilegi minimi necessari per accedere a Step Functions.AWSrisorse, come bucket e oggetti Amazon S3 e funzioni Lambda. Ti consigliamo vivamente di includere solo le autorizzazioni necessarie nelle tue policy IAM. Ad esempio, se il tuo flusso di lavoro include unMapimposta in modalità distribuita, limita le tue policy allo specifico bucket e alla cartella Amazon S3 che contiene il set di dati.

Importante

Se specifichi un bucket Amazon S3 e un oggetto, o prefisso, con unpercorso di riferimentoa una coppia chiave-valore esistente nelstato della mappa distribuitainput, assicurati di aggiornare le policy IAM per il tuo flusso di lavoro. Ambita le policy fino al bucket e ai nomi degli oggetti in cui il percorso si risolve in fase di esecuzione.

I seguenti esempi di policy IAM concedono i privilegi minimi necessari per accedere ai set di dati Amazon S3 utilizzandoListObjectsV2eGetObjectAzioni API.

Esempio Policy IAM per oggetti Amazon S3 come set di dati

L'esempio seguente mostra una policy IAM che concede i privilegi minimi per accedere agli oggetti organizzati all'internoprocessImagesin un bucket Amazon S3 denominatomyBucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "processImages"
                    ]
                }
            }
        }
    ]
}
Esempio Politica IAM per un file CSV come set di dati

L'esempio seguente mostra una policy IAM che concede i privilegi minimi per accedere a un file CSV denominatoratings.csv.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket/csvDataset/ratings.csv"
            ]
        }
    ]
}
Esempio Policy IAM per un inventario di Amazon S3 come set di dati

L'esempio seguente mostra una policy IAM che concede i privilegi minimi per accedere a un report di inventario di Amazon S3.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::destination-prefix/source-bucket/config-ID/YYYY-MM-DDTHH-MMZ/manifest.json",
                "arn:aws:s3:::destination-prefix/source-bucket/config-ID/data/*"
            ]
        }
    ]
}