Del via

Opprette en egendefinert kobling fra grunnen av

Notat

Denne artikkelen er en del av en opplæringsserie om oppretting og bruk av egendefinerte koblinger i Azure Logic Apps, Microsoft Power Automate og Microsoft Power Apps bruk av AI-aktiverte koblinger i Microsoft Copilot Studio. Pass på at du leser oversikten over den egendefinerte koblingen for å forstå prosessen. Gå til Bruk Power Platform koblinger i Copilot Studio for å finne ut hvordan du kan kalle koblingene som koblingshandlinger i agenten Microsoft Copilot .

Hvis du vil opprette en egendefinert kobling, må du beskrive API-en du vil koble til, slik at koblingen forstår API-ens operasjoner og datastrukturer. I denne artikkelen oppretter du en egendefinert kobling fra grunnen av, uten å bruke en OpenAPI definisjon til å beskrive API-sentimentoperasjonen for tekstanalyse i Azure Cognitive Services (vårt eksempel for denne serien). I stedet beskriver du koblingen fullstendig i veiviseren for egendefinert kobling.

Hvis du vil ha en annen måte å beskrive en API på, kan du gå til Opprette en egendefinert kobling fra en OpenAPI definisjon.

Notat

Du kan for øyeblikket opprette en egendefinert kobling fra grunnen av i Power Automate og Power Apps. For Logic Apps må du starte med minst en grunnleggende OpenAPI definisjon.

Forutsetning

Starte veiviseren for egendefinerte koblinger

  1. Logg deg på Power Apps eller Power Automate.

  2. I den venstre ruten velger du Egendefinerte datakoblinger>.

  3. Velg Ny egendefinert kobling>Opprett fra tom.

  4. Skriv inn et navn på den egendefinerte koblingen, og velg deretter Fortsett.

    Parameter Verdi
    Tittel på egendefinert kobling Sentiment-demo

Trinn 1: Oppdater generelle detaljer

Fra dette punktet viser vi brukergrensesnittet Power Automate , men trinnene er stort sett de samme på tvers av teknologiene. Vi påpeker eventuelle forskjeller.

Gjør følgende i kategorien Generelt:

  1. I Beskrivelse-feltet angir du en meningsfull verdi. Denne beskrivelsen vises i detaljene for den egendefinerte koblingen, og den kan hjelpe andre med å avgjøre om koblingen kan være nyttig for dem.

  2. Oppdater Vert-feltet til adressen for API-en for tekstanalyse. Koblingen bruker API-verten og basis-URL-adressen til å bestemme hvordan API-en skal kalles.

    Parameter Verdi
    Description Bruker sentiment-API-en for Cognitive Services-tekstanalyse til å avgjøre om teksten er positiv eller negativ
    Host westus.api.cognitive.microsoft.com

Trinn 2: Angi godkjenningstype

Det finnes flere tilgjengelige alternativer for godkjenning i egendefinerte koblinger. Cognitive Services-API-ene bruker API-nøkkelgodkjenning, så det er det du angir for denne opplæringen.

  1. På Sikkerhet-fanen , under Godkjenningstype, velger du API-nøkkel.

  2. Under API-nøkkel angir du en parameteretikett, et navn og en plassering. Angi en meningsfull etikett, fordi denne vises når noen først oppretter en tilkobling med den egendefinerte koblingen. Parameternavnet og plasseringen må samsvare med det API-en forventer. Velg Koble til.

    Parameter Verdi
    Parameteretikett API key
    Parameternavn Ocp-Apim-Abonnement-Nøkkel
    Parameterplassering Hode

  3. Øverst i veiviseren kontrollerer du at navnet er satt til SentimentDemo, og deretter velger du Opprett kobling.

Trinn 3: Opprette koblingsdefinisjonen

Veiviseren for egendefinert kobling gir deg mange alternativer for å definere hvordan koblingen fungerer, og hvordan den vises i logiske apper, flyter og apper. Vi forklarer brukergrensesnittet og dekker noen få alternativer i denne delen, men vi oppfordrer deg også til å utforske på egen hånd.

Opprette en handling

