Delen via

Een volledig nieuwe aangepaste connector maken

  • 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 artikel maakt u een aangepaste connector vanaf nul, zonder een OpenAPI definitie te gebruiken om de sentimentbewerking van de Azure Cognitive Services Text Analytics API te beschrijven (ons voorbeeld voor deze reeks). In plaats daarvan beschrijft u de connector volledig in de wizard voor aangepaste connectors.

Voor een andere manier om een API te beschrijven, gaat u naar Een aangepaste connector maken op basis van een OpenAPI definitie.

Notitie

U kunt momenteel een compleet nieuwe aangepaste connector maken in Power Automate en Power Apps. Voor Logic Apps moet u beginnen met ten minste een basis OpenAPI -definitie.

Vereisten

De wizard voor aangepaste connectors starten

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

  2. Selecteer in het linkerdeelvenster Gegevens>Aangepaste connectoren.

  3. Selecteer Nieuwe aangepaste connector>Maken van blanco.

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

    Parameter Weergegeven als
    Aangepaste connectortitel SentimentDemo

Stap 1: Algemene details bijwerken

Vanaf dit punt laten we de gebruikersinterface zien, maar de stappen zijn voor alle technologieën grotendeels hetzelfde. Power Automate Eventuele verschillen wijzen wij u erop.

Op het tabblad Algemeen hebt u de volgende mogelijkheden:

  1. Voer in het veld Beschrijving een betekenisvolle waarde in. Deze beschrijving wordt weergegeven in de details van de aangepaste connector en kan anderen helpen bepalen of de connector nuttig voor hen is.

  2. Werk het veld Host bij met 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
    Omschrijving Gebruikt de Cognitive Services Text Analytics Sentiment API om te bepalen of tekst positief of negatief is
    Host westus.api.cognitive.microsoft.com

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. Selecteer op het tabblad Beveiliging onder Authenticatietype de optie API-sleutel.

  2. Geef onder API-sleutel een parameterlabel, naam en locatie op. 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. Selecteer Verbinding maken.

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

  3. Controleer bovenaan de wizard of de naam is ingesteld op SentimentDemo en selecteer 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. In dit gedeelte leggen we de gebruikersinterface uit en bespreken we een aantal opties, maar we moedigen u ook aan om zelf op onderzoek uit te gaan.

Een actie maken

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

  1. Op het tabblad Definitie wordt in het linkerdeelvenster alle acties, triggers (voor Logic Apps en Power Automate) en verwijzingen weergegeven die voor de connector zijn gedefinieerd. Selecteer Nieuwe actie.

    Deze connector bevat geen triggers. Ga naar Webhooks gebruiken met Azure Logic Apps en Power Automate voor meer informatie over triggers voor aangepaste connectors.

  2. In het gedeelte Algemeen wordt informatie weergegeven over de actie of trigger die momenteel is geselecteerd. Voeg een samenvatting, beschrijving en bewerkings-id toe voor deze actie.

    Parameter Weergegeven als
    Overzicht 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 op geen staan. 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: wordt altijd als eerste aan de gebruiker getoond

  3. In het gebied Aanvraag wordt informatie weergegeven op basis van de HTTP-aanvraag voor de actie. Selecteer Importeren uit voorbeeld.

  4. Geef de informatie op die nodig is om verbinding te maken met de API, geef de aanvraagtekst op (na de volgende afbeelding) en selecteer vervolgens Importeren. Wij verstrekken u deze informatie, maar voor een openbare API haalt u deze informatie doorgaans uit documentatie zoals Text Analytics API (v2.0).

    Parameter Weergegeven als
    Term POSTEN
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Hoofdgedeelte Gebruik de volgende JSON-code:

    Voorbeeld:

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

  5. In het gebied Response wordt informatie weergegeven op basis van het HTTP-antwoord voor de actie. Selecteer Standaardantwoord toevoegen.

  6. Geef de antwoordtekst op en selecteer vervolgens Importeren. Net als bij de aanvraagtekst verstrekken we u deze informatie na de afbeelding, maar deze staat doorgaans in de API-documentatie.

    Voorbeeld:

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

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

De definitie bijwerken

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

  1. Selecteer in het gebied Aanvraag de optie body en selecteer 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 waarden voor de parameter bij en selecteer vervolgens Terug.

    Parameter Weergegeven als
    Title Id
    Omschrijving Een id voor elk document dat u verzendt
    Default value 0
    Is vereist Ja

  4. Selecteer in het gebied Parameter de optie taal>Bewerken en herhaal vervolgens het proces dat u hebt gebruikt voor id stap 2 en 3 van deze procedure, met de volgende waarden.

    Parameter Weergegeven als
    Title Taal
    Omschrijving De taalcode van twee of vier tekens voor de tekst
    Default value en
    Is vereist Ja

  5. Selecteer in het gebied Parameter de optie tekst>Bewerken en herhaal vervolgens het proces dat u hebt gebruikt voor id stap 2 en 3 van deze procedure, met de volgende waarden.

    Parameter Waarde
    Titel Tekst
    Beschrijving De tekst die moet worden geanalyseerd voor gevoel
    Standaardwaarde Geen
    Is vereist Ja

  6. Selecteer in het gebied Parameter de optie Terug om terug te gaan naar het hoofdtabblad Definitie .

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

Stap 4: (optioneel) uw connector inschakelen als AI-invoegtoepassing

Gebruik het tabblad AI Plugin (preview) alleen voor een connector als u van plan bent om uw connector te certificeren. Wilt u een connector als AI-invoegtoepassing kunnen gebruiken, dan moet de connector gecertificeerd zijn.

