Fonctions intrinsèques

L'Amazon States Language fournit plusieurs fonctions intrinsèques, également appelées intrinsèques, qui vous aident à effectuer des opérations de traitement de données de base sans utiliser d'Taskétat. Les intrinsèques sont des constructions qui ressemblent aux fonctions des langages de programmation. Ils peuvent être utilisés pour aider les constructeurs de charges utiles à traiter les données à destination et en provenance du Resource champ d'un Task État.

Dans Amazon States Language, les fonctions intrinsèques sont regroupées dans les catégories suivantes, en fonction du type de tâche de traitement des données que vous souhaitez effectuer :

• Intrinsèques pour les réseaux

• Intrinsèques pour le codage et le décodage des données

• Intrinsèque pour le calcul du hachage

• Intrinsèques pour la manipulation des données JSON

• Intrinsèques pour les opérations mathématiques

• Intrinsèque pour le fonctionnement des chaînes

• Intrinsèque pour la génération d'identifiants uniques

• Intrinsèque pour un fonctionnement générique

Note

• Pour utiliser des fonctions intrinsèques, vous devez spécifier .$ la valeur clé dans les définitions de votre machine à états, comme indiqué dans l'exemple suivant :

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

• Vous pouvez intégrer jusqu'à 10 fonctions intrinsèques dans un champ de vos flux de travail. L'exemple suivant montre un champ nommé myArn qui inclut neuf fonctions intrinsèques imbriquées :

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

Astuce

Si vous utilisez Step Functions dans un environnement de développement local, assurez-vous d'utiliser la version 1.12.0 ou supérieure pour pouvoir inclure toutes les fonctions intrinsèques dans vos flux de travail.

Champs prenant en charge les fonctions intrinsèques

Le tableau suivant indique quels champs prennent en charge les fonctions intrinsèques pour chaque état.

Champs prenant en charge les fonctions intrinsèques
State
	Passe	Tâche	Choix	Attente	Réussir	Échouer	Parallèle	Map
InputPath
Paramètres	✓	✓					✓	✓
ResultSelector		✓					✓	✓
ResultPath
OutputPath
Variable
<Comparison Operator>Chemin
TimeoutSecondsPath
HeartbeatSecondsPath
Informations d'identification		✓

Intrinsèques pour les réseaux

Utilisez les éléments intrinsèques suivants pour effectuer des manipulations de tableaux.

States.Array

La fonction States.Array intrinsèque ne prend aucun argument ou plus. L'interpréteur renvoie un tableau JSON contenant les valeurs des arguments dans l'ordre indiqué. Par exemple, avec les données d'entrée suivantes :

{
  "Id": 123456
}

Vous pourriez utiliser

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

Ce qui renverrait le résultat suivant :

“BuildId”: [123456]

States.ArrayPartition

Utilisez la fonction States.ArrayPartition intrinsèque pour partitionner un grand tableau. Vous pouvez également utiliser cet élément intrinsèque pour découper les données, puis envoyer la charge utile en petits morceaux.

Cette fonction intrinsèque prend deux arguments. Le premier argument est un tableau, tandis que le second définit la taille du bloc. L'interpréteur découpe le tableau d'entrée en plusieurs tableaux de la taille spécifiée par la taille du morceau. La longueur du dernier segment de tableau peut être inférieure à la longueur des fragments de tableau précédents si le nombre d'éléments restants dans le tableau est inférieur à la taille du morceau.

Validation des entrées

• Vous devez spécifier un tableau comme valeur d'entrée pour le premier argument de la fonction.

• Vous devez spécifier un entier positif différent de zéro pour le deuxième argument représentant la valeur de la taille du segment.

  Si vous spécifiez une valeur non entière pour le deuxième argument, Step Functions l'arrondira à l'entier le plus proche.

• Le tableau d'entrée ne peut pas dépasser la limite de charge utile de 256 Ko fixée par Step Functions.

Par exemple, étant donné le tableau d'entrée suivant :

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

Vous pouvez utiliser cette States.ArrayPartition fonction pour diviser le tableau en morceaux de quatre valeurs :

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

