ResultWriter

O campo ResultWriter é um objeto JSON que especifica a localização do Amazon S3 onde o Step Functions grava os resultados das execuções de um fluxo de trabalho secundário iniciadas por um estado Mapa Distribuído. Por padrão, o Step Functions não exporta esses resultados.

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 do seu payload de saída exceder 256 KB. 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 mostra a sintaxe do campo ResultWriter de quando você exporta os resultados da execução de um fluxo de trabalho secundário. Nesse exemplo, os resultados são armazenados em um bucket chamado myOutputBucket, dentro de um prefixo chamado csvProcessJobs.

{
  "ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
      "Bucket": "myOutputBucket",
      "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:123456789012:mapRun:csvProcess/Map:ad9b5f27-090b-3ac6-9beb-243cd77144a7",
  "ResultWriterDetails": {
    "Bucket": "myOutputBucket",
    "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:

nota

Se o tamanho da saída retornada exceder 256 KB, a execução da máquina de estado falhará e retornará um erro States.DataLimitExceeded.

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

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. Essas políticas 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 Mapa Distribuído. Essas políticas também incluem os privilégios mínimos necessários para que o Step Functions acesse recursos da AWS, como buckets e objetos do Amazon S3 e funções do Lambda. É altamente recomendável que você inclua apenas 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 o conjunto de 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:::resultBucket/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 AWS KMS key bucket criptografado do Amazon S3.