Oprette en brugerdefineret connector fra bunden

Når du skal oprette en brugerdefineret connector, skal du beskrive den API, du vil oprette forbindelse til, så connectoren forstår API'ens handlinger og datastrukturer. I dette emne kan du oprette en brugerdefineret connector fra bunden uden at bruge en Postman-samling eller OpenAPI-definition til at beskrive Cognitive Services-API'en til tekstanalyse (eksemplet for denne serie). I stedet skal du beskrive connectoren helt i guiden til brugerdefineret connector.

Du kan finde andre måder at beskrive en API på i følgende emner:

• Opret en brugerdefineret connector fra OpenAPI-definition
• Opret en brugerdefineret connector fra en Postman-samling

Forudsætninger

• En API-nøgle til Tekstanalyse-API'en for Cognitive Services
• Et af følgende abonnementer:
  • Power Automate
  • Power Apps

Start guiden for brugerdefineret connector

1. Log på Power Apps eller Power Automate.

2. I navigationsruden skal du vælge Data > Brugerdefinerede connectorer.

   

3. Vælg Ny brugerdefineret connector, og vælg derefter Opret fra bunden.

   

4. Angiv et navn til den brugerdefinerede connector, og vælg derefter Fortsæt.

   

   Parameter	Værdi
   Titel på brugerdefineret forbindelse	"SentimentDemo"

Trin 1: Opdater generelle oplysninger

Fra nu af vises brugergrænsefladen i Power Automate, men trinnene er stort set de samme i alle teknologier. Vi fremhæver eventuelle forskelle.

1. På siden Generelt:

   • Angiv en meningsfuld værdi for Beskrivelse. Denne beskrivelse vises i oplysningerne om den brugerdefinerede connector og kan hjælpe andre med at bestemme, om connectoren kan være nyttig for dem.

   • Opdater Vært til adressen for Tekstanalyse-API'en. Connectoren bruger API-værten og URL-basisadressen til at bestemme, hvordan API'en skal kaldes.

   

   Parameter	Værdi
   Beskrivelse	"Bruger Cognitive Services-API'en til tekstanalyse til at registrere, om teksten er positiv eller negativ"
   Vært	"westus.api.cognitive.microsoft.com"

   Bemærk

   Du kan finde flere oplysninger om indstillingen Opret forbindelse via datagateway i det lokale under Oprette forbindelse til lokale API'er ved hjælp af datagateway.

Trin 2: Angiv godkendelsestypen.

Der er flere tilgængelige indstillinger for godkendelse i brugerdefinerede connectorer. Cognitive Services-API'er bruger API-nøglegodkendelse, så det skal du angive i dette selvstudium.

1. På siden Sikkerhed under Godkendelsestype skal du vælge API-nøgle.

   

2. Angiv en parameteretiket, et navn og en placering under API-nøgle. Angiv en sigende etiket, for den vises, når nogen opretter forbindelse til den brugerdefinerede connector første gang. Parameternavnet og -placeringen skal matche det, som API'en forventer. Vælg Forbind.

   

   Parameter	Værdi
   Parameteretiket	"API-nøgle"
   Parameternavn	"Ocp-Apim-Subscription-Key"
   Parameterplacering	"Overskrift"

3. Sørg for, at navnet er angivet til "SentimentDemo" øverst i guiden, og vælg derefter Opret connector.

Trin 3: Oprettelse af forbindelsens definition

Guiden Brugerdefineret tilslutning giver dig mange muligheder for at definere, hvordan din tilslutning fungerer, og hvordan den vises i logikapps, flow og apps. Vi forklarer brugergrænsefladen og dækker et par muligheder i dette afsnit, men vi opfordrer dig også til at udforske på egen hånd.

Opret en handling

Det første, du skal gøre, er at oprette en handling, der kalder funktionen Tekstanalyse-synspunkt-API'en.

1. På siden Definition vises alle handlinger, udløsere (for Logic Apps og Power Automate) og referencer, der er defineret for connectoren, i området til venstre. Vælg Ny handling.

   

   Der er ingen udløsere i denne connector. Du kan få mere at vide om udløsere for brugerdefinerede connectorer i Brug webhooks med Azure Logic Apps og Power Automate.

2. I området Generelt vises oplysninger om den handling eller udløser, der er valgt i øjeblikket. Tilføj en oversigt, en beskrivelse og et handlings-id for denne handling.

   

   Parameter	Værdi
   Oversigt	"Returnerer en numerisk score, der repræsenterer det synspunkt, der er registreret"
   Beskrivelse	"API'en returnerer en numerisk værdi mellem 0 og 1. Scorer tæt på 1 indikerer et positivt synspunkt, mens scorer tæt på 0 indikerer et negativt synspunkt".
   Handlings-id	"DetectSentiment"

   Lad egenskaben Synlighed være angivet til ingen. Denne egenskab for handlinger og parametre i en logikapp eller et flow har følgende indstillinger:

   • ingen: vises normalt i logikappen eller flowet
   • avanceret: skjult under en anden menu
   • intern: for brugeren
   • vigtigt: vises altid først for brugeren

3. I Anmodning-området vises oplysninger, der er baseret på HTTP-anmodningen for handlingen. Vælg Importér fra eksempel.

   

4. Angiv de oplysninger, der er nødvendige for at oprette forbindelse til API'en, samt brødteksten i anmodningen, og vælg derefter Importér. Vi angiver disse oplysninger for dig (under billedet). For et offentlig API får du dem typisk i dokumentationen, f.eks. Tekstanalyse-synspunkt-API'.

   

   Parameter	Værdi
   Verbum	"POST"
   URL-adresse	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Tekst	Se nedenfor

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

