Funciones intrínsecas en Amazon States Language para los flujos de trabajo de Step Functions - AWS Step Functions
Campos que admiten funciones intrínsecasFunciones intrínsecas para matricesFunciones intrínsecas para la codificación y decodificación de datosFunción intrínseca para el cálculo del hashElementos intrínsecos para la manipulación de datos JSONFunciones intrínsecas para operaciones matemáticasFunción intrínseca para la operación de cadenaFunción intrínseca para la generación de identificadores únicosFunción intrínseca para una operación genéricaCaracteres reservados en funciones intrínsecas

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Funciones intrínsecas en Amazon States Language para los flujos de trabajo de Step Functions

Amazon States Language proporciona varias funciones intrínsecas, también conocidas como tipos intrínsecos, que ayudan a realizar operaciones básicas de procesamiento de datos sin usar un estado Task. Las funciones intrínsecas son componentes que tienen un aspecto similar a las funciones de los lenguajes de programación. Se pueden usar para ayudar a los constructores de cargas a procesar los datos que entran y salen del campo Resource de un estado Task.

En Amazon States Language, las funciones intrínsecas se agrupan en las siguientes categorías, según el tipo de tarea de procesamiento de datos que se desee realizar:

nota

  • Para utilizar funciones intrínsecas, debe especificar .$ en el valor clave de las definiciones de las máquinas de estado, tal y como se muestra en el ejemplo siguiente:

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

  • Puede anidar hasta 10 funciones intrínsecas dentro de un campo en sus flujos de trabajo. En el siguiente ejemplo se muestra un campo denominado myArn que incluye nueve funciones intrínsecas anidadas:

    "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))"
sugerencia

Si utiliza Step Functions en un entorno de desarrollo local, asegúrese de utilizar la versión 1.12.0 o posterior para poder incluir todas las funciones intrínsecas en sus flujos de trabajo.

Campos que admiten funciones intrínsecas

Los siguientes estados admiten funciones intrínsecas en los siguientes campos:

  • Estado de paso: parámetros

  • Estado de la tarea: parámetros ResultSelector, credenciales

  • Estado paralelo: parámetros, ResultSelector

  • Estado del mapa: parámetros, ResultSelector

Funciones intrínsecas para matrices

Utilice las siguientes funciones intrínsecas para realizar manipulaciones de matrices.

States.Array

La función intrínseca States.Array acepta cero o más argumentos. El intérprete devuelve una JSON matriz que contiene los valores de los argumentos en el orden indicado. Por ejemplo, en el caso de la entrada siguiente:

{
  "Id": 123456
}

Podría usar

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

Que devolvería el siguiente resultado:

“BuildId”: [123456]
States.ArrayPartition

Utilice la función intrínseca States.ArrayPartition para particionar una matriz grande. También puede utilizar esta función intrínseca para dividir en sectores los datos y, a continuación, enviar la carga en fragmentos de menor tamaño.

Esta función intrínseca toma dos argumentos. El primer argumento es una matriz, mientras que el segundo define el tamaño del fragmento. El intérprete divide la matriz de entrada en varias matrices del tamaño especificado por el tamaño del fragmento. La longitud del último fragmento de matriz puede ser menor que la longitud de los fragmentos de matriz anteriores si el número de elementos restantes de la matriz es menor que el tamaño del fragmento.

Validación de entrada

  • Debe especificar una matriz como valor de entrada para el primer argumento de la función.

  • Debe especificar un entero positivo distinto de cero para el segundo argumento, que representa el valor del tamaño del fragmento.

    Si especifica un valor no entero para el segundo argumento, Step Functions lo redondeará al entero más cercano.

  • La matriz de entrada no puede superar el límite de tamaño de carga de Step Functions de 256 KB.

Por ejemplo, en el caso de la matriz de entrada siguiente:

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

Puede usar la función States.ArrayPartition para dividir la matriz en fragmentos de cuatro valores:

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

Lo que devolvería los siguientes fragmentos de matriz:

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

En el ejemplo anterior, la función States.ArrayPartition genera tres matrices. Cada una de las dos primeras matrices contiene cuatro valores, según lo definido por el tamaño del fragmento. Una tercera matriz contiene el valor restante y su tamaño es menor que el tamaño de fragmento definido.

States.ArrayContains

Utilice la función intrínseca States.ArrayContains para determinar si un valor específico está presente en una matriz. Por ejemplo, puede usar esta función para detectar si hubo un error en una iteración de estado Map.

Esta función intrínseca toma dos argumentos. El primer argumento es una matriz, mientras que el segundo argumento es el valor que se debe buscar dentro de la matriz.

