Skapa ett anpassat anslutningsprogram från en OpenAPI-definition

  • Artikel

Anteckning

Detta ämne ingår i självstudier kring hur man skapar och använder anpassade anslutningsprogram i Azure Logic Apps, Microsoft Power Automate och Microsoft Power Apps. Se till att du läser översikt för anpassat anslutningsprogram för att förstå processen.

Om du vill skapa ett anpassat anslutningsprogram måste du beskriva det API du vill ansluta till, detta så att anslutningsprogrammet förstår API:ts åtgärder och datastrukturer. I detta ämne skapar du ett anpassat anslutningsprogram med hjälp av en OpenAPI-definition som beskriver sentiment-API för textanalys för Cognitive Services (vårt exempel för denna serie).

För ett annat sätt att beskriva ett API, gå till Skapa en anpassad anslutningsapp från grunden

Förutsättningar

  • En OpenAPI-definition som beskriver exemplets API. När du skapar ett anpassat anslutningsprogram måste OpenAPI-definitionen vara mindre än 1 MB. OpenAPI-definitionen måste vara i formatet för OpenAPI 2.0 (tidigare kallat "Swagger").

    Om det finns flera säkerhetsdefinitioner väljer det anpassade anslutningsprogrammet den högsta säkerhetsdefinitionen. När du skapar ett anpassat anslutningsprogram har det inte stöd för klientautentiseringsuppgifter (till exempel app och lösenord) i säkerhetsdefinitionen i OAuth.

  • En API-nyckel för textanalys-API för Cognitive Services.

  • En av följande prenumerationer:

  • Om du använder Logic Apps skapar du först ett anpassat anslutningsprogram för Azure Logic Apps.

Importera OpenAPI-definitionen

Du är nu redo att arbeta med den OpenAPI-definition du hämtade. All erforderlig information inkluderas i definitionen, och du kan visa och uppdatera denna information i takt med att du går igenom guiden för anpassade anslutningsprogram.

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

Anteckning

En OpenAPI-definition måste vara i formatet för OpenAPI 2.0 (tidigare kallat "Swagger"). OpenAPI-definitioner i formatet för OpenAPI 3.0 stöds inte.

Importera OpenAPI-definitionen för Logic Apps

  1. Gå till Azure-portalen och öppna det anslutningsprogram för Logic Apps som du tidigare skapade i Skapa ett anpassat anslutningsprogram för Azure Logic Apps.

  2. I menyn för ditt anslutningsprogram väljer du Logic Apps-anslutningsprogram och sedan Redigera.

    Redigera Logic Apps-anslutningsprogram.

  3. Under Allmänt väljer du Ladda upp en OpenAPI-fil innan du går till den OpenAPI-definition som du skapat.

    Överför OpenAPI fil.

Anteckning

Dessa självstudier fokuserar på ett REST-API, men du kan även använda ett SOAP-API med Logic Apps.

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

  1. Logga in på Power Apps eller Power Automate.

  2. På vänstra panelen väljer du Data > Anpassade anslutningar.

    Välj anpassat anslutningsprogram.

  3. Välj Nytt anpassat anslutningsprogram och sedan Importera en OpenAPI-fil.

    Importera en OpenAPI fil.

  4. Ange ett namn för det anpassade anslutningsprogrammet, gå sedan till den OpenAPI-definition som du hämtat eller skapat, och välj sedan Fortsätt.

    Ladda upp en samling.

    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 denna del av ämnet ska vi huvudsakligen granska användargränssnittet och visa dig hur värdena motsvarar delar av OpenAPI-filen.

  1. Högst upp i guiden ser du till att namnet angetts som SentimentDemo innan du väljer Skapa anslutningsprogram.

  2. På sidan Allmänt granskar du den information som importerats från OpenAPI-definitionen, inklusive API-värd och bas-URL för API:t. Anslutningsprogrammet använder API-värden och den grundläggande URL:en för att fastställa hur API:et ska anropas.

    Standardsida för anpassad anslutning.

    Anteckning

    Mer information om att ansluta till lokala API:er finns i Anslut till lokala API:er via datagatewayen.

    Följande avsnitt av OpenAPI-definitionen innehåller information för denna användargränssnittsida:

      "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. API:erna för Cognitive Services använder API-nyckelautentiseringer, varför detta anges i OpenAPI-definitionen.

På sidan Säkerhet granskar du 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. Parameterns namn och plats måste matcha det som API:n förväntar sig, i detta fall Ocp-Apim-Subscription-Key och Rubrik.

Följande avsnitt av OpenAPI-definitionen innehåller information för denna användargränssnittsida:

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

Granska anslutningsprogrammets definition

