ResultWriter (mapa) - AWS Step Functions
Conteúdo do campo ResultWriterExemplosExportar para o Amazon S3Políticas do IAM para ResultWriter

ResultWriter (mapa)

Gerenciar estados e transformar dados

Saiba mais sobre como transmitir dados entre estados com variáveis e transformar dados com JSONata.

O campo ResultWriter é um objeto JSON que fornece opções para os resultados da saída das execuções de um fluxo de trabalho secundário iniciadas por um estado de mapa distribuído. Você pode especificar diferentes opções de formatação para os resultados de saída com a localização do Amazon S3 para armazená-los, caso opte pela exportação. Por padrão, o Step Functions não exporta esses resultados.

Conteúdo do campo ResultWriter

O campo ResultWriter contém os seguintes subcampos: A escolha dos campos determina como a saída é formatada e se ela é exportada para o Amazon S3.

ResultWriter

Um objeto JSON que especifica os seguintes detalhes:

  • Resource

    A ação da API do Amazon S3 que o Step Functions invoca para exportar os resultados da execução.

  • Parameters

    Um objeto JSON que especifica o nome do bucket do Amazon S3 e o prefixo que armazena a saída da execução.

  • WriterConfig

    Esse campo permite configurar as seguintes opções.

    • Transformation

      • NONE: retorna a saída das execuções do fluxo de trabalho secundário inalteradas, além dos metadados do fluxo de trabalho. O padrão ao exportar os resultados da execução do fluxo de trabalho secundário para o Amazon S3 e WriterConfig não é especificado.

      • COMPACT: retorna a saída das execuções do fluxo de trabalho secundário. O padrão quando ResultWriter não é especificado.

      • FLATTEN: retorna a saída das execuções do fluxo de trabalho secundário. Se a execução de um fluxo de trabalho secundário retornar uma matriz, essa opção nivelará a matriz antes de retornar o resultado para uma saída de estado ou gravar o resultado em um objeto do Amazon S3.

        nota

        Se a execução de um fluxo de trabalho secundário falhar, o Step Functions retornará seu resultado de execução inalterado. Os resultados seriam equivalentes a ter definido Transformation como NONE.

    • OutputType

      • JSON: formata os resultados como uma matriz JSON.

      • JSONL: formata os resultados como linhas JSON.

Combinações de campo obrigatórias

O campo ResultWriter não pode ser vazio. É necessário especificar um desses conjuntos de subcampos.

  • WriterConfig: para visualizar a saída formatada, sem salvar os resultados no Amazon S3.

  • Resource e Parameters: para salvar os resultados no Amazon S3 sem formatação adicional.

  • Todos os três campos (WriterConfig, Resource e Parameters): para formatar a saída e salvá-la no Amazon S3.

Exemplo de configurações e saída de transformação

Os tópicos a seguir demonstram as possíveis configurações para ResultWriter e exemplos de resultados processados das diferentes opções de transformação.

Os exemplos a seguir demonstram configurações com as combinações possíveis dos três campos: WriterConfig, Resources e Parameters.

Somente WriterConfig

Este exemplo configura como a saída do estado é apresentada na visualização prévia, com o formato de saída e a transformação especificados no campo WriterConfig. Os campos Resource e Parameters inexistentes, que teriam sido fornecidos pelas especificações de bucket do Amazon S3, implicam no recurso de saída de estado. Os resultados são transmitidos para o próximo estado.

"ResultWriter": {
    "WriterConfig": { 
        "Transformation": "FLATTEN", 
        "OutputType": "JSON"
    }
}
Somente recursos e parâmetros

Este exemplo exporta a saída do estado para o bucket do Amazon S3 especificado, sem a formatação e a transformação adicionais que o campo inexistente WriterConfig teria especificado.

"ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
        "Bucket": "amzn-s3-demo-destination-bucket",
        "Prefix": "csvProcessJobs"
    }
Os três campos: WriterConfig, recursos e parâmetros

Este exemplo formata a saída do estado de acordo com as especificações no campo WriterConfig. Ele também o exporta para um bucket do Amazon S3 de acordo com as especificações nos campos Resource e Parameters.

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

Para esses exemplos, suponha que cada execução de fluxo de trabalho secundário retorne uma saída, que é uma matriz de objetos. 

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

Esses exemplos demonstram a saída formatada para diferentes valores de Transformation, com OutputType em JSON.

Transformação NONE

Esse é um exemplo do resultado processado quando você usa a transformação NONE. A saída permanece inalterada e inclui os metadados do fluxo de trabalho.

[
    {
        "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"
    }
]
Transformação COMPACT

Esse é um exemplo do resultado processado quando você usa a transformação COMPACT. Observe que é a saída combinada das execuções do fluxo de trabalho secundário com a estrutura 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"
        }
    ]
]
Transformação FLATTEN

Esse é um exemplo do resultado processado quando você usa a transformação FLATTEN. Observe que é a saída combinada das matrizes de execuções do fluxo de trabalho secundário agrupadas em uma 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"
    }
]

Exportar para o Amazon S3

Importante

Certifique-se de que o bucket do Amazon S3 utilizado para exportar os resultados de uma Execução de mapa esteja sob a mesma Conta da AWS e Região da AWS que a sua máquina de estado. Caso contrário, a execução da sua máquina de estado falhará com o erro States.ResultWriterFailed.

A exportação dos resultados para um bucket do Amazon S3 será uma operação útil se o tamanho da carga útil de saída exceder 256 KiB. O Step Functions consolida todos os dados da execução de um fluxo de trabalho secundário, como a entrada e saída de execução, ARN e status da execução. Em seguida, ele exporta as execuções com o mesmo status para seus respectivos arquivos na localização especificada do Amazon S3.

