Opret en brugerdefineret connector fra OpenAPI-definition

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 med en OpenAPI-definition til at beskrive Cognitive Services-API'en til tekstanalyse (eksemplet for denne serie).

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

• Opret en brugerdefineret connector fra en Postman-samling
• Oprette en brugerdefineret connector fra bunden

Forudsætninger

• En OpenAPI-definition, der beskriver eksempel-API'en. Når du opretter en brugerdefineret connector, skal OpenAPI-definitionen være mindre end 1 MB. OpenAPI-definitionen skal være i OpenAPI 2.0-format (tidligere kaldet Swagger).
• En API-nøgle til Tekstanalyse-API'en for Cognitive Services.
• Et af følgende abonnementer:
  • Azure, hvis du bruger Logic Apps
  • Power Automate
  • Power Apps
• Hvis du bruger Logic Apps, skal du først oprette en brugerdefineret connector til Azure Logic Apps.

Importér OpenAPI-definitionen

Du er nu klar til at arbejde med den OpenAPI-definition, du har downloadet. Alle de nødvendige oplysninger er indeholdt i definitionen, og du kan gennemse og opdatere disse oplysninger undervejs i guiden for den brugerdefinerede connector.

Start med at importere OpenAPI-definitionen for Logic Apps eller Power Automate og Power Apps.

Importér OpenAPI-definitionen for Logic Apps

1. Gå til Azure-portalen, og åbn den Logic Apps-connector, du oprettede tidligere i Opret en brugerdefineret Azure Logic Apps-connector.

2. Vælg Logic Apps Connector i connectorens menu, og vælg derefter Rediger.

   

3. Vælg Upload en OpenAPI-fil under Generelt, og gå derefter til den OpenAPI-definition, du har oprettet.

   

Importér OpenAPI-definitionen for Power Automate og Power Apps

1. Gå til make.powerapps.com eller flow.microsoft.com.

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

   

3. Vælg Ny brugerdefineret connector, og vælg derefter Importér en OpenAPI-fil.

   

4. Angiv et navn til den brugerdefinerede connector, og gå derefter til den OpenAPI-definition, du har downloadet eller oprettet, og vælg Fortsæt.

   

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

Gennemgå generelle oplysninger

Fra nu af vises brugergrænsefladen i Power Automate, men trinnene er stort set de samme i alle tre teknologier. Vi fremhæver eventuelle forskelle. I denne del af emnet vil vi hovedsageligt gennemgå brugergrænsefladen og vise dig, hvordan værdierne svarer til sektioner i OpenAPI-filen.

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

2. På siden Generelt skal du gennemse oplysningerne, der blev importeret fra OpenAPI-definitionen, herunder API-værten og den grundlæggende URL-adresse for API'en. Connectoren bruger API-værten og URL-basisadressen til at bestemme, hvordan API'en skal kaldes.

   

   Bemærk

   Du kan finde flere oplysninger om forbindelsen til lokale API'er under Oprette forbindelse til lokale API'er ved hjælp af datagateway.

   Følgende afsnit af OpenAPI-definitionen indeholder oplysninger til denne side i brugergrænsefladen:

     "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"
     ]
   

Gennemgå godkendelsestypen

Der er flere tilgængelige indstillinger for godkendelse i brugerdefinerede connectorer. Cognitive Services-API'er bruger API-nøglegodkendelse, så det er angivet i OpenAPI-definitionen.

Gennemse godkendelsesoplysningerne for API-nøglen på siden Sikkerhed.

Navnet vises, når en bruger opretter forbindelse til den brugerdefinerede connector første gang. Du kan vælge Rediger og ændre denne værdi. Parameterens navn og placering skal stemme overens med, hvad API'en forventer, i dette tilfælde "Ocp-Apim-Subscription-Key" og "Header".

Følgende afsnit af OpenAPI-definitionen indeholder oplysninger til denne side i brugergrænsefladen:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Gennemgå connector-definitionen