På sidan Definition i guiden för anpassade anslutningsprogram finns många alternativ för hur du definierar hur anslutningsprogrammet fungerar och hur det visas i logikappar, 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 definitionen av anslutningsprogrammet.

  1. Följande område visar eventuella åtgärder, utlösare (för Logic Apps och Power Automate) och referenser som definierats för anslutningsprogrammet. I detta fall visas åtgärden DetectSentiment från OpenAPI-definitionen. Det finns inga utlösare i detta anslutningsprogram,men du kan lära dig mer om utlösare för anpassade anslutningsprogram i Använd webhooks med Azure Logic Apps och Power Automate.

    Definitionssida – åtgärder och utlösare.

  2. 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.

      Definitionssida – allmän.

  3. Området Begäran visar information baserad på den HTTP-begäran som medföljer OpenAPI-definition. I detta fall ser du att verbet för HTTP är POST och att URL:en är /text/analytics/v2.0/sentiment (den kompletta URL:en är <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Vi kommer strax att titta närmare på parametern brödtext.

    Definitionssida – begäran.

    Följande avsnitt av OpenAPI-definitionen innehåller information för användargränssnittsområdena Allmänt och Begäran:

    "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. Området Svar visar information baserad på det HTTP-svar som medföljer OpenAPI-definitionen. I detta fall har det enda svaret definierats för 200 (ett framgångsrikt svar), men du kan definiera ytterligare svar.

    Definitionssida - svar.

    Följande avsnitt av OpenAPI-definitionen innehåller en del av informationen relaterad till svaret:

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

    Detta avsnitt beskriver de två värden som returneras av anslutningsprogrammet: id och score. Det omfattar dessas datatyper samt 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 ett anpassat anslutningsprogram.

  5. Området Validering visar de eventuella problem som upptäckts i API-definitionen. Se till att kontrollera detta område innan du sparar ett anslutningsprogram.

    Definitionssida - validering.

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.

  1. Välj brödtext i området Begäran och välj sedan Redigera.

    Redigera brödtext.

  2. I området Parameter ser du nu de tre parametrarna som förväntas av API:et: ID, Language och Text. Markera ID och sedan redigera.

    Redigera brödtext-ID.

  3. Gå till området Schemaegenskap, uppdatera beskrivningen för parametern och välj sedan Tillbaka.

    Redigera schemaegenskapen.

    Parameter Värde
    Description En numerisk identifierare för varje dokument som du skickar

  4. I området Parameter, välj Tillbaka för att gå tillbaka till huvudsidan för definitionen.

  5. Välj i det övre högra hörnet av guiden Uppdatera anslutningsprogram.

Hämta uppdaterad OpenAPI-fil

Du kan skapa en anpassad koppling från en OpenAPI-filen eller från början (i Power Automate och Power Apps). Oavsett hur du skapar anslutningsprogrammet kan du hämta den OpenAPI-definition som tjänsten använder internt.

  • I Logic Apps laddar du ned från det anpassade anslutningsprogrammet.

    Ladda ned OpenAPI-definition för Logic Apps.

  • I Power Automate eller Power Apps laddar du ned från listan över anpassade anslutningsprogram.

    Ladda ned OpenAPI-definitionen för Power Automate.

Testa anslutningsprogrammet

Nu när du har skapat anslutningsprogrammet testar du det i syfte att se till att det fungerar korrekt. Testning är för närvarande endast tillgänglig i Power Automate och Power Apps.

Viktigt

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

  1. Välj Ny anslutning på sidan Test.

    Ny anslutning.

  2. Ange API-nyckeln från API: et för textanalys och välj sedan Skapa anslutning.

    Skapa anslutning.

  3. Gå tillbaka till fliken Testa sida och gör något av följande:

    • I Power Automate återgår du till sidan Test. Välj uppdateringsikonen för att kontrollera att anslutningsinformationen är uppdaterad.

      Uppdatera anslutning.

    • I Power Apps kommer du till listan över anslutningar som är tillgängliga i den aktuella miljön. Välj växelikonen i det övre högra hörnet, välj Anpassade anslutningsprogram. Välj anslutningsprogrammet som du skapade och gå sedan tillbaka till sidan Test.

      Växel ikon i tjänst.

  4. 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.

    Teståtgärd.

  5. Anslutningsprogrammet anropar API och du kan granska svaret, vilket inkluderar sentimentpoäng.

    Svar från anslutningsprogram.

Nästa steg

Nu när du skapat ett anpassat anslutningsprogram och definierat dess beteenden kan du använda anslutningsprogrammet.

Du kan också dela en anslutning i din organisation och/eller få anslutningen certifierad så att personer utanför organisationen kan använda den.

Ge feedback

Vi uppskattar feedback på problem med vår plattform för anslutningsprogram eller förslag på nya funktioner. Om du vill lämna feedback går du till Skicka problem eller få hjälp med anslutningsprogram och väljer typ av feedback.