Conteúdo do campo ItemReader Processar conjuntos de dados aninhados (atualizado em 11 de setembro de 2025)Exemplos de conjuntos de dados Recomendações de políticas do IAM para conjuntos de dados

ItemReader (mapa)

O campo ItemReader é um objeto JSON, que especifica um conjunto de dados e sua localização. Um estado Mapa Distribuído usa esse conjunto de dados como entrada.

O exemplo a seguir mostra a sintaxe do campo ItemReader em um fluxo de trabalho baseado em JSONPath para um conjunto de dados em um arquivo delimitado por texto e armazenado em um bucket do Amazon S3.


"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
        "Bucket": "amzn-s3-demo-bucket",
        "Key": "csvDataset/ratings.csv",
        "VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
    }
}

No seguinte fluxo de trabalho baseado em JSONata, observe que Parameters foi substituído por argumentos.


"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Arguments": {
        "Bucket": "amzn-s3-demo-bucket",
        "Key": "csvDataset/ratings.csv"
        "VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
    }
}

Conteúdo do campo ItemReader

Dependendo do seu conjunto de dados, o conteúdo do campo ItemReader varia. Por exemplo, se seu conjunto de dados for uma matriz JSON transmitida de uma etapa anterior do fluxo de trabalho, o campo ItemReader será omitido. Se seu conjunto de dados for uma fonte de dados do Amazon S3, esse campo conterá os seguintes subcampos.

Resource

A ação de integração da API do Amazon S3 que o Step Functions usará, como arn:aws:states:::s3:getObject

Arguments (JSONata) or Parameters (JSONPath)

Um objeto JSON que especifica o nome do bucket do Amazon S3 e a chave do objeto em que o conjunto de dados está armazenado.

Se o bucket tem versionamento habilitado, você também pode fornecer a versão de objeto do Amazon S3.

ReaderConfig

Um objeto JSON que especifica os seguintes detalhes:

InputType

Aceita um dos seguintes valores: CSV, JSON, JSONL, PARQUET, MANIFEST.

Especifica o tipo de fonte de dados do Amazon S3, como um arquivo delimitado por texto (CSV), um objeto, um arquivo JSON, linhas JSON, um arquivo Parquet, um manifesto do Athena ou uma lista de inventário Amazon S3. No Workflow Studio, você pode selecionar um tipo de entrada na fonte do item do S3.

A maioria dos tipos de entrada que usam a recuperação S3GetObject também oferece suporte aos campos ExpectedBucketOwner e VersionId em seus parâmetros. Os arquivos Parquet são a única exceção que não é compatível com VersionId.

Os arquivos de entrada são compatíveis com os seguintes tipos de compactação externa: GZIP, ZSTD.

Exemplos de nomes de arquivo: myObject.jsonl.gz e myObject.csv.zstd.

Observação: os arquivos Parquet são um tipo de arquivo binário compactado internamente. As compressões em GZIP, ZSTD e Snappy são compatíveis.
Transformation

Opcional. O valor será NONE ou LOAD_AND_FLATTEN.

Se não for especificado, NONE será assumido. Quando definido como LOAD_AND_FLATTEN, você também deve definir o InputType.

Comportamento padrão: o mapa iterará sobre objetos de metadados retornados de chamadas para S3:ListObjectsV2. Quando definido como LOAD_AND_FLATTEN, o mapa lerá e processará os objetos de dados reais referenciados na lista de resultados.
ManifestType

Opcional. O valor será ATHENA_DATA ou S3_INVENTORY.

Observação: se definido como S3_INVENTORY, você também não deve especificar InputType porque se presume que o tipo seja CSV.
CSVDelimiter

Você pode especificar esse campo quando InputType for CSV ou MANIFEST.

Aceita um dos seguintes valores: COMMA (padrão), PIPE, SEMICOLON, SPACE, TAB.

nota
Com o campo CSVDelimiter, o ItemReader pode processar arquivos delimitados por caracteres que não sejam uma vírgula. As referências a “arquivos CSV” também incluem arquivos que usam delimitadores alternativos especificados pelo campo CSVDelimiter.
CSVHeaderLocation

Você pode especificar esse campo quando InputType for CSV ou MANIFEST.

