Workiva-ondersteuningscentrum

Bij dynamische integraties, vooral bij het gebruik van HTTP-connectoren in geautomatiseerde workflows (zoals Chains), is het van cruciaal belang om de respons van een API-aanroep effectief te verwerken. Uitvoerparameters stellen gebruikers in staat om essentiële gegevens vast te leggen die door de API worden geretourneerd - zoals de respons body, respons headers en statuscode - zodat deze gegevens in latere stappen kunnen worden gebruikt.

Welk probleem lost dit op?

Uitvoerparameters zijn cruciaal voor het creëren van responsieve en intelligente workflows.

• Dynamische workflows: Uitvoerparameters maken het mogelijk om aan te passen wat er vervolgens gebeurt op basis van wat de API retourneert - bijvoorbeeld een token extraheren, controleren of een record bestaat, of een succesvolle bewerking bevestigen.
• Automatisering: Door waarden automatisch vast te leggen, vermijden gebruikers handmatige invoer of hard-coding, waardoor workflows kunnen worden opgeschaald met minder onderhoud.
• Gestroomlijnde integraties: Het verbinden van systemen zoals verificatieservers, CRM's of aangepaste API's verloopt naadlozer omdat de connector zich aanpast op basis van de gegevens die hij ontvangt.

Op wie heeft dit invloed?

• Ontwikkelaars en integrators: Zij die automatiseringsketens of integraties tussen systemen bouwen.
• Gegevensanalisten: Zij die vertrouwen op realtime, nauwkeurige gegevensstromen om dashboards of rapportages te voeden.
• Systeembeheerders: Zij die integraties onderhouden en problemen oplossen - toegang tot uitvoerparameters helpt om problemen snel op te sporen.

Wat zijn uitvoerparameters?

De Uitvoerparameters in een HTTP Connector worden gebruikt om de verwachte uitvoer van een HTTP-verzoek te definiëren, zoals antwoordkoppen, antwoordtekst of antwoordcode. Deze definiëren de verwachte resultaten van een HTTP-verzoek, die vervolgens kunnen worden hergebruikt in volgende knooppunten of logische stappen in een keten.

Voorbeelduitvoerparameters:

• Response Headers: Metagegevens zoals inhoudstype, server of status van de snelheidslimiet.
• Response Body: De daadwerkelijke inhoud die door de API wordt geretourneerd - meestal in JSON of XML formaat.
• Responscode: Geeft succes (200), clientfout (400), serverfout (500), enz. aan.

Voorbeeld: Een toegangscode vastleggen

Stel dat een API een token als dit retourneert:

{ "token_type":"Bearer", "expires_in": 600, "access_token":"<access_token_string>", "scope":"graph:write graph_api|r permissions|w ..." }

U kunt access_token definiëren als een uitvoerparameter en deze vervolgens doorgeven aan de volgende stap (bijv. om een andere API-aanroep te authenticeren).

Waarom is de Response Body nodig?

De Response Body is typisch waar de API de belangrijkste informatie retourneert. Deze kunnen bestaan uit, maar zijn niet beperkt tot:

• ID's van nieuw aangemaakte records
• Authenticatietokens
• Queryresultaten of gegevenslading

Zonder toegang tot de response body bent u beperkt tot metadata, wat de dynamiek van uw workflow beperkt. 

We kunnen nu de access_token ophalen die beschikbaar is onder de vervolgkeuzelijst Response.

Veelvoorkomende scenario's voor foutafhandeling

Typische problemen die u kunt tegenkomen bij het werken met Uitvoerparameters:

• Fout: ongedefinieerde uitvoerparameter

  Oorzaak en oplossing: De structuur van het antwoordgedeelte is gewijzigd of genest. Bevestig het juiste JSON-pad naar het veld.

• Fout: 401 onbevoegd

  Oorzaak & Oplossing: Token ontbreekt of is verlopen. Zorg ervoor dat het token op de juiste manier wordt vastgelegd en doorgegeven.

• Fout: 500 Interne Serverfout

  Oorzaak & Oplossing: Serverprobleem of ongeldige payload. Raadpleeg het antwoordgedeelte voor meer context.

• Fout: Ongeldige JSON

  Oorzaak & Oplossing: De API retourneert een misvormde respons. Gebruik een Try-Catch blok of valideer de uitvoer voordat u deze parseert.

Wat is een Bearer Token en waarom is het nodig?

Een Bearer Token is een type toegangstoken dat gebruikt wordt in OAuth 2.0-verificatie. Het machtigt een gebruiker of toepassing om toegang te krijgen tot een API. Het wordt "Bearer" genoemd omdat u het token "draagt" in de header van uw HTTP-verzoek.

Voorbeeld kopregel:

Autorisatie: Bearer <access_token&gt

Dit token is veiliger dan basisauthenticatie omdat:

• Het verloopt, waardoor het risico van tokenlekken kleiner wordt.
• Het kan scopes en machtigingen dragen.
• Het scheidt authenticatie van autorisatie.

Waarom gebruikt u niet gewoon Basic Authentication?

Terwijl Basic Auth een gebruikersnaam en wachtwoord gecodeerd in elk verzoek verzendt:

• Is minder veilig - referenties kunnen hergebruikt of onderschept worden.
• Kan de toegang niet gemakkelijk verlopen of beperken.
• Ontbreekt aan token-gebaseerde toegangscontrole.

Tokens met drager ondersteunen het verlopen en vernieuwen van tokens en granulaire machtigingen, waardoor ze een betere keuze zijn voor moderne API's en beveiliging op bedrijfsniveau.