Fonctions définies par l’utilisateur

Les fonctions définies par l’utilisateur sont des fonctions personnalisées que vous configurez dans un moniteur API multi-étapes (MSA) ou une intégration personnalisée.

Elles traitent les valeurs des variables d’étape et renvoient un résultat transformé au moyen d’une conversion, d’une analyse par expression régulière et d’autres opérations prises en charge. Dans la plupart des cas, la valeur d’entrée est extraite du corps d’une réponse API et stockée dans une variable d’étape avant l’exécution de la fonction. Pour en savoir plus sur les variables MSA, consultez Variables d’API multi-étapes.

Par exemple, une fonction d’expression régulière peut extraire un nom de fichier, invoice-123.pdf, à partir d’un chemin de fichier capturé dans un champ de réponse JSON. Une fonction de conversion peut convertir un statut d’API, Ok, en statut d’incident, Healthy, pour le traitement en aval.

Contrairement aux fonctions d’encodage ou de décodage intégrées d’Uptrends, les fonctions définies par l’utilisateur sont propres à votre scénario de surveillance. Une fois définies, elles peuvent être réutilisées dans l’ensemble du moniteur ou de l’intégration sans nécessiter de scripts personnalisés. Pour en savoir plus sur les fonctions d’encodage ou de décodage intégrées, consultez Fonctions d’encodage ou de décodage.

Les fonctions définies par l’utilisateur simplifient l’extraction et la transformation des données, ce qui vous permet de réutiliser la même logique de façon cohérente partout où elle est nécessaire dans le moniteur ou l’intégration.

Types de fonctions définies par l’utilisateur

Hachage

Une fonction de hachage est un algorithme unidirectionnel qui accepte en entrée un message de n’importe quelle longueur et le transforme en une valeur de longueur fixe.

Utilisez cette fonction pour comparer en toute sécurité des données sensibles telles que des mots de passe, des jetons d’autorisation ou des signatures numériques sans échanger les valeurs d’origine.

Pour les algorithmes basés sur HMAC (HMAC-SHA1, HMAC-SHA256 et HMAC-SHA512), spécifiez une clé de hachage. Il s’agit du secret partagé combiné à la valeur d’entrée pour produire le hachage. Pour MD5, SHA1, SHA256 et SHA512, aucune clé de hachage n’est requise.

Pour en savoir plus sur les algorithmes de hachage, consultez l’article de la base de connaissances Hachage et encodage.

Encodage JSON Web Token (JWT)

La fonction d’encodage JWT crée un jeton signé à l’aide d’une clé de signature et d’un algorithme (par exemple, HS256), que vous pouvez utiliser pour l’authentification dans les étapes API suivantes.

Spécifiez la clé de signature lorsque vous définissez la fonction, puis transmettez la charge utile JWT en tant que variable lorsque vous exécutez la fonction.

Décodage JSON Web Token (JWT)

La fonction de décodage JWT lit un jeton à partir d’une variable, par exemple une valeur access_token extraite du corps d’une réponse JSON, et renvoie la charge utile décodée. Utilisez la même clé de signature que celle qui a été utilisée pour signer le jeton.

Conversion

Une fonction de conversion remplace les valeurs de variables par les valeurs correspondantes. Par exemple, si l’endpoint API /Status renvoie des valeurs telles que Error ou Ok, et qu’une étape suivante attend des termes tels que Incident ou Healthy, utilisez cette fonction pour convertir les valeurs en équivalents corrects.

Expression régulière

Utilisez une fonction d’expression régulière pour analyser une partie d’une chaîne capturée à partir du corps d’une réponse API. Le workflow type consiste à extraire une valeur de la réponse, à appliquer un motif RegEx pour isoler la partie dont vous avez besoin, puis à stocker le résultat dans une variable d’étape afin de l’utiliser dans une requête ultérieure.

Par exemple, si un champ JSON renvoie un chemin de fichier complet tel que /uploads/reports/invoice-123.pdf, commencez par capturer cette valeur dans une variable d’étape. Créez ensuite une deuxième variable d’étape pour appliquer votre fonction d’expression régulière afin d’extraire uniquement le nom de fichier, invoice-123.pdf. Référencez la variable obtenue dans les étapes suivantes à l’aide de {{variableName}}.

