Funções intrínsecas na Amazon States Language para fluxos de trabalho de Step Functions - AWS Step Functions
Campos compatíveis com funções intrínsecasFunções intrínsecas para matrizesFunções intrínsecas para codificação e decodificação de dadosFunção intrínseca para cálculo de hashIntrínsecos para manipulação de dados JSONFunções intrínsecas para operações matemáticasFunção intrínseca para operação de stringsFunção intrínseca para geração de identificadores exclusivosFunção intrínseca para operação genéricaCaracteres reservados em funções intrínsecas

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á.

Funções intrínsecas na Amazon States Language para fluxos de trabalho de Step Functions

A Amazon States Language fornece várias funções intrínsecas que ajudam você a realizar operações básicas de processamento de dados sem usar um estado Task. Funções intrínsecas são construções que se parecem com funções em linguagens de programação. Elas podem ser usadas para ajudar os criadores de carga a processar os dados que entram e saem do campo Resource de um estado Task.

Na Amazon States Language, as funções intrínsecas são agrupadas nas seguintes categorias, com base no tipo de tarefa de processamento de dados que você deseja realizar:

nota

  • Para usar funções intrínsecas, é necessário especificar .$ no valor da chave nas definições da máquina de estado, conforme mostrado no seguinte exemplo:

    "KeyId.$": "States.Array($.Id)"

  • Você pode agrupar até 10 funções intrínsecas em um campo em seus fluxos de trabalho. O seguinte exemplo mostra um campo chamado myArn que inclui nove funções intrínsecas aninhadas:

    "myArn.$": "States.Format('{}.{}.{}', States.ArrayGetItem(States.StringSplit(States.ArrayGetItem(States.StringSplit($.ImageRecipe.Arn, '/'), 2), '.'), 0), States.ArrayGetItem(States.StringSplit(States.ArrayGetItem(States.StringSplit($.ImageRecipe.Arn, '/'), 2), '.'), 1))"
dica

Se você usar o Step Functions em um ambiente de desenvolvimento local, verifique se está usando a versão 1.12.0 ou superior para poder incluir todas as funções intrínsecas em seus fluxos de trabalho.

Campos compatíveis com funções intrínsecas

Os estados a seguir oferecem suporte a funções intrínsecas nos seguintes campos:

  • Estado da passagem: Parâmetros

  • Estado da tarefa: parâmetros ResultSelector, credenciais

  • Estado paralelo: parâmetros, ResultSelector

  • Estado do mapa: Parâmetros, ResultSelector

Funções intrínsecas para matrizes

Use as funções intrínsecas a seguir para realizar manipulações de matriz.

States.Array

A função intrínseca States.Array aceita zero ou mais argumentos. O interpretador retorna uma JSON matriz contendo os valores dos argumentos na ordem fornecida. Por exemplo, dada a seguinte entrada:

{
  "Id": 123456
}

Você poderia usar

"BuildId.$": "States.Array($.Id)"

Que retornaria o seguinte resultado:

“BuildId”: [123456]
States.ArrayPartition

Use a função intrínseca States.ArrayPartition para particionar uma matriz grande. Você também pode usar essa função intrínseca para dividir os dados e, em seguida, enviar a carga em blocos menores.

Essa função intrínseca usa dois argumentos. O primeiro argumento é uma matriz, enquanto o segundo argumento define o tamanho do bloco. 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.

Validação de entrada

  • Você deve especificar uma matriz como o valor de entrada para o primeiro argumento da função.

  • Você deve especificar um número inteiro positivo diferente de zero para o segundo argumento que representa o valor do tamanho do bloco.

    Se você especificar um valor não inteiro para o segundo argumento, o Step Functions o arredondará para o número inteiro mais próximo.

  • A matriz de entrada não pode exceder o limite de tamanho de carga do Step Functions de 256 KB.

Por exemplo, dada a seguinte matriz de entrada:

{"inputArray": [1,2,3,4,5,6,7,8,9] }

Você pode usar a função States.ArrayPartition para dividir a matriz em blocos de quatro valores:

"inputArray.$": "States.ArrayPartition($.inputArray,4)"

O que retornaria os seguintes blocos de matriz:

{"inputArray": [ [1,2,3,4], [5,6,7,8], [9]] }