Voordat u uw connector inschakelt als AI-plug-in, moet u ervoor zorgen dat u de use case voor AI-plug-inscenario's begrijpt en andere overwegingen, zoals ondersteuning, best practices en aanbevelingen, hebt bekeken. Meer informatie: Een connector AI-plug-in maken (preview)

  1. Selecteer in het linkernavigatiedeelvenster Aangepaste connectoren.

    Als u Aangepaste connectoren niet ziet, selecteert u Meer>Alles ontdekken>Aangepaste connectoren. De optie verschijnt in het linkernavigatievenster.

  2. Selecteer rechtsboven een optie uit het menu Nieuwe aangepaste connector .

  3. Zorg ervoor dat u Stap 1, Stap 2 en Stap 3 in dit artikel hebt voltooid.

  4. Selecteer het tabblad AI Plugin (preview) .

  5. Voer in het gedeelte Pluginmanifest de details in om deze connector in te schakelen als een AI-plugin.

    Schermafbeelding van de velden op de pagina 'Plugin manifest'.

    Veld Omschrijving
    Manifest van invoegtoepassing: naam Naam van de AI-invoegtoepassing.
    Manifest van invoegtoepassing: beschrijving Beschrijving van de AI-invoegtoepassing. Meer informatie: Een connector AI-plug-in maken (preview)
    Manifest van invoegtoepassing: e-mailadres van contactpersoon Het e-mailadres van de contactpersoon voor deze AI-invoegtoepassing.
    Manifest van invoegtoepassing: URL voor juridische informatie Een openbaar toegankelijke locatie waar de juridische informatie met betrekking tot uw AI-invoegtoepassing wordt gepubliceerd.

  6. Scroll naar beneden naar het gedeelte Plugin Actions Details en voer de actiedetails in voor elke actie in uw connector AI-plug-in.

    Schermafbeelding van de velden op de pagina 'Pluginactiedetails'.

    Veld Omschrijving
    Actiedetails van invoegtoepassing: overzicht Overzicht van elke AI-invoegtoepassingsactie die de gebruikers kunnen uitvoeren.
    Actiedetails van invoegtoepassing: beschrijving Beschrijving van elke actie die de gebruikers kunnen uitvoeren met betrekking tot deze specifieke actiestap voor de AI-invoegtoepassing.
    Selectievakje: inschakelen als copilot-invoegtoepassingsbewerking Als er een vinkje in het selectievakje staat, is de AI-invoegtoepassingsbewerking ingeschakeld.
    Selectievakje: Gebruikersbevestiging vereist? Als er een vinkje in het selectievakje staat, is bevestiging door de gebruiker vereist.

    Tip

    Als u hulp nodig hebt bij het definiëren van uw acties, schakelt u de schakelaar Swagger-editor in.

  7. Scroll naar beneden naar het gedeelte Parameter en voer de parametergegevens voor uw connector AI-plug-in in.

    Schermafbeelding van de velden op de pagina 'Parameters'.

    Veld Omschrijving
    Parameter: naam Naam van de parameter. Gebruik herkenbare namen zoals Account Identifier in plaats van ID.
    Parameter: beschrijving Beschrijving van de parameter. Gebruik een beschrijvende uitleg, zoals Geboortedatum voor een contactpersoon in de notatie MM/DD/JJJJ in plaats van b_datum. Dergelijke namen en beschrijvingen helpen LLM's (Large Language Models) effectief te communiceren met de AI-invoegtoepassing.
    Parameter: overzicht Beknopte informatie over de parameter.
    Parameter: standaardwaarde Standaardwaarde van de parameter.

  8. Selecteer in de sectie Aanvraag onder de secties AI Plugin (preview) de invoerparameter en voer vervolgens een beschrijving in.

Stap 5: (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 er 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.

Notitie

  • Deze stap is optioneel. U kunt de codeloze ervaring voor het maken van uw connector voltooien door deze stap over te slaan en naar Stap 6: De connector testen te gaan.
  • Ondersteuning voor aangepaste code is beschikbaar in de openbare preview.

U kunt uw code plakken of een bestand met uw code uploaden. Uw code moet:

  • Geschreven zijn in C#.
  • Een maximale uitvoeringstijd van 5 seconden hebben.
  • Een bestandsgrootte hebben die niet groter is dan 1 MB.

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

Voor veelgestelde vragen over aangepaste code gaat u naar Veelgestelde vragen over aangepaste code.

  1. Voeg op het tabblad Code uw aangepaste code in met behulp van een van de volgende opties:

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

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

    Schermafbeelding van Upload uw aangepaste code.

    Belangrijk

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

  2. Nadat u uw code hebt geplakt of geüpload, selecteert u 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 vervolgmenu te selecteren. Als er geen bewerking is geselecteerd, worden de acties en triggers toegepast op alle bewerkingen.

    Schermafbeelding van geselecteerde acties en triggers.

Stap 6: 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 het tabblad Test de optie Nieuwe verbinding.

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

    Notitie

    Voor API's waarvoor bearer-authenticatie vereist is, voegt u Bearer en één spatie toe vóór de API-sleutel.

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

    • (In Power Automate) U wordt teruggebracht naar het tabblad Test . Selecteer het vernieuwingspictogram om ervoor te zorgen dat de verbindingsgegevens worden bijgewerkt.

      Schermafbeelding van de vernieuwingsverbinding.

    • (In Power Apps) U wordt naar de lijst met verbindingen geleid die beschikbaar zijn in de huidige omgeving. Selecteer in het linkerdeelvenster Gegevens>Aangepaste connectoren. Kies de connector die u hebt gemaakt en ga terug naar het tabblad Test .

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

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

    Schermafbeelding van de connectorrespons.

(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 ervan hebt gedefinieerd, kunt u de connector gebruiken vanuit:

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.