Delen via

Een aangepaste connector maken op basis van een OpenAPI-definitie

  • Artikel

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 OpenAPI-definitie die de Cognitive Services Text Analytics Sentiment-API beschrijft (ons voorbeeld voor deze serie).

Voor een andere manier om een API te beschrijven, gaat u naar Een aangepaste connector helemaal zelf maken.

Vereisten

  • Een OpenAPI definitie die de voorbeeld-API beschrijft. Wanneer u een aangepaste connector maakt, moet de OpenAPI-definitie kleiner zijn dan 1 MB. De OpenAPI-definitie moet in de OpenAPI 2.0-indeling (voorheen bekend als Swagger) zijn.

    Als er meerdere beveiligingsdefinities zijn, kiest de aangepaste connector de hoogste beveiligingsdefinitie. Het maken van aangepaste connectoren ondersteunt geen clientreferenties (bijvoorbeeld applicatie en wachtwoord) in de OAuth beveiligingsdefinitie.

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

  • Een van de volgende abonnementen:

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

De OpenAPI-definitie importeren

U bent nu klaar om te werken met de OpenAPI-definitie die u hebt gedownload. Alle vereiste informatie is opgenomen in de definitie en u kunt deze informatie bekijken en bijwerken terwijl u de wizard voor aangepaste connectors doorloopt.

Begin met het importeren van de OpenAPI definitie voor Logic Apps, of voor Power Automate en Power Apps.

Notitie

Een OpenAPI-definitie moet in de OpenAPI 2.0-indeling (voorheen bekend als Swagger) zijn. OpenAPI-definities in de OpenAPI 3.0-indeling worden niet ondersteund.

De OpenAPI-definitie importeren voor Logic Apps

  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. Selecteer in het menu van uw connector Logic Apps Connector en selecteer vervolgens Bewerken.

    Bewerk de Logic Apps-connector.

  3. Selecteer onder Algemeen de optie Een bestand uploaden OpenAPI en ga vervolgens naar dedefinitie die u hebt gemaakt. OpenAPI

    Upload het OpenAPI-bestand.

Notitie

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

De OpenAPI-definitie voor Power Automate en Power Apps importeren

  1. Meld u aan bij Power Apps of Power Automate.

  2. Selecteer in het linkerdeelvenster Gegevens>Aangepaste connectoren.

  3. Selecteer Nieuwe aangepaste connector en selecteer vervolgens Een OpenAPI bestand importeren.

  4. Voer een naam in voor de aangepaste connector, ga naar de OpenAPI definitie die u hebt gedownload of gemaakt en selecteer vervolgens Doorgaan.

    Upload een collectie.

    Parameter Weergegeven als
    Aangepaste connectortitel SentimentDemo

Algemene details bekijken

Vanaf dit punt laten we u de gebruikersinterface van Power Automate zien, maar de stappen zijn grotendeels hetzelfde voor alle drie de technologieën. We zullen eventuele verschillen aangeven. In dit deel van het onderwerp kijken we voornamelijk naar de gebruikersinterface en laten we zien hoe de waarden overeenkomen met secties van het OpenAPI-bestand.

  1. Controleer bovenaan de wizard of de naam is ingesteld op SentimentDemo en selecteer vervolgens Connector maken.

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

    Pagina Algemeen - Aangepaste connector.

    Notitie

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

    De volgende sectie van de OpenAPI-definitie bevat informatie voor deze pagina van de gebruikersinterface:

      "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ]

Type verificatie bekijken

Er zijn verschillende opties voor verificatie beschikbaar in aangepaste connectors. De Cognitive Services-API's gebruiken API-sleutelverificatie, dus dat is wat wordt opgegeven in de OpenAPI-definitie.

Controleer op de pagina Beveiliging de authenticatiegegevens voor de API-sleutel.

Parameters voor API-sleutel.

Het label wordt weergegeven wanneer iemand voor het eerst verbinding maakt met de aangepaste connector. U kunt Bewerken selecteren en deze waarde wijzigen. De parameternaam en -locatie moeten overeenkomen met wat de API verwacht, in dit geval Ocp-Apim-Subscription-Key en Header.

De volgende sectie van de OpenAPI-definitie bevat informatie voor deze pagina van de gebruikersinterface:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

De connectordefinitie bekijken

