Dela via

Skapa ett anpassat anslutningsprogram från en OpenAPI-definition

  • Artikel

Obs

Den här artikeln är en del av en självstudieserie om hur du skapar och använder anpassade anslutningsappar i Azure Logic Apps Microsoft Power Automate och Microsoft Power Apps hur du använder AI-aktiverade anslutningsappar i Microsoft Copilot Studio. Se till att du läser översikten över anpassade anslutningsprogram för att förstå processen. Gå till Använd Power Platform anslutningsprogram i Copilot Studio för att lära dig hur du kan anropa anslutningsprogrammen som anslutningsåtgärder i din Microsoft Copilot handläggare.

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

Ett annat sätt att beskriva ett API finns i Skapa en anpassad anslutningsapp från grunden.

Förutsättningar

  • En OpenAPI definition som beskriver exempel-API:et. 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. Skapande av anpassad anslutningsapp stöder inte klientautentiseringsuppgifter (till exempel program och lösenord) i OAuth säkerhetsdefinitionen.

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

  • En av följande prenumerationer:

  • Om du använder Logic Apps skapar du först en anpassad anslutningsapp 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 OpenAPI importera definitionen för Logic Apps eller för Power Automate och Power Apps.

Obs

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 Portal och öppna Logic Apps-anslutningsappen som du skapade tidigare i Skapa en anpassad Azure Logic Apps-anslutningsapp.

  2. I anslutningsappens meny väljer du Logic Apps Connector och sedan Redigera.

    Redigera Logic Apps-anslutningsprogram.

  3. Under Allmänt väljer du Ladda upp en OpenAPI fil och går sedan till den OpenAPI definition som du skapade.

    Överför OpenAPI fil.

Obs

Den här självstudien fokuserar på ett REST API, men du kan också 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. I den vänstra rutan väljer du Anpassade anslutningsappar> för data.

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

  4. Ange ett namn för det anpassade anslutningsprogrammet, gå till definitionen OpenAPI som du laddade ned eller skapade 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. Längst upp i guiden kontrollerar du att namnet är inställt på SentimentDemo och väljer sedan Skapa anslutningsapp.

  2. På sidan Allmänt granskar du informationen som importerades från definitionen OpenAPI , inklusive API-värden och bas-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.

    Standardsida för anpassad anslutning.

    Obs

    Mer information om hur du ansluter till lokala API:er finns i Anslut till lokala API:er med hjälp av 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 upprättar en anslutning med den anpassade kopplingen. Du kan välja Redigera och ändra det här 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 Header.

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

Sidan Definition i guiden för anpassat anslutningsprogram ger dig många alternativ för att definiera hur anslutningsprogrammet fungerar och hur det exponeras 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 anslutningsdefinitionen.

  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 det här fallet DetectSentiment visas åtgärden från definitionen OpenAPI . Det finns inga utlösare i den här anslutningsappen, men du kan lära dig mer om utlösare för anpassade anslutningsappar i Använda webhooks med Azure Logic Apps och Power Automate.

    Definitionssida – åtgärder och utlösare.

  2. I området Allmänt visas information om den åtgärd eller utlösare som för närvarande är markerad. Du kan redigera informationen här, inklusive egenskapen Synlighet för åtgärder och parametrar i en logikapp eller ett flöde:

    • Ingen: Visas normalt i logikappen eller flödet

    • Avancerat: Gömd under en extra meny

    • internt: dolt för användaren

    • Viktigt: Visas alltid för användaren först

      Definitionssida – allmän.

  3. Området Begäran visar information baserat på den HTTP-begäran som ingår i definitionen OpenAPI . I det här fallet ser du att HTTP-verbet är POST, och URL:en is /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 kommer att titta närmare på kroppsparametern inom kort.

    Definitionssida – begäran.

    Följande avsnitt i OpenAPI definitionen innehåller information om områdena General och Request 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"

  4. Området Svar visar information baserat på det HTTP-svar som ingår i definitionen OpenAPI . I det här fallet är det enda definierade svaret för 200 (ett lyckat 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"
}

    I det här avsnittet visas de två värden som returneras av anslutningsappen: id and score. Den innehåller deras 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 anpassad anslutningsapp.

  5. I området Validering visas alla problem som har identifierats 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. I området Begäran väljer du brödtext och sedan Redigera.

    Redigera brödtext.

  2. I området Parameter ser du nu de tre parametrar som API:et förväntar sig: ID, Language, och Text. Välj ID och välj sedan Redigera.

    Redigera brödtext-ID.

  3. I området Schemaegenskap uppdaterar du beskrivningen för parametern och väljer sedan Tillbaka.

    Redigera schemaegenskapen.

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

  4. I området Parameter väljer du Tillbaka för att ta dig tillbaka till huvuddefinitionssidan.

  5. I det övre högra hörnet i guiden väljer du Uppdatera anslutningsapp.

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. På sidan Test väljer du Ny anslutning.

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

  3. Gå tillbaka till sidan Testoch gör något av följande:

    • In Power Automate tas du tillbaka 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. I det övre högra hörnet väljer du kugghjulsikonen och sedan Anpassade anslutningsappar. Välj den anslutningsapp som du skapade och gå sedan tillbaka till sidan Test .

      Växel ikon i tjänst.

  4. På sidan Test anger du ett värde för textfältet (de andra fälten använder de standardvärden som du angav tidigare) och väljer sedan Teståtgärd.

    Teståtgärd.

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

    Svar från anslutningsprogram.

Använda den anpassade anslutningsappen

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

Skapa ett anpassat anslutningsprogram och en anslutningsåtgärd för Microsoft 365 Copilot för försäljning

Du kan skapa en anpassad anslutningsapp från en OpenAPI definition i Power Apps eller Power Automate som sedan kan användas för Microsoft 365 Copilot for Sales. Gå till Skapa ett anpassat anslutningsprogram och anslutningsåtgärd för att lära dig hur du kommer igång.

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 anslutningsplattform eller nya funktioner. Om du vill ge feedback går du till Skicka problem eller får hjälp med anslutningsprogram och väljer din feedbacktyp.