Een volledig nieuwe aangepaste connector maken

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 vervaardigt u een compleet nieuwe aangepaste connector zonder gebruik te maken van een Postman-verzameling of een OpenAPI-definitie voor het beschrijven van de Cognitive Services Text Analytics Sentiment API (ons voorbeeld voor deze serie). In plaats daarvan beschrijft u de connector volledig in de wizard voor aangepaste connectors.

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

• Een aangepaste connector maken op basis van een OpenAPI-definitie
• Een aangepaste connector maken op basis van een Postman-verzameling

Vereisten

• Een API-sleutel voor de Cognitive Services Text Analytics-API
• Gebruik een van de volgende abonnementen:
  • Power Automate
  • Power Apps

De wizard voor aangepaste connectors starten

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

2. Selecteer Gegevens > Aangepaste connectors in het navigatiedeelvenster.

   

3. Selecteer Nieuwe aangepaste connector en kies vervolgens Leeg item maken.

   

4. Voer een naam in voor de aangepaste connector en selecteer vervolgens Doorgaan.

   

   Parameter	Weergegeven als
   Aangepaste connectortitel	"Gevoelsdemo"

Stap 1: Algemene details bijwerken

Vanaf dit punt laten we u de gebruikersinterface van Power Automate zien, maar de stappen zijn grotendeels hetzelfde voor alle technologieën. We zullen eventuele verschillen aangeven.

1. Op de pagina Algemeen:

   • Geef een relevante waarde op voor Beschrijving. Deze beschrijving wordt weergegeven in de gegevens van de aangepaste connector en kan andere gebruikers helpen om te bepalen of de connector nuttig voor hen kan zijn.

   • Werk Host bij naar het adres voor de Text Analytics API. De connector maakt gebruik van de API-host en de basis-URL om te bepalen hoe de API moet worden aangeroepen.

   

   Parameter	Weergegeven als
   Beschrijving	"Gebruikt de Cognitive Services Text Analytics Sentiment API om te bepalen of tekst positief of negatief is"
   Host	"westus.api.cognitive.microsoft.com"

   Notitie

   Zie Verbinden met on-premises API's via de gegevensgateway voor meer informatie over de optie Verbinden via on-premises gegevensgateway.

Stap 2: Het type verificatie opgeven

Er zijn verschillende opties voor verificatie beschikbaar in aangepaste connectors. De Cognitive Services-API's gebruiken API-sleutelverificatie, dus dat is wat u opgeeft in deze zelfstudie.

1. Kies op de pagina Beveiliging bij Verificatietype de optie API-sleutel.

   

2. Geef bij API-sleutel een label, naam en locatie op voor de parameter. Zorg dat u een duidelijk label opgeeft, omdat dit label wordt weergegeven wanneer iemand de eerste keer verbinding maakt met de aangepaste connector. De parameternaam en locatie moeten overeenkomen met wat de API verwacht. Kies Verbinding maken.

   

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

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

Stap 3: De connectordefinitie maken

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 deze sectie behandelen, maar we raden u ook aan om deze zelf te verkennen.

Een actie maken

Het eerste dat u moet doen, is een actie maken die de Text Analytics Sentiment API aanroept.

1. Op het linkergedeelte van de pagina Definitie worden alle acties, triggers (voor Logic Apps en Power Automate) en referenties weergegeven die zijn gedefinieerd voor de connector. Kies Nieuwe actie.

   

   Deze connector bevat geen triggers. Meer informatie over triggers voor aangepaste connectoren vindt u in Webhooks gebruiken met Azure Logic Apps en Power Automate.

2. Het gebied Algemeen bevat informatie over de actie of trigger die momenteel is geselecteerd. Voeg een samenvatting, beschrijving en bewerkings-id toe voor deze actie.

   

   Parameter	Weergegeven als
   Samenvatting	"Geeft een numerieke score als resultaat die het gedetecteerde gevoel aangeeft"
   Beschrijving	"De API retourneert een numerieke score tussen 0 en 1." Scores dicht bij 1 duiden op een positief gevoel en scores dicht bij 0 op een negatief gevoel."
   Bewerkings-id	"DetectSentiment"

   Laat de eigenschap Zichtbaarheid ingesteld op geen. Deze eigenschap voor bewerkingen en parameters in een logische app of stroom heeft de volgende opties:

   • geen: wordt normaal weergegeven in de logische app of stroom
   • geavanceerd : verborgen onder een ander 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 voor de actie. Kies Importeren uit voorbeeld.

   