Op de pagina Definitie van de wizard voor aangepaste connectoren vindt u veel opties voor het definiëren van de werking van uw connector en hoe deze wordt weergegeven in logische apps, stromen en apps. We zullen de gebruikersinterface uitleggen en een paar opties in dit gedeelte behandelen, maar we raden u ook aan om deze zelf te verkennen. Ga naar De connectordefinitie maken voor informatie over het vanaf nul definiëren van objecten in deze gebruikersinterface.

  1. In het volgende 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 DetectSentiment actie uit de OpenAPI definitie weergegeven. 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.

    Pagina Definitie - Acties en triggers.

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

    • geen: wordt normaal weergegeven in de logische app of stroom

    • geavanceerd: verborgen onder een extra menu

    • intern: verborgen voor de gebruiker

    • belangrijk: wordt altijd als eerste aan de gebruiker getoond

      Pagina Definitie - Algemeen

  3. In het gebied Aanvraag wordt informatie weergegeven op basis van de HTTP-aanvraag die is opgenomen in de OpenAPI definitie. In dit geval ziet u dat het HTTP-werkwoord POST 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 straks dieper in op de body parameter.

    Pagina Definitie - Aanvraag.

    Het volgende gedeelte van de definitie bevat informatie voor de algemene gebieden en de aanvraaggebieden van de gebruikersinterface: OpenAPI 

    "paths": {
  "/text/analytics/v2.0/sentiment": {
    "post": {
      "summary": "Returns a numeric score representing the sentiment detected",
      "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
      "operationId": "DetectSentiment"

  4. In het gebied Response wordt informatie weergegeven op basis van het HTTP-antwoord dat is opgenomen in de OpenAPI definitie. In dit geval is het enige gedefinieerde antwoord 200 (een succesvol antwoord), maar u kunt aanvullende antwoorden definiëren.

    Pagina Definitie - Respons.

    De volgende sectie van de OpenAPI-definitie bevat enige informatie met betrekking tot de respons:

    "score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}

    In deze sectie worden de twee waarden weergegeven die door de connector worden geretourneerd: id en score. Het omvat hun gegevenstypen en het veld x-ms-summary, wat een OpenAPI extensie is. Ga naar Een definitie voor een aangepaste connector uitbreiden OpenAPI voor meer informatie over deze en andere extensies.

  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.

    Pagina Definitie - Validatie.

De definitie bijwerken

De OpenAPI-definitie die u hebt gedownload, is een eenvoudig voorbeeld. Het is echter ook mogelijk dat u werkt met definities die vaak moeten worden bijgewerkt. Hiervoor is het handig als duidelijk wordt aangegeven waarvoor de connector is bedoeld als iemand deze wil gebruiken in een logische app, stroom of app. We laten u zien hoe u een eenvoudige wijziging in de definitie aanbrengt.

  1. Selecteer in het gebied Aanvraag de optie body en selecteer vervolgens Bewerken.

    Bewerk de hoofdtekst van de aanvraag.

  2. In het gebied Parameter ziet u nu de drie parameters die de API verwacht: ID, Language en Text. Selecteer ID en selecteer vervolgens Bewerken.

    Bewerk de id van hoofdtekst van de aanvraag.

  3. Werk in het gebied Schema-eigenschap de beschrijving voor de parameter bij en selecteer vervolgens Terug.

    Bewerk de schema-eigenschap.

    Parameter Waarde
    Beschrijving Een numerieke id voor elk document dat u verzendt

  4. Selecteer in het gebied Parameter de optie Terug om terug te gaan naar de hoofdpagina met definities.

  5. Selecteer Connector bijwerken in de rechterbovenhoek van de wizard.

Het bijgewerkte OpenAPI-bestand downloaden

U kunt een aangepaste connector maken op basis van een OpenAPI-bestand of een volledig nieuwe connector maken (in Power Automate en Power Apps). Ongeacht hoe u de connector maakt, kunt u de OpenAPI-definitie downloaden die intern wordt gebruikt voor de service.

  • In Logic Apps kunt u downloaden vanuit de aangepaste connector.

    Download de OpenAPI-definitie voor Logic Apps.

  • Voer in Power Automate of Power Apps een download uit vanuit de lijst met aangepaste connectors.

    Download de OpenAPI-definitie voor Power Automate.

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. Selecteer op de pagina Test de optie Nieuwe verbinding.

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

  3. Ga terug naar de Testpagina en voer een van de volgende handelingen uit:

    • In Power Automate wordt u teruggeleid naar de Test pagina. Selecteer het pictogram Vernieuwen om ervoor te zorgen dat de verbindingsgegevens worden bijgewerkt.

      Verbinding vernieuwen.

    • 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 selecteer vervolgens Aangepaste connectoren. Kies de connector die u hebt gemaakt en ga terug naar de Test pagina.

      Tandwielpictogram in service.

  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 selecteer vervolgens Testbewerking.

    Testbewerking.

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

    Respons van connector.

Gebruik de aangepaste connector

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

Maak een aangepaste connector en connectoractie voor Microsoft 365 Copilot voor Sales

U kunt een aangepaste connector maken op basis van een OpenAPI definitie in Power Apps of Power Automate die vervolgens kan worden gebruikt voor Microsoft 365 Copilot for Sales. Ga naar Een aangepaste connector en connectoractie maken om te leren hoe u aan de slag kunt.

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

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.