Skapa ett anpassat anslutningsprogram från en OpenAPI-definition

Artikel
08/31/2021
7 minuter för att läsa

Anteckning

Det här avsnittet är en del av självstudieserien om att skapa och använda anpassade kopplingar i Azure Logic Apps, Microsoft Power Automate och Microsoft Power Apps. Se till att du läser översikt för anpassad koppling för att förstå processen.

Om du vill skapa en anpassad koppling måste du beskriva det API du vill ansluta så att kopplingen förstår API:ets åtgärder och datastrukturer. I det här ämnet skapar du en anpassad koppling med en OpenAPI-definition som beskriver API:et för attitydstextanalys i Cognitive Services (vårt exempel för den här serien).

Andra sätt att beskriva ett API finns i följande avsnitt:

Förutsättningar

En OpenAPI-definition som beskriver exempel-API:t. När du skapar en anpassad koppling måste den OpenAPI-definitionen vara mindre än 1 MB. OpenAPI-definitionen måste vara i OpenAPI 2.0-format (tidigare känt som Swagger).
En API-nyckel för API:et för textanalys i Cognitive Services.
En av följande prenumerationer:
- Azure, om du använder Logic Apps
- Power Automate
- Power Apps
Om du använder Logic Apps ska du först skapa en anpassad koppling för Azure Logic Apps.

Importera OpenAPI-definitionen

Nu är du redo att arbeta med den OpenAPI-definition som du hämtade. All nödvändig information finns i definitionen och du kan granska och uppdatera informationen när du går igenom guiden anpassad koppling.

Börja med att importera OpenAPI-definitionen för Logic Apps eller för Power Automate och Power Apps.

Anteckning

OpenAPI-definitionen måste vara i OpenAPI 2.0-format (tidigare känt som Swagger). OpenAPI-definitioner som är i OpenAPI 3.0-format stöds inte.

Importera OpenAPI-definitionen för Logic Apps

Gå till Azure-portalen och öppna Logic Apps-anslutningen du skapade tidigare i Skapa en anpassad koppling för Azure Logic Apps.
I din kopplingsmeny, välj Logic Apps-koppling och sedan Redigera.
Under Allmänt väljer du Ladda upp en OpenAPI-fil och går sedan till den OpenAPI-definition som du skapade.

Anteckning

Den här självstudien fokuserar på en REST-API, men du kan också använda en SOAP-API med Logic Apps.

Importera OpenAPI-definitionen för Power Automate och Power Apps

Gå till make.powerapps.com eller flow.microsoft.com.
I navigeringsfönstret väljer du Data > Anpassade anslutningsprogram.
Välj Nytt anpassat anslutningsprogram och sedan Importera en OpenAPI-fil.
Ange ett namn på den anpassade kopplingen och gå sedan till den OpenAPI-definition du hämtade eller skapade och välj Fortsätt.

Parameter Värde

Rubrik för anpassad anslutningsapp ”SentimentDemo”

Parameter	Värde
Rubrik för anpassad anslutningsapp	”SentimentDemo”

Granska allmän information

Härifrån visar vi Power Automate-användargränssnittet men stegen är i stort sett desamma för alla tre tekniker. Vi pekar på alla skillnader. I den här delen av ämnet granskar vi användar gränssnittet och visar hur värdena överensstämmer med avsnitten i OpenAPI-filen.

Längst upp i guiden, kontrollera att namnet är inställt på "SentimentDemo", välj sedan Skapa anslutning.
På sidan Allmänt granskar du informationen som har importerats från OpenAPI-definition, inklusive API-värden och den grundläggande URL:en för API:et. Anslutningsprogrammet använder API-värden och den grundläggande URL:en för att fastställa hur API:et ska anropas.

Anteckning

Mer information om ansluta till lokala API:er finns i Anslut till lokala API:er med datagatewa.

Följande avsnitt i OpenAPI-definitionen innehåller information om den här sidan i användargränssnittet:
```
  "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"
  ]
```

Granska autentiseringstyp

Det finns flera tillgängliga alternativ för autentisering i anpassade anslutningsprogram. I API:erna för kognitiva tjänster används API-autentiseringsnyckel så att det är vad som anges i OpenAPI-definition.

På sidan säkerhet läser du igenom autentiseringsinformationen för API-nyckeln.

API-nyckelparametrar

Etiketten visas när någon först skapar en anslutning till den anpassade anslutningen. Du kan välja redigera och ändra värdet. Parameternamnet och platsen måste matcha vad API:et förväntar sig i det här fallet "Ocp-Apim-Subscription-Key" och "rubrik".

Följande avsnitt i OpenAPI-definitionen innehåller information om den här sidan i användargränssnittet:

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

Granska definition av kopplingen