No exemplo anterior, a função States.ArrayPartition gera três matrizes. Cada uma das duas primeiras matrizes contém quatro valores, conforme definido pelo tamanho do bloco. Uma terceira matriz contém o valor restante e é menor que o tamanho do bloco definido.

States.ArrayContains

Use a função intrínseca States.ArrayContains para determinar se um valor específico está presente em uma matriz. Por exemplo, você pode usar essa função para detectar se houve um erro em uma iteração do estado Map.

Essa função intrínseca usa dois argumentos. O primeiro argumento é uma matriz, enquanto o segundo argumento é o valor a ser pesquisado dentro da matriz.

Validação de entrada

  • Você deve especificar uma matriz como o valor de entrada para o primeiro argumento da função.

  • Você deve especificar um JSON objeto válido como segundo argumento.

  • A matriz de entrada não pode exceder o limite de tamanho de carga do Step Functions de 256 KB.

Por exemplo, dada a seguinte matriz de entrada:

{
   "inputArray": [1,2,3,4,5,6,7,8,9],
   "lookingFor": 5
}

Você pode usar a função States.ArrayContains para encontrar o valor de lookingFor na inputArray:

"contains.$": "States.ArrayContains($.inputArray, $.lookingFor)"

Uma vez que o valor armazenado em lookingFor está incluído na inputArray, States.ArrayContains retorna o seguinte resultado:

{"contains": true }
States.ArrayRange

Use a função intrínseca States.ArrayRange para criar uma nova matriz contendo um intervalo específico de elementos. A nova matriz pode conter até mil elementos.

Essa função usa três argumentos. O primeiro argumento é o primeiro elemento da nova matriz, o segundo argumento é o elemento final da nova matriz e o terceiro argumento é o valor do incremento entre os elementos na nova matriz.

Validação de entrada

  • É necessário especificar valores inteiros para todos os argumentos.

    Se você especificar um valor não inteiro para qualquer um dos argumentos, o Step Functions o arredondará para o número inteiro mais próximo.

  • É necessário especificar um valor diferente de zero para o terceiro argumento.

  • A matriz recém-gerada não pode conter mais de mil itens.

Por exemplo, o seguinte uso da função States.ArrayRange criará uma matriz com o primeiro valor de 1, um valor final de 9 e os valores entre o primeiro e o valor final aumentarão em dois para cada item:

"array.$": "States.ArrayRange(1, 9, 2)"

O que retornaria a seguinte matriz:

{"array": [1,3,5,7,9] }
States.ArrayGetItem

Essa função intrínseca retorna o valor de um índice especificado. Essa função usa dois argumentos. O primeiro argumento é uma matriz de valores e o segundo argumento é o índice da matriz do valor a ser retornado.

Por exemplo, use os seguintes valores de inputArray e index:

{
   "inputArray": [1,2,3,4,5,6,7,8,9],
   "index": 5
}

A partir desses valores, você pode usar a função States.ArrayGetItem para retornar o valor na posição 5 do index dentro da matriz:

"item.$": "States.ArrayGetItem($.inputArray, $.index)"

Neste exemplo, States.ArrayGetItem deverá retornar o seguinte resultado:

{ "item": 6 }
States.ArrayLength

A função intrínseca States.ArrayLength retorna o comprimento de uma matriz. Ela tem um argumento: a matriz cujo comprimento deverá ser retornado.

Por exemplo, dada a seguinte matriz de entrada:

{
   "inputArray": [1,2,3,4,5,6,7,8,9]
}

Você pode usar States.ArrayLength para retornar o comprimento da inputArray:

"length.$": "States.ArrayLength($.inputArray)"

Neste exemplo, States.ArrayLength retornaria o seguinte JSON objeto que representa o comprimento da matriz:

{ "length": 9 }
States.ArrayUnique

A função intrínseca States.ArrayUnique remove valores duplicados de uma matriz e retorna uma matriz contendo somente elementos exclusivos. Essa função usa uma matriz, que pode ser desclassificada, como seu único argumento.

Por exemplo, a seguinte inputArray contém uma série de valores duplicados:

{"inputArray": [1,2,3,3,3,3,3,3,4] }

