ResultWriter (Mappa) - AWS Step Functions
Contenuto del ResultWriter campoEsempiEsportazione su Amazon S3Politiche IAM per ResultWriter

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

ResultWriter (Mappa)

Gestione dello stato e trasformazione dei dati

Scopri come passare dati tra stati con variabili e Trasformare dati con. JSONata

Il ResultWriter campo è un oggetto JSON che fornisce opzioni per i risultati di output delle esecuzioni dei flussi di lavoro secondari avviate da uno stato della mappa distribuita. Puoi specificare diverse opzioni di formattazione per i risultati di output insieme alla posizione Amazon S3 in cui archiviarli se scegli di esportarli. Step Functions non esporta questi risultati per impostazione predefinita.

Contenuto del ResultWriter campo

Il ResultWriter campo contiene i seguenti sottocampi. La scelta dei campi determina il modo in cui l'output viene formattato e se viene esportato in Amazon S3.

ResultWriter

Un oggetto JSON che specifica i seguenti dettagli:

  • Resource

    L'azione dell'API Amazon S3 richiamata da Step Functions per esportare i risultati dell'esecuzione.

  • Parameters

    Un oggetto JSON che specifica il nome e il prefisso del bucket Amazon S3 che memorizza l'output di esecuzione.

  • WriterConfig

    Questo campo consente di configurare le seguenti opzioni.

    • Transformation

      • NONE- restituisce invariato l'output delle esecuzioni dei flussi di lavoro secondari, oltre ai metadati del flusso di lavoro. Impostazione predefinita per l'esportazione dei risultati di esecuzione del flusso di lavoro secondario in Amazon S3 WriterConfig e non è specificata.

      • COMPACT- restituisce l'output delle esecuzioni dei flussi di lavoro secondari. Impostazione predefinita quando non ResultWriter è specificato.

      • FLATTEN- restituisce l'output delle esecuzioni dei flussi di lavoro secondari. Se l'esecuzione di un flusso di lavoro secondario restituisce un array, questa opzione appiattisce l'array, prima di restituire il risultato a uno stato di output o di scrivere il risultato su un oggetto Amazon S3.

        Nota

        Se l'esecuzione di un workflow secondario non riesce, Step Functions restituisce il risultato dell'esecuzione invariato. I risultati sarebbero equivalenti a quelli impostati suTransformation. NONE

    • OutputType

      • JSON- formatta i risultati come array JSON.

      • JSONL- formatta i risultati come linee JSON.

Combinazioni di campi obbligatorie

Il ResultWriter campo non può essere vuoto. È necessario specificare uno di questi set di sottocampi.

  • WriterConfig- per visualizzare in anteprima l'output formattato, senza salvare i risultati su Amazon S3.

  • Resourcee Parameters - per salvare i risultati su Amazon S3 senza formattazione aggiuntiva.

  • Tutti e tre i campi: WriterConfig Resource e Parameters - per formattare l'output e salvarlo in Amazon S3.

Esempi di configurazioni e output di trasformazione

I seguenti argomenti illustrano le possibili impostazioni di configurazione ResultWriter ed esempi di risultati elaborati dalle diverse opzioni di trasformazione.

Negli esempi seguenti vengono illustrate le configurazioni con le possibili combinazioni dei tre campi:WriterConfig, Resources e. Parameters

Solo WriterConfig

Questo esempio configura il modo in cui l'output dello stato viene presentato in anteprima, con il formato di output e la trasformazione specificati nel WriterConfig campo. ParametersI campi Resource e inesistenti, che avrebbero fornito le specifiche del bucket Amazon S3, implicano la risorsa di output statale. I risultati vengono passati allo stato successivo.

"ResultWriter": {
    "WriterConfig": { 
        "Transformation": "FLATTEN", 
        "OutputType": "JSON"
    }
}
Solo risorse e parametri

Questo esempio esporta l'output dello stato nel bucket Amazon S3 specificato, senza la formattazione e la trasformazione aggiuntive che il campo inesistente WriterConfig avrebbe specificato.

"ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
        "Bucket": "amzn-s3-demo-destination-bucket",
        "Prefix": "csvProcessJobs"
    }
Tutti e tre i campi: Risorse e parametri WriterConfig

Questo esempio formatta l'output dello stato in base alle specifiche del WriterConfig campo. Inoltre, lo esporta in un bucket Amazon S3 in base alle specifiche nei campi and. Resource Parameters