Det første du må gjøre, er å opprette en handling som kaller sentimentoperasjonen API-en for tekstanalyse.

  1. I kategorien Definisjon viser den venstre ruten alle handlinger, utløsere (for Logic Apps og Power Automate) og referanser som er definert for koblingen. Velg Ny handling.

    Det er ingen utløsere i denne koblingen. Hvis du vil vite mer om utløsere for egendefinerte koblinger, kan du gå til Bruke webhooks med Azure Logic Apps og Power Automate.

  2. Generelt-området viser informasjon om handlingen eller utløseren som er valgt. Legg til et sammendrag, en beskrivelse og en operasjons-ID for denne handlingen.

    Parameter Verdi
    Sammendrag Returnerer en numerisk poengsum som representerer sentimentet som er oppdaget
    Description API-en returnerer en numerisk poengsum mellom 0 og 1. Poengsummer nær 1 indikerer positivt sentiment, mens poengsummer nær 0 indikerer negativt sentiment.
    Operasjons-ID Oppdage sentiment

    La egenskapen Synlighet være satt til ingen. Denne egenskapen for operasjoner og parametere i en logikkapp eller flyt har følgende alternativer:

    • Ingen: Vises normalt i logikkappen eller flyten
    • Avansert: skjult under en annen meny
    • internt: skjult for brukeren
    • Viktig: Vises alltid til brukeren først

  3. Forespørsel-området viser informasjon basert på HTTP-forespørselen for handlingen. Velg Importer fra eksempel.

  4. Angi informasjonen som er nødvendig for å koble til API-en, angi forespørselsteksten (angitt etter bildet nedenfor), og velg deretter Importer. Vi gir deg denne informasjonen, men for et offentlig API får du vanligvis denne informasjonen fra dokumentasjon som Text Analytics API (v2.0).

    Parameter Verdi
    Verb POST
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Body Bruk følgende JSON-kode

    Eksempel:

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

  5. Svar-området viser informasjon basert på HTTP-svaret for handlingen. Velg Legg til standardsvar.

  6. Angi svarteksten, og velg deretter Importer. Som vi gjorde for forespørselsteksten, gir vi deg denne informasjonen etter bildet, men den er vanligvis angitt i API-dokumentasjonen.

    Eksempel:

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

  7. Valideringsområdet viser eventuelle problemer som oppdages i API-definisjonen. Kontroller statusen, og velg deretter Oppdater kobling øverst til høyre i veiviseren.

Oppdater definisjonen

La oss nå endre noen ting slik at koblingen er mer brukervennlig når noen bruker den i en logikkapp, flyt eller app.

  1. I Forespørsel-området velger du brødtekst, og deretter velger du Rediger.

  2. I Parameter-området ser du nå de tre parameterne som API-en forventer: id, language, og text. Velg id, og velg deretter Rediger.

  3. Oppdater verdiene for parameteren i Skjemaegenskap-området , og velg deretter Tilbake.

    Parameter Verdi
    Title ID
    Description En identifikator for hvert dokument du sender inn
    Default value 1
    Er obligatorisk Ja

  4. I Parameter-området velger du språk>Rediger, og deretter gjentar du prosessen du brukte til id i trinn 2 og 3 i denne prosedyren, med følgende verdier.

    Parameter Verdi
    Title Språk
    Description Språkkoden på to eller fire tegn for teksten
    Default value en
    Er obligatorisk Ja

  5. Velg teksten Rediger i Parameter-området, og gjenta deretter prosessen du brukte i>trinn 2 og 3 i denne prosedyren, med følgende verdier. id

    Parameter Verdi
    Title Tekstmelding
    Description Teksten som skal analyseres for sentiment
    Default value None
    Er obligatorisk Ja

  6. I Parameter-området velger du Tilbake for å ta deg tilbake til hovedkategorien Definisjon .

  7. I øvre høyre hjørne av veiviseren velger du Oppdater kobling.

Trinn 4: (Valgfritt) Aktiver koblingen som en AI-plugin-modul

Bruk kategorien AI-plugin-modul (forhåndsversjon) for en kobling bare hvis du planlegger å sertifisere koblingen. For at en kobling skal kunne brukes som en AI-plugin, må koblingen være sertifisert.

