As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # 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 `ItemReader` campo em um fluxo de trabalho **JSONPathbaseado**, para um conjunto de dados em um arquivo delimitado por texto que é 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 fluxo de trabalho **JSONatabaseado** a seguir, observe que ele `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 ItemReader campo 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. + `ItemsPointer` *Opcional.* Você pode especificar esse campo quando `InputType` estiver`JSON`. `ItemsPointer`usa a JSONPointer sintaxe para selecionar uma matriz ou objeto específico aninhado em seu arquivo JSON. JSONPointer é uma sintaxe padronizada projetada exclusivamente para navegar e referenciar locais em documentos JSON. JSONPointer a sintaxe usa barras (/) para separar cada nível de aninhamento, com índices de matriz representados como números sem colchetes. Por exemplo: + `/Data/Contents`- faz referência à matriz Contents dentro do objeto Data + `/Data/Contents/0`- faz referência ao primeiro elemento da matriz Contents A posição inicial da matriz de destino deve estar dentro dos primeiros 16 MB do arquivo JSON e o JSONPointer caminho deve ter menos de 2.000 caracteres. Por exemplo, se seu arquivo JSON contiver: ``` {"data": {"items": [{"id": 1}, {"id": 2}]}} ``` Você especificaria `"ItemsPointer": "/data/items"` o processamento da matriz de itens. + `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 **JSONPath**fluxos de trabalho, você pode usar `MaxItemsPath` um *caminho de referência* para um par de valores-chave 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** Seus buckets do Amazon S3 devem estar na mesma máquina de estado Conta da AWS e Região da AWS na mesma. Observe que, embora sua máquina de estado possa acessar arquivos em buckets diferentes Contas da AWS que estejam na mesma Região da AWS, o Step Functions só suporta a listagem de objetos em buckets do Amazon S3 que estejam *na* mesma máquina e na Conta da AWS Região da AWS mesma 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 com`S3: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](#itemsource-json-array) + [Uma lista de objetos do Amazon S3](#itemsource-example-s3-object-data) + [Objetos do Amazon S3 transformados por LOAD\$1AND\$1FLATTEN](#itemsource-example-s3-object-data-flatten) + [Arquivo JSON em um bucket do Amazon S3](#itemsource-example-json-data) + [Arquivo de linhas JSON em um bucket do Amazon S3](#itemsource-example-json-lines-data) + [Arquivo CSV em um bucket do Amazon S3](#itemsource-example-csv-data) + [Arquivo Parquet em um bucket do Amazon S3](#itemsource-example-parquet-data) + [Manifesto do Athena (processar vários itens)](#itemsource-example-athena-manifest-data) + [Inventário Amazon S3 (processar vários itens)](#itemsource-example-s3-inventory) **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](#itemreader-iam-policies). ### Dados JSON de uma etapa anterior 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 ou objeto JSON aninhado na entrada, você pode usar o `ItemsPath (Mapa, JSONPath somente)` ou usar uma JSONata expressão no `Items` campo para JSONata estados. 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. ------ #### [ Input passed to the Map state ] Considere a seguinte matriz JSON de três itens. ``` "facts": [ { "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" } ] ``` ------ #### [ Input passed to a child workflow execution ] O *estado Mapa Distribuído* inicia três execuções do fluxo de trabalho secundário. Cada execução recebe um item de matriz como entrada. O exemplo a seguir mostra a entrada recebida pela execução de um fluxo de trabalho secundário. ``` { "verdict": "true", "statement_date": "6/11/2008", "statement_source": "speech" } ``` ------ ### Uma lista de objetos do Amazon S3 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 `Map` estado, o Step Functions invoca a ação da API [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html), que retorna uma matriz dos metadados do objeto Amazon S3.** Nessa matriz, cada item contém dados, como **ETag**e **Key**, dos 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\$1AND\$1FLATTEN 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 cada pasta, recomendamos que você use o AWS CLI para criar pastas. Para obter informações, consulte [Comandos de alto nível do Amazon S3](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-buckets-creating) 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](#itemreader-iam-policies). 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. ------ #### [ ItemReader syntax ] Nesse exemplo, foi mostrado como organizar seus dados, que incluem imagens, arquivos JSON e objetos, dentro de um prefixo nomeado `processData` em um bucket do Amazon S3 designado `amzn-s3-demo-bucket`. ``` "ItemReader": { "Resource": "arn:aws:states:::s3:listObjectsV2", "Parameters": { "Bucket": "amzn-s3-demo-bucket", "Prefix": "processData" } } ``` ------ #### [ Input passed to a child workflow execution ] O *estado de mapa distribuído* iniciará tantas execuções de fluxo de trabalho secundário quanto o número de itens de metadados presentes no bucket do Amazon S3. O exemplo a seguir mostra a entrada recebida pela execução de um fluxo de trabalho secundário. ``` { "Etag": "\"05704fbdccb224cb01c59005bebbad28\"", "Key": "processData/images/n02085620_1073.jpg", "LastModified": 1668699881, "Size": 34910, "StorageClass": "STANDARD" } ``` ------ ### Objetos do Amazon S3 transformados por `LOAD_AND_FLATTEN` Com suporte aprimorado para o S3 ListObjects V2 como fonte de entrada no Distributed Map, 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\$1 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. + Analise o conteúdo com base em 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\$1AND\$1FLATTEN 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. ### Arquivo JSON em um bucket do Amazon S3 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 `Map` estado, o Step Functions invoca a ação da [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API 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](#itemreader-iam-policies). 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" }, ... ] ``` ------ #### [ ItemReader syntax ] ``` "ItemReader": { "Resource": "arn:aws:states:::s3:getObject", "ReaderConfig": { "InputType": "JSON" }, "Parameters": { "Bucket": "amzn-s3-demo-bucket", "Key": "jsonDataset/factcheck.json" } } ``` ------ #### [ Input to a child workflow execution ] O *estado Mapa Distribuído* iniciará quantas execuções de fluxo de trabalho secundário forem necessárias para o número de itens de matriz presentes no arquivo JSON. O exemplo a seguir mostra a entrada recebida pela execução de um fluxo de trabalho secundário. ``` { "verdict": "true", "statement_date": "6/11/2008", "statement_source": "speech" } ``` ------ ### Arquivo de linhas JSON em um bucket do Amazon S3 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](#itemreader-iam-policies). 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"} ``` ------ #### [ ItemReader syntax ] ``` "ItemReader": { "Resource": "arn:aws:states:::s3:getObject", "ReaderConfig": { "InputType": "JSONL" }, "Parameters": { "Bucket": "amzn-s3-demo-bucket", "Key": "jsonlDataset/factcheck.jsonl" } } ``` ------ #### [ Input to a child workflow execution ] O *estado Mapa Distribuído* iniciará tantas execuções de fluxo de trabalho secundário quanto o número de linhas presentes no arquivo JSON. O exemplo a seguir mostra a entrada recebida pela execução de um fluxo de trabalho secundário. ``` { "verdict": "true", "statement_date": "6/11/2008", "statement_source": "speech" } ``` ------ ### Arquivo CSV em um bucket do Amazon S3 **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 ItemReader campo](#itemreader-field-contents). O Step Functions analisa arquivos delimitados por texto com base nas seguintes regras: + O delimitador que separa os campos é especificado por in. `CSVDelimiter` *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)](input-output-itemselector.md). + 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 (\$1) 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](example-csv-parse-dist-map.md#example-csv-parse). Quando a execução do fluxo de trabalho atinge o `Map` estado, o Step Functions invoca a ação da [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API 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](#itemreader-iam-policies). 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. ------ #### [ ItemReader syntax ] Por exemplo, digamos que você tenha um arquivo CSV chamado `ratings.csv`. Você armazenou esse arquivo em um prefixo designado `csvDataset`, em um bucket do Amazon S3. ``` "ItemReader": { "ReaderConfig": { "InputType": "CSV", "CSVHeaderLocation": "FIRST_ROW", "CSVDelimiter": "PIPE" }, "Resource": "arn:aws:states:::s3:getObject", "Parameters": { "Bucket": "amzn-s3-demo-bucket", "Key": "csvDataset/ratings.csv" } } ``` ------ #### [ Input to a child workflow execution ] O *estado Mapa Distribuído* iniciará quantas execuções de fluxo de trabalho secundário forem necessárias para o número de linhas presentes no arquivo CSV, excluindo a linha de cabeçalho, se presente no arquivo. O exemplo a seguir mostra a entrada recebida pela execução de um fluxo de trabalho secundário. ``` { "rating": "3.5", "movieId": "307", "userId": "1", "timestamp": "1256677221" } ``` ------ ### Arquivo Parquet em um bucket do Amazon S3 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. ### Manifesto do Athena (processar vários itens) 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 () TO 'S3_URI_FOR_STORING_DATA_OBJECT' WITH (format = 'JSON') ``` Visão geral conceitual do processo, em resumo: 1. Selecione seus dados de uma tabela usando uma consulta `UNLOAD` no Athena. 1. O Athena gerará um arquivo de manifesto (CSV) e os objetos de dados no Amazon S3. 1. 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 InputType formato. 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": "", "Key": "-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. ### Inventário S3 (processar vários itens) 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 `Map` estado, o Step Functions invoca a ação da [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)API para buscar o arquivo de manifesto de inventário especificado do 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\$1INVENTORY, 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](#itemreader-iam-policies). 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html). 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. ------ #### [ ItemReader syntax ] ``` "ItemReader": { "ReaderConfig": { "InputType": "MANIFEST" }, "Resource": "arn:aws:states:::s3:getObject", "Parameters": { "Bucket": "amzn-s3-demo-destination-bucket", "Key": "destination-prefix/amzn-s3-demo-bucket/config-id/YYYY-MM-DDTHH-MMZ/manifest.json" } } ``` ------ #### [ Input to a child workflow execution ] ``` { "LastModifiedDate": "2022-11-16T00:29:32.000Z", "Bucket": "amzn-s3-demo-source-bucket", "Size": "3399671", "Key": "csvDataset/titles.csv" } ``` Dependendo dos campos selecionados ao configurar o relatório do Inventário Amazon S3, o conteúdo do arquivo `manifest.json` pode variar do exemplo. ------ ## 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 a função de máquina de estado invoque a ação da `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API para o *estado do Mapa Distribuído* e acesse AWS recursos, como buckets e objetos do Amazon S3 e funções 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](amazon-states-language-paths.md#amazon-states-language-reference-paths) 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 seus conjuntos de dados do Amazon S3 usando ListObjects as ações de V2 e API. [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) **Example 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" ] } } ``` **Example 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" ] ``` **Example 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/*" ] ``` **Example usando ListObjects V2 para restringir a um prefixo de pasta** Ao usar a [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html), 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.