Ce qui renverrait les fragments de tableau suivants :

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

Dans l'exemple précédent, la States.ArrayPartition fonction produit trois tableaux. Les deux premiers tableaux contiennent chacun quatre valeurs, telles que définies par la taille des morceaux. Un troisième tableau contient la valeur restante et est inférieur à la taille de bloc définie.

States.ArrayContains

Utilisez la fonction States.ArrayContains intrinsèque pour déterminer si une valeur spécifique est présente dans un tableau. Par exemple, vous pouvez utiliser cette fonction pour détecter s'il y a eu une erreur lors d'une itération d'Mapétat.

Cette fonction intrinsèque prend deux arguments. Le premier argument est un tableau, tandis que le second est la valeur à rechercher dans le tableau.

Validation des entrées

• Vous devez spécifier un tableau comme valeur d'entrée pour le premier argument de la fonction.

• Vous devez spécifier un objet JSON valide comme deuxième argument.

• Le tableau d'entrée ne peut pas dépasser la limite de charge utile de 256 Ko fixée par Step Functions.

Par exemple, étant donné le tableau d'entrée suivant :

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

Vous pouvez utiliser la States.ArrayContains fonction pour trouver la lookingFor valeur dans inputArray :

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

Comme la valeur stockée dans lookingFor est incluse dans leinputArray, States.ArrayContains renvoie le résultat suivant :

{"contains": true }

States.ArrayRange

Utilisez la fonction States.ArrayRange intrinsèque pour créer un nouveau tableau contenant une plage spécifique d'éléments. Le nouveau tableau peut contenir jusqu'à 1 000 éléments.

Cette fonction prend trois arguments. Le premier argument est le premier élément du nouveau tableau, le deuxième est le dernier élément du nouveau tableau et le troisième argument est la valeur d'incrément entre les éléments du nouveau tableau.

Validation des entrées

• Vous devez spécifier des valeurs entières pour tous les arguments.

  Si vous spécifiez une valeur non entière pour l'un des arguments, Step Functions l'arrondira à l'entier le plus proche.

• Vous devez spécifier une valeur différente de zéro pour le troisième argument.

• Le tableau nouvellement généré ne peut pas contenir plus de 1 000 éléments.

Par exemple, l'utilisation suivante de la States.ArrayRange fonction créera un tableau avec une première valeur de 1, une valeur finale de 9, et les valeurs comprises entre les première et dernière valeurs augmenteront de deux pour chaque élément :

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

Ce qui renverrait le tableau suivant :

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

States.ArrayGetItem

Cette fonction intrinsèque renvoie la valeur d'un indice spécifié. Cette fonction prend deux arguments. Le premier argument est un tableau de valeurs et le second est l'index du tableau de la valeur à renvoyer.

Par exemple, utilisez les index valeurs inputArray et suivantes :

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

À partir de ces valeurs, vous pouvez utiliser la States.ArrayGetItem fonction pour renvoyer la valeur à la index position 5 dans le tableau :

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

Dans cet exemple, States.ArrayGetItem renverrait le résultat suivant :

{ "item": 6 }

States.ArrayLength

La fonction States.ArrayLength intrinsèque renvoie la longueur d'un tableau. Il a un argument, le tableau dont la longueur doit être renvoyée.

Par exemple, étant donné le tableau d'entrée suivant :

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

Vous pouvez l'utiliser States.ArrayLength pour renvoyer la longueur de inputArray :

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

Dans cet exemple, States.ArrayLength renverrait l'objet JSON suivant qui représente la longueur du tableau :

{ "length": 9 }

States.ArrayUnique

La fonction States.ArrayUnique intrinsèque supprime les valeurs dupliquées d'un tableau et renvoie un tableau contenant uniquement des éléments uniques. Cette fonction prend un tableau, qui peut être détrié, comme seul argument.

Par exemple, le texte suivant inputArray contient une série de valeurs dupliquées :

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

Vous pouvez utiliser la States.ArrayUnique fonction as et spécifier le tableau dont vous souhaitez supprimer les doublons :

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

