Een aangepaste connector maken op basis van een OpenAPI-definitie

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).

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

• Een aangepaste connector maken op basis van een Postman-verzameling
• Een volledig nieuwe aangepaste connector maken

Vereisten

• Een OpenAPI-definitie die de voorbeeld-API beschrijft. Bij het maken van een aangepaste connector moet de OpenAPI-definitie kleiner zijn dan 1 MB. De OpenAPI-definitie moet de OpenAPI 2.0-indeling hebben (voorheen bekend als Swagger).
• 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, gaat u eerst naar Een aangepaste connector voor Azure Logic Apps 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 door de OpenAPI-definitie voor Logic Apps of voor Power Automate en Power Apps te importeren.

De OpenAPI-definitie voor Logic Apps importeren

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

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

   

3. Kies onder Algemeen de optie Een OpenAPI-definitie uploaden en navigeer vervolgens naar het OpenAPI-bestand dat u hebt gemaakt.

   

De OpenAPI-definitie voor Power Automate en Power Apps importeren

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

2. Selecteer Gegevens > Aangepaste connectors in het navigatiedeelvenster.

   

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

   

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

   

   Parameter	Weergegeven als
   Aangepaste connectortitel	"Gevoelsdemo"

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 zullen we voornamelijk de gebruikersinterface bekijken en u laten zien hoe de waarden overeenkomen met secties van het OpenAPI-bestand.

1. Controleer boven aan de wizard of de naam is ingesteld op "Gevoelsdemo" en kies vervolgens Connector maken.

2. Controleer op de pagina Algemeen de gegevens die zijn geïmporteerd uit de OpenAPI-definitie, met inbegrip van 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.

   

   Notitie

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

   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 is gespecificeerd in de OpenAPI-definitie.

Bekijk op de pagina Beveiliging de verificatiegegevens voor de API-sleutel.

Het label wordt weergegeven wanneer iemand voor het eerst verbinding maakt met de aangepaste connector. U kunt Bewerken kiezen en deze waarde wijzigen. De naam en locatie van de parameter 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

De pagina Definitie van de aangepaste connector 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. Zie De connectordefinitie maken voor informatie over het helemaal opnieuw 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 actie DetectSentiment uit de OpenAPI-definitie weergegeven. Deze connector bevat geen triggers, maar in Een webhook gebruiken voor Azure Logic Apps en Power Automate kunt u meer leren over triggers voor aangepaste connectors.

   

2. Het gebied Algemeen bevat informatie over de actie of trigger die momenteel is geselecteerd. U kunt de informatie hier bewerken, met inbegrip van 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 in een aanvullend menu

   • intern: verborgen voor de gebruiker

   • belangrijk: altijd eerst voor de gebruiker weergegeven

     

3. In het gebied Aanvraag wordt informatie weergegeven op basis van de HTTP-aanvraag die is opgenomen in de OpenAPI-definitie. In dit geval is het HTTP-werkwoord POST 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 de parameter hoofdtekst kort nader bekijken.

   

   De volgende sectie van de OpenAPI-definitie bevat informatie voor de gebieden Algemeen en Aanvraag van de gebruikersinterface:

   "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 Respong wordt informatie weergegeven op basis van de HTTP-respons die is opgenomen in de OpenAPI-definitie. In dit geval is er alleen een antwoord gedefinieerd voor '200' (een geslaagd antwoord), maar u kunt aanvullende antwoorden definiëren.

   

   De volgende sectie van de OpenAPI-definitie bevat enige informatie die verband houdt met de respons:

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

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

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

   

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. Kies in het gebied Aanvraag de optie hoofdtekst en vervolgens Bewerken.

   

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

   

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

   

   Parameter	Weergegeven als
   Beschrijving	"Een numerieke id voor elk document dat u verzendt"

4. Kies Vorige in het gebied Parameter om terug te gaan naar de hoofdpagina van de definitie.

5. Kies rechtsboven in de wizard de optie Connector bijwerken.

Het bijgewerkte OpenAPI-bestand bijwerken

U kunt een aangepaste connector maken op basis van een OpenAPI-bestand of een Postman-verzameling, maar u kunt er ook voor kiezen om het helemaal zelf te doen (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.

  

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

  

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.

1. Kies Nieuwe verbinding op de pagina Testen.

   

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

   

3. Ga terug naar de Testpagina:

   • In Microsoft Flow wordt u teruggeleid naar de pagina Testen. 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. Kies het tandwielpictogram in de rechterbovenhoek en kies vervolgens Aangepaste connectors. Kies de connector die u hebt gemaakt en ga vervolgens terug naar de pagina Testen.

     

4. Voer op de pagina Testen een waarde in het veld tekst in (de andere velden hebben de standaardwaarden die u eerder hebt ingesteld). Kies vervolgens Testbewerking.

   

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

   

Volgende stappen

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

• Een aangepaste connector gebruiken vanuit een stroom
• Een aangepaste connector gebruiken vanuit een app
• Een aangepaste connector gebruiken vanuit 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.

• Uw connector delen
• Uw connector certificeren