Aceita um dos seguintes valores para especificar a localização do cabeçalho da coluna:
- FIRST_ROW — use essa opção se a primeira linha do arquivo for o cabeçalho.
- GIVEN — use essa opção para especificar o cabeçalho na definição da máquina de estado.
  
  Por exemplo, se seu arquivo contém os dados a seguir.
```
1,307,3.5,1256677221
1,481,3.5,1256677456
1,1091,1.5,1256677471
...
```
  Você pode fornecer a seguinte matriz JSON como cabeçalho CSV.
```
"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "GIVEN",
        "CSVHeaders": [
            "userId",
            "movieId",
            "rating",
            "timestamp"
        ]
    }
}
```
Tamanho do cabeçalho CSV
O Step Functions é compatível com cabeçalhos de até 10 KiB para arquivos delimitados por texto.
MaxItems

Por padrão, o estado Map itera todos os itens no conjunto de dados especificado. Ao definir MaxItems, você pode limitar o número de itens de dados transmitidos para o estado Map. Por exemplo, se você fornecer um arquivo delimitado por texto que contém 1.000 linhas e definir um limite de 100, o intérprete passará somente 100 linhas para o estado de mapa distribuído. O estado Map processa os itens em ordem sequencial, começando depois da linha do cabeçalho.

Para fluxos de trabalho JSONPath, você pode usar MaxItemsPath e um caminho de referência para um par de chave/valor na entrada de estado, que é resolvido como um número inteiro. Observe que você pode especificar MaxItems ou MaxItemsPath, mas não ambos.

nota
É possível especificar um limite de até cem milhões após o qual o Distributed Map para de ler itens.

Requisitos de conta e região

Os buckets do Amazon S3 devem estar na mesma Conta da AWS e Região da AWS que a máquina de estado.

Observe que, embora a máquina de estado possa acessar arquivos em buckets de diferentes Contas da AWS que estejam na mesma Região da AWS, o Step Functions só oferece suporte à listagem de objetos em buckets do Amazon S3 que estejam ambos na mesma Conta da AWS e Região da AWS que a máquina de estado.

Processar conjuntos de dados aninhados (atualizado em 11 de setembro de 2025)

Com o novo parâmetro Transformation, você pode especificar um valor de LOAD_AND_FLATTEN e o mapa lerá os objetos de dados reais referenciados na lista de resultados de uma chamada para S3:ListObjectsV2.

Antes dessa versão, você precisaria criar mapas distribuídos aninhados para recuperar os metadados e então processar os dados reais. O primeiro mapa iteraria sobre os metadados retornados por S3:ListObjectsV2 e invocaria fluxos de trabalho secundários. Outro mapa dentro de cada máquina de estado secundário leria os dados reais de arquivos individuais. Com a opção de transformação, você pode realizar ambas as etapas ao mesmo tempo.

Imagine que você queira executar uma auditoria diária nos últimos 24 arquivos de log que seu sistema produz de hora em hora e armazena no Amazon S3. Seu estado de mapa distribuído pode listar os arquivos de log comS3:ListObjectsV2 e iterar sobre os metadados de cada objeto, ou pode carregar e analisar os objetos de dados reais armazenados em seu bucket do Amazon S3.

Usar a LOAD_AND_FLATTEN opção pode aumentar a escalabilidade, reduzir as contagens de execuções de mapas abertos e processar vários objetos simultaneamente. Normalmente, os trabalhos do Athena e do Amazon EMR geram resultados que podem ser processados com a nova configuração.

Veja o seguinte exemplo desses parâmetros em uma definição ItemReader:


