Door de gebruiker gedefinieerde functies

Door de gebruiker gedefinieerde functies zijn aangepaste functies die u configureert in een multi-step API (MSA)-controleregel of aangepaste integratie.

Ze verwerken waarden van stapvariabelen en retourneren een getransformeerd resultaat via mapping, parsing met regular expressions en andere ondersteunde bewerkingen. In de meeste gevallen wordt de invoerwaarde geëxtraheerd uit een API-response body en opgeslagen in een stapvariabele voordat de functie wordt uitgevoerd. Voor details over MSA-variabelen, zie Multi-step API-variabelen.

Een regular expression-functie kan bijvoorbeeld een bestandsnaam, invoice-123.pdf, extraheren uit een bestandspad dat is vastgelegd in een JSON-responseveld. Een mappingfunctie kan een API-status, Ok, omzetten naar een incidentstatus, Healthy, voor downstream verwerking.

In tegenstelling tot de ingebouwde coderings- of decoderingsfuncties van Uptrends zijn door de gebruiker gedefinieerde functies specifiek voor uw monitoringscenario. Zodra ze zijn gedefinieerd, kunnen ze in de hele controleregel of integratie opnieuw worden gebruikt zonder aangepaste scripts te vereisen. Voor details over ingebouwde coderings- of decoderingsfuncties, zie Coderings- of decoderingsfuncties.

Door de gebruiker gedefinieerde functies vereenvoudigen het extraheren en transformeren van data, zodat u dezelfde logica consistent opnieuw kunt gebruiken waar deze nodig is binnen de controleregel of integratie.

Types van gebruiker-gedefinieerde functies

Hash

Een hashing-functie is een eenrichtingsalgoritme dat een bericht van elke lengte als invoer accepteert en dit omzet in een waarde met een vaste lengte.

Gebruik deze functie om gevoelige gegevens zoals wachtwoorden, autorisatietokens of digitale handtekeningen veilig te vergelijken zonder de oorspronkelijke waarden uit te wisselen.

Geef voor HMAC-gebaseerde algoritmen (HMAC-SHA1, HMAC-SHA256 en HMAC-SHA512) een hash key op. Dit is het gedeelde geheim dat wordt gecombineerd met de invoerwaarde om de hash te produceren. Voor MD5, SHA1, SHA256 en SHA512 is geen hash key vereist.

Voor details over hashing-algoritmen, zie het knowledgebase-artikel Hashing en codering.

JSON Web Token (JWT) encode

De JWT encode-functie maakt een ondertekend token met een signing key en algoritme (bijvoorbeeld HS256), dat u kunt gebruiken voor authenticatie in latere API-stappen.

Geef de signing key op wanneer u de functie definieert en geef vervolgens de JWT-payload door als variabele wanneer u de functie uitvoert.

JSON Web Token (JWT) decode

De JWT decode-functie leest een token uit een variabele, bijvoorbeeld een access_token-waarde die uit een JSON-response body is geëxtraheerd, en retourneert de gedecodeerde payload. Gebruik dezelfde signing key die is gebruikt om het token te ondertekenen.

Mapping

Een mappingfunctie vervangt waarden van variabelen door overeenkomstige waarden. Als het /Status API-eindpunt bijvoorbeeld waarden zoals Error of Ok retourneert en een volgende stap termen zoals Incident of Healthy verwacht, gebruikt u deze functie om waarden naar de juiste equivalenten te mappen.

Regular expression

Gebruik een regular expression-functie om een deel van een string te parsen die uit een API-response body is vastgelegd. De typische workflow is een waarde uit de response extraheren, een RegEx-patroon toepassen om het deel te isoleren dat u nodig heeft en het resultaat opslaan in een stapvariabele voor gebruik in een vervolgrequest.

