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á.
# Processar entrada e saída no Step Functions
**Gerenciando o estado com variáveis e JSONata**
Recentemente, o Step Functions adicionou variáveis JSONata para gerenciar dados de estado e transformação.
Saiba mais na postagem do blog [Simplificando a experiência do desenvolvedor com variáveis e JSONata ](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/) em AWS Step Functions
Quando uma execução do Step Functions recebe entrada em JSON, ele passa os dados para o primeiro estado no fluxo de trabalho como entrada.
Com JSONata, você pode recuperar a entrada de estado de`$states.input`. As execuções de sua máquina de estado também fornecem os dados de entrada iniciais no [Objeto de contexto](input-output-contextobject.md). Você pode recuperar a entrada original da máquina de estado em qualquer ponto do seu fluxo de trabalho em `$states.context.Execution.Input`.
Quando os estados são encerrados, a saída fica disponível para o *próximo* estado na máquina de estados. As entradas de estado passarão como saída de estado por padrão, a menos que você **modifique** a saída de estado. Se precisar de dados em etapas posteriores, considere armazená-los em variáveis. Para obter mais informações, consulte [Transmitir dados entre estados com variáveis](workflow-variables.md).
**QueryLanguage recomendação**
Para novas máquinas de estado, recomendamos a linguagem de JSONata consulta. Em máquinas de estado que não especificam um idioma de consulta, o padrão da máquina de estado é JSONPath para compatibilidade com versões anteriores. Você deve optar JSONata por usar em suas máquinas de estado ou estados individuais.
**Processando entrada e saída com JSONata**
Com JSONata expressões, você pode selecionar e transformar dados. No campo `Arguments`, é possível personalizar os dados enviados para a ação. O resultado pode ser transformado em saída de estado personalizada no campo `Output`. Você também pode armazenar dados em variáveis no campo `Assign`. Para obter mais informações, consulte [Transformação de dados com JSONata](transforming-data.md).
O diagrama a seguir mostra como as informações JSON se movem em um estado de JSONata tarefa.
![\[Diagram showing JSONata task state flow with input, arguments, output, and action components.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/vars-jsonata.png)
**Processando entrada e saída com JSONPath**
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Para máquinas de estado que usam JSONPath, os seguintes campos controlam o fluxo de dados de um estado para `InputPath` outro: `Parameters``ResultSelector`,`ResultPath`,, `OutputPath` e. Cada JSONPath campo pode manipular o JSON à medida que ele se move por cada estado em seu fluxo de trabalho.
JSONPath os campos podem usar [caminhos](amazon-states-language-paths.md) para selecionar partes do JSON da entrada ou do resultado. Um caminho é uma string, começando com `$`, que identifica nós com texto JSON. Os caminhos do Step Functions usam [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintaxe.
O diagrama a seguir mostra como as informações JSON se movem em um estado de JSONPath tarefa. O `InputPath` seleciona as partes da entrada JSON a serem passadas para a tarefa do `Task` estado (por exemplo, uma AWS Lambda função). Você pode ajustar os dados enviados à ação no campo `Parameters` campo. Em seguida, com `ResultSelector`, você pode selecionar partes do resultado da ação para levar adiante. `ResultPath` seleciona a combinação de entrada de estado e resultados da tarefa para transmitir para a saída. `OutputPath` pode filtrar a saída JSON para limitar ainda mais as informações passadas para a saída.
![\[Ordem dos filtros: InputPath, Parâmetros ResultSelector ResultPath,, OutputPath e.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/vars-jsonpath.png)
**Topics**
+ [
# Transmitir dados entre estados com variáveis
](workflow-variables.md)
+ [
# Transformando dados com Step JSONata Functions
](transforming-data.md)
+ [
# Acessar dados de execução do objeto de contexto no Step Functions
](input-output-contextobject.md)
+ [
# Usando JSONPath caminhos
](amazon-states-language-paths.md)
+ [
# Manipular parâmetros nos fluxos de trabalho do Step Functions
](input-output-inputpath-params.md)
+ [
# Exemplo: manipular dados de estado com caminhos em fluxos de trabalho do Step Functions
](input-output-example.md)
+ [
# Especificando a saída de estado usando ResultPath em Step Functions
](input-output-resultpath.md)
+ [
# Campos de entrada e de saída de estado do mapa no Step Functions
](input-output-fields-dist-map.md)
# Transmitir dados entre estados com variáveis
**Gerenciar estados com variáveis e JSONata**
Recentemente, o Step Functions adicionou variáveis e JSONata para gerenciar estados e transformar dados.
Saiba mais na publicação do blog [Simplifying developer experience with variables and JSONata in AWS Step Functions](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/)
O seguinte vídeo descreve variáveis e JSONata no Step Functions com um exemplo do DynamoDB:
Com variáveis e saída de estado, você pode transmitir dados entre as etapas do fluxo de trabalho.
Usando variáveis de fluxo de trabalho, é possível armazenar dados em uma etapa e recuperá-los em etapas futuras. Por exemplo, você pode armazenar uma resposta de API que contenha dados que talvez sejam necessários posteriormente. Por outro lado, a saída de estado só pode ser usada como entrada para a próxima etapa.
## Visão geral conceitual das variáveis
Com as variáveis de fluxo de trabalho, é possível armazenar dados para referência posterior. Por exemplo, a Etapa 1 pode armazenar o resultado de uma solicitação de API para que uma parte dessa solicitação possa ser reutilizada posteriormente na Etapa 5.
No cenário a seguir, a máquina de estado recupera dados de uma API uma vez. Na Etapa 1, o fluxo de trabalho armazena os dados retornados da API (até 256 KiB por estado) em uma variável “x” para ser usado em etapas posteriores.
Sem variáveis, seria preciso passar os dados pela saída da Etapa 1 à Etapa 2, da Etapa 3 à Etapa 4 para usá-los na Etapa 5. E se as etapas intermediárias não precisarem dos dados? Passar dados de um estado para outro por meio de saídas e entradas seria um esforço desnecessário.
Com as variáveis, é possível armazenar dados e usá-los em qualquer etapa futura. Você também pode modificar, reorganizar ou adicionar etapas sem interromper o fluxo de seus dados. Dada a flexibilidade das variáveis, talvez você só precise usar **Saída** para retornar dados dos subfluxos de trabalho paralelo, de mapa e no final da execução da sua máquina de estado.
![\[Diagram showing step 1 assigning a value to $x, used in step 5.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/vars-diag-opt1.png)
**Estados compatíveis com variáveis**
Os seguintes tipos de estado permitem que `Assign` declare e atribua valores a variáveis: *Passagem, Tarefa, Mapa, Paralelo, Escolha, Espera*.
Para definir uma variável, forneça um objeto JSON com os nomes e os valores das variáveis:
```
"Assign": {
"productName": "product1",
"count" : 42,
"available" : true
}
```
Para referenciar uma variável, acrescente um cifrão (`$`) ao nome, por exemplo, `$productName`.
## Variável reservada: \$1states
O Step Functions define uma única variável reservada chamada **`$states`**. Nos estados JSONata, as seguintes estruturas são atribuídas a `$states` para uso em expressões JSONata:
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
Na entrada de estado, o Step Functions atribui a entrada de estado a **`$states.input`**. O valor de `$states.input` pode ser usado em todos os campos que aceitam expressões JSONata. `$states.input` sempre se refere à entrada do estado original.
Para os estados `Task`, `Parallel` e `Map`:
+ **`$states.result`** se refere ao resultado bruto da API ou do subfluxo de trabalho, se for bem-sucedido.
+ **`$states.errorOutput`** se refere à saída de erro caso a API ou o subfluxo de trabalho falhem.
`$states.errorOutput` pode ser usado nos campos `Assign` ou `Output` de `Catch`.
A tentativa de acessar `$states.result` ou `$states.errorOutput` em campos e estados onde eles não estão acessíveis será detectada na criação, atualização ou validação da máquina de estado.
O objeto `$states.context` fornece aos fluxos de trabalho informações sobre sua execução específica, como `StartTime`, o token de tarefa e a entrada inicial do fluxo de trabalho. Para saber mais, consulte [Acessar dados de execução do objeto de contexto no Step Functions](input-output-contextobject.md).
## Sintaxe do nome da variável
Os nomes das variáveis seguem as regras para identificadores Unicode, conforme descrito no [Anexo \$131 do Padrão Unicode®](https://unicode.org/reports/tr31/). O primeiro caractere do nome de uma variável deve ser um caractere Unicode ID\$1Start, e os caracteres seguintes devem ser caracteres Unicode ID\$1Continue. O tamanho máximo de um nome da variável é 80 caracteres.
A convenção de nome da variável é semelhante às regras para JavaScript e outras linguagens de programação.
## Escopo da variável
Os fluxos de trabalho do Step Functions evitam condições de corrida com variáveis usando um escopo *workflow-local*.
O escopo local do fluxo de trabalho inclui todos os estados dentro do campo **Estados** de uma máquina de estado, exceto Paralelo e Mapa. Os estados dentro dos estados Paralelo ou Mapa podem se referir a variáveis de escopo externo, mas eles criam e mantêm suas próprias variáveis e valores locais de fluxo de trabalho separados.
As ramificações de `Parallel` e as iterações de `Map` podem acessar valores de variável de **escopos externos**, mas não tem acesso a valores de variáveis de outras ramificações ou iterações simultâneas. Ao tratar erros, o campo `Assign` em um `Catch` pode atribuir valores às variáveis no escopo externo, ou seja, o escopo no qual o estado Paralelo/Mapa existe.
Exceção: os **estados de mapa distribuído** atualmente não podem fazer referência a variáveis em escopos externos.
Uma variável existe em um escopo se algum estado no escopo atribuir um valor a ela. Para evitar erros comuns, uma variável atribuída em um escopo interno não pode ter o mesmo nome de uma atribuída em um escopo externo. Por exemplo, se o escopo de nível superior atribuir um valor a uma variável chamada `myVariable`, nenhum outro escopo (dentro de um `Map` ou `Parallel`) também poderá atribuir `myVariable`.
O acesso às variáveis depende do escopo atual. Os estados Paralelo e Mapa têm seu próprio escopo, mas podem acessar variáveis em escopos externos.
Quando um estado de Paralelo ou Mapa for concluído, todas as suas variáveis sairão do escopo e deixarão de ser acessíveis. Use o **campo Saída** para transmitir dados de ramificações Paralelas e iterações de Mapa.
## Atribuir um campo em ASL
O campo `Assign` em ASL é usado para atribuir valores a uma ou mais variáveis. O campo `Assign` está disponível no nível superior de cada estado (exceto `Succeed` e `Fail`), dentro das regras de estado `Choice` e dos campos `Catch`. Por exemplo:
```
# Example of Assign with JSONata
"Store inputs": {
"Type": "Pass",
"Next": "Get Current Price",
"Comment": "Store the input desired price into a variable: $desiredPrice",
"Assign": {
"desiredPrice": "{% $states.input.desired_price %}",
"maximumWait": "{% $states.input.max_days %}"
}
},
```
O campo `Assign` usa um objeto JSON. Cada campo de nível superior nomeia uma variável a ser atribuída. Nos exemplos anteriores, os nomes das variáveis são `desiredPrice` e `maximumWait`. Ao usar JSONata, `{% ... %}` indica uma expressão JSONata que pode conter variáveis ou expressões mais complexas. Para obter mais informações sobre expressões JSONata, consulte a [documentação em JSONata.org](https://docs.jsonata.org/overview.html).
Ao usar **JSONata** como linguagem de consulta, o diagrama a seguir mostra como os campos **Atribuir** e **Saída** são processados paralelamente. Há uma implicação: *a atribuição de valores de variáveis não afetará a saída do estado*.
![\[Diagram showing a comparison of JSONPath and JSONata flow.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/vars-jsonata.png)
O exemplo de JSONata a seguir recupera `order.product` da entrada de estado. A variável `currentPrice` é definida como um valor a partir do resultado da tarefa.
```
# Example of Task with JSONata assignment from result
{
"Type": "Task",
...
"Assign": {
"product": "{% $states.input.order.product %}",
"currentPrice": "{% $states.result.Payload.current_price %}"
},
"Next": "the next state"
}
```
Observação: **não** é possível atribuir um valor a uma parte de uma variável. Por exemplo, você pode usar `"Assign":{"x":42}`, mas não pode usar `"Assign":{"x.y":42}` ou `"Assign":{"x[2]":42}`.
## Ordem de avaliação em um campo de atribuição
Todas as referências de variáveis nos estados do Step Functions usam os valores como estavam na **entrada do estado**.
O fato anterior é importante para entender como o campo `Assign` atribui valores a uma ou mais variáveis. Primeiro, novos valores são calculados e o Step Functions então atribui os novos valores às variáveis. Os novos valores das variáveis estarão disponíveis a partir do **próximo** estado. Por exemplo, considere o seguinte campo `Assign`:
```
# Starting values: $x=3, $a=6
"Assign": {
"x": "{% $a %}",
"nextX": "{% $x %}"
}
# Ending values: $x=6, $nextX=3
```
No exemplo anterior, a variável `x` é atribuída e referenciada.
Lembre-se: todas as expressões são ***primeiro avaliadas*** e, em seguida, atribuídas. Valores recém-atribuídos estarão disponíveis no **próximo** estado.
Vamos examinar o exemplo em detalhes. Suponha que em um estado anterior, `$x` recebeu um valor de três (3) e `$a` recebeu um valor de seis (6). As etapas a seguir descrevem o processo:
1. Todas as expressões são avaliadas usando os valores **atuais** de todas as variáveis.
A expressão `"{% $a %}"` será avaliada como 6 e `"{% $x %}"` será avaliada como 3.
1. Em seguida, as atribuições são feitas:
`$x` receberá o valor seis (6)
`$nextX` receberá três (3)
Observação: se `$x` não tivesse sido atribuído anteriormente, o exemplo **falharia** porque `$x` seria *indefinido*.
Em resumo, o Step Functions avalia **todas** as expressões e depois faz as atribuições. A ordem na qual as variáveis ocorrem no campo `Assign` **não** importa.
## Limites
O tamanho máximo de uma única variável é 256 KiB, tanto para fluxos de trabalho Padrão quanto Expressos.
O tamanho máximo combinado para todas as variáveis em um único campo `Assign` também é de 256 KiB. Por exemplo, você pode atribuir X e Y a 128 KiB, mas não pode atribuir X e Y a 256 KiB no mesmo campo `Assign`.
O tamanho total de todas as variáveis armazenadas não pode exceder 10 MiB por execução.
## Usar variáveis em estados JSONPath
As variáveis também estão disponíveis em estados que usam JSONPath como linguagem de consulta.
Você pode referenciar uma variável em qualquer campo que aceite uma expressão JSONPath (sintaxe `$.` ou `$$.`), com exceção de `ResultPath`, que especifica um local na entrada de estado para injetar o resultado do estado. Variáveis não podem ser usadas em `ResultPath`.
Em JSONPath, o símbolo `$` se refere ao valor “atual” e `$$` representa o objeto de contexto do estado. As expressões JSONPath podem começar com `$.`, como em `$.customer.name`. Você pode acessar o contexto com `$$.`, como em `$$.Execution.Id`.
Para referenciar uma variável, use o símbolo `$` antes do nome da variável, por exemplo, `$x` ou `$order.numItems`.
Em campos **JSONPath** que aceitam funções intrínsecas, as variáveis podem ser usadas em argumentos, por exemplo `States.Format('The order number is {}', $order.number)`.
O seguinte diagrama ilustra como a etapa de atribuição em uma tarefa **JSONPath** ocorre ao mesmo tempo que o ResultSelector:
![\[Logical diagram of a state that uses JSONPath query language.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/vars-jsonpath.png)
**Atribuir variáveis em JSONPath**
As atribuições de variáveis em JSONPath se comportam de forma semelhante aos modelos de carga útil. Os campos que terminam com `.$` indicam que o valor é uma expressão JSONPath que o Step Functions avalia como um valor durante a execução da máquina de estado (por exemplo, `$.order..product` e `$.order.total`).
```
# Example of Assign with JSONPath
{
"Type": "Task",
...
"Assign": {
"products.$": "$.order..product",
"orderTotal.$": "$.order.total"
},
"Next": "the next state"
}
```
Para estados JSONPath, o valor de `$` em um campo `Assign` depende do tipo de estado. Em estados `Task,` `Map` e `Parallel`, `$` se refere ao resultado da API/subfluxo de trabalho. Em estados `Choice` e `Wait`, `$` se refere à *entrada efetiva*, que é o valor após `InputPath` ter sido aplicado à entrada de estado. Para `Pass`, `$` se refere ao resultado, seja gerado pelo campo `Result` campo ou pelos campos `InputPath`/`Parameters`.
O exemplo de JSONPath a seguir atribui um objeto JSON à variável `details`, o resultado da expressão JSONPath `$.result.code` a `resultCode` e o resultado da expressão JSONPath `States.Format('Hello {}', $customer.name)` a `message`. Se estiver em um estado `Task`, então `$` em `$.order.items` e `$.result.code` se refere ao resultado da API. A variável `startTime` é atribuída com um valor do objeto de contexto, `$$.Execution.StartTime`.
```
"Assign": {
"details": {
"status": "SUCCESS",
"lineItems.$": "$.order.items"
},
"resultCode.$": "$.result.code",
"message.$": "States.Format('Hello {}', $customer.name)",
"startTime.$": "$$.Execution.StartTime"
}
```
# Transformando dados com Step JSONata Functions
Com JSONata isso, você obtém uma poderosa linguagem de consulta e expressão de código aberto para **selecionar** e **transformar** dados em seus fluxos de trabalho. Para uma breve introdução e uma JSONata referência completa, consulte a [JSONatadocumentação.org](https://docs.jsonata.org/overview.html).
**JSONata Versão suportada**
Step Functions suporta a JSONata versão 2.0.6.
O vídeo a seguir descreve variáveis e, JSONata em Step Functions, com um exemplo do DynamoDB:
Você deve optar por usar a linguagem de JSONata consulta e transformação para fluxos de trabalho existentes. Ao criar um fluxo de trabalho no console, recomendamos escolher a máquina JSONata `QueryLanguage` de estado de nível superior. Para fluxos de trabalho novos ou existentes que usam JSONPath, o console oferece uma opção para converter estados individuais em. JSONata
Depois de selecionar JSONata, seus campos de fluxo de trabalho serão reduzidos de cinco JSONPath campos (`InputPath``Parameters``ResultSelector`,`ResultPath`,,, e`OutputPath`) para apenas dois campos: `Arguments` `Output` e. Além disso, você **não** usará `.$` em nomes de chaves de objetos JSON.
Se você não conhece Step Functions, só precisa saber que JSONata as expressões usam a seguinte sintaxe:
**JSONata sintaxe:** `"{% %}"`
Os exemplos de código a seguir mostram uma conversão de JSONPath para JSONata:
```
# Original sample using JSONPath
{
"QueryLanguage": "JSONPath", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Parameters": {
"static": "Hello",
"title.$": "$.title",
"name.$": "$customerName", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
```
# Sample after conversion to JSONata
{
"QueryLanguage": "JSONata", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Arguments": { // JSONata states do not have Parameters
"static": "Hello",
"title": "{% $states.input.title %}",
"name": "{% $customerName %}", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
Com a entrada `{ "title" : "Doctor" }` e a variável `customerName` atribuídas para `"María"`, ambas as máquinas de estado produzirão o seguinte resultado JSON:
```
{
"static": "Hello",
"title": "Doctor",
"name": "María",
"not-evaluated": "$customerName"
}
```
No diagrama a seguir, você pode ver uma representação gráfica mostrando como a conversão JSONPath (esquerda) para JSONata (direita) reduzirá a complexidade das etapas em suas máquinas de estado:
![\[Diagrama que compara os campos em JSONPath e JSONata estados.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/compare-jsonpath-jsonata.png)
Opcionalmente, você pode selecionar e transformar dados da entrada de estado em **argumentos** para enviar para sua ação integrada. **Com JSONata, você pode então (opcionalmente) selecionar e transformar os **resultados** da ação para atribuição a variáveis e para saída de estado.**
Observação: as etapas **Atribuir** e **Saída** ocorrem **em paralelo**. Se você optar por transformar dados durante a atribuição de variáveis, esses dados transformados **não** estarão disponíveis na etapa Saída. Você deve reaplicar a JSONata transformação na etapa Saída.
![\[Diagrama lógico de um estado que usa linguagem de JSONata consulta.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/vars-jsonata.png)
## QueryLanguage campo
Nas definições de ASL do seu fluxo de trabalho, há um campo `QueryLanguage` no nível superior de uma definição de máquina de estado e em estados individuais. Ao configurar estados `QueryLanguage` individuais, você pode adotar incrementalmente JSONata em uma máquina de estado existente em vez de atualizar a máquina de estado de uma só vez.
O campo `QueryLanguage` pode ser definido como `"JSONPath"` ou `"JSONata"`. Se o campo `QueryLanguage` de nível superior for omitido, o padrão será `"JSONPath"`. Se um estado contiver um campo `QueryLanguage` em nível de estado, o Step Functions usará a linguagem de consulta especificada para esse estado. Se o estado não contiver um campo `QueryLanguage`, ele usará a linguagem de consulta especificada no campo `QueryLanguage` de nível superior.
## Escrevendo JSONata expressões em strings JSON
Quando uma string no valor de um campo ASL, um campo de objeto JSON ou um elemento de matriz JSON é cercada por `{% %}` caracteres, essa string será avaliada como. JSONata Observe que a string deve começar com `{%` sem espaços iniciais e terminar com `%}` sem espaços finais. Abrir ou fechar a expressão de forma inadequada resultará em um erro de validação.
Alguns exemplos:
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `"Arguments" : {"field1" : "{% $name %}"}` em um estado `Task`
+ `"Items": [1, "{% $two %}", 3]` em um estado `Map`
Nem todos os campos ASL são JSONata aceitos. Por exemplo, o campo `Type` de cada estado deve ser definido como uma string constante. Da mesma forma, o campo `Resource` do estado `Task` deve ser uma string constante. O `Items` campo `Map` state aceitará uma matriz JSON, um objeto JSON ou uma JSONata expressão que deve ser avaliada como uma matriz ou objeto.
## Variável reservada: \$1states
Step Functions define uma única variável reservada chamada **`$states`**. Nos JSONata estados, as seguintes estruturas são atribuídas `$states` para uso em JSONata expressões:
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
Na entrada de estado, Step Functions atribui a entrada de estado a. **`$states.input`** O valor de `$states.input` pode ser usado em todos os campos que aceitam JSONata expressões. `$states.input`sempre se refere à entrada do estado original.
Para os estados `Task`, `Parallel` e `Map`:
+ **`$states.result`**se refere ao resultado bruto da API ou do subfluxo de trabalho, se for bem-sucedido.
+ **`$states.errorOutput`**refere-se à saída de erro se a API ou o subfluxo de trabalho falharem.
`$states.errorOutput` pode ser usado nos campos `Assign` ou `Output` de `Catch`.
A tentativa de acessar `$states.result` ou `$states.errorOutput` em campos e estados onde eles não estão acessíveis será detectada na criação, atualização ou validação da máquina de estado.
O objeto `$states.context` fornece aos fluxos de trabalho informações sobre sua execução específica, como `StartTime`, o token de tarefa e a entrada inicial do fluxo de trabalho. Para saber mais, consulte[Acessar dados de execução do objeto de contexto no Step Functions](input-output-contextobject.md).
## Gerenciar erros de expressão
Em tempo de execução, a avaliação da JSONata expressão pode falhar por vários motivos, como:
+ **Erro de tipo**: uma expressão, como `{% $x + $y %}`, falhará se `$x` ou `$y` não for um número.
+ **Incompatibilidade de tipo**: uma expressão pode ser avaliada como um tipo que o campo não aceitará. Por exemplo, o campo `TimeoutSeconds` exige uma entrada numérica, então a expressão `{% $timeout %}` falhará se `$timeout` retornar uma string.
+ **Valor fora do intervalo**: uma expressão que produz um valor fora do intervalo aceitável para um campo falhará. Por exemplo, uma expressão como `{% $evaluatesToNegativeNumber %}` falhará no campo `TimeoutSeconds`.
+ **Falha ao retornar um resultado**: o JSON não pode representar uma expressão de valor indefinido, portanto, a expressão `{% $data.thisFieldDoesNotExist %}` resultaria em erro.
Em cada caso, o intérprete lançará o erro: `States.QueryEvaluationError`. Seus estados de Tarefa, Mapa e Paralelo podem fornecer um campo `Catch` para capturar o erro e um campo `Retry` para tentar novamente o erro.
## Convertendo de para JSONPath JSONata
As seções a seguir comparam e explicam as diferenças entre o código escrito com JSONPath JSONata e.
### Sem campos de caminho
O ASL exige que os desenvolvedores usem `Path` versões de campos, como em`TimeoutSecondsPath`, para selecionar um valor dos dados de estado ao usar JSONPath. Ao usar JSONata, você não usa mais `Path` campos porque o ASL interpretará automaticamente JSONata expressões `{% %}` fechadas para você em campos que não sejam do Path, como. `TimeoutSeconds`
+ JSONPath exemplo de legado: `"TimeoutSecondsPath": "$timeout"`
+ JSONata : `"TimeoutSeconds": "{% $timeout %}"`
Da mesma forma, o `Map` estado `ItemsPath` foi substituído pelo `Items` campo que aceita uma matriz JSON, um objeto JSON ou uma JSONata expressão que deve ser avaliada como uma matriz ou objeto.
### Objetos JSON
O ASL usa o termo *modelo de carga útil* para descrever um objeto JSON que pode conter JSONPath expressões `Parameters` e `ResultSelector` valores de campo. O ASL não usará o termo modelo de carga útil JSONata porque a JSONata avaliação acontece para todas as strings, independentemente de elas ocorrerem sozinhas ou dentro de um objeto JSON ou de uma matriz JSON.
### Sem .\$1
O ASL exige que você acrescente '`.$`' aos nomes dos campos nos modelos de carga útil a serem usados JSONPath e nas funções intrínsecas. Ao especificar `"QueryLanguage":"JSONata"`, você não usa mais a convenção “`.$`” para nomes de campos de objetos JSON. Em vez disso, você inclui JSONata expressões em `{% %}` caracteres. A mesma convenção é usada em todos os campos com valor de string, independentemente da profundidade com que o objeto esteja aninhado em outras matrizes ou objetos.
### Argumentos e campos de saída
Quando `QueryLanguage` definido como`JSONata`, os campos de I/O processamento antigos serão desativados (`InputPath`,`Parameters`,`ResultSelector`, `ResultPath` e`OutputPath`) e a maioria dos estados receberá dois novos campos: `Arguments` `Output` e.
JSONata fornece uma maneira mais simples de realizar I/O transformações em comparação com os campos usados com. JSONPath JSONataAs características do tornam `Arguments` e são `Output` mais capazes do que os cinco campos anteriores com JSONPath. Esses novos nomes de campo também ajudam a simplificar sua ASL e esclarecer o modelo para transmitir e retornar valores.
Os campo `Arguments` e `Output` (e outros campos semelhantes, como o `ItemSelector` do estado `Map`) aceitarão um objeto JSON, como:
```
"Arguments": {
"field1": 42,
"field2": "{% jsonata expression %}"
}
```
Ou você pode usar uma JSONata expressão diretamente, por exemplo:
```
"Output": "{% jsonata expression %}"
```
A saída também pode aceitar qualquer tipo de valor JSON, por exemplo, `"Output":true` ou `"Output":42`.
Os `Output` campos `Arguments` e são compatíveis apenas JSONata, portanto, é inválido usá-los com fluxos de trabalho que usam. JSONPath Por outro lado,`InputPath`,`Parameters`,`ResultSelector`, `ResultPath``OutputPath`, e outros JSONPath campos são suportados somente no JSONPath, portanto, é inválido usar campos baseados em caminho ao usar JSONata como seu fluxo de trabalho de nível superior ou linguagem de consulta de estado.
### Estado de passagem
O **resultado** opcional em um estado de passagem era tratado anteriormente como a *saída* de uma tarefa virtual. Com a JSONata opção selecionada como fluxo de trabalho ou linguagem de consulta de estado, agora você pode usar o novo campo **Saída**.
### Estado de escolha
Ao usar JSONPath, os estados de escolha têm uma entrada `Variable` e vários caminhos de comparação, como os seguintes`NumericLessThanEqualsPath`:
```
# JSONPath choice state sample, with Variable and comparison path
"Check Price": {
"Type": "Choice",
"Default": "Pause",
"Choices": [
{
"Variable": "$.current_price.current_price",
"NumericLessThanEqualsPath": "$.desired_price",
"Next": "Send Notification"
} ],
}
```
Com JSONata, o estado de escolha tem um `Condition` onde você pode usar uma JSONata expressão:
```
# Choice state after JSONata conversion
"Check Price": {
"Type": "Choice",
"Default": "Pause"
"Choices": [
{
"Condition": "{% $current_price <= $states.input.desired_priced %}",
"Next": "Send Notification"
} ]
```
Nota: Variáveis e campos de comparação só estão disponíveis para JSONPath. A condição só está disponível para JSONata.
## JSONata exemplos
Os exemplos a seguir podem ser criados no Workflow Studio para fazer experiências JSONata. Você pode criar e executar as máquinas de estado ou usar o **estado de teste** para transmitir dados e até mesmo modificar a definição da máquina de estado.
### Exemplo: entrada e saída
Este exemplo mostra como usar `$states.input` a entrada de estado e o `Output` campo para especificar a saída de estado quando você opta por participar JSONata.
```
{
"Comment": "Input and Output example using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "Basic Input and Output",
"States": {
"Basic Input and Output": {
"QueryLanguage": "JSONata",
"Type": "Succeed",
"Output": {
"lastName": "{% 'Last=>' & $states.input.customer.lastName %}",
"orderValue": "{% $states.input.order.total %}"
}
}
}
}
```
Quando o fluxo de trabalho é executado com o seguinte como entrada:
```
{
"customer": {
"firstName": "Martha",
"lastName": "Rivera"
},
"order": {
"items": 7,
"total": 27.91
}
}
```
O estado de teste ou a execução da máquina de estado retornará a seguinte saída JSON:
```
{
"lastName": "Last=>Rivera",
"orderValue": 27.91
}
```
![\[Captura de tela mostrando a entrada e a saída de um estado em teste.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/jsonata-basic-io.png)
### Exemplo: filtragem com JSONata
Você pode filtrar seus dados com [operadores de JSONata caminho](https://docs.jsonata.org/path-operators). Por exemplo, imagine que você tenha uma lista de produtos para entrada e queira processar somente produtos que contenham zero calorias. Você pode criar uma definição de máquina de estado com a seguinte ASL e testar o estado `FilterDietProducts` com a entrada de amostra a seguir.
**Definição de máquina de estado para filtragem com JSONata**
```
{
"Comment": "Filter products using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "FilterDietProducts",
"States": {
"FilterDietProducts": {
"Type": "Pass",
"Output": {
"dietProducts": "{% $states.input.products[calories=0] %}"
},
"End": true
}
}
}
```
**Entrada de amostra para o teste**
```
{
"products": [
{
"calories": 140,
"flavour": "Cola",
"name": "Product-1"
},
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 160,
"flavour": "Orange",
"name": "Product-3"
},
{
"calories": 100,
"flavour": "Orange",
"name": "Product-4"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
**Resultado do teste da etapa na máquina de estado**
```
{
"dietProducts": [
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
![\[Exemplo de saída para JSONata expressões em teste.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/test-state-jsonata.png)
## JSONata funções fornecidas pelo Step Functions
JSONata contém bibliotecas de funções para funções de string, numérica, agregação, booleana, matriz, objeto, data/hora e alta ordem. Step Functions fornece JSONata funções adicionais que você pode usar em suas JSONata expressões. Essas funções integradas servem como substitutas das funções intrínsecas do Step Functions. As funções intrínsecas só estão disponíveis em estados que usam a linguagem de JSONPath consulta.
Observação: JSONata as funções integradas que exigem valores inteiros como parâmetros arredondarão automaticamente para baixo todos os números não inteiros fornecidos.
**\$1partition -** JSONata equivalente à função `States.ArrayPartition` intrínseca para particionar uma grande matriz.
O primeiro parâmetro é a matriz a ser particionada, o segundo parâmetro é um número inteiro representando o tamanho do bloco. O valor retornado será uma matriz bidimensional. O interpretador divide a matriz de entrada em várias matrizes do tamanho especificado pelo tamanho do bloco. O comprimento do último bloco da matriz pode ser menor que o comprimento dos blocos anteriores se o número de itens restantes na matriz for menor que o tamanho do bloco.
```
"Assign": {
"arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}
```
**\$1range** - JSONata equivalente à função `States.ArrayRange` intrínseca para gerar uma matriz de valores.
Essa função usa três argumentos. O primeiro argumento é um valor inteiro que representa o primeiro elemento da nova matriz. O segundo argumento é um número inteiro que representa o elemento final da nova matriz. Já o terceiro argumento é o valor delta do número inteiro para os elementos da nova matriz. O valor de retorno é uma matriz de valores recém-gerada que varia do primeiro argumento ao segundo argumento da função com elementos intermediários ajustados pelo delta. O valor delta pode ser positivo ou negativo, o que incrementará ou diminuirá cada elemento do último até que o valor final seja atingido ou excedido.
```
"Assign": {
"arrayRange": "{% $range(0, 10, 2) %}"
}
```
**\$1hash** - JSONata equivalente à função `States.Hash` intrínseca para calcular o valor de hash de uma determinada entrada.
Essa função usa dois argumentos. O primeiro argumento é a string de origem a ser codificada. O segundo argumento é uma string que representa o algoritmo de hash para o cálculo de hash. O algoritmo de hash deve ter um dos seguintes valores: `"MD5"`, `"SHA-1"`, `"SHA-256"`, `"SHA-384"` ou `"SHA-512"`. O valor de retorno é uma string do hash calculado dos dados.
Essa função foi criada porque JSONata não oferece suporte nativo à capacidade de calcular hashes.
```
"Assign": {
"myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}
```
**\$1random** - JSONata equivalente à função `States.MathRandom` intrínseca para retornar um número aleatório n onde. `0 ≤ n < 1`
A função usa um argumento inteiro *opcional* representando o valor inicial da função aleatória. Se você usar essa função com o mesmo valor de seed, ela retornará um número idêntico.
Essa função sobrecarregada foi criada porque a JSONata função integrada [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)não aceita um valor inicial.
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**\$1uuid** - JSONata versão da função intrínseca. `States.UUID`
A função não aceita argumentos. Ela retorna um UUID v4.
Essa função foi criada porque JSONata não oferece suporte nativo à capacidade de gerar UUIDs.
```
"Assign": {
"uniqueId": "{% $uuid() %}"
}
```
**\$1parse** - JSONata função para desserializar strings JSON.
A função JSON transformado em string como seu único argumento.
JSONata suporta essa funcionalidade via`$eval`; no entanto, não `$eval` é suportado nos fluxos de trabalho do Step Functions.
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```
# Acessar dados de execução do objeto de contexto no Step Functions
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
O objeto de contexto é uma estrutura JSON interna que está disponível durante uma execução e contém informações sobre sua máquina de estado e execução. O contexto fornece aos seus fluxos de trabalho informações sobre sua execução específica. Seus fluxos de trabalho podem referenciar o objeto Context em uma JSONata expressão com`$states.context`.
## Acessar o objeto de contexto
**Para acessar o objeto Context em JSONata**
Para acessar o objeto Context em JSONata estados, use `$states.context` em uma JSONata expressão.
```
{
"ExecutionID" : "{% $states.context.Execution.Id %}"
}
```
**Para acessar o objeto Context em JSONPath**
Para acessar o objeto Context em JSONPath, primeiro você acrescenta `.$` ao final da chave para indicar que o valor é um caminho. Em seguida, acrescente o valor `$$.` para selecionar um nó no objeto de contexto.
```
{
"ExecutionID.$": "$$.Execution.Id"
}
```
JSONPath os estados podem se referir ao contexto (`$$.`) nos seguintes JSONPath campos:
+ `InputPath`
+ `OutputPath`
+ `ItemsPath` (em estados Mapa)
+ `Variable` (em estados Escolha)
+ `ResultSelector`
+ `Parameters`
+ Operadores de comparação de variável para variável
## Campos de objeto de contexto
O objeto de contexto inclui informações sobre a máquina de estado, o estado, a execução e a tarefa. O objeto de contexto JSON inclui nós para cada tipo de dados no seguinte formato:
```
{
"Execution": {
"Id": "String",
"Input": {},
"Name": "String",
"RoleArn": "String",
"StartTime": "Format: ISO 8601",
"RedriveCount": Number,
"RedriveTime": "Format: ISO 8601"
},
"State": {
"EnteredTime": "Format: ISO 8601",
"Name": "String",
"RetryCount": Number
},
"StateMachine": {
"Id": "String",
"Name": "String"
},
"Task": {
"Token": "String"
}
}
```
Durante uma execução, o objeto de contexto é preenchido com dados relevantes para o campo.
Ocasionalmente, novos campos são adicionados ao contexto. Se estiver processando o contexto JSON diretamente, recomendamos criar um código que possa manipular facilmente novos campos desconhecidos. Por exemplo, se estiver usando a biblioteca Jackson para desempacotar o JSON, recomendamos definir `FAIL_ON_UNKNOWN_PROPERTIES` como `false` em seu `ObjectMapper` para evitar um `UnrecognizedPropertyException`.
O objeto de contexto `RedriveTime` só estará disponível se você tiver redriven uma execução. Se você tiver [redriven a Map Run](redrive-map-run.md), o objeto de contexto `RedriveTime` só estará disponível para fluxos de trabalho secundários do tipo Padrão. Para uma Execução de mapa redriven com fluxos de trabalho secundários do tipo Express, `RedriveTime` não está disponível.
O conteúdo de uma execução que está em andamento inclui informações específicas no formato abaixo:
```
{
"Execution": {
"Id": "arn:aws:states:region:123456789012:execution:stateMachineName:executionName",
"Input": {
"key": "value"
},
"Name": "executionName",
"RoleArn": "arn:aws:iam::123456789012:role...",
"StartTime": "2025-08-27T10:04:42Z"
},
"State": {
"EnteredTime": "2025-08-27T10:04:42.001Z",
"Name": "Test",
"RetryCount": 3
},
"StateMachine": {
"Id": "arn:aws:states:region:123456789012:stateMachine:stateMachineName",
"Name": "stateMachineName"
},
"Task": {
"Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
}
}
```
**Formato de carimbo de data/hora com segundos fracionários**
Step Functions segue a ISO8601 especificação que afirma que a saída pode ser de zero, três, seis ou nove dígitos, conforme necessário. Quando um carimbo de data/hora tem zero segundos fracionários, o Step Functions remove os zeros à direita em vez de preencher a saída.
Se você criar um código que consuma carimbos de data/hora do Step Functions, seu código deverá conseguir processar um número variável de segundos fracionários.
## Dados de objeto de contexto para estados de mapa
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Ao processar um [estado `Map`](state-map.md), o contexto também conterá `Index`, `Value` e `Source`.
Para cada iteração de `Map` estado, `Index` contém o número do índice do item da matriz que está sendo processado atualmente, `Value` contém o item da matriz que está sendo processado e `Source` será o InputType de`CSV`, `JSON``JSONL`, ou`PARQUET`.
Em um estado `Map`, o objeto de contexto inclui os seguintes dados:
```
"Map": {
"Item": {
"Index" : Number,
"Key" : "String", // Only valid for JSON objects
"Value" : "String",
"Source": "String"
}
}
```
Eles estão disponíveis somente em um estado `Map` e podem ser especificados no campo `ItemSelector (mapa)`.
**nota**
Você deve definir parâmetros do objeto de contexto no bloco `ItemSelector` do estado `Map` principal, não nos estados incluídos na seção `ItemProcessor`.
Dada uma máquina de estado usando um **JSONPath**`Map`estado, você pode injetar informações do objeto Context da seguinte maneira.
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex.$": "$$.Map.Item.Index",
"ContextValue.$": "$$.Map.Item.Value",
"ContextSource.$": "$$.Map.Item.Source"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Para JSONata, as informações adicionais do contexto do estado do mapa podem ser acessadas a partir da `$states.context` variável:
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex": "{% $states.context.Map.Item.Index %}",
"ContextValue": "{% $states.context.Map.Item.Value %}",
"ContextSource": "{% $states.context.Map.Item.Source %}"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Se você executar a máquina de estado anterior com a entrada a seguir, `Index` e `Value` serão inseridos na saída.
```
[
{
"who": "bob"
},
{
"who": "meg"
},
{
"who": "joe"
}
]
```
A saída da execução retorna os valores dos itens `Index` e `Value` de cada uma das três iterações, da seguinte forma:
```
[
{
"ContextIndex": 0,
"ContextValue": {
"who": "bob"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 1,
"ContextValue": {
"who": "meg"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 2,
"ContextValue": {
"who": "joe"
},
"ContextSource" : "STATE_DATA"
}
]
```
Observe que `$states.context.Map.Item.Source` será um dos seguintes:
+ Na entrada de estado, o valor será: `STATE_DATA`
+ Para `Amazon S3 LIST_OBJECTS_V2` com `Transformation=NONE`, o valor mostrará o URI do S3 para o bucket. Por exemplo: `S3://bucket-name`.
+ Para todos os outros tipos de entrada, o valor será o URI do Amazon S3. Por exemplo: `S3://bucket-name/object-key`.
# Usando JSONPath caminhos
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Na Amazon States Language um *caminho* é uma string que começa com `$`, que você pode usar para identificar componentes dentro do texto JSON. Os caminhos seguem a [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintaxe, que só está disponível quando definida como. `QueryLanguage` JSONPath É possível especificar um caminho para acessar os subconjuntos de entrada definindo valores para `InputPath`, `ResultPath` e `OutputPath`.
Você deve usar a notação de colchetes se o nome do campo contiver algum caractere que não esteja incluído na `member-name-shorthand` definição da regra [JsonPath ABNF](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf). Portanto, para codificar caracteres especiais, como sinais de pontuação (excluindo `_`), você deve usar a notação de colchetes. Por exemplo, .`$.abc.['def ghi']`
## Caminhos de referência
Um *caminho de referência* é um caminho cuja sintaxe é limitada para que possa identificar somente um nó em uma estrutura JSON:
+ Você pode acessar os campos de objeto usando somente ponto (`.`) e colchete (`[ ]`).
+ Funções como `length()` não são compatíveis.
+ Operadores lexicais, que não são simbólicos, como `subsetof` não são compatíveis.
+ A filtragem por expressão regular ou por referência a outro valor na estrutura JSON não é aceita.
+ Os operadores `@`, `,`, `:` e `?` não são aceitos.
Por exemplo, se os dados de entrada de estado contivessem os seguintes valores:
```
{
"foo": 123,
"bar": ["a", "b", "c"],
"car": {
"cdr": true
}
}
```
Os caminhos de referência a seguir retornariam o seguinte:
```
$.foo => 123
$.bar => ["a", "b", "c"]
$.car.cdr => true
```
Alguns estados usam caminhos e caminhos de referência para controlar o fluxo de uma máquina de estado ou configurar as definições ou opções de um estado. Para obter mais informações, consulte [Modelagem do processamento do caminho de entrada e saída do fluxo de trabalho com simulador de fluxo de dados](https://aws.amazon.com/blogs/compute/modeling-workflow-input-output-path-processing-with-data-flow-simulator/) e [Uso JSONPath eficaz em AWS Step Functions](https://aws.amazon.com/blogs/compute/using-jsonpath-effectively-in-aws-step-functions/).
### Nivelamento de uma matriz de matrizes
Se o estado [Estado paralelo do fluxo de trabalho](state-parallel.md) ou [Estado de mapa do fluxo de trabalho](state-map.md) em suas máquinas de estado retornar uma matriz de matrizes, você poderá transformá-las em uma matriz nivelada com o campo [ResultSelector](input-output-inputpath-params.md#input-output-resultselector). Você pode incluir esse campo na definição do estado Paralelo ou Mapa para manipular o resultado desses estados.
Para nivelar matrizes, use a sintaxe `[*]` no campo `ResultSelector`, conforme mostrado no exemplo a seguir.
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
Para exemplos mostrando como nivelar uma matriz, consulte a *Etapa 3* nos seguintes tutoriais:
+ [Processar dados em lote em uma função do Lambda no Step Functions](tutorial-itembatcher-param-task.md)
+ [Processar itens individuais com uma função do Lambda no Step Functions](tutorial-itembatcher-single-item-process.md)
# Manipular parâmetros nos fluxos de trabalho do Step Functions
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Os campos `InputPath`, `Parameters` e `ResultSelector` fornecem uma maneira de manipular o JSON à medida que ele se move por seu fluxo de trabalho. `InputPath` pode limitar a entrada que será transmitida filtrando a notação JSON por meio de um caminho (consulte [Usando JSONPath caminhos](amazon-states-language-paths.md)). Com o campo `Parameters`, é possível transmitir uma coleção de pares de valor-chave usando valores estáticos ou seleções da entrada usando um caminho.
O `ResultSelector` campo fornece uma forma de manipular o resultado do estado antes de ser `ResultPath` aplicado.
AWS Step Functionsaplica o `InputPath` campo primeiro e depois o `Parameters` campo. É possível primeiro filtrar a entrada bruta para uma seleção desejada usando `InputPath` e, então, aplicar `Parameters` para manipular ainda mais essa entrada ou adicionar novos valores. Em seguida, você pode usar o campo `ResultSelector` para manipular a saída do estado antes da aplicação de `ResultPath`.
## InputPath
Use `InputPath` para selecionar uma parte da entrada de estado.
Por exemplo, vamos supor que a entrada para seu estado inclua o seguinte:
```
{
"comment": "Example for InputPath.",
"dataset1": {
"val1": 1,
"val2": 2,
"val3": 3
},
"dataset2": {
"val1": "a",
"val2": "b",
"val3": "c"
}
}
```
Você poderá aplicar `InputPath`.
```
"InputPath": "$.dataset2",
```
Com o `InputPath` anterior, o JSON transmitido como a entrada é exibido a seguir.
```
{
"val1": "a",
"val2": "b",
"val3": "c"
}
```
**nota**
Um caminho pode gerar uma seleção de valores. Considere o seguinte exemplo.
```
{ "a": [1, 2, 3, 4] }
```
Se você aplicar o caminho `$.a[0:2]`, o resultado será o que é mostrado a seguir.
```
[ 1, 2 ]
```
## Parâmetros
Esta seção descreve as diferentes formas de usar o campo Parâmetros.
### Pares de chave/valor
Use o campo `Parameters` para criar um conjunto de pares de chave-valor que serão transmitidos como entrada. Os valores de cada um podem ser valores estáticos, incluídos na definição da máquina de estado, ou selecionados na entrada ou no objeto de contexto por meio de um caminho. Para os pares de chave-valor, em que o valor é selecionado usando um caminho, o nome da chave deve terminar em `.$`.
Por exemplo, vamos supor que você forneça a entrada a seguir.
```
{
"comment": "Example for Parameters.",
"product": {
"details": {
"color": "blue",
"size": "small",
"material": "cotton"
},
"availability": "in stock",
"sku": "2317",
"cost": "$23"
}
}
```
Para selecionar algumas das informações, você poderá especificar esses parâmetros na definição da máquina de estado.
```
"Parameters": {
"comment": "Selecting what I care about.",
"MyDetails": {
"size.$": "$.product.details.size",
"exists.$": "$.product.availability",
"StaticValue": "foo"
}
},
```
Dada a entrada anterior e o campo `Parameters`, este é o JSON que será transmitido.
```
{
"comment": "Selecting what I care about.",
"MyDetails": {
"size": "small",
"exists": "in stock",
"StaticValue": "foo"
}
},
```
Além da entrada, é possível acessar um objeto JSON especial, conhecido como o objeto de contexto. O objeto de contexto inclui informações sobre a execução da máquina de estado. Consulte [Acessar dados de execução do objeto de contexto no Step Functions](input-output-contextobject.md).
### Recursos conectados
O campo `Parameters` também pode transmitir informações para recursos conectados. Por exemplo, se o estado da sua tarefa for orquestrar um AWS Batch trabalho, você poderá passar os parâmetros relevantes da API diretamente para as ações da API desse serviço. Para obter mais informações, consulte:
+ [Transmitir parâmetros a uma API de serviço no Step Functions](connect-parameters.md)
+ [Integração de produtos da ](integrate-services.md)
### Amazon S3
Se a quantidade de dados da função do Lambda que você está transmitindo entre estados puder ultrapassar 262.144 bytes, recomendamos o uso do Amazon S3 para armazenar os dados e implementar um dos seguintes métodos:
+ Use o *estado Mapa Distribuído* em seu fluxo de trabalho para que o estado `Map` possa ler a entrada diretamente das fontes de dados do Amazon S3. Para obter mais informações, consulte [Modo distribuído](state-map-distributed.md).
+ Analise o nome do recurso da Amazon (ARN) do bucket no parâmetro `Payload` para obter o nome do bucket e o valor da chave. Para obter mais informações, consulte [Usando o Amazon S3 ARNs em vez de transmitir grandes cargas em Step Functions](sfn-best-practices.md#avoid-exec-failures).
Como alternativa, é possível ajustar a implementação para passar cargas menores em suas execuções.
## ResultSelector
Use o campo `ResultSelector` para manipular um resultado do estado antes da aplicação de `ResultPath`. O campo `ResultSelector` permite criar uma coleção de pares de chave-valor, em que os valores são estáticos ou selecionados a partir do resultado do estado. Usando o campo `ResultSelector`, você pode escolher quais partes do resultado de um estado deseja passar para o campo `ResultPath`.
**nota**
Com o campo `ResultPath`, você pode adicionar a saída do campo `ResultSelector` à entrada original.
`ResultSelector` é um campo opcional nos seguintes estados:
+ [Estado de mapa do fluxo de trabalho](state-map.md)
+ [Estado de tarefa do fluxo de trabalho](state-task.md)
+ [Estado paralelo do fluxo de trabalho](state-parallel.md)
Por exemplo, as integrações de serviço do Step Functions retornam metadados além da carga útil no resultado. `ResultSelector` pode selecionar partes do resultado e mesclá-las com a entrada de estado com `ResultPath`. Neste exemplo, queremos selecionar apenas `resourceType` e `ClusterId` mesclá-los com a entrada de estado de um createCluster.sync do Amazon EMR. Considerando o seguinte:
```
{
"resourceType": "elasticmapreduce",
"resource": "createCluster.sync",
"output": {
"SdkHttpMetadata": {
"HttpHeaders": {
"Content-Length": "1112",
"Content-Type": "application/x-amz-JSON-1.1",
"Date": "Mon, 25 Nov 2019 19:41:29 GMT",
"x-amzn-RequestId": "1234-5678-9012"
},
"HttpStatusCode": 200
},
"SdkResponseMetadata": {
"RequestId": "1234-5678-9012"
},
"ClusterId": "AKIAIOSFODNN7EXAMPLE"
}
}
```
Em seguida, você pode selecionar `resourceType` e `ClusterId` usando `ResultSelector`:
```
"Create Cluster": {
"Type": "Task",
"Resource": "arn:aws:states:::elasticmapreduce:createCluster.sync",
"Parameters": {
},
"ResultSelector": {
"ClusterId.$": "$.output.ClusterId",
"ResourceType.$": "$.resourceType"
},
"ResultPath": "$.EMROutput",
"Next": "Next Step"
}
```
Com a entrada fornecida, usar `ResultSelector` gera:
```
{
"OtherDataFromInput": {},
"EMROutput": {
"ClusterId": "AKIAIOSFODNN7EXAMPLE",
"ResourceType": "elasticmapreduce",
}
}
```
### Nivelamento de uma matriz de matrizes
Se o estado [Estado paralelo do fluxo de trabalho](state-parallel.md) ou [Estado de mapa do fluxo de trabalho](state-map.md) em suas máquinas de estado retornar uma matriz de matrizes, você poderá transformá-las em uma matriz nivelada com o campo [ResultSelector](#input-output-resultselector). Você pode incluir esse campo na definição do estado Paralelo ou Mapa para manipular o resultado desses estados.
Para nivelar matrizes, use a sintaxe `[*]` no campo `ResultSelector`, conforme mostrado no exemplo a seguir.
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
Para exemplos mostrando como nivelar uma matriz, consulte a *Etapa 3* nos seguintes tutoriais:
+ [Processar dados em lote em uma função do Lambda no Step Functions](tutorial-itembatcher-param-task.md)
+ [Processar itens individuais com uma função do Lambda no Step Functions](tutorial-itembatcher-single-item-process.md)
# Exemplo: manipular dados de estado com caminhos em fluxos de trabalho do Step Functions
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Este tópico contém exemplos de como manipular JSON de entrada e de saída de estado usando os campos InputPath, ResultPath e OutputPath.
Qualquer estado que não seja [Estado de falha do fluxo de trabalho](state-fail.md) ou [Estado de sucesso do fluxo de trabalho](state-succeed.md) pode incluir os campos de processamento de entrada e saída, como `InputPath`, `ResultPath` ou `OutputPath`. Além disso, os estados [Estado de espera do fluxo de trabalho](state-wait.md) e [Estado de escolha do fluxo de trabalho](state-choice.md) não são compatíveis com o campo `ResultPath`. Com esses campos, você pode usar um [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) para filtrar os dados JSON à medida que eles se movem pelo seu fluxo de trabalho.
Você também pode usar o campo `Parameters` para manipular os dados JSON à medida que eles se movem pelo seu fluxo de trabalho. Para obter informações sobre como utilizar o `Parameters`, consulte [Manipular parâmetros nos fluxos de trabalho do Step Functions](input-output-inputpath-params.md).
Por exemplo, comece com a função do AWS Lambda e a máquina de estado descrita no tutorial [Como criar uma máquina de estado Step Functions que usa Lambda](tutorial-creating-lambda-state-machine.md). Modifique a máquina de estado para que ela inclua o `InputPath`, o `ResultPath` e o `OutputPath` a seguir.
```
{
"Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:HelloFunction",
"InputPath": "$.lambda",
"ResultPath": "$.data.lambdaresult",
"OutputPath": "$.data",
"End": true
}
}
}
```
Inicie uma execução usando a entrada a seguir.
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
Suponha que os nós `comment` e `extra` possam ser descartados, mas que você deseja incluir a saída da função do Lambda e preservar as informações no nó `data`.
Na máquina de estado atualizada, o estado `Task` é alterado para processar a entrada para a tarefa.
```
"InputPath": "$.lambda",
```
Essa linha na definição de máquina de estado limita a tarefa de entrada para apenas o nó `lambda` da entrada de estado. A função do Lambda recebe somente o objeto JSON `{"who": "AWS Step Functions"}` como entrada.
```
"ResultPath": "$.data.lambdaresult",
```
Esse `ResultPath` diz à máquina de estado para inserir o resultado da função do Lambda em um nó chamado `lambdaresult`, como um filho do nó `data` na entrada da máquina de estado original. Como você não está realizando nenhuma outra manipulação na entrada original e no resultado usando `OutputPath`, a saída do estado agora inclui o resultado da função do Lambda com a entrada original.
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
Porém, nosso objetivo era preservar apenas o nó `data` e incluir o resultado da função do Lambda. O `OutputPath` filtra esse JSON combinado antes de transmiti-lo para a saída do estado.
```
"OutputPath": "$.data",
```
Isso seleciona apenas o nó `data` da entrada original (incluindo o filho `lambdaresult` inserido por `ResultPath`) a ser passada para a saída. A saída do estado é filtrada como está a seguir.
```
{
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
}
```
Nesse estado `Task`:
1. O `InputPath` envia somente o nó `lambda` da entrada para a função do Lambda.
1. `ResultPath` insere o resultado como um filho do nó `data` na entrada original.
1. O `OutputPath` filtra a entrada de estado (que agora inclui o resultado da função do Lambda) para que ele transmita somente o nó `data` para a saída de estado.
**Example Para manipular a entrada, o resultado e a saída final da máquina de estado original usando JsonPath**
Considere a seguinte máquina de estado que verifica a identidade e o endereço de um solicitante de seguro.
Para ver o exemplo completo, consulte [Como usar o JSON Path no Step Functions](https://github.com/aws-samples/serverless-account-signup-service).
```
{
"Comment": "Sample state machine to verify an applicant's ID and address",
"StartAt": "Verify info",
"States": {
"Verify info": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "Verify identity",
"States": {
"Verify identity": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-identity:$LATEST"
},
"End": true
}
}
},
{
"StartAt": "Verify address",
"States": {
"Verify address": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-address:$LATEST"
},
"End": true
}
}
}
]
}
}
}
```
Se você executar essa máquina de estado usando a entrada a seguir, a execução falhará porque as funções do Lambda que realizam a verificação esperam apenas os dados que precisam ser verificados como entrada. Portanto, você deve especificar os nós que contêm as informações a serem verificadas usando um JsonPath apropriado.
```
{
"data": {
"firstname": "Jane",
"lastname": "Doe",
"identity": {
"email": "jdoe@example.com",
"ssn": "123-45-6789"
},
"address": {
"street": "123 Main St",
"city": "Columbus",
"state": "OH",
"zip": "43219"
},
"interests": [
{
"category": "home",
"type": "own",
"yearBuilt": 2004
},
{
"category": "boat",
"type": "snowmobile",
"yearBuilt": 2020
},
{
"category": "auto",
"type": "RV",
"yearBuilt": 2015
},
]
}
}
```
Para especificar o nó que a função do Lambda `check-identity` deve usar, use o campo `InputPath` da seguinte forma:
```
"InputPath": "$.data.identity"
```
E para especificar o nó que a função do Lambda `check-address` deve usar, use o campo `InputPath` da seguinte forma:
```
"InputPath": "$.data.address"
```
Agora, se você quiser armazenar o resultado da verificação na entrada original da máquina de estado, use o campo `ResultPath` da seguinte forma:
```
"ResultPath": "$.results"
```
No entanto, se você precisar apenas dos resultados de identidade e verificação e descartar a entrada original, use o campo `OutputPath` da seguinte forma:
```
"OutputPath": "$.results"
```
Para obter mais informações, consulte [Processar entrada e saída no Step Functions](concepts-input-output-filtering.md).
## Filtrar a saída de estado usando OutputPath
Com o `OutputPath`, é possível selecionar parte da saída de estado para seguir para o próximo estado. Com essa abordagem, é possível filtrar informações indesejáveis e transmitir somente a parte do JSON necessária.
Se você não especificar um `OutputPath`, o valor padrão será `$`. Isso transmitirá todo o nó JSON (determinado pela entrada de estado, o resultado da tarefa e `ResultPath`) para o próximo estado.
# Especificando a saída de estado usando ResultPath em Step Functions
**Gerenciar estados e transformar dados**
Esta página se refere JSONPath a. Recentemente, o Step Functions adicionou variáveis JSONata para gerenciar dados de estado e transformação.
Saiba mais sobre como [transmitir dados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
A saída de um estado pode ser uma cópia de sua entrada, o resultado que ele produz (por exemplo, a saída da função do Lambda de um estado `Task`) ou uma combinação da entrada e do resultado. Use `ResultPath` para controlar qual combinação desses itens são passadas para o estado de saída.
Os seguintes tipos de estado podem gerar um resultado e podem incluir `ResultPath:`
+ [Estado de passagem do fluxo de trabalho](state-pass.md)
+ [Estado de tarefa do fluxo de trabalho](state-task.md)
+ [Estado paralelo do fluxo de trabalho](state-parallel.md)
+ [Estado de mapa do fluxo de trabalho](state-map.md)
Use `ResultPath` para combinar um resultado de tarefa com entrada de tarefa, ou para selecionar um desses. O caminho que você fornece para `ResultPath` controla quais informações passam para a saída.
**nota**
`ResultPath` é limitado a usar [caminhos de referência](amazon-states-language-paths.md#amazon-states-language-reference-paths), que limitam o escopo para que o caminho possa identificar somente um nó em JSON. Consulte [Caminhos de referência](amazon-states-language-paths.md#amazon-states-language-reference-paths) no [Linguagem de estados da Amazon](concepts-amazon-states-language.md).
## Use ResultPath para substituir a entrada pelo resultado da tarefa
Se você não especificar um `ResultPath`, o comportamento padrão será o mesmo de `"ResultPath": "$"`. O estado substituirá toda a entrada do estado pelo resultado da tarefa.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$"
# Task result
"Hello, Step Functions!"
# State Output
"Hello, Step Functions!"
```
**nota**
`ResultPath` é usado para incluir conteúdo do resultado com a entrada, antes de transmiti-lo para a saída. No entanto, se `ResultPath` não for especificado, a ação padrão será substituir a entrada completa.
## Descartar o resultado e manter a entrada original
Se você definir `ResultPath` como `null`, o estado passará a **entrada original** para a saída. A carga útil de entrada do estado será copiada diretamente para a saída, sem considerar o resultado da tarefa.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": null
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
```
## Use ResultPath para incluir o resultado com a entrada
Se você especificar um caminho para ResultPath, a saída do estado combinará a entrada do estado e o resultado da tarefa:
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.taskresult"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions",
"taskresult" : "Hello, Step Functions!"
}
```
Você também pode inserir o resultado em um nó filho da entrada. Defina o `ResultPath` da seguinte forma.
```
"ResultPath": "$.strings.lambdaresult"
```
Considerando a seguinte entrada:
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz"
},
"who": "AWS Step Functions"
}
```
O resultado da tarefa seria inserido como um adicionar do nó `strings` na entrada.
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz",
"lambdaresult": "Hello, Step Functions!"
},
"who": "AWS Step Functions"
}
```
A saída de estado JSON agora inclui a entrada original com o resultado como um nó filho.
## Use ResultPath para atualizar um nó na entrada com o resultado
Se você especificar um nó existente para ResultPath, o resultado da tarefa substituirá esse nó existente:
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.comment"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "Hello, Step Functions!",
"details": "Default example",
"who" : "Step Functions"
}
```
## Use ResultPath para incluir erro e entrada em um `Catch`
Em alguns casos, talvez você queira preservar a entrada original com o erro. Use `ResultPath` em um `Catch` para incluir o erro com a entrada original, em vez de substituí-lo.
```
"Catch": [{
"ErrorEquals": ["States.ALL"],
"Next": "NextTask",
"ResultPath": "$.error"
}]
```
Se a declaração `Catch` anterior detectar um erro, ela incluirá o resultado em um nó `error` dentro da mesma entrada de estado. Por exemplo, com a seguinte entrada:
```
{"foo": "bar"}
```
A saída do estado ao detectar um erro é exibida a seguir.
```
{
"foo": "bar",
"error": {
"Error": "Error here"
}
}
```
Para obter mais informações sobre como tratar erros, consulte o seguinte:
+ [Tratar erros em fluxos de trabalho do Step Functions](concepts-error-handling.md)
+ [Tratar condições de erro em uma máquina de estado do Step Functions](tutorial-handling-error-conditions.md)
# Campos de entrada e de saída de estado do mapa no Step Functions
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Os estados de mapa iteram em uma coleção de itens em um conjunto de dados. Exemplos de conjuntos de dados incluem:
+ Matrizes e objetos JSON de estados anteriores.
+ Arquivos de dados individuais armazenados no Amazon S3 em formatos como: JSON, JSONL, CSV e arquivos Parquet.
+ Referências a vários objetos, como: manifestos do Athena e arquivos de inventário Amazon S3
Um mapa repete um conjunto de etapas para cada item no conjunto de dados. Você pode configurar a entrada que o `Map state` recebe e a saída que ele gera usando várias opções de configuração. O Step Functions aplica cada opção em seu *estado de mapa distribuído* na ordem mostrada na lista a seguir. Dependendo do caso de uso, pode não ser necessário aplicar todos os campos.
1. [ItemReader (Mapa)](input-output-itemreader.md): usado para ler os itens de dados
1. [ItemsPath (Mapa, JSONPath somente)](input-output-itemspath.md)ou **Itens (JSONata)** - opcional; usado para especificar itens em seu conjunto de dados
1. [ItemSelector (mapa)](input-output-itemselector.md): opcional; usado para selecionar e modificar itens no conjunto de dados
1. [ItemBatcher (mapa)](input-output-itembatcher.md): usado para processar grupos de itens ao processar grandes conjuntos de itens
1. [ResultWriter (Mapa)](input-output-resultwriter.md): fornece opções para resultados de saída de fluxos de trabalho secundários
# 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.
# ItemsPath (Mapa, JSONPath somente)
**Gerenciar estados e transformar dados**
Esta página se refere JSONPath a. Recentemente, o Step Functions adicionou variáveis JSONata para gerenciar dados de estado e transformação.
Saiba mais sobre como [transmitir dados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Em estados JSONPath baseados, use o `ItemsPath` campo para selecionar uma matriz ou objeto em uma entrada JSON fornecida a um `Map` estado. Por padrão, um estado `Map` define `ItemsPath` como `$`, o que seleciona toda a entrada.
+ Se a entrada para o `Map` estado for uma matriz JSON, ela executará uma iteração para cada item na matriz, passando esse item para a iteração como entrada
+ Se a entrada para o `Map` estado for um objeto JSON, ela executará uma iteração para cada par de valores-chave no objeto, passando o par para a iteração como entrada
**nota**
Você só poderá usar `ItemsPath` no *estado Mapa Distribuído* se usar uma entrada JSON transmitida de um estado anterior no fluxo de trabalho.
O valor de `ItemsPath` deve ser um [caminho de referência](amazon-states-language-paths.md#amazon-states-language-reference-paths), e esse caminho deve ser avaliado como uma matriz ou objeto JSON. Por exemplo, considere a entrada para um estado `Map` que inclua duas matrizes, como o exemplo a seguir.
```
{
"ThingsPiratesSay": [
{
"say": "Avast!"
},
{
"say": "Yar!"
},
{
"say": "Walk the Plank!"
}
],
"ThingsGiantsSay": [
{
"say": "Fee!"
},
{
"say": "Fi!"
},
{
"say": "Fo!"
},
{
"say": "Fum!"
}
]
}
```
Nesse caso, você pode especificar qual matriz usar para iterações do estado `Map` selecionando-a com `ItemsPath`. A definição de máquina de estado a seguir especifica a matriz `ThingsPiratesSay` na entrada usando `ItemsPath`. Em seguida, ela executa uma iteração do estado de passagem `SayWord` para cada item na matriz `ThingsPiratesSay`.
```
{
"StartAt": "PiratesSay",
"States": {
"PiratesSay": {
"Type": "Map",
"ItemsPath": "$.ThingsPiratesSay",
"ItemProcessor": {
"StartAt": "SayWord",
"States": {
"SayWord": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Para objetos JSON aninhados, você pode usar `ItemsPath` para selecionar um objeto específico na entrada. Considere a seguinte entrada com dados de configuração aninhados:
```
{
"environment": "production",
"servers": {
"web": {
"server1": {"port": 80, "status": "active"},
"server2": {"port": 8080, "status": "inactive"}
},
"database": {
"primary": {"host": "db1.example.com", "port": 5432},
"replica": {"host": "db2.example.com", "port": 5432}
}
}
}
```
Para iterar sobre o objeto do servidor web, você definiria como`ItemsPath`: `$.servers.web`
```
{
"StartAt": "ProcessWebServers",
"States": {
"ProcessWebServers": {
"Type": "Map",
"ItemsPath": "$.servers.web",
"ItemProcessor": {
"StartAt": "CheckServer",
"States": {
"CheckServer": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
Ao processar a entrada, o estado `Map` aplica `ItemsPath` depois do [`InputPath`](input-output-inputpath-params.md#input-output-inputpath). Ele é operado na entrada efetiva para o estado depois que `InputPath` filtra a entrada.
Para obter mais informações sobre estados `Map`, consulte os tópicos a seguir:
+ [Estado do mapa](state-map.md)
+ [Modos de processamento do estado do mapa](state-map.md#concepts-map-process-modes)
+ [Repetir ações com o mapa inline](tutorial-map-inline.md)
+ [Processamento de entrada e saída do estado `Map` inline.](state-map-inline.md#inline-map-state-output)
# ItemSelector (mapa)
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
Por padrão, a entrada efetiva para o estado `Map` é o conjunto de itens de dados individuais presentes na entrada de estado bruto. Com o campo `ItemSelector`, você pode substituir os valores dos itens de dados antes que eles sejam transmitidos para o estado `Map`.
Para substituir os valores, especifique uma entrada JSON válida que contenha um coleção de pares de chave-valor. Os pares podem ser valores estáticos fornecidos na definição da máquina de estado, valores selecionados da entrada de estado usando um [caminho](amazon-states-language-paths.md) ou valores acessados a partir do [objeto de contexto](input-output-contextobject.md).
Se você especificar pares de chave-valor usando um caminho ou objeto de contexto, o nome da chave deverá terminar em `.$`.
**nota**
O campo `ItemSelector` substitui o campo `Parameters` dentro do estado `Map`. Se você usa o campo `Parameters` em suas definições do estado `Map` para criar entradas personalizadas, recomendados substituí-las por `ItemSelector`.
Você pode especificar o campo `ItemSelector` tanto em um *estado Mapa inline* quanto *Mapa distribuído*.
Por exemplo, considere a seguinte entrada JSON contendo uma matriz de três itens dentro do nó `imageData`. Para cada *iteração do estado `Map`*, um item de matriz é passado para a iteração como entrada.
```
[
{
"resize": "true",
"format": "jpg"
},
{
"resize": "false",
"format": "png"
},
{
"resize": "true",
"format": "jpg"
}
]
```
Usando o campo `ItemSelector`, você pode definir uma entrada JSON personalizada para substituir a entrada original, conforme mostrado no exemplo a seguir. O Step Functions então transmite essa entrada personalizada para cada *iteração do estado `Map`*. A entrada personalizada contém um valor estático para `size` e o valor dos dados de um objeto de contexto para o estado `Map`. O objeto de contexto `$$.Map.Item.Value` contém o valor de cada item de dados individual.
```
{
"ItemSelector": {
"size": 10,
"value.$": "$$.Map.Item.Value"
}
}
```
O exemplo a seguir mostra a entrada recebida por uma iteração do *estado Mapa inline*:
```
{
"size": 10,
"value": {
"resize": "true",
"format": "jpg"
}
}
```
**dica**
Para obter um exemplo completo de um *estado Mapa Distribuído* usando o campo `ItemSelector`, consulte [Copiar dados CSV em grande escala usando o mapa distribuído](tutorial-map-distributed.md).
# ItemBatcher (mapa)
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
O campo `ItemBatcher` é um objeto JSON, que especifica o processamento de um grupo de itens na execução de um único fluxo de trabalho secundário. Use lotes ao processar arquivos CSV ou matrizes JSON grandes, ou conjuntos de objetos grandes do Amazon S3.
O exemplo a seguir mostra a sintaxe do campo `ItemBatcher`. Na sintaxe a seguir, o número máximo de itens que cada execução de fluxo de trabalho secundário deve processar é definido como cem.
```
{
"ItemBatcher": {
"MaxItemsPerBatch": 100
}
}
```
Por padrão, cada item em um conjunto de dados é transmitido como entrada para execuções individuais de fluxos de trabalho secundários. Por exemplo, suponha que você especifique um arquivo JSON como entrada que contém a seguinte matriz:
```
[
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "true",
"statement_date": "5/18/2016",
"statement_source": "news"
},
...
]
```
Para a entrada fornecida, cada execução do fluxo de trabalho secundário recebe um item de matriz como entrada. O exemplo a seguir mostra a entrada da execução de um fluxo de trabalho secundário:
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
Para ajudar a otimizar o desempenho e o custo do seu trabalho de processamento, selecione um tamanho de lote que equilibre o número de itens em relação ao tempo de processamento deles. Se você usar lotes, o Step Functions adiciona os itens a uma matriz de **Itens**. Em seguida, ele transmite a matriz como entrada para a execução de cada fluxo de trabalho secundário. O exemplo a seguir mostra um lote de dois itens transmitido como entrada para a execução de um fluxo de trabalho secundário:
```
{
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
}
]
}
```
**dica**
Para saber mais sobre como usar o campo `ItemBatcher` em seus fluxos de trabalho, experimente os seguintes tutoriais e workshops:
[Processar um lote inteiro de dados em uma função do Lambda](tutorial-itembatcher-param-task.md)
[Iterar itens em um lote dentro das execuções do fluxo de trabalho secundário](tutorial-itembatcher-single-item-process.md)
[Mapa distribuído e recursos relacionados](https://catalog.workshops.aws/stepfunctions/use-cases/distributed-map) no *Workshop AWS Step Functions*
**Contents**
+ [
## Campos para especificar o agrupamento de itens em lotes
](#input-output-itembatcher-subfields)
## Campos para especificar o agrupamento de itens em lotes
Para agrupar itens em lotes, especifique o número máximo de itens por lote, o tamanho máximo do lote ou ambos. É necessário especificar um desses valores para agrupar os itens.
**Máximo de itens por lote**
Especifica o número máximo de itens que a execução de cada fluxo de trabalho secundário processa. O intérprete limita o número de itens agrupados em lote na matriz `Items` a esse valor. Se você especificar o número e o tamanho do lote, o intérprete reduzirá o número de itens em um lote para evitar que o limite de tamanho do lote especificado seja excedido.
Se você não especificar esse valor, mas fornecer um valor para o tamanho máximo do lote, o Step Functions processará o máximo de itens possível na execução de cada fluxo de trabalho secundário sem exceder o tamanho máximo do lote, em bytes.
Por exemplo, imagine que você esteja executando uma execução com um arquivo JSON de entrada que contenha 1130 nós. Se você especificar um valor máximo de cem itens a cada lote, o Step Functions criará 12 lotes. Destes, 11 lotes conterão cem itens cada, enquanto o décimo segundo lote conterá os 30 itens restantes.
Como alternativa, você pode especificar o número máximo de itens para cada lote como um [caminho de referência](amazon-states-language-paths.md#amazon-states-language-reference-paths) para um par de chave-valor existente na entrada do *estado Mapa Distribuído*. Esse caminho deve ser resolvido como um inteiro positivo.
Por exemplo, dada a seguinte entrada:
```
{
"maxBatchItems": 500
}
```
Você pode especificar o número máximo de itens por lote usando um caminho de referência (**somente JSONPath**) da seguinte forma:
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxItemsPerBatchPath": "$.maxBatchItems"
}
...
...
}
}
```
Para estados **baseados em JSONata**, você pode fornecer uma expressão JSONata que seja avaliada como um número inteiro positivo.
Você pode especificar o `MaxItemsPerBatch` ou o subcampo `MaxItemsPerBatchPath (JSONPath only)`, mas não ambos.
**Máximo de KiB por lote**
Especifica o tamanho máximo de um lote, em bytes, que é 256 KiB. Se você especificar tanto número quanto o tamanho máximos de um lote, o Step Functions reduzirá o número de itens em um lote para evitar que o limite de tamanho do lote especificado seja excedido.
Como alternativa, você pode especificar o tamanho máximo do lote como um [caminho de referência](amazon-states-language-paths.md#amazon-states-language-reference-paths) para um par de chave-valor existente na entrada do *estado Mapa Distribuído*. Esse caminho deve ser resolvido como um inteiro positivo.
Se você usar o agrupamento em lotes e não especificar um tamanho máximo para o lote, o intérprete processará o máximo possível de itens até 256 KiB em cada execução de um fluxo de trabalho secundário.
Por exemplo, dada a seguinte entrada:
```
{
"batchSize": 131072
}
```
Você pode especificar o tamanho máximo do lote usando um caminho de referência, da seguinte forma:
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxInputBytesPerBatchPath": "$.batchSize"
}
...
...
}
}
```
Para estados **baseados em JSONata**, você pode fornecer uma expressão JSONata que seja avaliada como um número inteiro positivo.
Você pode especificar o `MaxInputBytesPerBatch` ou o subcampo `MaxInputBytesPerBatchPath` (somente JSONPath), mas não ambos.
**Entrada em lote**
Opcionalmente, você também pode especificar a inclusão de uma entrada JSON fixa em cada lote transmitido para a execução de cada fluxo de trabalho secundário. O Step Functions mescla essa entrada com aquela para cada execução individual do fluxo de trabalho secundário. Por exemplo, dada a seguinte entrada fixa de uma data de verificação de fatos em uma matriz de itens:
```
"ItemBatcher": {
"BatchInput": {
"factCheck": "December 2022"
}
}
```
Cada execução do fluxo de trabalho secundário recebe o seguinte como entrada:
```
{
"BatchInput": {
"factCheck": "December 2022"
},
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
...
]
}
```
Para estados **baseados em JSONata**, você pode fornecer expressões JSONata diretamente para BatchInput ou usar expressões JSONata dentro de objetos ou matrizes JSON.
# ResultWriter (Mapa)
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
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.
**Topics**
+ [
## Conteúdo do ResultWriter campo
](#input-output-resultwriter-field-contents)
+ [Exemplos](#input-output-resultwriter-examples)
+ [
## Exportar para o Amazon S3
](#input-output-resultwriter-exporting-to-S3)
+ [
## Políticas do IAM para ResultWriter
](#resultwriter-iam-policies)
## Conteúdo do ResultWriter campo
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.
+ [ResultWriter configurações](#input-output-resultwriter-example-configurations)
+ [Transformações](#input-output-resultwriter-example-transformations)
### Exemplos de ResultWriter configurações
Os exemplos a seguir demonstram configurações com as combinações possíveis dos três campos: `WriterConfig`, `Resources` e `Parameters`.
**Somente dispositivos privados *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"
}
```
**Todos 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"
}
}
```
### Exemplos de transformações
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 que você usa para exportar os resultados de uma execução de mapa esteja abaixo da mesma máquina de estado Conta da AWS e na Região da AWS mesma. 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, usando **JSONPath**, mostra a sintaxe do `ResultWriter` campo com `Parameters` para exportar os resultados da execução do 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 **JSONata**estados, `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](#resultwriter-iam-policies).
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](redrive-map-run.md) 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 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.
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 nomeada *csvJobs* em um bucket do Amazon S3 usando `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)` a ação de 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/*"
]
}
]
}
```
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 AWS Key Management Service (AWS KMS) chave, você deverá incluir as AWS KMS permissões 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](iam-policies-eg-dist-map.md#multiupload-dmap-result-policy).
# Como o Step Functions analisa arquivos CSV de entrada
**Gerenciar estados e transformar dados**
Saiba mais sobre como [transmitir dados entre estados com variáveis](workflow-variables.md) e [transformar dados com JSONata](transforming-data.md).
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.
**Exemplo de de como analisar um arquivo CSV de entrada**
Digamos que você tenha fornecido um arquivo CSV chamado `myCSVInput.csv` que contém uma linha como entrada. Em seguida, você armazenou esse arquivo em um bucket do Amazon S3 que é chamado de `amzn-s3-demo-bucket`. O arquivo CSV é como a seguir.
```
abc,123,"This string contains commas, a double quotation marks (""), and a newline (
)",{""MyKey"":""MyValue""},"[1,2,3]"
```
A máquina de estado a seguir lê esse arquivo CSV e usa [ItemSelector (mapa)](input-output-itemselector.md) para converter os tipos de dados de alguns dos campos.
```
{
"StartAt": "Map",
"States": {
"Map": {
"Type": "Map",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "STANDARD"
},
"StartAt": "Pass",
"States": {
"Pass": {
"Type": "Pass",
"End": true
}
}
},
"End": true,
"Label": "Map",
"MaxConcurrency": 1000,
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "GIVEN",
"CSVHeaders": [
"MyLetters",
"MyNumbers",
"MyString",
"MyObject",
"MyArray"
]
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "myCSVInput.csv"
}
},
"ItemSelector": {
"MyLetters.$": "$$.Map.Item.Value.MyLetters",
"MyNumbers.$": "States.StringToJson($$.Map.Item.Value.MyNumbers)",
"MyString.$": "$$.Map.Item.Value.MyString",
"MyObject.$": "States.StringToJson($$.Map.Item.Value.MyObject)",
"MyArray.$": "States.StringToJson($$.Map.Item.Value.MyArray)"
}
}
}
}
```
Quando você executa essa máquina de estado, ela produz a saída a seguir.
```
[
{
"MyNumbers": 123,
"MyObject": {
"MyKey": "MyValue"
},
"MyString": "This string contains commas, a double quote (\"), and a newline (\n)",
"MyLetters": "abc",
"MyArray": [
1,
2,
3
]
}
]
```