La States.ArrayUnique fonction renverrait le tableau suivant contenant uniquement des éléments uniques, en supprimant toutes les valeurs dupliquées :

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

Intrinsèques pour le codage et le décodage des données

Utilisez les fonctions intrinsèques suivantes pour coder ou décoder des données selon le schéma de codage Base64.

States.Base64Encode

Utilisez la fonction States.Base64Encode intrinsèque pour coder les données selon le schéma de codage MIME Base64. Vous pouvez utiliser cette fonction pour transmettre des données à d'autres AWS services sans utiliser de AWS Lambda fonction.

Cette fonction prend comme seul argument une chaîne de données de 10 000 caractères maximum à coder.

Par exemple, considérez la input chaîne suivante :

{"input": "Data to encode" }

Vous pouvez utiliser la States.Base64Encode fonction pour encoder la input chaîne en tant que chaîne MIME Base64 :

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

La States.Base64Encode fonction renvoie les données codées suivantes en réponse :

{"base64": "RGF0YSB0byBlbmNvZGU=" }

States.Base64Decode

Utilisez la fonction States.Base64Decode intrinsèque pour décoder les données selon le schéma de décodage MIME Base64. Vous pouvez utiliser cette fonction pour transmettre des données à d'autres AWS services sans utiliser de fonction Lambda.

Cette fonction prend comme seul argument une chaîne de données codée en Base64 de 10 000 caractères maximum à décoder.

Par exemple, avec les données d'entrée suivantes :

{"base64": "RGF0YSB0byBlbmNvZGU=" }

Vous pouvez utiliser la States.Base64Decode fonction pour décoder la chaîne base64 en une chaîne lisible par l'homme :

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

Ils States.Base64Decode function renverraient les données décodées suivantes en réponse :

{"data": "Decoded data" }

Intrinsèque pour le calcul du hachage

States.Hash

Utilisez la fonction States.Hash intrinsèque pour calculer la valeur de hachage d'une entrée donnée. Vous pouvez utiliser cette fonction pour transmettre des données à d'autres AWS services sans utiliser de fonction Lambda.

Cette fonction prend deux arguments. Le premier argument concerne les données dont vous souhaitez calculer la valeur de hachage. Le deuxième argument est l'algorithme de hachage à utiliser pour effectuer le calcul du hachage. Les données que vous fournissez doivent être une chaîne d'objets contenant 10 000 caractères ou moins.

L'algorithme de hachage que vous spécifiez peut être l'un des algorithmes suivants :

• MD5

• SHA-1

• SHA-256

• SHA-384

• SHA-512

Par exemple, vous pouvez utiliser cette fonction pour calculer la valeur de hachage de la Data chaîne à l'aide de la valeur spécifiée Algorithm :

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

Vous pouvez utiliser la States.Hash fonction pour calculer la valeur de hachage :

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

La States.Hash fonction renvoie la valeur de hachage suivante en réponse :

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

Intrinsèques pour la manipulation des données JSON

Utilisez ces fonctions pour effectuer des opérations de traitement de données de base sur des objets JSON.

States.JsonMerge

Utilisez la fonction States.JsonMerge intrinsèque pour fusionner deux objets JSON en un seul objet. Cette fonction prend trois arguments. Les deux premiers arguments sont les objets JSON que vous souhaitez fusionner. Le troisième argument est une valeur booléenne de. false Cette valeur booléenne détermine si le mode de fusion profonde est activé.

Step Functions ne prend actuellement en charge que le mode de fusion superficielle ; vous devez donc spécifier la valeur booléenne sous la forme. false En mode superficiel, si la même clé existe dans les deux objets JSON, la clé du dernier objet remplace la même clé dans le premier objet. De plus, les objets imbriqués dans un objet JSON ne sont pas fusionnés lorsque vous utilisez une fusion superficielle.

Par exemple, vous pouvez utiliser la States.JsonMerge fonction pour fusionner les objets JSON suivants qui partagent la cléa.

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