Validación de entrada

  • Debe especificar una matriz como valor de entrada para el primer argumento de la función.

  • Debe especificar un JSON objeto válido como segundo argumento.

  • La matriz de entrada no puede superar el límite de tamaño de carga de Step Functions de 256 KB.

Por ejemplo, en el caso de la matriz de entrada siguiente:

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

Puede usar la función States.ArrayContains para encontrar el valor lookingFor dentro de la inputArray:

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

Como el valor almacenado en lookingFor está incluido eninputArray, States.ArrayContains devuelve el siguiente resultado:

{"contains": true }
States.ArrayRange

Utilice la función intrínseca States.ArrayRange para crear una nueva matriz que contenga un rango específico de elementos. La nueva matriz puede contener hasta 1000 elementos.

Esta función toma tres argumentos. El primer argumento es el primer elemento de la nueva matriz, el segundo argumento es el elemento final de la nueva matriz y el tercer argumento es el valor del incremento entre los elementos de la nueva matriz.

Validación de entrada

  • Debe especificar valores enteros para todos los argumentos.

    Si especifica un valor no entero para alguno de los argumentos, Step Functions lo redondeará al entero más cercano.

  • Debe especificar un valor distinto de cero para el tercer argumento.

  • La matriz recién generada no puede contener más de 1000 elementos.

Por ejemplo, el siguiente uso de la función States.ArrayRange creará una matriz con un primer valor de 1, un valor final de 9 y los valores entre el primer valor y el valor final aumentarán en dos por cada elemento:

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

Lo que devolvería la siguiente matriz:

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

Esta función intrínseca devuelve el valor de un índice especificado. Esta función toma dos argumentos. El primer argumento es una matriz de valores y el segundo argumento es el índice de matriz del valor que se va a devolver.

Por ejemplo, utilice los siguientes valores inputArray y index:

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

A partir de estos valores, puede usar la función States.ArrayGetItem para devolver el valor de la posición index 5 dentro de la matriz:

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

En este ejemplo, States.ArrayGetItem devolvería el siguiente resultado:

{ "item": 6 }
States.ArrayLength

La función intrínseca States.ArrayLength devuelve la longitud de una matriz. Tiene un argumento, la matriz cuya longitud se devuelve.

Por ejemplo, en el caso de la matriz de entrada siguiente:

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

Se puede utilizar States.ArrayLength para devolver la longitud deinputArray:

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

En este ejemplo, States.ArrayLength devolvería el siguiente JSON objeto que representa la longitud de la matriz:

{ "length": 9 }
States.ArrayUnique

La función intrínseca States.ArrayUnique elimina los valores duplicados de una matriz y devuelve una matriz que contiene solo elementos únicos. Esta función toma una matriz, que puede estar desordenada, como único argumento.

Por ejemplo, la siguiente inputArray contiene una serie de valores duplicados:

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

Puede usar la función States.ArrayUnique y especificar la matriz de la que desea eliminar los valores duplicados:

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

La función States.ArrayUnique devolvería la siguiente matriz que contiene solo elementos únicos y eliminaría todos los valores duplicados:

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

Funciones intrínsecas para la codificación y decodificación de datos

Utilice las siguientes funciones intrínsecas para codificar o decodificar datos según el esquema de codificación Base64.

States.Base64Encode

Utilice la función States.Base64Encode intrínseca para codificar datos según el esquema de codificación MIME Base64. Puede utilizar esta función para pasar datos a otros AWS servicios sin utilizar un AWS Lambda función.

Esta función toma una cadena de datos de hasta 10 000 caracteres para codificarla como único argumento.

Por ejemplo, considere la siguiente cadena input:

{"input": "Data to encode" }

Puede usar la States.Base64Encode función para codificar la input cadena como una cadena de MIME Base64:

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

La función States.Base64Encode devuelve los siguientes datos codificados en la respuesta:

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

Utilice la función States.Base64Decode intrínseca para decodificar datos según el esquema de decodificación de MIME Base64. Puede utilizar esta función para pasar datos a otros AWS servicios sin utilizar una función Lambda.

Esta función utiliza una cadena de datos codificada en Base64 de hasta 10 000 caracteres para descodificarla como único argumento.

Por ejemplo, en el caso de la entrada siguiente:

{"base64": "RGF0YSB0byBlbmNvZGU=" }

Puede usar la función States.Base64Decode para descodificar la cadena en base64 y convertirla en una cadena en lenguaje natural:

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

En respuesta, la States.Base64Decode function devolvería los siguientes datos descodificados:

{"data": "Decoded data" }

Función intrínseca para el cálculo del hash

States.Hash