{
  "QueryLanguage": "JSONata",
  "States": {
    ...
    "Map": {
        ...
        "ItemReader": {
            "Resource": "arn:aws:states:::s3:listObjectsV2",
            "ReaderConfig": {
                // InputType is required if Transformation is LOAD_AND_FLATTEN.
                "InputType": "CSV | JSON | JSONL | PARQUET",

                // Transformation is OPTIONAL and defaults to NONE if not present
                "Transformation": "NONE | LOAD_AND_FLATTEN" 
            },
            "Arguments": {
                "Bucket": "amzn-s3-demo-bucket1",
                "Prefix": "{% $states.input.PrefixKey %}"
            }
        },
        ...
    }
}

Exemplos de conjuntos de dados

Você pode especificar uma das seguintes opções como conjunto de dados:

Dados JSON de uma etapa anterior
Uma lista de objetos do Amazon S
Objetos do Amazon S3 transformados por LOAD_AND_FLATTEN
Arquivo JSON em um bucket do Amazon S
Arquivo de linhas JSON em um bucket do Amazon S3
Arquivo CSV em um bucket do Amazon S
Arquivo Parquet em um bucket do Amazon S3
Manifesto do Athena (processar vários itens)
Inventário Amazon S3 (processar vários itens)

nota

O Step Functions precisa das devidas permissões para acessar conjuntos de dados do Amazon S3 que você usa. Para obter informações sobre políticas do IAM para o conjunto de dados, consulte Recomendações de políticas do IAM para conjuntos de dados.

Um estado Mapa Distribuído pode aceitar uma entrada JSON transmitida de uma etapa anterior no fluxo de trabalho.

A entrada pode ser uma matriz JSON, um objeto JSON ou uma matriz dentro do nó de um objeto JSON.

O Step Functions iterará diretamente sobre os elementos de uma matriz ou os pares de chave/valor de um objeto JSON.

Para selecionar um nó específico que contém uma matriz de um objeto JSON, você pode usar ItemsPath (somente mapa, JSONPath) ou usar uma expressão JSONata no campo Items para estados JSONata.

Para processar itens individuais, o estado de mapa distribuído inicia a execução de um fluxo de trabalho secundário para cada item. As guias a seguir mostram exemplos da entrada transmitidas para o estado Map e a entrada correspondente para a execução de um fluxo de trabalho secundário.

nota

O campo ItemReader não é necessário quando o conjunto de dados são dados JSON de uma etapa anterior.

Um estado Mapa Distribuído pode iterar os objetos que são armazenados em um bucket do Amazon S3. Quando a execução do fluxo de trabalho atinge o estado Map, o Step Functions invoca a ação da API ListObjectsV2, que retorna uma matriz dos metadados de objeto do Amazon S3. Nessa matriz, cada item contém dados, como ETag e Key, para os dados reais armazenados no bucket.

Para processar itens individuais na matriz, o estado Mapa Distribuído inicia a execução de um fluxo de trabalho secundário. Por exemplo, suponha que seu bucket do Amazon S3 contenha cem imagens. Então, a matriz retornada após invocar a ação da API ListObjectsV2 contém cem itens de metadados. O estado de mapa distribuído inicia cem execuções de fluxo de trabalho secundário para processar cada item.

Para processar objetos de dados diretamente, sem fluxos de trabalho aninhados, você pode escolher a opção Transformação LOAD_AND_FLATTEN para processar itens diretamente.

nota

O Step Functions também incluirá um item para cada pasta criada no bucket do Amazon S3 usando o console do Amazon S3. Os itens da pasta resultam no início de execuções adicionais do fluxo de trabalho secundário.

Para evitar a criação de execuções adicionais de fluxo de trabalho secundário para a pasta, recomendamos usar a AWS CLI para criar pastas. Para obter informações, consulte Comandos de alto nível do Amazon S3 no Guia do usuário da AWS Command Line Interface.
O Step Functions precisa das devidas permissões para acessar conjuntos de dados do Amazon S3 que você usa. Para obter informações sobre políticas do IAM para o conjunto de dados, consulte Recomendações de políticas do IAM para conjuntos de dados.

As guias a seguir mostram exemplos da sintaxe do campo ItemReader e da entrada transmitida para a execução de um fluxo de trabalho secundário para esse conjunto de dados.

Com suporte aprimorado para ListObjectsV2 do S3 como fonte de entrada no mapa distribuído, suas máquinas de estado podem ler e processar vários objetos de dados diretamente dos buckets do Amazon S3, eliminando a necessidade de mapas aninhados para processar os metadados.

Com a opção LOAD_AND_FLATTEN, sua máquina de estado fará o seguinte:

Ler o conteúdo real de cada objeto listado pela chamada ListObjectsV2 do Amazon S3.
Analisar o conteúdo com base no InputType (CSV, JSON, JSONL, Parquet).
Criar itens a partir do conteúdo do arquivo (linhas/registros) em vez de metadados.

Com a opção de transformação, você não precisa mais de mapas distribuídos aninhados para processar os metadados. Usar a opção LOAD_AND_FLATTEN aumenta a escalabilidade, reduz as contagens de execuções de mapas ativos e processa vários objetos simultaneamente.

A seguinte configuração mostra a definição para um ItemReader:


"ItemReader": {
   "Resource": "arn:aws:states:::s3:listObjectsV2",
   "ReaderConfig": {
      "InputType": "JSON",
      "Transformation": "LOAD_AND_FLATTEN"
   },
   "Arguments": {
      "Bucket": "S3_BUCKET_NAME",
      "Prefix": "S3_BUCKET_PREFIX"
   }
}

Recomendação de prefixo de bucket

Recomendamos incluir uma barra final no prefixo. Por exemplo, se você selecionar dados com um prefixo de folder1, sua máquina de estado processará ambos folder1/myData.csv e folder10/myData.csv. Usar folder1/ processará estritamente somente uma pasta.

Um estado Mapa Distribuído pode aceitar um arquivo JSON armazenado em um bucket do Amazon S3 como um conjunto de dados. O arquivo JSON deve conter uma matriz ou um objeto JSON.

Quando a execução do fluxo de trabalho atinge o estado Map, o Step Functions invoca a ação da API GetObject para buscar o arquivo JSON especificado.

Se o arquivo JSON contiver uma estrutura de objeto aninhada, você poderá selecionar o nó específico com seu conjunto de dados com um ItemsPointer. Por exemplo, a configuração a seguir extrairia uma lista aninhada de produtos em destaque no inventário.


"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "InputType": "JSON",
      "ItemsPointer": "/inventory/products/featured"
   },
   "Arguments": {
      "Bucket": "amzn-s3-demo-bucket",
      "Key": "nested-data-file.json"
   }
}

