Een aangepaste connector maken op basis van een Postman-verzameling

Notitie

Dit artikel is onderdeel van een zelfstudiereeks over het maken en gebruiken van aangepaste connectors in Azure Logic Apps, Microsoft Power Automate en Microsoft Power Apps en het gebruiken van AI-connectors in Microsoft Copilot Studio. Zorg ervoor dat u het overzicht van de aangepaste connector leest om het proces te begrijpen. Ga naar gebruik Power Platform connectors in Copilot Studio om te leren hoe u de connectors als connectoracties in uw Microsoft Copilot agent kunt aanroepen.

Als u een aangepaste connector wilt maken, beschrijft u de API waarmee u verbinding wilt maken, zodat de connector de bewerkingen en gegevensstructuren van de API begrijpt. In dit onderwerp maakt u een aangepaste connector met behulp van een Postman-verzameling die de Cognitive Services Text Analytics Sentiment API beschrijft (ons voorbeeld voor deze reeks).

Ga naar de volgende onderwerpen voor andere manieren om een API te beschrijven:

• Maak een aangepaste connector van een OpenAPI definitie

• Maak een aangepaste connector vanaf nul

Voorwaarden

Controleer alle vereisten zodat u zeker weet dat u over de benodigde informatie beschikt om een aangepaste connector te maken. U hebt het volgende nodig:

• Een Postman-verzameling die de voorbeeld-API beschrijft. U hebt twee opties:

  • Download de Postman-collectie die we hebben gemaakt.
    or
  • Rond het onderwerp af Een Postman-verzameling maken voor een aangepaste connectorHoud er rekening mee dat bij het maken van een aangepaste connector de Postman-verzameling niet groter mag zijn dan 1 MB.

• Een API-sleutel voor de Cognitive Services Text Analytics API.

• Gebruik een van de volgende abonnementen:

  • Azure, als u Logic Apps gebruikt
  • Power Automate
  • Power Apps

• Als u Logic Apps gebruikt, moet u eerst een aangepaste Azure Logic Apps-connector maken.

De Postman-verzameling importeren

U bent nu klaar om te werken met de Postman-collectie die u hebt gemaakt of gedownload. Een groot deel van de vereiste informatie is opgenomen in de verzameling. U kunt deze informatie ook bekijken en bijwerken terwijl u de wizard voor aangepaste connectors doorloopt. Begin met het importeren van de Postman-collectie voor Logic Apps, of voor Power Automate en Power Apps.

De Postman-verzameling voor Logic Apps importeren

1. Ga naar de Azure-portal en open de Logic Apps-connector die u eerder hebt gemaakt in Een aangepaste Azure Logic Apps-connector maken.

2. Kies in het menu van uw connector de optie Logic Apps Connector en kies vervolgens Bewerken.

   

3. Kies onder Algemeen de optie Postman-collectie V1 uploaden en navigeer vervolgens naar de Postman-collectie die u hebt gemaakt.

   

   De wizard importeert de verzameling en converteert deze vervolgens naar een OpenAPI definitie met de naam generatedApiDefinition.swagger.json.

Notitie

In deze tutorial ligt de nadruk op een REST API, maar u kunt ook een SOAP API gebruiken met Logic Apps.

De Postman-verzameling voor Power Automate en Power Apps importeren

1. Ga naar make.powerapps.com of flow.microsoft.com.

2. Selecteer in het navigatiedeelvenster Gegevens > Aangepaste connectoren.

3. Kies Nieuwe aangepaste connector en kies vervolgens Postman-collectie importeren.

4. Voer een naam in voor de aangepaste connector, navigeer naar de Postman-verzameling die u hebt gedownload of gemaakt en kies Doorgaan.

   

   Parameter	Waarde
   Aangepaste connectortitel	"SentimentDemo"

   De wizard importeert de verzameling en converteert deze vervolgens naar een OpenAPI definitie met de naam generatedApiDefinition.swagger.json.

Algemene details bijwerken

Vanaf dit punt laten we u de gebruikersinterface van Power Automate zien, maar de stappen zijn grotendeels hetzelfde voor alle drie de technologieën. Eventuele verschillen worden gemarkeerd.