Utilice la función intrínseca States.Hash para calcular el valor de hash de una entrada determinada. Puede utilizar esta función para pasar datos a otros AWS servicios sin utilizar una función Lambda.

Esta función toma dos argumentos. El primer argumento son los datos cuyo valor hash se desea calcular. El segundo argumento es el algoritmo de hash que se utilizará para realizar el cálculo de hash. Los datos que proporcione deben ser una cadena de objeto que contenga 10 000 caracteres o menos.

El algoritmo de hash que especifique puede ser cualquiera de los siguientes:

  • MD5

  • SHA-1

  • SHA-256

  • SHA-384

  • SHA-512

Por ejemplo, puede usar esta función para calcular el valor de hash de la cadena Data utilizando el Algorithm especificado:

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

Puede usar la función States.Hash para calcular el valor de hash:

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

La función States.Hash devuelve el siguiente valor de hash como respuesta:

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

Elementos intrínsecos para la manipulación de datos JSON

Utilice estas funciones para realizar operaciones básicas de procesamiento de datos en JSON objetos.

States.JsonMerge

Utilice la función States.JsonMerge intrínseca para combinar dos JSON objetos en uno solo. Esta función toma tres argumentos. Los dos primeros argumentos son los JSON objetos que desea combinar. El tercer argumento es un valor booleano de false. Este valor booleano determina si el modo de combinación profunda está activado.

Actualmente, Step Functions solo admite el modo de combinación superficial; por lo tanto, debe especificar el valor booleano como false. En el modo superficial, si existe la misma clave en ambos JSON objetos, la clave del último objeto anula la misma clave del primer objeto. Además, los objetos anidados dentro de un JSON objeto no se fusionan cuando se utiliza una combinación superficial.

Por ejemplo, puede utilizar la States.JsonMerge función para combinar los siguientes JSON objetos que comparten la clave. a

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

Puede especificar los objetos JSON1 y JSON2 como entradas en la función States.JsonMerge para combinarlos:

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

Como resultado, States.JsonMerge devuelve el siguiente JSON objeto combinado. En el JSON objeto fusionadooutput, la clave del json2 objeto a reemplaza a la clave del json1 objetoa. Además, el objeto anidado de la clave a del objeto json1 se descarta porque el modo superficial no admite la combinación de objetos anidados.

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

La States.StringToJson función toma como único argumento una ruta de referencia a una JSON cadena de escape.

El intérprete aplica un JSON analizador y devuelve la forma analizada JSON de la entrada. Por ejemplo, puede utilizar esta función para incluir la siguiente cadena de entrada entre caracteres de escape:

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

Utilice la función States.StringToJson y especifique escapedJsonString como argumento de entrada:

States.StringToJson($.escapedJsonString)

La función States.StringToJson devuelve el siguiente resultado: 

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

La States.JsonToString función solo toma un argumento, que es la ruta que contiene los JSON datos para devolverlos como una cadena sin escape. El intérprete devuelve una cadena que contiene JSON texto que representa los datos especificados en la ruta. Por ejemplo, puede proporcionar la siguiente JSON ruta que contenga un valor de escape:

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

Proporcione a la función States.JsonToString los datos contenidos en unescapedJson:

States.JsonToString($.unescapedJson)

La función States.JsonToString devuelve la siguiente respuesta:

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

Funciones intrínsecas para operaciones matemáticas

Utilice estas funciones para realizar operaciones matemáticas.

States.MathRandom

Utilice la función intrínseca States.MathRandom para devolver un número al azar entre el número inicial (incluido) y el número final (excluido) especificados.

Puede usar esta función para distribuir una tarea específica entre dos o más recursos.

Esta función toma tres argumentos. El primer argumento es el número inicial, el segundo argumento es el número final y el último argumento controla el valor inicial opcional. Tenga en cuenta que si utiliza esta función con el mismo valor inicial, devolverá números idénticos.

importante

Como la States.MathRandom función no devuelve números aleatorios criptográficamente seguros, le recomendamos que no la utilice para aplicaciones sensibles a la seguridad.

Validación de entradas

  • Debe especificar valores enteros para los argumentos del número inicial y del número final.

    Si especifica un valor no entero para el argumento del número inicial o del número final, Step Functions lo redondeará al entero más cercano.

Por ejemplo, para generar un número aleatorio entre uno y 999, puede usar los siguientes valores de entrada:

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

Para generar el número aleatorio, proporcione los valores start y end a la función States.MathRandom:

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

La función States.MathRandom devuelve el siguiente número aleatorio como respuesta:

{"random": 456 }
States.MathAdd

Utilice la función intrínseca States.MathAdd para devolver la suma de dos números. Por ejemplo, puede usar esta función para incrementar los valores dentro de un bucle sin invocar una función de Lambda.