O estado Map então itera cada item na matriz e inicia a execução de um fluxo de trabalho secundário para cada item. Por exemplo, se seu arquivo JSON contiver mil itens de matriz, o estado Map iniciará mil execuções de fluxo de trabalho secundário.

nota

A entrada de execução usada para iniciar a execução de um fluxo de trabalho secundário não pode exceder 256 KiB. No entanto, o Step Functions oferece suporte à leitura de um item de até 8 MB de um arquivo delimitado por texto, JSON linhas JSON quando você aplica o campo ItemSelector opcional para reduzir o tamanho de um item.
O Step Functions oferece suporte de no máximo 10 GB a arquivos individuais no Amazon S3.
O Step Functions precisa das devidas permissões para acessar conjuntos de dados do Amazon S3 que você usa. Para obter informações sobre políticas do IAM para o conjunto de dados, consulte Recomendações de políticas do IAM para conjuntos de dados.

As guias a seguir mostram exemplos da sintaxe do campo ItemReader e da entrada transmitida para a execução de um fluxo de trabalho secundário para esse conjunto de dados.

Por exemplo, imagine que você tenha um arquivo JSON chamado factcheck.json. Você armazenou esse arquivo em um prefixo chamado jsonDataset, em um bucket do Amazon S3. A seguir, veja um exemplo do conjunto de dados 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"
  },
  ...
]

Um estado de mapa distribuído pode aceitar um arquivo de linhas JSON armazenado em um bucket do Amazon S3 como um conjunto de dados.

nota

A entrada de execução usada para iniciar a execução de um fluxo de trabalho secundário não pode exceder 256 KiB. No entanto, o Step Functions oferece suporte à leitura de um item de até 8 MB de um arquivo delimitado por texto, JSON linhas JSON quando você aplica o campo ItemSelector opcional para reduzir o tamanho de um item.
O Step Functions oferece suporte de no máximo 10 GB a arquivos individuais no Amazon S3.
O Step Functions precisa das devidas permissões para acessar conjuntos de dados do Amazon S3 que você usa. Para obter informações sobre políticas do IAM para o conjunto de dados, consulte Recomendações de políticas do IAM para conjuntos de dados.