Før du aktiverer koblingen som en AI-plugin-modul, må du sørge for at du forstår brukstilfellet for scenarioer for AI-plugin-moduler og gjennomgår andre hensyn, for eksempel støtte, anbefalte fremgangsmåter og anbefalinger. Mer informasjon: Opprette en AI-plugin-modul for kobling (forhåndsversjon)

  1. I den venstre navigasjonsruten velger du Egendefinerte koblinger.

    Hvis du ikke ser Egendefinerte koblinger, velger du Mer>Oppdag alle>egendefinerte koblinger. Alternativet vises i venstre navigasjonsrute.

  2. Øverst til høyre velger du et alternativ fra menyen Ny egendefinert kobling .

  3. Kontroller at du har fullført trinn 1, trinn 2 og trinn 3 i denne artikkelen.

  4. Velg kategorien AI-plugin-modul (forhåndsversjon).

  5. I delen Plugin-manifest angir du detaljer for å aktivere denne koblingen som en AI-plugin-modul.

    Skjermbilde av feltene på «Programtillegg-manifest»-siden.

    Felt Description
    Plugin-manifest: Navn Navnet på AI-pluginen.
    Plugin-manifest: Beskrivelse Beskrivelse av AI-plugin. Mer informasjon: Opprette en AI-plugin-modul for kobling (forhåndsversjon)
    Plugin-manifest: E-postadresse for kontakt E-postadressen til kontakten for denne AI-pluginen.
    Plugin-manifest: URL for juridisk informasjon Et offentlig tilgjengelig sted der den juridiske informasjonen knyttet til AI-plugin-modulen publiseres.

  6. Rull ned til delen Detaljer om plugin-handlinger, og skriv inn handlingsdetaljene for hver handling i AI-plugin-modulen for kobling.

    Skjermbilde av feltene på siden

    Felt Description
    Detaljer om plugin-handling: Sammendrag Sammendrag om hver AI-plugin-handling som brukerne kan utføre.
    Detaljer om plugin-handling: Beskrivelse Beskrivelse av hver handling som brukerne kan utføre angående dette spesifikke handlingstrinnet for AI-plugin.
    Avmerkingsboks: Aktiver som copilot-plugin-operasjon Når en hake er i avmerkingsboksen, er AI-plugin-operasjonen aktivert.
    Avmerkingsboks: Brukerbekreftelse kreves? Når en hake er i avmerkingsboksen, kreves brukerbekreftelse.

    Tips

    Hvis du trenger hjelp til å definere handlingene dine, kan du slå på Swagger-redigeringsbryteren .

  7. Rull ned til Parameter-delen , og skriv inn parameterdetaljene for AI-plugin-modulen for koblingen.

    Skjermbilde av feltene på «Parameters»-siden.

    Felt Description
    Parameter: Navn Navn på parameteren. Bruk identifiserbare navn som kontoidentifikator i stedet for ID.
    Parameter: Beskrivelse Beskrivelse av parameteren. Bruk en beskrivende forklaring, for eksempel Fødselsdato for en kontakt i formatet MM/DD/ÅÅÅÅ, i stedet for b_date. Slike navn og beskrivelser hjelper LLM-er (store språkmodeller) med å samhandle effektivt med AI-pluginen.
    Parameter: Sammendrag Sammendragsinformasjon om parameteren.
    Parameter: Standardverdi Standardverdi for parameteren.

  8. I Forespørsel-delen under AI-plugin-modulen (forhåndsvisning) seksjoner, velger du inndataparameteren, og deretter skriver du inn en beskrivelse.

Trinn 5: (Valgfritt) Bruk støtte for egendefinert kode

Egendefinert kode transformerer forespørsels- og svarnyttelaster utover omfanget av eksisterende policymaler. Transformasjoner inkluderer sending av eksterne forespørsler om å hente tilleggsdata. Når kode brukes, har den forrang over den kodeløse definisjonen. Dette betyr at koden vil kjøres, og vi sender ikke forespørselen til backend.

Notat

  • Dette trinnet er valgfritt. Du kan fullføre den kodeløse opplevelsen for å opprette koblingen ved å ignorere dette trinnet og gå til Trinn 6: Test koblingen.
  • Støtte for egendefinert kode er tilgjengelig i offentlig forhåndsversjon.

Du kan enten lime inn koden eller laste opp en fil med koden din. Koden din må:

  • Skrives i C#.
  • Ha en maksimal utførelsestid på fem sekunder.
  • Ha en filstørrelse som ikke er større enn 1 MB.