Sidan Definition för anpassade kopplingar har du många alternativ för att definiera funktioner för kopplingar och hur de exponeras i Logic Apps, flöden och appar. Vi förklarar användargränssnittet och täcker några alternativ i det här avsnittet, men vi uppmanar dig också att utforska på egen hand. Information om hur du definierar objekt från grunden i det här användargränssnittet finns i Skapa kopplingsdefinitionen.

I följande område visas eventuella åtgärder, utlösare (för Logic Apps och Power Automate) och referenser som har definierats för kopplingen. I det här fallet visas åtgärden DetectSentiment från OpenAPI-definition. Det finns inga utlösare i den här kopplingen, men du kan lära dig om utlösare för anpassade kopplingar i avsnittet använda webhooks med Azure Logic Apps och Power Automate.
I området Allmänt visas information om den markerade åtgärden eller utlösaren. Du kan redigera informationen här, inklusive egenskapen för synlighet för åtgärder och parametrar i en logikapp eller ett flöde:
- inget: visas normalt i logikappen eller flödet.
- avancerat: dolt under ytterligare en meny
- internt: från användaren
- viktigt: visas alltid först för användaren.
Området Begäran visar information baserat på en HTTP-begäran som ingår i OpenAPI-definition. I det här fallet ser du att HTTP verb är POST och URL är "/text/analytics/v2.0/sentiment" (den fullständiga URL:en till API:et är "https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment"). Vi ska titta närmare på parametern brödtext inom kort.

Följande avsnitt i OpenAPI-definitionen innehåller information för området Allmän och Begäran i användargränssnittet:
```
"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"
```
Området Svar visar information baserat på en HTTP-svar som ingår i OpenAPI-definition. I det här fallet är det enda definierade svaret för ”200” (ett ”lyckades”-svar) men du kan definiera fler svar.

Följande avsnitt i OpenAPI-definitionen innehåller viss av den information som är relaterad till svaret:
```
"score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}
```
I det här avsnittet visas de två värden som returneras av kopplingen: id och score. Den innehåller datatyper och fältet x-ms-summary som är ett OpenAPI-tillägg. Mer information om detta och andra tillägg finns i utöka en OpenAPI-definition för en egen koppling.
I området Validering visas eventuella problem som identifierats i API-definitionen. Kontrollera det här området innan du sparar en anslutningsapp.

Uppdatera definitionen

Den OpenAPI-definition du har laddat ned är ett bra grundläggande exempel men du kanske arbetar med definitioner som kräver mycket uppdatering – så att anslutningen är mer användarvänlig när någon använder den i en logikapp, ett flöde eller en app. Du lär dig hur du gör en enkel ändring i definitionen.

Välj brödtext i området Begäran och välj sedan Redigera.
I området Parameter ser du nu de tre parametrarna som förväntas av API:et: ID, Language och Text. Välj ID och sedan Redigera.
Gå till området Schemaegenskap, uppdatera beskrivningen för parametern och välj sedan Tillbaka.

Parameter Värde

Beskrivning ”En numerisk identifierare för varje dokument som du skickar”.
I området Parameter, välj Tillbaka för att gå tillbaka till huvudsidan för definitionen.
Välj Uppdatera kopplingen längst upp i guiden.

Parameter	Värde
Beskrivning	”En numerisk identifierare för varje dokument som du skickar”.

Hämta den uppdaterade OpenAPI-filen

Du kan skapa en anpassad koppling från en OpenAPI-fil, en Postman-samling eller från början (i Power Automate och Power Apps). Oavsett hur du skapar anslutningen kan du ladda ned OpenAPI-definitionen som tjänsten använder internt.

Ladda ned från den anpassade anslutningen i Logic Apps.
I Power Automate eller Power Apps kan du hämta från listan över anpassade kopplingar.

Testa anslutningsprogrammet

Nu när du har skapat kopplingen kan du testa den och kontrollera att den fungerar. Testning är för närvarande endast tillgänglig i Power Automate och Power Apps.

Viktigt

När du använder en API-nyckel rekommenderar vi att du inte testar kopplingen direkt efter att du har skapat den. Det kan ta några minuter tills anslutningen är klar att ansluta till API.

Välj Ny anslutning på sidan Test.
Ange API-nyckeln från API: et för textanalys och välj sedan Skapa anslutning.
Gå tillbaka till testsidan:
- I Microsoft Flow återgår du till sidan Test. Välj uppdateringsikonen för att kontrollera att anslutningsinformationen är uppdaterad.
- I Power Apps kommer du till listan över anslutningar som är tillgängliga i den aktuella miljön. Välj kugghjulsikonen i det övre högra hörnet och välj sedan Anpassade anslutningsprogram. Välj kopplingen som du skapade och gå sedan tillbaka till sidan Test.
På sidan Test, ange ett värde för fältet text (i de andra fälten används de standardvärden du angav tidigare) och välj sedan Teståtgärd.
Anslutningen anropar API och du kan granska svaret, vilket inkluderar sentimentpoäng.