Vous pouvez spécifier les objets json1 et json2 comme entrées dans la States.JsonMerge fonction pour les fusionner :

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

States.JsonMergeRenvoie l'objet JSON fusionné suivant en conséquence. Dans l'objet JSON fusionnéoutput, la clé de l'json2objet a remplace la clé de l'json1objeta. De plus, l'objet imbriqué dans la clé de json1 l'objet a est supprimé car le mode superficiel ne permet pas de fusionner des objets imbriqués.

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

States.StringToJson

La States.StringToJson fonction prend comme seul argument un chemin de référence vers une chaîne JSON échappée.

L'interpréteur applique un analyseur JSON et renvoie le formulaire JSON analysé de l'entrée. Par exemple, vous pouvez utiliser cette fonction pour échapper à la chaîne de saisie suivante :

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

Utilisez la States.StringToJson fonction et spécifiez le escapedJsonString comme argument d'entrée :

States.StringToJson($.escapedJsonString)

La States.StringToJson fonction renvoie le résultat suivant :

{ "foo": "bar" }

States.JsonToString

La States.JsonToString fonction ne prend qu'un seul argument, à savoir le chemin qui contient les données JSON à renvoyer sous forme de chaîne non échappée. L'interpréteur renvoie une chaîne contenant du texte JSON représentant les données spécifiées par le chemin. Par exemple, vous pouvez fournir le chemin JSON suivant contenant une valeur échappée :

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

Fournissez à la States.JsonToString fonction les données contenues dans unescapedJson :

States.JsonToString($.unescapedJson)
                

La States.JsonToString fonction renvoie la réponse suivante :

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

Intrinsèques pour les opérations mathématiques

Utilisez ces fonctions pour effectuer des opérations mathématiques.

States.MathRandom

Utilisez la fonction States.MathRandom intrinsèque pour renvoyer un nombre aléatoire compris entre le numéro de début (inclus) et le numéro de fin (exclusif) spécifiés.

Vous pouvez utiliser cette fonction pour répartir une tâche spécifique entre deux ressources ou plus.

Cette fonction prend trois arguments. Le premier argument est le numéro de début, le deuxième est le numéro de fin et le dernier argument contrôle la valeur initiale. L'argument valeur initiale est facultatif. Si vous utilisez cette fonction avec la même valeur initiale, elle renvoie un nombre identique.

Important

Comme la States.MathRandom fonction ne renvoie pas de nombres aléatoires sécurisés par cryptographie, nous vous recommandons de ne pas l'utiliser pour les applications sensibles en termes de sécurité.

Validation des entrées

• Vous devez spécifier des valeurs entières pour les arguments du numéro de début et du numéro de fin.

  Si vous spécifiez une valeur non entière pour l'argument du numéro de début ou de fin, Step Functions l'arrondira à l'entier le plus proche.

Par exemple, pour générer un nombre aléatoire compris entre un et 999, vous pouvez utiliser les valeurs d'entrée suivantes :

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

Pour générer le nombre aléatoire, fournissez les end valeurs start et à la States.MathRandom fonction :

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

La States.MathRandom fonction renvoie le nombre aléatoire suivant en réponse :

{"random": 456 }

States.MathAdd

Utilisez la fonction States.MathAdd intrinsèque pour renvoyer la somme de deux nombres. Par exemple, vous pouvez utiliser cette fonction pour incrémenter des valeurs dans une boucle sans appeler de fonction Lambda.

Validation des entrées

• Vous devez spécifier des valeurs entières pour tous les arguments.

  Si vous spécifiez une valeur non entière pour l'un des arguments ou pour les deux, Step Functions l'arrondira à l'entier le plus proche.

• Vous devez spécifier des valeurs entières comprises entre -2147483648 et 2147483647.

Par exemple, vous pouvez utiliser les valeurs suivantes pour soustraire un de 111 :

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

Utilisez ensuite la States.MathAdd fonction définissant value1 comme valeur de départ et step comme valeur à incrémenter value1 de :

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

La States.MathAdd fonction renverrait le nombre suivant en réponse :

{"value1": 110 }

