Benutzerdefinierte Funktionen

Benutzerdefinierte Funktionen sind eigene Funktionen, die du in einem Multi-step API (MSA) Prüfobjekt oder einer benutzerdefinierten Integration konfigurierst.

Sie verarbeiten Werte von Schrittvariablen und geben ein transformiertes Ergebnis über Mapping, Parsing mit regulären Ausdrücken und andere unterstützte Operationen zurück. In den meisten Fällen wird der Eingabewert aus einem API Response Body extrahiert und in einer Schrittvariable gespeichert, bevor die Funktion ausgeführt wird. Details zu MSA-Variablen findest du unter Multi-step API-Variablen.

Beispielsweise kann eine Funktion für reguläre Ausdrücke einen Dateinamen, invoice-123.pdf, aus einem Dateipfad extrahieren, der in einem JSON-Antwortfeld erfasst wurde. Eine Mapping-Funktion kann einen API-Status, Ok, in einen Incident-Status, Healthy, für die nachgelagerte Verarbeitung konvertieren.

Im Gegensatz zu den integrierten Codierungs- oder Decodierungsfunktionen von Uptrends sind benutzerdefinierte Funktionen spezifisch für dein Monitoring-Szenario. Sobald sie definiert sind, kannst du sie im gesamten Prüfobjekt oder in der Integration wiederverwenden, ohne dass benutzerdefinierte Skripte erforderlich sind. Details zu integrierten Codierungs- oder Decodierungsfunktionen findest du unter Codierungs- oder Decodierungsfunktionen.

Benutzerdefinierte Funktionen vereinfachen die Datenextraktion und Transformation, sodass du dieselbe Logik überall dort konsistent wiederverwenden kannst, wo sie innerhalb des Prüfobjekts oder der Integration benötigt wird.

Arten benutzerdefinierter Funktionen

Hash

Eine Hash-Funktion ist ein Einweg-Algorithmus, der eine Nachricht beliebiger Länge als Eingabe akzeptiert und sie in einen Wert mit fester Länge umwandelt.

Verwende diese Funktion, um sensible Daten wie Passwörter, Autorisierungs-Tokens oder digitale Signaturen sicher zu vergleichen, ohne die ursprünglichen Werte auszutauschen.

Gib für HMAC-basierte Algorithmen (HMAC-SHA1, HMAC-SHA256 und HMAC-SHA512) einen Hash-Schlüssel an. Dies ist das gemeinsame Geheimnis, das mit dem Eingabewert kombiniert wird, um den Hash zu erzeugen. Für MD5, SHA1, SHA256 und SHA512 ist kein Hash-Schlüssel erforderlich.

Details zu Hashing-Algorithmen findest du im Knowledge-Base-Artikel Hashing und Codierung.

JSON Web Token (JWT) encode

Die JWT encode-Funktion erstellt ein signiertes Token mit einem Signaturschlüssel und Algorithmus (zum Beispiel HS256), das du für die Authentifizierung in späteren API-Schritten verwenden kannst.

Gib den Signaturschlüssel an, wenn du die Funktion definierst, und übergib dann den JWT-Payload als Variable, wenn du die Funktion ausführst.

JSON Web Token (JWT) decode

Die JWT decode-Funktion liest ein Token aus einer Variable, zum Beispiel einen access_token-Wert, der aus einem JSON Response Body extrahiert wurde, und gibt den decodierten Payload zurück. Verwende denselben Signaturschlüssel, mit dem das Token signiert wurde.

Mapping

Eine Mapping-Funktion ersetzt Variablenwerte durch entsprechende Werte. Wenn beispielsweise der API-Endpunkt /Status Werte wie Error oder Ok zurückgibt und ein nachfolgender Schritt Begriffe wie Incident oder Healthy erwartet, verwendest du diese Funktion, um Werte den richtigen Entsprechungen zuzuordnen.

Regulärer Ausdruck

Verwende eine Funktion für reguläre Ausdrücke, um einen Teil einer Zeichenfolge zu parsen, die aus einem API Response Body erfasst wurde. Der typische Workflow besteht darin, einen Wert aus der Antwort zu extrahieren, ein RegEx-Muster anzuwenden, um den benötigten Teil zu isolieren, und das Ergebnis in einer Schrittvariable zur Verwendung in einer Folgeanfrage zu speichern.