1. Controleer op de pagina Algemeen de informatie die is geïmporteerd uit de Postman-verzameling, inclusief de host en de basis-URL voor de API. De connector maakt gebruik van de host en de basis-URL om te bepalen hoe de API moet worden aangeroepen.

   Notitie

   Zie Verbinding maken met on-premises API's via de gegevensgateway voor meer informatie over het verbinden met on-premises API's.

2. Wijzig de beschrijving om deze wat zinvoller te maken. Deze beschrijving wordt weergegeven in de gegevens van de aangepaste connector en maakt aan andere gebruikers duidelijk op welke manier de connector nuttig voor hen kan zijn.

   Parameter	Weergegeven als
   Omschrijving	"Gebruikt de Cognitive Services Text Analytics Sentiment API om te bepalen of tekst positief of negatief is"

Type verificatie opgeven

Er zijn verschillende opties voor verificatie beschikbaar in aangepaste connectors. De Cognitive Services-API's maken gebruik van API-sleutelverificatie.

1. Selecteer op de pagina Beveiliging onder Authenticatietype de optie API-sleutel.

2. Geef onder API-sleutel een parameterlabel, naam en locatie op. Kies een duidelijk en zinvol label. Deze tekst wordt weergegeven voor gebruikers zodat ze verbindingen kunnen maken met behulp van uw aangepaste connector. De naam en locatie van de parameter moeten overeenkomen met wat de API verwacht (in dit geval de header die u hebt opgegeven in Postman). Kies Verbinding maken.

   

   Parameter	Weergegeven als
   Parameterlabel	"API-sleutel"
   Parameternaam	"Ocp-Apim-Subscription-Key"
   Parameterlocatie	"Koptekst"

3. Controleer bovenaan de wizard of de naam is ingesteld op 'SentimentDemo' en kies vervolgens Connector maken.

De definitie van de connector controleren en bijwerken

De wizard voor aangepaste connectors biedt u een groot aantal opties om te definiëren hoe de connector functioneert en hoe deze zichtbaar wordt gemaakt in logische apps, stromen en apps. We zullen de gebruikersinterface uitleggen en een paar opties in deze sectie behandelen, maar we raden u ook aan om deze zelf te verkennen.

De gebruikersinterface en definitie controleren

Voordat we ingaan op de specifieke stappen op de pagina Definitie , bekijken we eerst de gebruikersinterface.

1. In dit gebied worden alle acties, triggers (voor Logic Apps en Power Automate) en referenties weergegeven die voor de connector zijn gedefinieerd. In dit geval wordt de actie uit de Postman-collectie weergegeven. DetectSentiment Deze connector bevat geen triggers, maar u kunt meer te weten komen over triggers voor aangepaste connectors in Webhooks gebruiken met Azure Logic Apps en Power Automate.

   

2. In het gedeelte Algemeen wordt informatie weergegeven over de actie of trigger die momenteel is geselecteerd. Deze informatie wordt opgehaald uit de Postman-verzameling. U kunt hier de informatie bewerken, inclusief de eigenschap Zichtbaarheid voor bewerkingen en parameters in een logische app of stroom:

   • belangrijk: wordt altijd als eerste aan de gebruiker getoond
   • geen: wordt normaal weergegeven in de logische app of stroom
   • geavanceerd: aanvankelijk verborgen onder een extra menu
   • intern: niet getoond aan de gebruiker

3. In het gebied Aanvraag wordt informatie weergegeven op basis van de HTTP-aanvraag die is opgenomen in de Postman-verzameling. In dit geval ziet u dat het HTTP werkwoordPOST is en de URL "/text/analytics/v2.0/sentiment" (de volledige URL naar de API is <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). We gaan binnenkort de bodyparameter nader bekijken.

4. In het gebied Response wordt informatie weergegeven op basis van het HTTP-antwoord dat is opgenomen in de Postman-verzameling. In dit geval is er alleen een antwoord gedefinieerd voor '200' (een geslaagd antwoord), maar u kunt aanvullende antwoorden definiëren.

5. In het gedeelte Validatie worden eventuele problemen weergegeven die in de API-definitie zijn gedetecteerd. Controleer dit gebied goed voordat u een connector opslaat.