Als een JSON-veld bijvoorbeeld een volledig bestandspad retourneert zoals /uploads/reports/invoice-123.pdf, legt u die waarde eerst vast in een stapvariabele. Maak vervolgens een tweede stapvariabele om uw regular expression-functie toe te passen en alleen de bestandsnaam, invoice-123.pdf, te extraheren. Verwijs in latere stappen naar de resulterende variabele met {{variableName}}.

Gebruiker-gedefinieerde functies maken

Als u een door de gebruiker gedefinieerde functie wilt maken, selecteert u het pad op basis van uw behoeften:

• Multi-step API (MSA)-controleregel — ga naar uw MSA-controleregel > tabblad Stappen > Door gebruiker gedefinieerde functies.
• Aangepaste integraties — ga naar uw aangepaste integratie > tabblad Aanpassingen > Door gebruiker gedefinieerde functies.

Opmerking

Een door de gebruiker gedefinieerde functie is specifiek voor de multi-step API-controleregel of aangepaste integratie waarvoor u deze instelt en wordt niet overgedragen naar andere controleregels of integraties.

1. Klik in de sectie Door gebruiker gedefinieerde functies op Functie toevoegen om een nieuwe functie te maken.

2. Selecteer het functietype op basis van uw behoeften:

• Hash
• JWT coderen
• JWT decoderen
• Mapping
• Regular expression

3. Geef de functienaam op. We raden aan spaties in de functienaam te vermijden.

4. Geef de volgende details op:

• Geef voor mappingfuncties de from-waarden uit de API-variabele op naar de overeenkomstige to-waarden.
• Geef voor regular expression-functies het RegEx-patroon op. Het patroon wordt gematcht met een waarde uit een stapvariabele, doorgaans een waarde die uit de response body is vastgelegd, en extraheert het gematchte gedeelte.
• Selecteer voor hashing-functies het hash-algoritme en geef de hash key-waarde op voor HMAC-gebaseerde algoritmen.
• Geef voor JWT encode- en decode-functies de signing key en het algoritme op.

Voor hash keys en JWT signing keys kunt u vault-inloggegevens gebruiken in plaats van plattetekstwaarden. Voor meer details over het gebruik van vault-inloggegevens, zie Uptrends Vault.

5. Klik op Opslaan om de wijzigingen te bevestigen.

Zodra u de door de gebruiker gedefinieerde functie configureert, gebruikt u de functie met de variabele.

Door de gebruiker gedefinieerde functies toepassen

Om uw door de gebruiker gedefinieerde functies te gebruiken, verpakt u de variabele in de functie:

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

Voorbeeld

In dit voorbeeld wordt een mappingfunctie met de naam ErrorMapping gebruikt om statuswaarden van één API te vertalen voor gebruik in een latere stap.

• De functie mapt Error → Incident, Warning → Unhealthy en Ok → Healthy.
• De API retourneert een JSON-response met een Status-veld dat Error, Warning of Ok bevat.
• De volgende stap stuurt deze status naar een andere API die in plaats daarvan Incident, Unhealthy of Healthy verwacht.

Om ErrorMapping toe te passen en de statuswaarde automatisch te vertalen:

1. Maak een variabele om het Status-veld uit de response body te extraheren. Geef de variabele de naam statusRaw. Deze slaat waarden op zoals Error, Warning of Ok.

2. Klik op Variabele toevoegen om nog een variabele toe te voegen.

3. Stel de variabelebron in de vervolgkeuzelijst in op Functie uitvoeren.

4. Verpak in de functie-expressie de variabeleverwijzing in de functie:

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

5. De resulterende waarde is Incident, Unhealthy of Healthy, afhankelijk van de waarde van statusRaw. Geef in het veld Naam van de variabele een naam op voor de uitvoerwaarde. Bijvoorbeeld status.

U kunt nu in latere stappen naar de variabele status verwijzen met {{status}}.

Volg dezelfde stappen om andere types door de gebruiker gedefinieerde functies toe te passen. Alleen de velden en expressie van de functiedefinitie verschillen.