Hvis du vil ha instruksjoner og eksempler på hvordan du skriver kode, kan du gå til Skrive kode i egendefinerte koblinger.

Hvis du vil ha vanlige spørsmål om egendefinert kode, kan du gå til Vanlige spørsmål om egendefinert kode.

  1. Sett inn den egendefinerte koden ved hjelp av ett av følgende alternativer i kategorien Kode :

    • Kopier / lim inn
    • Velg Last opp-knappen.

    Hvis du velger å laste opp den egendefinerte koden, er bare filer med filtypen .cs eller .csx tilgjengelige.

    Skjermbilde av Last opp den egendefinerte koden din.

    Viktig!

    Foreløpig støtter vi bare syntaksutheving i koderedigeringsprogrammet. Sørg for å teste koden din lokalt.

  2. Når du har limt inn eller lastet opp koden, velger du bryteren ved siden av Kode deaktivert for å aktivere koden. Vekslenavnet endres til Kode aktivert.

    Du kan aktivere eller deaktivere koden når som helst. Hvis bryteren er Kode deaktivert, slettes koden.

  3. Velg handlingene og utløserne som skal brukes på den egendefinerte koden, ved å velge et alternativ i rullegardinmenyen. Hvis ingen operasjon er valgt, brukes handlingene og utløserne på alle operasjoner.

    Skjermbilde av Velg handlinger og utløsere.

Trinn 6: Test kontakten

Nå som du opprettet koblingen, tester du den for å sikre at den fungerer som den skal. Testing er foreløpig bare tilgjengelig i Power Automate og Power Apps.

Viktig!

Når du bruker en API-nøkkel, anbefaler vi at du ikke tester koblingen umiddelbart etter at du har opprettet den. Det kan ta noen minutter før koblingen er klar til å koble til API-en.

  1. I kategorien Test velger du Ny tilkobling.

  2. Skriv inn API-nøkkelen fra API-en for tekstanalyse, og velg deretter Opprett tilkobling.

    Notat

    For API-er som krever bærerautentisering, legger du til Bærer og ett mellomrom før API-nøkkelen.

  3. Gå tilbake til Test-fanen , og gjør ett av følgende:

    • (Inn Power Automate) Du kommer tilbake til Test-fanen . Velg oppdateringsikonet for å kontrollere at tilkoblingsinformasjonen er oppdatert.

      Skjermbilde av oppdateringstilkoblingen.

    • (Inn Power Apps) Du kommer til listen over tilkoblinger som er tilgjengelige i det gjeldende miljøet. I den venstre ruten velger du Egendefinerte datakoblinger>. Velg koblingen du opprettet, og gå deretter tilbake til Test-fanen .

  4. I kategorien Test angir du en verdi for tekstfeltet (de andre feltene bruker standardene du angav tidligere), og deretter velger du Testoperasjon.

  5. Koblingen kaller API-en, og du kan se gjennom svaret, som inkluderer sentimentpoengsummen.

    Skjermbilde av koblingssvaret.

(For CLI-brukere) Anbefalte fremgangsmåter

  • Last ned alle koblingene dine, og bruk Git eller et hvilket som helst kildekodebehandlingssystem til å lagre filene.

  • Hvis det er feil oppdatering, distribuerer du koblingen på nytt ved å kjøre oppdateringskommandoen på nytt med riktig sett med filer fra kildekodebehandlingssystemet.

  • Test den egendefinerte koblingen og innstillingsfilen i et testmiljø før du distribuerer i produksjonsmiljøet.

  • Dobbeltsjekk alltid at miljø- og koblings-ID-en er riktig.

Neste trinn

Nå som du opprettet en egendefinert kobling og definerte virkemåten, kan du bruke koblingen fra:

Du kan også dele en kobling i organisasjonen, eller få koblingen sertifisert slik at personer utenfor organisasjonen kan bruke den.

gi tilbakemelding

Vi setter stor pris på tilbakemeldinger om problemer med koblingsplattformen vår, eller ideer til nye funksjoner. Hvis du vil gi tilbakemelding, kan du gå til Sende inn problemer eller få hjelp med koblinger og velge tilbakemeldingstype.