4. Geef de informatie op die nodig is om verbinding te maken met de API en de aanvraagbody en selecteer vervolgens Importeren. Wij verstrekken deze informatie voor u (onder de afbeelding). Voor een openbare API haalt u deze meestal uit de documentatie, zoals Text Analytics Sentiment API.

   

   Parameter	Weergegeven als
   Bewerking	"POST"
   URL	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Tekst	Zie hieronder

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. In het gebied Respons wordt informatie weergegeven op basis van de HTTP-respons voor de actie. Kies Standaardantwoord toevoegen.

   

6. Geef de responstekst op en kies vervolgens Importeren. Net als bij de aanvraag verstrekken wij deze informatie voor u, maar deze staat meestal in de API-documentatie.

   

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

7. In het gebied Validatie worden eventuele problemen weergegeven die zijn gedetecteerd in de API-definitie. Controleer de status en kies vervolgens in de rechterbovenhoek van de wizard de optie Connector bijwerken.

   

De definitie bijwerken

Nu gaan we een aantal dingen wijzigen, zodat de connector handiger is wanneer iemand deze gebruikt in een logische app, stroom of app.

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 waarden voor de parameter bij en kies vervolgens Vorige.

   

4. Kies in het gebied Parameter de opties taal en Bewerken en herhaal vervolgens het proces dat u voor id hebt gebruikt met de volgende waarden.

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

5. Kies in het gebied Parameter de opties tekst en Bewerken en herhaal vervolgens het proces dat u voor id en language hebt gebruikt met de volgende waarden.

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

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

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

Stap 4: (Optioneel) gebruik ondersteuning voor aangepaste code

Aangepaste code transformeert payloads voor aanvragen en antwoorden buiten het bereik van bestaande beleidssjablonen. Transformaties omvatten het verzenden van externe aanvragen voor het ophalen van aanvullende gegevens. Wanneer code wordt gebruikt, heeft deze voorrang op de codeloze definitie. Dit betekent dat de code wordt uitgevoerd en dat we de aanvraag niet naar de back-end sturen.

U kunt uw code plakken of een bestand met uw code uploaden. Uw code moet aan de volgende vereisten voldoen:

• Geschreven zijn in C#.
• Een maximale uitvoeringstijd van 5 seconden hebben.
• Mag niet groter zijn dan 1 MB (grootte van het codebestand).

Ga voor instructies en voorbeelden van het schrijven van code naar Code schrijven in aangepaste connectoren.

Ga voor veelgestelde vragen over aangepaste code naar Veelgestelde vragen over aangepaste code.

1. Voer op de codepagina uw aangepaste code in met een van de volgende opties:

   • Kopiëren/plakken of
   • Selecteer de knop Uploaden.

   Als u ervoor kiest om uw aangepaste code te uploaden, zijn alleen bestanden met de extensie .cs of .csx beschikbaar.

   
   

   Belangrijk

   Momenteel ondersteunen we alleen syntaxismarkering in de code-editor. Zorg ervoor dat u uw code lokaal test.

2. Selecteer, nadat u uw code hebt geplakt of geüpload, de schakelaar naast Code uitgeschakeld om uw code in te schakelen. De naam van de schakelaar verandert in Code ingeschakeld.

   U kunt uw code op elk moment in- of uitschakelen. Als de schakelaar op Code uitgeschakeld staat, wordt uw code verwijderd.

   

3. Selecteer de acties en triggers die u op uw aangepaste code wilt toepassen door een optie in de vervolgkeuzelijst te selecteren. Als er geen bewerking is geselecteerd, wordt deze toegepast op alle bewerkingen.

   

Stap 5: 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 Power Automate 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 Gegevens > Aangepaste connectors in het navigatiedeelvenster. 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.

   

(Voor CLI-gebruikers) Aanbevolen procedures

• Download al uw connectoren en gebruik git of een ander broncodebeheersysteem om de bestanden op te slaan.

• In het geval van een onjuiste update, implementeert u de connector opnieuw door de bijwerkopdracht opnieuw uit te voeren met de juiste set bestanden van het broncodebeheersysteem.

• Test de aangepaste connector en het instellingenbestand in een testomgeving voordat u deze implementeert in de productieomgeving.

• Controleer altijd goed of de omgevings- en connector-id juist zijn.

Volgende stappen

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

• Een stroom
• Een app
• Een Logic 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