Siden Definition i guiden til brugerdefinerede connectorer giver dig mange valgmuligheder i forhold til at definere, hvordan din connector fungerer, og hvordan den vises i logikapps, flows 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. Du kan finde oplysninger om, hvordan du definerer objekter helt fra bunden i denne brugergrænseflade, under Oprette connector-definitionen.

1. Alle handlinger, udløsere (for Logic Apps og Power Automate) og referencer, der er defineret for connectoren, vises i det følgende område. I dette tilfælde vises handlingen DetectSentiment fra OpenAPI-definitionen. Der er ingen udløsere i denne connector, men du kan få mere at vide om udløsere for brugerdefinerede connectorer under Bruge 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. Du kan redigere oplysningerne her, herunder egenskaben Synlighed for handlinger og parametre i en logikapp eller et flow:

   • ingen: vises normalt i logikappen eller flowet

   • avanceret: skjult under en ekstra menu

   • intern: for brugeren

   • vigtigt: vises altid først for brugeren

     

3. I området Anmodning vises oplysninger baseret på HTTP-anmodningen, der er inkluderet i OpenAPI-definitionen. I dette tilfælde er HTTP verbet lig med POST, og URL-adressen er "/text/analytics/v2.0/sentiment" (den fulde URL-adresse til API'en er "https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment"). Vi ser nærmere på brødtekst-parameteren om lidt.

   

   Følgende afsnit af OpenAPI-definitionen indeholder oplysninger for områderne Generelt og Anmodning i brugergrænsefladen:

   "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. I området Svar vises oplysninger baseret på HTTP-svaret, der er inkluderet i OpenAPI-definitionen. I dette tilfælde er der kun defineret et svar for "200" (et vellykket svar), men du kan angive yderligere svar.

   

   Følgende afsnit af OpenAPI-definitionen indeholder nogle af oplysningerne vedrørende svaret:

   "score": {
    "type": "number",
    "format": "float",
    "description": "score",
    "x-ms-summary": "score"
   },
   "id": {
    "type": "string",
    "description": "id",
    "x-ms-summary": "id"
   }
   

   I denne sektion vises de to værdier, der returneres af connectoren: id og score. Den indeholder datatyperne og feltet x-ms-summary, som er en OpenAPI-udvidelse. Du kan finde flere oplysninger om denne og andre udvidelser under Udvide en OpenAPI-definition for en brugerdefineret connector.

5. I området Validering vises eventuelle problemer, der er fundet i API-definitionen. Sørg for at kontrollere dette område, før du gemmer en connector.

   

Opdater definitionen

Den OpenAPI-definition, som du downloadede, er et godt grundlæggende eksempel, men du arbejder muligvis med definitioner, der kræver en masse opdateringer, så connectoren er mere brugervenlig, når nogen bruger den i en logikapp, et flow eller en app. Du får vist, hvordan du kan foretage en simpel ændring af definitionen.

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 beskrivelsen af parameteren og derefter vælge Tilbage.

   

   Parameter	Værdi
   Beskrivelse	"En numerisk identifikator for hvert indsendt dokument"

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

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

Download den opdaterede OpenAPI-fil

Du kan oprette en brugerdefineret connector fra en OpenAPI-fil, en Postman-samling eller fra bunden (i Power Automate og Power Apps). Uanset hvordan du opretter connectoren, kan du downloade den OpenAPI-definition, som tjenesten bruger internt.

• I Logic Apps kan du downloade fra den brugerdefinerede connector.

  

• I Power Automate eller Power Apps skal du downloade fra listen over brugerdefinerede connectorer.

  

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 Microsoft Flow 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ø. Vælg tandhjulsikonet i øverste højre hjørne, og vælg derefter 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.

   

Næste trin

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

• Brug en brugerdefineret connector fra et flow
• Anvende en brugerdefineret connector fra en app
• Brug en brugerdefineret connector fra en logikapp

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