Transmitir dados entre estados com variáveis

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.

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: $states

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:

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 .

Sintaxe do nome da variável

Os nomes das variáveis seguem as regras para identificadores Unicode, conforme descrito no Anexo #31 do Padrão Unicode®. O primeiro caractere do nome de uma variável deve ser um caractere Unicode ID_Start, e os caracteres seguintes devem ser caracteres Unicode ID_Continue. 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.

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.

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:

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:

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