Delen via

HTTP-aanvragen maken

  • Artikel

In Copilot Studio kunt u de mogelijkheden van een copilot uitbreiden door externe REST API's aan te roepen met behulp van het knooppunt HTTP-aanvraag. Deze aanroep kan handig zijn wanneer u gegevens van een extern systeem moet ophalen of gegevens op dat systeem moet bewerken.

Vereisten

Het knooppunt HTTP-aanvraag gebruiken

  1. Selecteer Knooppunt toevoegen (+), open het submenu Geavanceerd en selecteer vervolgens HTTP-aanvraag verzenden.

    Schermopname van de optie HTTP-aanvraag verzenden in het menu Geavanceerd.

  2. Voer in het vak URL de URL in van het API eindpunt dat u wilt aanroepen.

  3. Selecteer de juiste methode voor de aanvraag in de vervolgkeuzelijst. De methoden GET, POST, PATCH, PUT en DELETE worden ondersteund.

    Schermopname van de voltooide API-URL en vervolgkeuzelijst met methoden

  4. Selecteer onder Headers en hoofdtekst op het knooppunt de knop Bewerken om het deelvenster Eigenschappen van HTTP-aanvraag te openen.

  5. U kunt optioneel een of meer kopteksten toevoegen aan de HTTP-aanvraag. Selecteer de knop Toevoegen om de sleutel en waarde van elke header toe te voegen.

    Schermopname van de lijst met sleutel-waardeparen voor kopteksten voor HTTP-knooppunt.

  6. Standaard wordt er geen inhoud verzonden in de hoofdtekst van de HTTP-aanvraag, maar u kunt inhoud in de hoofdtekst opgeven.

  7. Kies op het knooppunt het responsgegevenstype uit de beschikbare opties.

    U kunt een voorbeeld-JSON-respons opgeven. Deze kunt u doorgaans vinden in de documentatie voor de API die u aanroept. Het genereert een Power Fx-variabele, zodat u deze elders in uw ontwerpcanvas kunt gebruiken, met Intellisense-ondersteuning in de Power Fx-editor. Selecteer Uit voorbeeldgegevens en vervolgens Schema ophalen uit voorbeeld-JSON. Plak uw voorbeeldrespons in de editor en selecteer Bevestigen.

    Schermopname van vanhet Get-schema uit de voorbeeld-JSON-editor.

  8. Kies onder Respons opslaan als waar u de respons op de HTTP-aanvraag wilt opslaan, door een nieuwe variabele te maken of een bestaande variabele te selecteren.

Inhoud verzenden in de HTTP-aanvraagbody

  1. Selecteer onder Headers en hoofdtekst op het knooppunt de knop Bewerken om het deelvenster Eigenschappen van HTTP-aanvraag te openen.

  2. Selecteer onder Hoofdtekst het juiste inhoudstype. Standaard is Hoofdtekst ingesteld op Geen inhoud, wat betekent dat er geen inhoud aanwezig mag zijn in de aanvraagbody, wat meestal wordt gebruikt bij GET-aanvragen. Als u inhoud aan de hoofdtekst wilt toevoegen, selecteert u een van de beschikbare opties.

    Schermopname van de vervolgkeuzelijst met opties voor hoofdinhoud

    • JSON-inhoud: met JSON-inhoud kunt u een JSON-object opgeven in de hoofdtekst van de aanvraag. Dit object wordt vaak gebruikt bij het maken van POST- of PUT-aanvragen. Wanneer deze optie is geselecteerd, kunt u via een editor uw JSON-inhoud invoeren.

      U kunt uw JSON-inhoud ook opgeven met Power Fx, zodat u dynamische waarden en referentievariabelen kunt opnemen. Selecteer de knop JSON bewerken, kies Formule en voer vervolgens een Power Fx-object in (elke bestaande JSON die is ingevoerd, wordt voor u omgezet in een Power Fx-object). Dit object wordt omgezet in JSON wanneer de HTTP-aanvraag wordt gedaan.

      Schermopname van JSON-inhoud geselecteerd voor inhoudstype hoofdtekst.

    • Onbewerkte inhoud: met onbewerkte inhoud kunt u een reeks gegevens in de hoofdtekst van de aanvraag invoegen, en deze tekenreeks kan elke inhoudstype zijn die u opgeeft. Onbewerkte inhoud wordt ingevoerd met behulp van een Power Fx-formule, zoals de tekenreeksinhoud in het volgende voorbeeld.

      Schermopname van RAW-inhoud geselecteerd voor inhoudstype hoofdtekst.

Foutafhandeling en time-out

Het knooppunt HTTP-aanvraag heeft meerdere opties voor het afhandelen van situaties waarin de HTTP-aanvraag mislukt of een fout retourneert.

Standaard genereert de functie een fout. Dit betekent dat wanneer een HTTP-aanvraag een fout retourneert of niet kan worden uitgevoerd, de copilot de bewerking stopt en het systeemonderwerp Fout activeert, waarbij een foutmelding wordt weergegeven.

U kunt de foutverwerking echter zo configureren dat het systeemonderwerp Fout niet wordt geactiveerd. In plaats daarvan worden de HTTP-statuscode en eventuele tekst van de foutrespons ingevuld in variabelen die u opgeeft. Zo kunt u deze variabelen indien nodig opvragen en kan het onderwerp actief blijven. Deze configuratie is handig in scenario's waarin u wilt dat de copilot blijft werken, zelfs als een bepaalde HTTP-aanvraag mislukt.

Het foutafhandelingsgedrag configureren.

  1. Selecteer onder Headers en hoofdtekst op het knooppunt de knop Bewerken om het deelvenster Eigenschappen van HTTP-aanvraag te openen.

  2. Kies het gewenste gedrag in de vervolgkeuzelijst Foutafhandeling.

  3. Als u Doorgaan bij fout kiest, configureert u de variabelen Statuscode en Tekst van foutreactie, door nieuwe variabelen te maken of bestaande variabelen uit de kiezer te selecteren.

    Schermopname van de foutafhandeling die is geconfigureerd om door te gaan bij een fout, met variabelen die zijn opgegeven voor de statuscode en de hoofdtekst van de foutreactie.

Als de HTTP-aanvraag in dit codevoorbeeld mislukt, slaat de copilot de HTTP-statuscode op in de variabele Topic.StatusCode en de antwoordtekst in de variabele Topic.ErrorResponse. De copilot gaat verder met de volgende stappen in het onderwerp.

Het variabeletype Foutrespons is Elke. U kunt het knooppunt Waarde parseren gebruiken om deze variabele om te zetten in een Power Fx-record.

Het eigenschappenvenster bevat ook een eigenschap Time-out voor aanvraag, die een waarde in milliseconden accepteert. De standaardwaarde is 30 seconden, maar u kunt deze waarde indien nodig wijzigen.