"ResultWriter": {
     "WriterConfig": { 
        "Transformation": "FLATTEN",
        "OutputType": "JSON"
    },
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
        "Bucket": "amzn-s3-demo-destination-bucket",
        "Prefix": "csvProcessJobs"
    }
}

Per questi esempi, si supponga che ogni esecuzione del workflow secondario restituisca un output, ovvero una matrice di oggetti. 

[
  {
    "customer_id": "145538",
    "order_id": "100000"
  },
  {
    "customer_id": "898037",
    "order_id": "100001"
  }
]

Questi esempi mostrano l'output formattato per Transformation valori diversi, con OutputType ofJSON.

Trasformazione NESSUNA

Questo è un esempio del risultato elaborato quando si utilizza la FLATTEN trasformazione. L'output è invariato e include i metadati del flusso di lavoro.

[
    {
        "ExecutionArn": "arn:aws:states:us-east-1:123456789012: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:us-east-1:123456789012:stateMachine:orderProcessing/getOrders",
        "Status": "SUCCEEDED",
        "StopDate": "2025-02-04T01:49:50.163Z"
    },
    ...
    {
        "ExecutionArn": "arn:aws:states:us-east-1:123456789012: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:us-east-1:123456789012:stateMachine:orderProcessing/getOrders",
        "Status": "SUCCEEDED",
        "StopDate": "2025-02-04T01:49:50.227Z"
    }
]
Trasformazione COMPACT

Questo è un esempio del risultato elaborato quando si utilizza la COMPACT trasformazione. Si noti che è l'output combinato delle esecuzioni del flusso di lavoro secondario con la struttura dell'array originale.

[
    [
        {
            "customer_id": "145538",
            "order_id": "100000"
        },
        {
            "customer_id": "898037",
            "order_id": "100001"
        }
    ],
    ...,
    
    [
        {
            "customer_id": "169881",
            "order_id": "100005"
        },
        {
            "customer_id": "797471",
            "order_id": "100006"
        }
    ]
]
Trasformazione FLATTEN

Questo è un esempio del risultato elaborato quando si utilizza la FLATTEN trasformazione. Si noti che si tratta dell'output combinato degli array secondari di esecuzione dei flussi di lavoro riuniti in un unico array.

[
    {
        "customer_id": "145538",
        "order_id": "100000"
    },
    {
        "customer_id": "898037",
        "order_id": "100001"
    },
    ...
    {
        "customer_id": "169881",
        "order_id": "100005"
    },
    {
        "customer_id": "797471",
        "order_id": "100006"
    }
]

Esportazione su Amazon S3

Importante

Assicurati che il bucket Amazon S3 che usi per esportare i risultati di un Map Run si trovi nella stessa macchina Account AWS a Regione AWS stati. In caso contrario, l'esecuzione della macchina a stati fallirà con l'States.ResultWriterFailederrore.

L'esportazione dei risultati in un bucket Amazon S3 è utile se la dimensione del payload di output supera i 256 KB. Step Functions consolida tutti i dati di esecuzione del workflow secondario, come input e output dell'esecuzione, ARN e stato di esecuzione. Quindi esporta le esecuzioni con lo stesso stato nei rispettivi file nella posizione Amazon S3 specificata.

L'esempio seguente, using JSONPath, mostra la sintassi del ResultWriter campo con cui Parameters esportare i risultati dell'esecuzione del flusso di lavoro secondario. In questo esempio, si memorizzano i risultati in un bucket denominato amzn-s3-demo-destination-bucket all'interno di un prefisso chiamato. csvProcessJobs 

{
  "ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
      "Bucket": "amzn-s3-demo-destination-bucket",
      "Prefix": "csvProcessJobs"
    }
  }
}

Per JSONatagli stati, Parameters verrà sostituito con. Arguments

{
  "ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Arguments": {
      "Bucket": "amzn-s3-demo-destination-bucket",
      "Prefix": "csvProcessJobs"
    }
  }
}
Suggerimento

In Workflow Studio, puoi esportare i risultati dell'esecuzione del flusso di lavoro secondario selezionando Esporta risultati dello stato della mappa su Amazon S3. Quindi, fornisci il nome del bucket Amazon S3 e il prefisso in cui desideri esportare i risultati.

Step Functions necessita delle autorizzazioni appropriate per accedere al bucket e alla cartella in cui si desidera esportare i risultati. Per informazioni sulla policy IAM richiesta, consulta. Politiche IAM per ResultWriter

