ResultWriter (Map) - AWS Step Functions
Contenido del campo ResultWriterEjemplosExportación a Amazon S3Políticas de IAM para ResultWriter

ResultWriter (Map)

Administración del estado y transformación de los datos

Obtenga información sobre la Transmisión de datos entre estados con variables y la Transformación de datos con JSONata.

El campo ResultWriter es un objeto JSON que proporciona opciones para los resultados de salida de las ejecuciones de flujos de trabajo secundarios iniciadas por un estado Distributed Map. Puede especificar diferentes opciones de formato para los resultados de salida junto con la ubicación de Amazon S3 para almacenarlos si decide exportarlos. Step Functions no exporta estos resultados de forma predeterminada.

Contenido del campo ResultWriter

El campo ResultWriter contiene los siguientes subcampos. La elección de los campos determina el formato de la salida y si se exporta a Amazon S3.

ResultWriter

Un objeto JSON que especifica los detalles siguientes:

  • Resource

    La acción de la API de Amazon S3 que Step Functions invoca para exportar los resultados de la ejecución.

  • Parameters

    Un objeto JSON que especifica el nombre del bucket de Amazon S3 y el prefijo que almacena el resultado de la ejecución.

  • WriterConfig

    Este campo le permite configurar las siguientes opciones.

    • Transformation

      • NONE: devuelve la salida de las ejecuciones del flujo de trabajo secundario sin cambios, además de los metadatos del flujo de trabajo. Es el valor predeterminado al exportar los resultados de la ejecución del flujo de trabajo secundario a Amazon S3 y no se especifica WriterConfig.

      • COMPACT: devuelve el resultado de las ejecuciones del flujo de trabajo secundario. Es el valor predeterminado cuando no se especifica ResultWriter.

      • FLATTEN: devuelve el resultado de las ejecuciones del flujo de trabajo secundario. Si la ejecución de un flujo de trabajo secundario devuelve una matriz, esta opción aplana la matriz antes de devolver el resultado a una salida de estado o de escribir el resultado en un objeto de Amazon S3.

        nota

        Si se produce un error en la ejecución de un flujo de trabajo secundario, Step Functions devuelve el resultado de la ejecución sin cambios. Los resultados equivaldrían a haber establecido Transformation en NONE.

    • OutputType

      • JSON: formatea los resultados como una matriz JSON.

      • JSONL: formatea los resultados como líneas JSON

Combinaciones de campos obligatorios

El campo ResultWriter no puede estar vacío. Debe especificar uno de estos conjuntos de subcampos.

  • WriterConfig: para obtener una vista previa de la salida formateada, sin guardar los resultados en Amazon S3.

  • Resource y Parameters: para guardar los resultados en Amazon S3 sin formato adicional.

  • Los tres campos WriterConfig, Resource y Parameters: para formatear el resultado y guardarlo en Amazon S3.

Ejemplos de configuraciones y salida de transformación

En los temas siguientes se muestran las posibles opciones de configuración para ResultWriter y ejemplos de los resultados procesados de las distintas opciones de transformación.

En los siguientes ejemplos se muestran las configuraciones con las posibles combinaciones de los tres campos: WriterConfig, Resources y Parameters.

Solo WriterConfig

Este ejemplo configura cómo se presenta la salida del estado en la vista previa, con el formato de salida y la transformación especificados en el campo WriterConfig. Los campos Resource y Parameters inexistentes, que habrían proporcionado las especificaciones del bucket de Amazon S3, implican el recurso de la salida de estado. Los resultados se pasan al siguiente estado.

"ResultWriter": {
    "WriterConfig": { 
        "Transformation": "FLATTEN", 
        "OutputType": "JSON"
    }
}
Solo recursos y parámetros

En este ejemplo se exporta la salida del estado al bucket de Amazon S3 especificado, sin el formato ni la transformación adicionales que habría especificado el campo WriterConfig inexistente.

"ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
        "Bucket": "amzn-s3-demo-destination-bucket",
        "Prefix": "csvProcessJobs"
    }
Los tres campo: WriterConfig, Resources y Parameters

En este ejemplo se formatea la salida del estado según las especificaciones del campo WriterConfig. También la exporta a un bucket de Amazon S3 según las especificaciones de los campos Resource y Parameters.

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

Para estos ejemplos, supongamos que cada ejecución del flujo de trabajo secundario devuelve una salida, que es una matriz de objetos. 

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

En estos ejemplos se muestra la salida formateada para diferentes valores Transformation, con OutputType de JSON.

Transformación NONE

Este es un ejemplo del resultado procesado cuando se utiliza la transformación NONE. La salida no cambia e incluye los metadatos del flujo de trabajo.