As guias a seguir mostram exemplos da sintaxe do campo ItemReader e da entrada transmitida para a execução de um fluxo de trabalho secundário para esse conjunto de dados.

Por exemplo, imagine que você tenha um arquivo de linhas JSON chamado factcheck.jsonl. Você armazenou esse arquivo em um prefixo chamado jsonlDataset, em um bucket do Amazon S3. Veja a seguir um exemplo do conteúdo de um arquivo.


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

nota

Com o campo CSVDelimiter, o ItemReader pode processar arquivos delimitados por caracteres que não sejam uma vírgula. As referências a “arquivos CSV” também incluem arquivos que usam delimitadores alternativos especificados pelo campo CSVDelimiter.

Um estado de mapa distribuído pode aceitar um arquivo delimitado por texto armazenado em um bucket do Amazon S3 como um conjunto de dados. Se você usar um arquivo delimitado por texto como o conjunto de dados, precisará especificar um cabeçalho de coluna. Para obter informações sobre como especificar um cabeçalho, consulte Conteúdo do campo ItemReader.

O Step Functions analisa arquivos delimitados por texto com base nas seguintes regras:

O delimitador que separa os campos é especificado por CSVDelimiter em ReaderConfig. O delimitador usa COMMA como padrão.
As novas linhas são um delimitador que separa registros.
Os campos são tratados como strings. Para conversões de tipo de dados, use a função intrínseca States.StringToJson em ItemSelector (mapa).
Não são necessárias aspas duplas (“ ”) nas strings. No entanto, strings delimitadas por aspas duplas podem conter vírgulas e novas linhas sem agir como delimitadores de registro.
É possível preservar as aspas duplas repetindo-as.
Barras invertidas (\) são outra forma de escapar de caracteres especiais. As barras invertidas só funcionam com outras barras invertidas, aspas duplas e com o separador de campo configurado, como vírgula ou barra vertical. Uma barra invertida seguida por qualquer outro caractere é removida silenciosamente.
É possível preservar as barras invertidas repetindo-as. Por exemplo:
```
path,size
C:\\Program Files\\MyApp.exe,6534512
```
Barras invertidas que escapam das aspas duplas (\") só funcionam quando incluídas em pares, então recomendamos escapar das aspas duplas as repetindo: "".
Se o número de campos em uma linha for menor que o número de campos no cabeçalho, o Step Functions fornecerá strings vazias para os valores que estão faltando.
Se o número de campos em uma linha for maior que aquele no cabeçalho, o Step Functions vai ignorar os campos adicionais.

Para obter mais informações sobre como Step Functions analisa um arquivo delimitado por texto, consulte Example of parsing an input CSV file.

Quando a execução do fluxo de trabalho atinge o estado Map, o Step Functions invoca a ação da API GetObject para buscar o arquivo especificado. O estado Map então itera cada linha no arquivo e inicia a execução de um fluxo de trabalho secundário para processar os itens em cada linha. Por exemplo, suponha que você vá fornecer um arquivo delimitado por texto contendo cem linhas como entrada. Então, o intérprete transmitirá cada linha para o estado Map. O estado Map processa os itens em ordem serial, começando depois da linha do cabeçalho.

nota

A entrada de execução usada para iniciar a execução de um fluxo de trabalho secundário não pode exceder 256 KiB. No entanto, o Step Functions oferece suporte à leitura de um item de até 8 MB de um arquivo delimitado por texto, JSON linhas JSON quando você aplica o campo ItemSelector opcional para reduzir o tamanho de um item.
O Step Functions oferece suporte de no máximo 10 GB a arquivos individuais no Amazon S3.
O Step Functions precisa das devidas permissões para acessar conjuntos de dados do Amazon S3 que você usa. Para obter informações sobre políticas do IAM para o conjunto de dados, consulte Recomendações de políticas do IAM para conjuntos de dados.

As guias a seguir mostram exemplos da sintaxe do campo ItemReader e da entrada transmitida para a execução de um fluxo de trabalho secundário para esse conjunto de dados.

Os arquivos Parquet podem ser usados como fonte de entrada. Os arquivos Apache Parquet armazenados no Amazon S3 fornecem processamento eficiente de dados colunares em grande escala.

Ao usar arquivos Parquet, as seguintes condições se aplicam:

O tamanho máximo do grupo de linhas é 256 MB, e o tamanho máximo do rodapé é 5 MB. Se você fornecer arquivos de entrada que excedam qualquer um dos limites, sua máquina de estado retornará um erro de runtime.
O campo VersionId não é compatível com InputType=Parquet.
As compressões de dados internas em GZIP, ZSTD e Snappy são nativamente compatíveis. Nenhuma extensão de nome de arquivo é necessária.

Veja a seguir um exemplo de configuração de ASL para InputType definido como Parquet:


"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "InputType": "PARQUET"
   },
   "Arguments": {
      "Bucket": "amzn-s3-demo-bucket",
      "Key": "my-parquet-data-file-1.parquet"
   }
}