Créer des fonctions définies par l’utilisateur

Pour créer une fonction définie par l’utilisateur, sélectionnez le chemin en fonction de vos besoins :

• Moniteur API multi-étapes (MSA) — accédez à votre moniteur MSA > onglet Étapes > Fonctions définies par l'utilisateur.
• Intégrations personnalisées — accédez à votre intégration personnalisée > onglet Personnalisations > Fonctions définies par l'utilisateur.

Remarque

Une fonction définie par l’utilisateur est propre au moniteur API multi-étapes ou à l’intégration personnalisée pour lequel vous l’avez configurée, et ne s’applique pas aux autres moniteurs ou intégrations.

1. Dans la section Fonctions définies par l'utilisateur, cliquez sur Ajouter une fonction pour créer une nouvelle fonction.

2. Sélectionnez le type de fonction en fonction de vos besoins :

• Hacher
• Encodage JWT
• Décodage JWT
• Conversion
• Expression régulière

3. Spécifiez le nom de la fonction. Nous vous recommandons d’éviter les espaces dans le nom de la fonction.

4. Spécifiez les détails suivants :

• Pour les fonctions de conversion, spécifiez les valeurs source de la variable API et les valeurs cible correspondantes.
• Pour les fonctions d’expression régulière, spécifiez le motif RegEx. Le motif est comparé à une valeur provenant d’une variable d’étape, généralement une valeur capturée depuis le corps de la réponse, et extrait la partie correspondante.
• Pour les fonctions de hachage, sélectionnez l’algorithme de hachage et spécifiez la valeur de la clé de hachage pour les algorithmes basés sur HMAC.
• Pour les fonctions d’encodage et de décodage JWT, spécifiez la clé de signature et l’algorithme.

Pour les clés de hachage et les clés de signature JWT, vous pouvez utiliser les identifiants du coffre-fort plutôt que des valeurs en texte brut. Pour en savoir plus sur l’utilisation des identifiants du coffre-fort, consultez Uptrends Vault.

5. Cliquez sur Enregistrer pour confirmer les modifications.

Une fois la fonction définie par l’utilisateur configurée, utilisez-la avec la variable.

Appliquer des fonctions définies par l’utilisateur

Pour utiliser vos fonctions définies par l’utilisateur, enveloppez la variable dans la fonction :

{{userDefinedFunction({{variableReference}})}}

Exemple

Cet exemple utilise une fonction de conversion nommée ErrorMapping pour traduire les valeurs de statut d’une API afin de les utiliser dans une étape ultérieure.

• La fonction convertit Error → Incident, Warning → Unhealthy et Ok → Healthy.
• L’API renvoie une réponse JSON avec un champ Status contenant Error, Warning ou Ok.
• L’étape suivante envoie ce statut à une autre API qui attend plutôt Incident, Unhealthy ou Healthy.

Pour appliquer ErrorMapping et traduire automatiquement la valeur de statut :

1. Créez une variable pour extraire le champ Status du corps de la réponse. Nommez la variable statusRaw. Elle stocke des valeurs telles que Error, Warning ou Ok.

2. Cliquez sur Ajouter une variable pour ajouter une autre variable.

3. Définissez la source de la variable dans la liste déroulante sur Exécuter la fonction.

4. Dans l’expression de la fonction, enveloppez la référence de la variable dans la fonction :

{{ErrorMapping({{statusRaw}})}}

5. La valeur obtenue est Incident, Unhealthy ou Healthy, selon la valeur de statusRaw. Dans le champ Nom de la variable, spécifiez un nom pour la valeur de sortie. Par exemple, status.

Vous pouvez maintenant référencer la variable status dans les étapes suivantes à l’aide de {{status}}.

Suivez les mêmes étapes pour appliquer d’autres types de fonctions définies par l’utilisateur. Seuls les champs de définition de la fonction et l’expression diffèrent.