Se esporti i risultati dell'esecuzione del flusso di lavoro secondario, l'esecuzione dello stato della mappa distribuita restituisce l'ARN Map Run e i dati sulla posizione di esportazione di Amazon S3 nel seguente formato:

{
  "MapRunArn": "arn:aws:states:us-east-2:123456789012: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 esporta le esecuzioni con lo stesso stato nei rispettivi file. Ad esempio, se le esecuzioni dei flussi di lavoro secondari hanno prodotto 500 risultati di successo e 200 di errore, Step Functions crea due file nella posizione Amazon S3 specificata per i risultati di successo e di errore. In questo esempio, il file dei risultati di successo contiene i 500 risultati di successo, mentre il file dei risultati di errore contiene i 200 risultati di errore.

Per un determinato tentativo di esecuzione, Step Functions crea i seguenti file nella posizione Amazon S3 specificata in base all'output dell'esecuzione:

  • manifest.json— Contiene metadati Map Run, come la posizione di esportazione, l'ARN di Map Run e informazioni sui file dei risultati.

    Se hai redrivenun Map Run, il manifest.json file, contiene riferimenti a tutte le esecuzioni di workflow secondarie riuscite in tutti i tentativi di Map Run. Tuttavia, questo file contiene riferimenti alle esecuzioni fallite e in sospeso per uno specifico redrive.

  • SUCCEEDED_n.json— Contiene i dati consolidati per tutte le esecuzioni di workflow secondarie riuscite. n rappresenta il numero di indice del file. Il numero di indice inizia da 0. Ad esempio SUCCEEDED_1.json.

  • FAILED_n.json— Contiene i dati consolidati per tutte le esecuzioni di workflow secondarie non riuscite, scadute e interrotte. Utilizzate questo file per eseguire il ripristino in caso di esecuzioni non riuscite. n rappresenta l'indice del file. Il numero di indice inizia da 0. Ad esempio FAILED_1.json.

  • PENDING_n.json— Contiene i dati consolidati per tutte le esecuzioni di workflow secondarie che non sono state avviate perché l'esecuzione della mappa non è riuscita o è stata interrotta. n rappresenta l'indice del file. Il numero di indice inizia da 0. Ad esempio PENDING_1.json.

Step Functions supporta file di risultati individuali fino a 5 GB. Se la dimensione di un file supera i 5 GB, Step Functions crea un altro file per scrivere i risultati di esecuzione rimanenti e aggiunge un numero di indice al nome del file. Ad esempio, se la dimensione del SUCCEEDED_0.json file supera i 5 GB, Step Functions crea un SUCCEEDED_1.json file per registrare i risultati rimanenti.

Se non avete specificato di esportare i risultati dell'esecuzione del flusso di lavoro secondario, l'esecuzione della macchina a stati restituisce una matrice di risultati di esecuzione del flusso di lavoro secondario, come illustrato nell'esempio seguente:

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

Se la dimensione dell'output restituita supera i 256 KB, l'esecuzione della macchina a stati fallisce e restituisce un States.DataLimitExceeded errore.

Politiche IAM per ResultWriter

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 l'azione dell'StartExecutionAPI per lo stato della mappa distribuita. Queste policy includono anche i privilegi minimi necessari Step Functions per accedere alle AWS risorse, come i bucket e gli oggetti Amazon S3 e le funzioni Lambda. Ti consigliamo vivamente di includere solo le autorizzazioni necessarie nelle tue policy IAM. Ad esempio, se il tuo flusso di lavoro include uno Map stato in modalità Distribuita, limita le 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 un percorso di riferimento a una coppia chiave-valore esistente nell'input dello stato della mappa distribuita, assicurati di aggiornare le policy IAM per il tuo flusso di lavoro. Definisci le policy fino ai nomi dei bucket e degli oggetti in cui il percorso si risolve in fase di esecuzione.

Il seguente esempio di policy IAM concede i privilegi minimi richiesti per scrivere i risultati dell'esecuzione del flusso di lavoro secondario in una cartella denominata csvJobs in un bucket Amazon S3 utilizzando l'azione API. PutObject

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

Se il bucket Amazon S3 su cui stai scrivendo il risultato dell'esecuzione del flusso di lavoro secondario è crittografato utilizzando un AWS Key Management Service (AWS KMS) chiave, devi includere le AWS KMS autorizzazioni necessarie nella tua policy IAM. Per ulteriori informazioni, consulta Autorizzazioni IAM per bucket Amazon S3 AWS KMS key crittografato.