[
    {
        "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

Este es un ejemplo del resultado procesado cuando se utiliza la transformación COMPACT. Tenga en cuenta que se trata de la salida combinada de las ejecuciones del flujo de trabajo secundario con la estructura de matriz original.

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

Este es un ejemplo del resultado procesado cuando se utiliza la transformación FLATTEN. Tenga en cuenta que se trata de la salida combinada del flujo de trabajo secundario que ejecuta matrices aplanadas en una sola matriz.

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

Exportación a Amazon S3

importante

Asegúrese de que el bucket de Amazon S3 que utilice para exportar los resultados de Map Run esté en la misma Cuenta de AWS y Región de AWS que su máquina de estado. De lo contrario, la ejecución de la máquina de estado fallará y se producirá el error States.ResultWriterFailed.

La exportación de los resultados a un bucket de Amazon S3 es útil si el tamaño de la carga de salida es superior a 256 KiB. Step Functions consolida todos los datos de ejecución del flujo de trabajo secundario, como la entrada y salida de la ejecución, el ARN y el estado de ejecución. A continuación, exporta las ejecuciones con el mismo estado a sus archivos respectivos en la ubicación de Amazon S3 especificada.

En el siguiente ejemplo, que utiliza JSONPath, se muestra la sintaxis del campo ResultWriter con Parameters para exportar los resultados de la ejecución del flujo de trabajo secundario. En este ejemplo, los resultados se almacenan en un bucket llamado amzn-s3-demo-destination-bucket dentro de un prefijo llamado csvProcessJobs. 

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

Para los estados de JSONata, Parameters se reemplazará por Arguments.

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

En Workflow Studio, puede exportar los resultados de la ejecución del flujo de trabajo secundario seleccionando Exportar los resultados del estado Map a Amazon S3. A continuación, escriba el nombre del bucket de Amazon S3 y el prefijo donde desea exportar los resultados.

Step Functions necesita los permisos adecuados para acceder al bucket y a la carpeta a los que desea exportar los resultados. Para obtener información acerca de la política de IAM necesarias, consulte Políticas de IAM para ResultWriter.

Si exporta los resultados de la ejecución del flujo de trabajo secundario, la ejecución del estado Map Distributed devuelve el ARN del Map Run y los datos sobre la ubicación de exportación de Amazon S3 en el siguiente formato:

{
  "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 exporta las ejecuciones con el mismo estado a sus respectivos archivos. Por ejemplo, si las ejecuciones de flujos de trabajo secundarios dieron como resultado 500 resultados satisfactorios y 200 con error, Step Functions creará dos archivos en la ubicación de Amazon S3 especificada para los resultados correctos y erróneos. En este ejemplo, el archivo de resultados con éxito contiene los 500 resultados con éxito, mientras que el archivo de resultados con error contiene los 200 resultados con error.

Para un intento de ejecución determinado, Step Functions crea los siguientes archivos en la ubicación de Amazon S3 especificada en función del resultado de la ejecución:

  • manifest.json – Contiene metadatos de Map Run, como la ubicación de exportación, el ARN del Map Run e información sobre los archivos de resultados.

    Si ha utilizado redriven con un Map Run, el archivo manifest.json contendrá referencias a todas las ejecuciones correctas de flujos de trabajo secundarios en todos los intentos de un Map Run. Sin embargo, este archivo contiene referencias a las ejecuciones con errores y pendientes de un uso específico de redrive.

  • SUCCEEDED_n.json – Contiene los datos consolidados de todas las ejecuciones correctas de flujos de trabajo secundarios. n representa el número de índice del archivo. El número de índice comienza en 0. Por ejemplo, SUCCEEDED_1.json.

  • FAILED_n.json – Contiene los datos consolidados de todas las ejecuciones de flujos de trabajo secundarios con error, con tiempo de espera agotado o anuladas. Utilice este archivo para recuperarse de ejecuciones con error. n representa el índice del archivo. El número de índice comienza en 0. Por ejemplo, FAILED_1.json.

  • PENDING_n.json – Contiene los datos consolidados de todas las ejecuciones de flujos de trabajo secundarios que no se iniciaron porque el Map Run produjo un error o se anuló. n representa el índice del archivo. El número de índice comienza en 0. Por ejemplo, PENDING_1.json.

Step Functions admite archivos de resultados individuales de hasta 5 GB. Si el tamaño de un archivo supera los 5 GB, Step Functions crea otro archivo para escribir el resto de los resultados de la ejecución y añade un número de índice al nombre del archivo. Por ejemplo, si el tamaño del archivo SUCCEEDED_0.json supera los 5 GB, Step Functions crea un archivo SUCCEEDED_1.json para registrar los resultados restantes.

Si no especifica que se exporten los resultados de la ejecución del flujo de trabajo secundario, la ejecución de la máquina de estado devuelve una matriz de resultados de la ejecución del flujo de trabajo secundario, como se muestra en el siguiente ejemplo:

[
  {
    "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

Si el tamaño de salida devuelto supera los 256 KiB, se produce un error en la ejecución de la máquina de estado y se devuelve un error States.DataLimitExceeded.

Políticas de IAM para ResultWriter

Al crear flujos de trabajo con la consola de Step Functions, Step Functions puede generar automáticamente políticas de IAM basadas en los recursos de la definición de flujo de trabajo. Las políticas generadas incluyen los privilegios mínimos necesarios para permitir que el rol de la máquina de estado invoque la acción de la API StartExecution para el estado Distributed Map y acceda a los recursos de AWS, como buckets y objetos de Amazon S3 y las funciones de Lambda.

Le recomendamos que incluya únicamente los permisos necesarios en las políticas de IAM. Por ejemplo, si el flujo de trabajo incluye un estado Map en modo distribuido, aplique las políticas al bucket y a la carpeta de Amazon S3 específicos que contengan los datos.

importante

Si especifica un bucket y un objeto de Amazon S3, o un prefijo, con una ruta de referencia a un par clave-valor existente en la entrada del estado Map Distributed, no olvide actualizar las políticas de IAM para el flujo de trabajo. Limite las políticas hasta los nombres de objeto y bucket a los que se dirige la ruta en tiempo de ejecución.

El siguiente ejemplo de política de IAM otorga los privilegios mínimos necesarios para escribir los resultados de la ejecución del flujo de trabajo secundario en una carpeta denominada csvJobs de un bucket de Amazon S3 mediante la acción PutObject de la 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 el bucket de Amazon S3 en el que está escribiendo el resultado de la ejecución del flujo de trabajo secundario está cifrado con una clave AWS Key Management Service (AWS KMS), debe incluir los permisos AWS KMS necesarios en la política de IAM. Para obtener más información, consulte Permisos de IAM para bucket de Amazon S3 cifrado AWS KMS key.