Een aangepaste connector maken op basis van een OpenAPI-definitie

Notitie

Dit onderwerp maakt deel uit van een reeks zelfstudies over het maken en gebruiken van aangepaste connectors in Azure Logic Apps, Microsoft Power Automate en Microsoft Power Apps. Zorg ervoor dat u het overzicht van aangepaste connectors leest om het proces te begrijpen.

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

Ga naar 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. 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 een aangepaste connector biedt geen ondersteuning voor clientreferenties (bijvoorbeeld toepassing en wachtwoord) in de OAuth-beveiligingsdefinitie.

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

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

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 connector voor Azure Logic Apps maken.

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

   

3. Selecteer onder Algemeen de optie Een OpenAPI-bestand uploaden en navigeer vervolgens naar de OpenAPI-definitie die u hebt gemaakt.

   

Notitie

Deze zelfstudie richt zich op een REST API, maar u kunt ook gebruikmaken van een SOAP API met Logic Apps.

De OpenAPI-definitie voor Power Automate en Power Apps importeren

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

2. Selecteer in het linkerdeelvenster Gegevens > Aangepaste connectors.

   

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	Waarde
   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 boven in 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

   Ga voor meer informatie over het maken van verbinding met on-premises API's naar 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 wordt opgegeven 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 selecteren 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 wizard voor aangepaste connectoren biedt u veel opties om te definiëren hoe uw connector werkt en hoe deze wordt weergegeven in Logic 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 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: wordt altijd eerst voor de gebruiker weergegeven

     

3. Het gebied Aanvraag bevat informatie 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 bekijken de parameter hoofdtekst hieronder nog eens nader.

   

   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. Het gebied Respons bevat informatie 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 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"
   }
   

   Deze sectie toont de twee waarden die door de connector worden geretourneerd: id en score. De sectie bevat de bijbehorende gegevenstypen en het veld x-ms-summary, een OpenAPI-extensie. Ga voor meer informatie over deze en andere extensies naar Een OpenAPI-definitie uitbreiden voor een aangepaste connector.

5. In het gebied Validatie worden eventuele problemen weergegeven die zijn gedetecteerd in de API-definitie. Controleer dit gebied 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. Selecteer 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. Selecteer Id en selecteer vervolgens Bewerken.

   

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

   

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

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

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

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. Op de pagina Testen selecteert u Nieuwe verbinding.

   

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

   

3. Ga terug naar het tabblad Testen en voer een van de volgende handelingen uit:

   • In Power Automate wordt u teruggeleid naar de pagina Testen. Selecteer 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 het tandwielpictogram in de rechterbovenhoek en selecteer daarna 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). Selecteer 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 of ervoor zorgen dat de connector wordt gecertificeerd zodat personen buiten de organisatie deze kunnen gebruiken.

• Uw connector delen
• Uw connector certificeren

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Om feedback te geven, gaat u naar Problemen melden of hulp krijgen met connectoren en selecteer uw feedbacktype.