O exemplo a seguir, que usa JSONPath, mostra a sintaxe do campo ResultWriter com Parameters para exportar os resultados da execução de um fluxo de trabalho secundário. Nesse exemplo, os resultados são armazenados em um bucket chamado amzn-s3-demo-destination-bucket, dentro de um prefixo chamado csvProcessJobs. 

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

Para estados JSONata, Parameters será substituído por Arguments.

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

No Workflow Studio, você pode exportar os resultados da execução do fluxo de trabalho secundário selecionando Exportar resultados do estado Mapa para o Amazon S3. Em seguida, forneça o nome do bucket do Amazon S3 e o prefixo para o qual você deseja exportar os resultados.

O Step Functions precisa das permissões apropriadas para acessar o bucket e a pasta para onde você deseja exportar os resultados. Para obter informações sobre as políticas do IAM necessárias, consulte Políticas do IAM para ResultWriter.

Se você exportar os resultados da execução do fluxo de trabalho secundário, a execução do estado Mapa Distribuído retornará o ARN da Execução de mapa e os dados sobre o local de exportação do Amazon S3, no seguinte 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"
  }
}

O Step Functions exporta execuções com o mesmo status para seus respectivos arquivos. Por exemplo, se as execuções de fluxo de trabalho secundário resultaram em 500 resultados de êxito e 200 resultados de falha, o Step Functions criará dois arquivos no local especificado do Amazon S3 para os resultados de êxito e falha. Nesse exemplo, o arquivo de resultados de êxito contém os 500 resultados de êxito, enquanto o arquivo de resultados de falha contém os 200 resultados de falha.

Para uma determinada tentativa de execução, o Step Functions cria os seguintes arquivos no local especificado do Amazon S3, dependendo da saída da execução:

  • manifest.json — contém metadados da Execução de mapa, como local de exportação, ARN e informações sobre os arquivos de resultados.

    Se você tiver redriven uma Execução de mapa, o arquivo manifest.json conterá as referências a todas as execuções bem-sucedidas do fluxo de trabalho secundário, em todas as tentativas de uma Execução de mapa. No entanto, esse arquivo contém referências às execuções com falhas e pendentes de um redrive específico.

  • SUCCEEDED_n.json — contém os dados consolidados de todas as execuções bem-sucedidas do fluxo de trabalho secundário. n representa o número do índice do arquivo. O número do índice começa em 0. Por exemplo, SUCCEEDED_1.json.

  • FAILED_n.json — contém os dados consolidados de todas as execuções do fluxo de trabalho secundário com falha, que atingiram o tempo limite ou foram abortadas. Use esse arquivo para se recuperar a partir de execuções com falha. n representa o índice do arquivo. O número do índice começa em 0. Por exemplo, FAILED_1.json.

  • PENDING_n.json — contém os dados consolidados de todas as execuções do fluxo de trabalho secundário que não foram iniciadas porque a Execução de mapa falhou ou foi abortada. n representa o índice do arquivo. O número do índice começa em 0. Por exemplo, PENDING_1.json.

O Step Functions oferece suporte a arquivos de resultados individuais de até 5 GB. Se o tamanho do arquivo exceder 5 GB, o Step Functions criará outro arquivo para gravar os resultados restantes da execução e anexará um número de índice ao nome do arquivo. Por exemplo, se o tamanho do arquivo SUCCEEDED_0.json exceder 5 GB, o Step Functions criará um arquivo SUCCEEDED_1.json para registrar os resultados restantes.

Se você não especificou a exportação dos resultados da execução do fluxo de trabalho secundário, a execução da máquina de estado retornará uma matriz dos resultados da execução do fluxo de trabalho secundário, conforme mostrado no exemplo a seguir.

[
  {
    "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 o tamanho da saída retornada exceder 256 KiB, a execução da máquina de estado falhará e retornará um erro States.DataLimitExceeded.

Políticas do IAM para ResultWriter

Ao criar fluxos de trabalho com o console do Step Functions, o Step Functions pode gerar automaticamente políticas do IAM com base nos recursos na definição de fluxo de trabalho. As políticas geradas incluem os privilégios mínimos necessários para permitir que o perfil da máquina de estado invoque a ação da API StartExecution para o estado de Mapa distribuído e acesse recursos da AWS, como buckets e objetos do Amazon S3 e funções do Lambda.

Recomendamos incluir somente as permissões que forem necessárias em suas políticas do IAM. Por exemplo, se o fluxo de trabalho incluir um estado Map no modo distribuído, defina o escopo de suas políticas até o bucket e a pasta específicos do Amazon S3 que contêm os dados.

Importante

Se você especificar um bucket e um objeto do Amazon S3, ou prefixo, com um caminho de referência para um par de valores-chave existente na entrada do estado Mapa Distribuído, certifique-se de atualizar as políticas de IAM do fluxo de trabalho. Defina o escopo das políticas até o bucket e os nomes de objetos para os quais o caminho é resolvido em runtime.

O exemplo de política do IAM a seguir concede os privilégios mínimos necessários para gravar os resultados da execução do fluxo de trabalho secundário em uma pasta chamada csvJobs em um bucket do Amazon S3 usando a ação de 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 o bucket do Amazon S3 no qual você está gravando o resultado da execução do fluxo de trabalho secundário for criptografado usando uma chave AWS Key Management Service (AWS KMS), você deverá incluir as permissões AWS KMS necessárias em sua política do IAM. Para obter mais informações, consulte Permissões do IAM para bucket criptografado do Amazon S3 AWS KMS key.