Você pode usar a função States.ArrayUnique e especificar a matriz da qual deseja remover valores duplicados:

"array.$": "States.ArrayUnique($.inputArray)"

A função States.ArrayUnique retornaria a seguinte matriz contendo somente elementos exclusivos, removendo todos os valores duplicados:

{"array": [1,2,3,4] }

Funções intrínsecas para codificação e decodificação de dados

Use as funções intrínsecas a seguir para codificar ou decodificar dados com base no esquema de codificação Base64.

States.Base64Encode

Use a função States.Base64Encode intrínseca para codificar dados com base no esquema de codificação MIME Base64. Você pode usar essa função para passar dados para outros AWS serviços sem usar um AWS Lambda função.

Essa função usa uma sequência de dados de até 10 mil caracteres para codificar como seu único argumento.

Por exemplo, considere a seguinte string de input:

{"input": "Data to encode" }

Você pode usar a States.Base64Encode função para codificar a input string como uma string MIME Base64:

"base64.$": "States.Base64Encode($.input)"

A função States.Base64Encode retorna os seguintes dados codificados como resposta:

{"base64": "RGF0YSB0byBlbmNvZGU=" }
States.Base64Decode

Use a função States.Base64Decode intrínseca para decodificar dados com base no esquema de decodificação MIME Base64. Você pode usar essa função para passar dados para outros AWS serviços sem usar uma função Lambda.

Essa função usa uma sequência de dados codificados com Base64 de até 10 mil caracteres para decodificar como seu único argumento.

Por exemplo, dada a seguinte entrada:

{"base64": "RGF0YSB0byBlbmNvZGU=" }

Você pode usar a função States.Base64Decode para decodificar a string base64 em uma string legível:

"data.$": "States.Base64Decode($.base64)"

A States.Base64Decode function retornaria os seguintes dados decodificados em resposta:

{"data": "Decoded data" }

Função intrínseca para cálculo de hash

States.Hash

Use a função intrínseca States.Hash para calcular o valor de hash de uma determinada entrada. Você pode usar essa função para passar dados para outros AWS serviços sem usar uma função Lambda.

Essa função usa dois argumentos. O primeiro argumento são os dados dos quais você deseja calcular o valor de hash. O segundo argumento é o algoritmo de hash a ser usado para realizar o cálculo de hash. Os dados fornecidos devem ser uma sequência de objetos contendo 10 mil caracteres ou menos.

O algoritmo de hash especificado pode ser qualquer um dos seguintes algoritmos:

  • MD5

  • SHA-1

  • SHA-256

  • SHA-384

  • SHA-512

Por exemplo, você pode usar essa função para calcular o valor de hash da string Data usando o Algorithm especificado:

{
   "Data": "input data", 
   "Algorithm": "SHA-1" 
}

Você pode usar a função States.Hash para calcular o valor do hash:

"output.$": "States.Hash($.Data, $.Algorithm)"

A função do States.Hash retorna o seguinte valor de hash em resposta:

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

Intrínsecos para manipulação de dados JSON

Use essas funções para realizar operações básicas de processamento de dados em JSON objetos.

States.JsonMerge

Use a função States.JsonMerge intrínseca para mesclar dois JSON objetos em um único objeto. Essa função usa três argumentos. Os dois primeiros argumentos são os JSON objetos que você deseja mesclar. O terceiro argumento é um valor booleano de false. Esse valor booleano determina se o modo de mesclagem profunda está ativado.

Atualmente, o Step Functions é compatível apenas com o modo de mesclagem superficial; portanto, você deve especificar o valor booleano como false. No modo superficial, se a mesma chave existir nos dois JSON objetos, a chave do último objeto substituirá a mesma chave no primeiro objeto. Além disso, objetos aninhados em um JSON objeto não são mesclados quando você usa a mesclagem superficial.

Por exemplo, você pode usar a States.JsonMerge função para mesclar os seguintes JSON objetos que compartilham a chavea.

{
   "json1": { "a": {"a1": 1, "a2": 2}, "b": 2 },
   "json2": { "a": {"a3": 1, "a4": 2}, "c": 3 }
}

Você pode especificar os objetos json1 e json2 como entradas na função States.JsonMerge para mesclá-los:

"output.$": "States.JsonMerge($.json1, $.json2, false)"