De definitie bijwerken

Nu gaan we een aantal dingen wijzigen, zodat de connector handiger is wanneer iemand deze gebruikt in een Logic App, Power Automate of Power Apps.

1. Werk in het gedeelte Algemeen de samenvatting bij naar 'Geeft een numerieke score terug die het gedetecteerde sentiment weergeeft'.

2. Kies in het gedeelte Aanvraag de optie body en vervolgens Bewerken.

3. In het gebied Parameter ziet u nu de drie parameters die de API verwacht: id, language en text. Kies id en vervolgens Bewerken.

4. Werk in het gebied Schema-eigenschap de waarden voor de parameter bij en kies vervolgens Terug.

   

   Parameter	Waarde
   Title	"ID"
   Omschrijving	"Een id voor elk document dat u verzendt"
   Standaardwaarde	"1"
   Is vereist	"Ja"

5. Kies in het gebied Parameter de optie taal en vervolgens Bewerken en herhaal het proces dat u hierboven hebt gebruikt met de volgende waarden.

   Parameter	Weergegeven als
   Title	"Language"
   Omschrijving	"De taalcode van 2 of 4 tekens voor de tekst"
   Standaardwaarde	"en"
   Is vereist	"Ja"

6. Kies in het gebied Parametertekst en vervolgens Bewerken en herhaal het proces dat u hierboven hebt gebruikt met de volgende waarden.

   Parameter	Weergegeven als
   Title	"Tekst"
   Omschrijving	"De tekst die moet worden geanalyseerd op gevoel"
   Standaardwaarde	Geen
   Is vereist	"Yes"

7. In het gebied Parameter kiest u Terug om terug te gaan naar de hoofdpagina met definities.

8. Selecteer rechtsboven in de wizard de optie Connector bijwerken.

De connector testen

Nu u de connector hebt gemaakt, test u deze om te controleren of de connector juist werkt. Testen is momenteel alleen beschikbaar in Power Automate en Power Apps.

Belangrijk

Als u een API-sleutel gebruikt, raden we u aan de connector niet onmiddellijk na het maken te testen. Het kan een paar minuten duren voordat de connector gereed is om verbinding te maken met de API.

1. Kies op de Test pagina de optie Nieuwe verbinding.

2. Voer de API-sleutel van de Text Analytics API in en kies vervolgens Verbinding maken.

3. Terug naar de Testpagina:

   • In Power Automate wordt u teruggeleid naar de Test pagina. Kies het pictogram Vernieuwen om ervoor te zorgen dat de verbindingsgegevens worden bijgewerkt.
   • In Power Apps wordt u naar de lijst met verbindingen geleid die beschikbaar zijn in de huidige omgeving. Selecteer in de rechterbovenhoek het tandwielpictogram en kies vervolgens Aangepaste connectoren. Kies de connector die u hebt gemaakt en ga terug naar de Test pagina.

4. Voer op de pagina Test een waarde in voor het veld tekst (de andere velden gebruiken de standaardinstellingen die u eerder hebt ingesteld) en kies vervolgens Testbewerking.

5. De connector roept de API aan en u kunt de respons bekijken, inclusief de gevoelsscore.

   

Beperkingen

Als u in Power Automate en Power Apps een bestaande aangepaste connector bijwerkt met behulp van een Postman-verzameling, moet u eerdere aanpassingen opnieuw uitvoeren voordat u de connector opslaat. U moet bijvoorbeeld het verificatietype, de standaardwaarden van de parameters voor de acties en andere zaken opnieuw configureren.

Volgende stappen

Nu u een aangepaste connector hebt gemaakt en het gedrag van deze connector hebt gedefinieerd, kunt u de connector gaan gebruiken.

• gebruik een aangepaste connector van een stroom
• gebruik een aangepaste connector van een app
• gebruik een aangepaste connector van een logische app

U kunt een connector ook delen binnen uw organisatie en/of ervoor zorgen dat de connector wordt gecertificeerd zodat personen buiten de organisatie deze kunnen gebruiken.

• Deel uw connector
• Certificeer uw connector

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Als u feedback wilt geven, gaat u naar Problemen melden of hulp krijgen met connectoren en selecteert u het type feedback.