Processamento de trabalhos em grande escala

Para trabalhos de escala extremamente grande, o Step Functions usará muitos leitores de entrada. Os leitores intercalam o processamento, o que pode fazer com que alguns pausem enquanto outros progridem. O progresso intermitente é o comportamento esperado em grande escala.

Você pode usar os arquivos de manifesto do Athena, gerados a partir dos resultados da consulta UNLOAD, para especificar a origem dos arquivos de dados para o estado do mapa. Defina ManifestType como ATHENA_DATA e InputType como CSV, JSONL ou Parquet.

Ao executar uma consulta UNLOAD, o Athena gera um arquivo de manifesto de dados, além dos objetos de dados reais. O arquivo de manifesto fornece uma lista CSV estruturada dos arquivos de dados. Os dois arquivos de manifesto e dados são salvos no local dos resultados das consultas do Athena no Amazon S3.


UNLOAD (<YOUR_SELECT_QUERY>) TO 'S3_URI_FOR_STORING_DATA_OBJECT' WITH (format = 'JSON')

Visão geral conceitual do processo, em resumo:

Selecione seus dados de uma tabela usando uma consulta UNLOAD no Athena.
O Athena gerará um arquivo de manifesto (CSV) e os objetos de dados no Amazon S3.
Configure o Step Functions para ler o arquivo de manifesto e processar a entrada.

O recurso pode processar os formatos de saída CSV, JSONL e Parquet do Athena. Todos os objetos referenciados em um único arquivo de manifesto devem ter o mesmo formato InputType. Observe que os objetos CSV exportados por uma consulta UNLOAD não incluem cabeçalho na primeira linha. Consulte CSVHeaderLocation se precisar fornecer cabeçalhos de coluna.

O contexto do mapa também incluirá um $states.context.Map.Item.Source para que você possa personalizar o processamento com base na fonte dos dados.

Veja a seguir um exemplo de configuração de um ItemReader configurado para usar um manifesto do Athena:


"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "ManifestType": "ATHENA_DATA",
      "InputType": "CSV | JSONL | PARQUET"
   },
   "Arguments": {
      "Bucket": "<S3_BUCKET_NAME>",
      "Key": "<S3_KEY_PREFIX><QUERY_ID>-manifest.csv"
   }
}

Usar o padrão de manifesto do Athena no Workflow Studio

Um cenário comum para processamento de dados aplica um mapa aos dados provenientes de uma consulta UNLOAD do Athena. O mapa invoca uma função do Lambda para processar cada item descrito no manifesto do Athena. O Step Functions Workflow Studio fornece um padrão pronto que combina todos esses componentes em um bloco que você pode arrastar para a tela da sua máquina de estado.

Um estado Mapa Distribuído pode aceitar um manifesto do Inventário Amazon S3 armazenado em um bucket do Amazon S3 como um conjunto de dados.

Quando a execução do fluxo de trabalho atinge o estado Map, o Step Functions invoca a ação da API GetObject para buscar o arquivo do manifesto do Inventário Amazon S3.

Por padrão, o estado Map então itera os objetos no inventário para retornar uma matriz de metadados de objetos do Inventário Amazon S3.

Se você especificar ManifestType como S3_INVENTORY, então InputType não poderá ser especificado.

nota

