Funciones intrínsecas

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:

• Funciones intrínsecas para matrices

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

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

• Funciones intrínsecas para la manipulación de datos de JSON

• Funciones intrínsecas para operaciones matemáticas

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

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

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

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

En la tabla siguiente se muestra qué campos admiten funciones intrínsecas para cada estado.

Campos que admiten funciones intrínsecas
State
	Pass	Task	Choice	Wait	Succeed	Fail	Parallel	Map
InputPath
Parameters	✓	✓					✓	✓
ResultSelector		✓					✓	✓
ResultPath
OutputPath
Variable
<Operador de comparación>Path
TimeoutSecondsPath
HeartbeatSecondsPath
Credentials		✓

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 matriz JSON 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 objeto JSON 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 objeto JSON 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 intrínseca States.Base64Encode para codificar datos según el esquema de codificación MIME Base64. Puede utilizar esta función para pasar datos a otros servicios AWS sin utilizar una función AWS Lambda.

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 utilizar la función States.Base64Encode para codificar la cadena input como una cadena 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 intrínseca States.Base64Decode para descodificar datos según el esquema de descodificación MIME Base64. Puede usar esta función para pasar datos a otros servicios AWS sin usar una función de 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 usar esta función para pasar datos a otros servicios AWS sin usar una función de 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" }

Funciones intrínsecas para la manipulación de datos de JSON

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

States.JsonMerge

Utilice la función intrínseca States.JsonMerge para combinar dos objetos JSON en un único objeto. Esta función toma tres argumentos. Los dos primeros argumentos son los objetos JSON que se 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 objetos JSON, la clave del último objeto anula la misma clave del primer objeto. Además, los objetos anidados dentro de un objeto JSON no se combinan cuando se utiliza la combinación superficial.

Por ejemplo, puede usar la función States.JsonMerge para combinar los siguientes objetos JSON 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 objeto JSON combinado. En el objeto JSON combinado output, la clave a del objeto json2 reemplaza a la clave a del objeto json1. 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 función States.StringToJson toma como único argumento una ruta de referencia a una cadena JSON con caracteres de escape.

El intérprete aplica un analizador JSON y devuelve el formulario JSON analizado 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 función States.JsonToString solo toma un argumento, que es la ruta que contiene los datos JSON que se devuelven como una cadena sin caracteres de escape. El intérprete devuelve una cadena con texto JSON que representa los datos especificados en la ruta. Por ejemplo, puede proporcionar la siguiente ruta JSON que contiene un valor con caracteres 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 de inicio. El argumento del valor de inicio es opcional. Si utiliza esta función con el mismo valor de inicio, devolverá un número idéntico.

importante

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

Validación de entrada

• 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 intrínseca States.UUID para devolver un identificador único universal (UUID v4) de la versión 4 generado con números al azar. Por ejemplo, puede usar esta función para llamar a otros servicios o recursos de AWS que necesiten un parámetro UUID o para 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 UUID generado aleatoriamente, 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 de {}. 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 bien

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

En JSON, las barras invertidas contenidas en un valor literal de cadena se deben incluir en una secuencia de escape con otra barra invertida. La lista equivalente para JSON es:

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