Como resultado, States.JsonMerge retorna o seguinte JSON objeto mesclado. No JSON objeto mescladooutput, a chave do json2 objeto a substitui a chave do json1 objeto. a Além disso, o objeto aninhado na chave a do objeto json1 é descartado porque o modo superficial não é compatível com mesclagem de objetos aninhados.

{
   "output": {
      "a": {"a3": 1, "a4": 2},
      "b": 2, 
      "c": 3 
   }
}
States.StringToJson

A States.StringToJson função usa um caminho de referência para uma JSON string de escape como seu único argumento.

O intérprete aplica um JSON analisador e retorna o formulário JSON analisado da entrada. Por exemplo, você pode usar essa função para efetuar o escape da seguinte string de entrada:

{
 "escapedJsonString": "{\"foo\": \"bar\"}"
}

Use a função States.StringToJson e especifique a escapedJsonString como argumento de entrada:

States.StringToJson($.escapedJsonString)

A função States.StringToJson retorna o seguinte resultado: 

{ "foo": "bar" }
States.JsonToString

A States.JsonToString função usa apenas um argumento, que é o caminho que contém os JSON dados a serem retornados como uma string sem escape. O interpretador retorna uma string que contém JSON texto representando os dados especificados pelo Path. Por exemplo, você pode fornecer o seguinte JSON caminho contendo um valor de escape:

{
  "unescapedJson": {
     "foo": "bar"
  }
}

Forneça à função States.JsonToString os dados contidos em unescapedJson:

States.JsonToString($.unescapedJson)

A função States.JsonToString retorna a seguinte resposta:

{\"foo\": \"bar\"}

Funções intrínsecas para operações matemáticas

Use essas funções para realizar operações matemáticas.

States.MathRandom

Use a função intrínseca States.MathRandom para retornar um número aleatório entre o número inicial especificado (inclusivo) e o número final (exclusivo).

Você pode usar essa função para distribuir uma tarefa específica entre dois ou mais recursos.

Essa função usa três argumentos. O primeiro argumento é o número inicial, o segundo argumento é o número final e o último argumento controla o valor inicial opcional. Observe que se você usar essa função com o mesmo valor inicial, ela retornará números idênticos.

Importante

Como a States.MathRandom função não retorna números aleatórios criptograficamente seguros, recomendamos que você não a use para aplicativos sensíveis à segurança.

Validação de entrada

  • É necessário especificar valores inteiros para os argumentos do número inicial e do número final.

    Se você especificar um valor não inteiro para o argumento do número inicial ou final, o Step Functions o arredondará para o número inteiro mais próximo.

Por exemplo, para gerar um número aleatório entre um e 999, você pode usar os seguintes valores de entrada:

{
   "start": 1,
   "end": 999
}

Para gerar o número aleatório, forneça os valores start e end para a função States.MathRandom:

"random.$": "States.MathRandom($.start, $.end)"

A função States.MathRandom retorna o seguinte número aleatório como resposta:

{"random": 456 }
States.MathAdd

Use a função intrínseca States.MathAdd para retornar a soma de dois números. Por exemplo, você pode usar essa função para incrementar valores dentro de um loop sem invocar uma função do Lambda.

Validação de entrada

  • É necessário especificar valores inteiros para todos os argumentos.

    Se você especificar um valor não inteiro para um ou ambos os argumentos, o Step Functions o arredondará para o número inteiro mais próximo.

  • É necessário especificar valores inteiros no intervalo de -2147483648 e 2147483647.

Por exemplo, você pode usar os seguintes valores para subtrair um de 111:

{
   "value1": 111,
   "step": -1
}

Em seguida, usar a função States.MathAdd definindo value1 como o valor inicial e step como o valor de aumento do value1:

"value1.$": "States.MathAdd($.value1, $.step)"

A função States.MathAdd retornaria o seguinte número como resposta:

{"value1": 110 }

Função intrínseca para operação de strings

States.StringSplit

Use a função intrínseca States.StringSplit para dividir uma string em uma matriz de valores. Essa função usa dois argumentos. O primeiro argumento é uma string e o segundo argumento é o caractere delimitador que a função usará para dividir a string.

exemplo - Divida uma string de entrada usando um único caractere delimitador

Neste exemplo, use States.StringSplit para dividir a seguinte inputString, que contém uma série de valores separados por vírgula:

{
    "inputString": "1,2,3,4,5",
    "splitter": ","
}

Use a função States.StringSplit e defina inputString como o primeiro argumento e o caractere delimitador splitter como o segundo argumento:

"array.$": "States.StringSplit($.inputString, $.splitter)"

A função States.StringSplit retorna a seguinte matriz de string como resultado:

{"array":  ["1","2","3","4","5"] }
exemplo - Divida uma string de entrada usando vários caracteres delimitadores

Neste exemplo, use States.StringSplit para dividir a seguinte inputString, que contém vários caracteres delimitadores:

{
  "inputString": "This.is+a,test=string",
  "splitter": ".+,="
}

Use a função States.StringSplit da seguinte forma:

{
  "myStringArray.$": "States.StringSplit($.inputString, $.splitter)"
}

A função States.StringSplit retorna a seguinte matriz de string como resultado:

{"myStringArray": [
  "This",
  "is",
  "a",
  "test",
  "string"
]}

Função intrínseca para geração de identificadores exclusivos

States.UUID

Use a função States.UUID intrínseca para retornar um identificador universal exclusivo (v4UUID) da versão 4 gerado usando números aleatórios. Por exemplo, você pode usar essa função para chamar outros AWS serviços ou recursos que precisam de um UUID parâmetro ou inserem itens em uma tabela do DynamoDB.

A função States.UUID é chamada sem nenhum argumento especificado:

"uuid.$": "States.UUID()"

A função retorna um gerado aleatoriamenteUUID, como no exemplo a seguir:

{"uuid": "ca4c1140-dcc1-40cd-ad05-7b4aa23df4a8" }

Função intrínseca para operação genérica

States.Format

Use a função intrínseca States.Format para construir uma string a partir de valores literais e interpolados. Essa função usa um ou mais argumentos. O valor do primeiro argumento deve ser uma string e pode incluir zero ou mais instâncias da sequência de caracteres {}. Deve haver tantos argumentos restantes na invocação da função intrínseca quanto ocorrências de. {} O interpretador retorna a string definida no primeiro argumento, com cada {} substituída pelo valor do argumento correspondente posicionalmente na invocação da função intrínseca.

Por exemplo, você pode usar as seguintes entradas do name de uma pessoa e uma frase template para inserir o nome dela: 

{
 "name": "Arnav",
 "template": "Hello, my name is {}."
}

Use a função States.Format e especifique a string template e a string a ser inserida no lugar dos caracteres {}:

States.Format('Hello, my name is {}.', $.name)

ou

States.Format($.template, $.name)

Com qualquer uma das entradas anteriores, a função States.Format retorna a string completa como resposta: 

Hello, my name is Arnav.

Caracteres reservados em funções intrínsecas

Os caracteres a seguir são reservados para funções intrínsecas e seu escape deve ser efetuado com uma barra invertida ('\') se você quiser que eles apareçam no Valor: '{} e \.

Se o caractere \ precisar aparecer como parte do valor sem servir como um caractere de escape, você deverá efetuar o escape dele com uma barra invertida. As seguintes sequências de caracteres com escape são usadas com funções intrínsecas:

  • A string literal \' representa '.

  • A string literal \{ representa {.

  • A string literal \} representa }.

  • A string literal \\ representa \.

EmJSON, as barras invertidas contidas em um valor literal de string devem ser escapadas com outra barra invertida. A lista equivalente para JSON é:

  • A string de escape \\\' representa \'.

  • A string de escape \\\{ representa \{.

  • A string de escape \\\} representa \}.

  • A string de escape \\\\ representa \\.

nota

Se uma barra invertida de escape aberta \ for encontrada na string de invocação da função intrínseca, o interpretador retornará um erro de runtime.

Você deve usar a notação de colchetes para um caminho passado como argumento para uma função intrínseca se o nome do campo contiver algum caractere que não esteja incluído na member-name-shorthand definição da regra. JsonPath ABNF Além disso, se o caminho contiver caracteres não alfanuméricos_, você deverá usar a notação de colchetes. Por exemplo, $.abc.['def ghi'].