Validación de entrada

  • Debe especificar valores enteros para todos los argumentos.

    Si especifica un valor no entero para uno o ambos argumentos, Step Functions lo redondeará al entero más cercano.

  • Debe especificar valores enteros en el rango de -2147483648 a 2147483647.

Por ejemplo, puede utilizar los siguientes valores para restarle uno a 111:

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

A continuación, utilice la función States.MathAdd definiendo value1 como valor inicial y step como valor para incrementar value1 en:

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

La función States.MathAdd devolverá el siguiente número como respuesta:

{"value1": 110 }

Función intrínseca para la operación de cadena

States.StringSplit

Utilice la función intrínseca States.StringSplit para dividir una cadena en una lista de valores de cadena. Esta función toma dos argumentos. El primer argumento es una cadena y el segundo es el carácter delimitador que la función utilizará para dividir la cadena.

ejemplo - Dividir una cadena de entrada utilizando un único carácter delimitador

Para este ejemplo, utilice States.StringSplit para dividir la siguiente inputString, que contiene una serie de valores separados por comas:

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

Utilice la función States.StringSplit y defina inputString como primer argumento y el carácter delimitador splitter como segundo argumento:

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

Como resultado, la función States.StringSplit devuelve la siguiente matriz de cadenas:

{"array":  ["1","2","3","4","5"] }
ejemplo - Dividir una cadena de entrada con varios caracteres delimitadores

Para este ejemplo, utilice States.StringSplit para dividir la siguienteinputString, que contiene varios caracteres delimitadores:

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

Utilice la función States.StringSplit de la siguiente manera:

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

Como resultado, la función States.StringSplit devuelve la siguiente matriz de cadenas:

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

Función intrínseca para la generación de identificadores únicos

States.UUID

Utilice la función States.UUID intrínseca para devolver un identificador único universal (v4UUID) de la versión 4 generado con números aleatorios. Por ejemplo, puede usar esta función para llamar a otros AWS servicios o recursos que necesitan un UUID parámetro o insertar elementos en una tabla de DynamoDB.

Se llama a la función States.UUID sin especificar ningún argumento:

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

La función devuelve un dato generado aleatoriamenteUUID, como en el siguiente ejemplo:

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

Función intrínseca para una operación genérica

States.Format

Utilice la función intrínseca States.Format para construir una cadena a partir de valores literales e interpolados. Esta función toma uno o más argumentos. El valor del primer argumento debe ser una cadena y puede incluir cero o más instancias de la secuencia de caracteres {}. Debe haber tantos argumentos restantes en la invocación de la función intrínseca como ocurrencias{}. El intérprete devuelve la cadena definida en el primer argumento, sustituyendo cada {} por el valor del argumento correspondiente a la posición en la invocación de función intrínseca.

Por ejemplo, puede usar las siguientes entradas de name de un individuo y una frase template en la que insertar su nombre: 

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

Utilice la función States.Format y especifique la cadena template y la cadena que desee insertar en lugar de los caracteres {}:

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

o

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

Con cualquiera de las entradas anteriores, la función States.Format devuelve la cadena completa como respuesta: 

Hello, my name is Arnav.

Caracteres reservados en funciones intrínsecas

Los siguientes caracteres están reservados para funciones intrínsecas y deben incluirse en secuencias de escape con ('\') si desea que aparezcan en el valor: '{} y \.

Si el carácter \ debe aparecer como parte del valor sin servir como carácter de escape, debe incluirlo en una secuencia de escape con una barra invertida. Las siguientes secuencias de caracteres de escape se utilizan con funciones intrínsecas:

  • La cadena literal \' representa'.

  • La cadena literal \{ representa{.

  • La cadena literal \} representa}.

  • La cadena literal \\ representa\.

EnJSON, las barras invertidas contenidas en un valor literal de cadena se deben separar con otra barra invertida. La lista equivalente para es: JSON

  • La cadena de escape \\\' representa \'.

  • La cadena de escape \\\{ representa \{.

  • La cadena de escape \\\} representa \}.

  • La cadena de escape \\\\ representa \\.

nota

Si se encuentra una barra invertida de escape abierta \ en la cadena de invocación intrínseca, el intérprete devolverá un error de tiempo de ejecución.

Debe utilizar la notación entre corchetes para una ruta pasada como argumento a una función intrínseca si el nombre del campo contiene algún carácter que no esté incluido en la member-name-shorthand definición de la JsonPath ABNFregla. Además, si tu ruta contiene caracteres no alfanuméricos_, debes usar la notación entre corchetes. Por ejemplo, $.abc.['def ghi'].