Intrinsèque pour le fonctionnement des chaînes

States.StringSplit

Utilisez la fonction States.StringSplit intrinsèque pour diviser une chaîne en un tableau de valeurs. Cette fonction prend deux arguments. Le premier argument est une chaîne et le second est le caractère de délimitation que la fonction utilisera pour diviser la chaîne.

Exemple - Diviser une chaîne d'entrée en utilisant un seul caractère de délimitation

Pour cet exemple, utilisez States.StringSplit pour diviser ce qui suitinputString, qui contient une série de valeurs séparées par des virgules :

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

Utilisez la States.StringSplit fonction et définissez inputString comme premier argument, et le caractère de délimitation splitter comme second argument :

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

La States.StringSplit fonction renvoie le tableau de chaînes suivant comme résultat :

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

Exemple - Diviser une chaîne d'entrée à l'aide de plusieurs caractères de délimitation

Pour cet exemple, utilisez States.StringSplit pour diviser ce qui suitinputString, qui contient plusieurs caractères de délimitation :

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

Utilisez la States.StringSplit fonction comme suit :

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

La States.StringSplit fonction renvoie le tableau de chaînes suivant comme résultat :

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

Intrinsèque pour la génération d'identifiants uniques

States.UUID

Utilisez la fonction States.UUID intrinsèque pour renvoyer un identifiant unique universel (UUID v4) de version 4 généré à l'aide de nombres aléatoires. Par exemple, vous pouvez utiliser cette fonction pour appeler d'autres AWS services ou ressources nécessitant un paramètre UUID ou pour insérer des éléments dans une table DynamoDB.

La States.UUID fonction est appelée sans qu'aucun argument ne soit spécifié :

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

La fonction renvoie un UUID généré de manière aléatoire, comme dans l'exemple suivant :

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

Intrinsèque pour un fonctionnement générique

States.Format

Utilisez la fonction States.Format intrinsèque pour construire une chaîne à partir de valeurs littérales et interpolées. Cette fonction prend un ou plusieurs arguments. La valeur du premier argument doit être une chaîne et peut inclure zéro ou plusieurs instances de la séquence de caractères{}. Il doit rester autant d'arguments dans l'invocation de l'intrinsèque qu'il y a d'occurrences de{}. L'interpréteur renvoie la chaîne définie dans le premier argument, chacune étant {} remplacée par la valeur de l'argument correspondant à la position dans l'invocation intrinsèque.

Par exemple, vous pouvez utiliser les entrées suivantes parmi celles d'un individuname, ainsi qu'une template phrase dans laquelle insérer son nom :

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

Utilisez la States.Format fonction et spécifiez la template chaîne et la chaîne à insérer à la place des {} caractères :

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

or

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

Avec l'une des entrées précédentes, la States.Format fonction renvoie la chaîne complète en réponse :

Hello, my name is Arnav.

Caractères réservés dans les fonctions intrinsèques

Les caractères suivants sont réservés aux fonctions intrinsèques et doivent être évités par une barre oblique inverse (« \ ») si vous souhaitez qu'ils apparaissent dans la valeur : ' { } et. \

Si le caractère \ doit apparaître dans la valeur sans servir de caractère d'échappement, vous devez y échapper par une barre oblique inverse. Les séquences de caractères échappées suivantes sont utilisées avec des fonctions intrinsèques :

• La chaîne littérale \' représente'.

• La chaîne littérale \{ représente{.

• La chaîne littérale \} représente}.

• La chaîne littérale \\ représente\.

En JSON, les barres obliques inverses contenues dans une valeur littérale de chaîne doivent être évitées par une autre barre oblique inverse. La liste équivalente pour JSON est la suivante :

• La chaîne échappée \\\' représente\'.

• La chaîne échappée \\\{ représente\{.

• La chaîne échappée \\\} représente\}.

• La chaîne échappée \\\\ représente\\.

Note

Si une barre oblique inverse ouverte \ est détectée dans la chaîne d'invocation intrinsèque, l'interpréteur renvoie une erreur d'exécution.