5. I Svar-området vises oplysninger, der er baseret på HTTP-svaret for handlingen. Vælg Tilføj standardsvar.

   

6. Angiv svarteksten, og vælg derefter Importér. På samme måde som med anmodningen leverer vi disse oplysninger til dig, men de er som regel i API-dokumentationen.

   

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

7. I området Validering vises eventuelle problemer, der er fundet i API-definitionen. Kontrollér status, og vælg derefter Opdater connector øverst til højre i guiden.

   

Opdater definitionen

Lad os nu ændre et par ting, så connectoren er mere brugervenlig, når nogen bruger den i en logikapp, et flow eller en app.

1. I området Anmodning skal du vælge brødtekst og derefter Rediger.

   

2. I området Parameter kan du nu se de tre parametre, som API'en forventer: id, language og text. Vælg id og derefter Rediger.

   

3. I området Skemaegenskab skal du opdatere værdier af parameteren og derefter vælge Tilbage.

   

4. I området Parameter skal du vælge language og derefter Rediger og gentage processen, som du brugte for id, med følgende værdier.

   Parameter	Værdi
   Titel	"Sprog"
   Beskrivelse	"Tekstens sprogkode på to eller fire tegn"
   Standardværdi	"en"
   Er påkrævet	"Ja"

5. I området Parameter skal du vælge text og derefter Rediger og gentage processen, som du brugte for id og language, med følgende værdier.

   Parameter	Værdi
   Titel	"Tekst"
   Beskrivelse	"Den tekst, der skal analyseres for synspunkt"
   Standardværdi	Intet
   Er påkrævet	"Ja"

6. I området Parameter skal du vælge Tilbage for at gå tilbage til den primære definitionsside.

7. Vælg Opdater connector øverst til højre i guiden.

Trin 4: (Valgfrit) Brug understøttelse af brugerdefineret kode

I brugerdefineret kode transformeres nyttedata for anmodninger og svar ud over omfanget af eksisterende politikskabeloner. Transformeringerne omfatter afsendelse af eksterne forespørgsler om hentning af flere data. Når der bruges kode, tilsidesættes den kodeløse definition. Det betyder, at koden køres, og vi sender ikke anmodningen til backend.

Du kan enten indsætte koden eller overføre en fil med koden. Din kode skal opfylde følgende krav:

• Skrives i C#.
• Hav en maks. udførelsestid på 5 sekunder.
• Må ikke være mere end 1 MB (kodefilens størrelse).

Hvis du vil have instruktioner i og eksempler på skrivning af kode, skal du gå til Skriv kode i brugerdefinerede connectorer.

Hvis du har ofte stillede spørgsmål om brugerdefineret kode, skal du gå til Ofte stillede spørgsmål om brugerdefineret kode.

1. Indsæt den brugerdefinerede kode på siden Kode ved hjælp af en af følgende indstillinger:

   • Kopiér/indsæt, eller
   • Vælg knappen Upload.

   Hvis du vælger at uploade den brugerdefinerede kode, er det kun filer med filtypenavnet .cs eller .csx, der er tilgængelige.

   
   

   Vigtigt

   I øjeblikket understøtter vi kun syntaksfremhævdelse i kodeeditoren. Sørg for at teste koden lokalt.

2. Når du har indsat eller overført koden, skal du vælge til/fra ud for Deaktiveret kode for at aktivere koden. Til/fra-navnet ændres til Kode aktiveret.

   Du kan aktivere eller deaktivere koden når som helst. Hvis til/fra-knappen er Kode deaktiveret, slettes koden.

   

3. Vælg de handlinger og udløsere, der skal anvendes på din brugerdefinerede kode, ved at vælge en indstilling på rullelisten. Hvis der ikke vælges en handling, anvendes den på alle handlinger.

   

Trin 5: Test connectoren

Nu, hvor du har oprettet connectoren, kan du teste den for at sikre dig, at den fungerer korrekt. Test er i øjeblikket kun tilgængelig i Power Automate og Power Apps.

1. På siden Test skal du vælge Ny forbindelse.

   

2. Angiv API-nøglen fra API'en til Tekstanalyse, og vælg derefter Opret forbindelse.

   

3. Gå tilbage til siden Test:

   • I Power Automate bliver du ført tilbage til siden Test. Vælg opdateringsikonet for at sikre, at forbindelsesoplysningerne er opdateret.

   

   • I Power Apps bliver du ført til listen over tilgængelige forbindelser i det aktuelle miljø. I navigationsruden skal du vælge Data > Brugerdefinerede connectorer. Vælg den connector, som du oprettede, og gå derefter tilbage til siden Test.

     

4. På siden Test skal du angive en værdi for feltet tekst (de andre felter bruger de standarder, du tidligere har angivet), og vælg derefter Test handling.

   

5. Connectorn kalder API'en, og du kan gennemgå svaret, som omfatter synspunktsscoren.

   

(Til CLI-brugere) Best practices

• Download alle dine connectors, og brug Git eller et andet kildekodesystem til at gemme filerne.

• I tilfælde af en forkert opdatering skal du udrulle connectoren igen ved at køre opdateringskommandoen igen med det korrekte sæt filer fra kildekodesystemet.

• Test den brugerdefinerede connector og indstillingsfilen i et testmiljø, før du udruller i produktionsmiljøet.

• Dobbelttjek altid, at miljø- og connector-id'et er korrekt.

Næste trin

Nu, hvor du har oprettet en brugerdefineret connector og defineret dens funktionsmåde, kan du bruge connectoren fra.

• Et flow
• En app
• En logic App

Du kan også dele en connector i din organisation og/eller få connectoren certificeret, så folk uden for din organisation kan bruge den:

• Dele din connector
• Certificere din connector