O Step Functions oferece suporte de no máximo 10 GB a arquivos individuais em um relatório do Inventário Amazon S3 após descompressão. No entanto, o Step Functions é capaz de processar mais de 10 GB se o tamanho de cada arquivo individual é inferior a esse valor.
O Step Functions precisa das devidas permissões para acessar conjuntos de dados do Amazon S3 que você usa. Para obter informações sobre políticas do IAM para o conjunto de dados, consulte Recomendações de políticas do IAM para conjuntos de dados.

Veja a seguir o exemplo de um arquivo de inventário no formato CSV. Esse arquivo inclui os objetos chamados csvDataset e imageDataset, que são armazenados em um bucket do Amazon S3 com o nome amzn-s3-demo-source-bucket.


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

Importante

O Step Functions não oferece suporte ao uso de um relatório do Inventário Amazon S3 definido pelo usuário como um conjunto de dados.

O formato de saída do seu relatório do Inventário Amazon S3 deve ser em CSV.

Para obter mais informações sobre inventários Amazon S3 e como configurá-los, consulte Inventário Amazon S3.

O exemplo a seguir de um arquivo de manifesto de inventário Amazon S3 mostra os cabeçalhos CSV dos metadados do objeto de inventário.


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

As guias a seguir mostram exemplos da sintaxe do campo ItemReader e da entrada transmitida para a execução de um fluxo de trabalho secundário para esse conjunto de dados.

Recomendações de políticas do IAM para conjuntos de dados

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.

Os exemplos a seguir mostram técnicas para conceder os privilégios mínimos necessários para acessar os conjuntos de dados do Amazon S3 usando as ações de API ListObjectsV2 e GetObject.

exemplo condição usando um objeto do Amazon S3 como o conjunto de dados

A condição a seguir concede os privilégios mínimos para acessar objetos em uma pasta processImages de um bucket do Amazon S3.


"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ],
"Condition": {
   "StringLike": { 
      "s3:prefix": [ "processImages" ]
   }
}

exemplo usando um arquivo CSV como um conjunto de dados

O exemplo a seguir mostra as ações necessárias para acessar um arquivo CSV chamado ratings.csv.


"Action": [ "s3:GetObject" ],
"Resource": [
   "arn:aws:s3:::amzn-s3-demo-bucket/csvDataset/ratings.csv"
   ]

exemplo usando um inventário Amazon S3 como um conjunto de dados

Veja a seguir exemplos de recursos para um manifesto de arquivos de dados e Inventário Amazon S3.


"Resource": [
   "arn:aws:s3:::myPrefix/amzn-s3-demo-bucket/myConfig-id/YYYY-MM-DDTHH-MMZ/manifest.json",
   "arn:aws:s3:::myPrefix/amzn-s3-demo-bucket/myConfig-id/data/*"
   ]

exemplo usando ListObjectsV2 para restringir a um prefixo de pasta

Ao usar ListObjectsV2, duas políticas serão geradas. Uma é necessária para permitir a listagem do conteúdo do bucket (ListBucket) e outra política permitirá recuperar objetos no bucket (GetObject).

Veja a seguir exemplos de ações, recursos e uma condição:


"Action": [ "s3:ListBucket" ],
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ],
"Condition": {
   "StringLike": {
      "s3:prefix": [ "/path/to/your/json/" ]
   }
}


"Action": [ "s3:GetObject" ],
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/path/to/your/json/*" ]

Observe que GetObject não será definido no escopo e você usará um curinga (*) para o objeto.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Configuração do estado mapa

ItemsPath (JSONPath)

ItemReader (mapa)

Conteúdo do campo ItemReader

nota

Tamanho do cabeçalho CSV

nota

Requisitos de conta e região

Processar conjuntos de dados aninhados (atualizado em 11 de setembro de 2025)

Exemplos de conjuntos de dados

nota

nota

nota

Recomendação de prefixo de bucket

nota

nota

nota

nota

Processamento de trabalhos em grande escala

Usar o padrão de manifesto do Athena no Workflow Studio

nota

Importante

Recomendações de políticas do IAM para conjuntos de dados

Importante

exemplo condição usando um objeto do Amazon S3 como o conjunto de dados

exemplo usando um arquivo CSV como um conjunto de dados

exemplo usando um inventário Amazon S3 como um conjunto de dados

exemplo usando ListObjectsV2 para restringir a um prefixo de pasta