Wenn beispielsweise ein JSON-Feld einen vollständigen Dateipfad wie /uploads/reports/invoice-123.pdf zurückgibt, erfasse diesen Wert zuerst in einer Schrittvariable. Erstelle dann eine zweite Schrittvariable, um deine Funktion für reguläre Ausdrücke anzuwenden und nur den Dateinamen, invoice-123.pdf, zu extrahieren. Verweise in späteren Schritten mit {{variableName}} auf die resultierende Variable.

Benutzerdefinierte Funktionen erstellen

Um eine benutzerdefinierte Funktion zu erstellen, wähle den Pfad entsprechend deinen Anforderungen:

• Multi-step API (MSA) Prüfobjekt — gehe zu deinem MSA-Prüfobjekt > Tab Schritte > Benutzerdefinierte Funktionen.
• Benutzerdefinierte Integrationen — gehe zu deiner benutzerdefinierten Integration > Tab Anpassungen > Benutzerdefinierte Funktionen.

Hinweis

Eine benutzerdefinierte Funktion ist spezifisch für das Multi-step API-Prüfobjekt oder die benutzerdefinierte Integration, für die du sie eingerichtet hast, und wird nicht in andere Prüfobjekte oder Integrationen übernommen.

1. Klicke im Abschnitt Benutzerdefinierte Funktionen auf Funktion hinzufügen, um eine neue Funktion zu erstellen.

2. Wähle den Funktionstyp entsprechend deinen Anforderungen:

• Hash
• JWT-Kodierung
• JWT-Dekodierung
• Mapping
• Regular Expression

3. Gib den Funktionsnamen an. Wir empfehlen, Leerzeichen im Funktionsnamen zu vermeiden.

4. Gib die folgenden Details an:

• Gib für Mapping-Funktionen die Ausgangswerte aus der API-Variable und die entsprechenden Zielwerte an.
• Gib für Funktionen mit regulären Ausdrücken das RegEx-Muster an. Das Muster wird mit einem Wert aus einer Schrittvariable abgeglichen, normalerweise einem Wert, der aus dem Response Body erfasst wurde, und extrahiert den übereinstimmenden Teil.
• Wähle für Hash-Funktionen den Hash-Algorithmus aus und gib den Hash-Schlüsselwert für HMAC-basierte Algorithmen an.
• Gib für JWT encode- und decode-Funktionen den Signaturschlüssel und Algorithmus an.

Für Hash-Schlüssel und JWT-Signaturschlüssel kannst du Vault-Anmeldedaten anstelle von Klartextwerten verwenden. Weitere Details zur Verwendung von Vault-Anmeldedaten findest du unter Uptrends Vault.

5. Klicke auf Speichern, um die Änderungen zu bestätigen.

Sobald du die benutzerdefinierte Funktion konfiguriert hast, verwendest du die Funktion mit der Variable.

Benutzerdefinierte Funktionen anwenden

Um deine benutzerdefinierten Funktionen zu verwenden, schließe die Variable in die Funktion ein:

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

Beispiel

Dieses Beispiel verwendet eine Mapping-Funktion namens ErrorMapping, um Statuswerte aus einer API für die Verwendung in einem späteren Schritt zu übersetzen.

• Die Funktion ordnet Error → Incident, Warning → Unhealthy und Ok → Healthy zu.
• Die API gibt eine JSON-Antwort mit einem Feld Status zurück, das Error, Warning oder Ok enthält.
• Der nächste Schritt sendet diesen Status an eine andere API, die stattdessen Incident, Unhealthy oder Healthy erwartet.

Um ErrorMapping anzuwenden und den Statuswert automatisch zu übersetzen:

1. Erstelle eine Variable, um das Feld Status aus dem Response Body zu extrahieren. Benenne die Variable statusRaw. Sie speichert Werte wie Error, Warning oder Ok.

2. Klicke auf Variable hinzufügen, um eine weitere Variable hinzuzufügen.

3. Setze die Variablenquelle im Dropdown-Menü auf Funktion ausführen.

4. Schließe im Funktionsausdruck die Variablenreferenz in die Funktion ein:

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

5. Der resultierende Wert ist Incident, Unhealthy oder Healthy, abhängig vom Wert statusRaw. Gib im Feld Name der Variable einen Namen für den Ausgabewert an. Zum Beispiel status.

Du kannst jetzt in späteren Schritten mit {{status}} auf die Variable status verweisen.

Folge denselben Schritten, um andere Typen benutzerdefinierter Funktionen anzuwenden. Nur die Felder für die Funktionsdefinition und der Ausdruck unterscheiden sich.