Skapa ett anpassat anslutningsprogram från en OpenAPI-definition

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 det här avsnittet skapar du en anpassad anslutning utifrån en OpenAPI-definition som beskriver Cognitive Services Text Analytics Sentiment API (vårt exempel i den här serien).

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

Förutsättningar

• En OpenAPI-definition (OAD) 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 OpenAPI 2.0-format (tidigare kallat Swagger).

  Om det finns flera säkerhetsdefinitioner väljer det anpassade anslutningsprogrammet den högsta säkerhetsdefinitionen. Det går inte att skapa anpassade anslutningar med klientautentiseringsuppgifter (till exempel program-ID 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:

  • Azure, om du använder Logic Apps
  • Power Automate
  • Power Apps

• Om du använder Logic Apps skapar du först en anpassad anslutningsapp för Azure Logic Apps.

Importera OpenAPI-definitionen

I den här självstudien används ett exempel på en OpenAPI-definition för Cognitive Services Text Analytics Sentiment API. Om du vill följa med skapar du en lokal JSON-fil med namnet SentimentDemo.json och klistrar in följande OpenAPI 2.0-definition:

{
  "swagger": "2.0",
  "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"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  },
  "security": [{"api_key": []}],
  "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",
        "parameters": [{
          "in": "body",
          "name": "body",
          "schema": {
            "type": "object",
            "properties": {
              "documents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "string", "x-ms-summary": "id"},
                    "language": {"type": "string", "x-ms-summary": "language"},
                    "text": {"type": "string", "x-ms-summary": "text"}
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "documents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "score": {"type": "number", "format": "float", "description": "score", "x-ms-summary": "score"},
                      "id": {"type": "string", "description": "id", "x-ms-summary": "id"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Nu är du redo att importera den här OpenAPI-definitionen. Definitionen innehåller all nödvändig information. Du kan granska och uppdatera den här informationen när du går igenom guiden för anpassad anslutningsapp.

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

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.

   

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

   

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 Lösningar och öppnar sedan den lösning som du vill använda eller skapar en ny.

3. Välj Ny>Automation>Anpassad anslutning.

4. Välj Importera en OpenAPI-fil.

5. Ange ett namn för den anpassade anslutningsappen, välj den SentimentDemo.json fil som du skapade och välj sedan Fortsätt.

   

   Parameter	Värde
   Rubrik för anpassad anslutning	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 anslutning.

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

   

   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.

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 definitionen för anslutningsprogrammet

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 visas åtgärden DetectSentiment från OpenAPI-definitionen. 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.

   

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

     

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.

   

   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.

   

   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.

   

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.

   

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.

   

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

   

   Parameter	Värde
   Beskrivning	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 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.

  

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

  

Testa anslutningen

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.

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.

     

   • 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 väljer sedan Anpassade kopplingar. Välj det anslutningsprogram som du skapade och gå sedan tillbaka till sidan Test.

     

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.

   

5. Anslutningsappen anropar API:et och du kan granska svaret, som innehåller sentimentpoängen.

   

Använd den anpassade anslutningen

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

• Använd en anpassad anslutning i Power Automate
• Använd en anpassad anslutning i Power Apps
• Använd en anpassad anslutningsapp i Logic Apps
• Använd ett anpassat anslutningsprogram och en anslutningsåtgärd i Copilot Studio

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 för försäljning. Gå till Skapa ett anpassat anslutningsprogram och en anslutningsåtgärd om du vill veta 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.

• Dela din anslutning
• Certifiera din anslutning

Ge feedback

Vi uppskattar feedback på problem med vår anslutningsplattform eller nya funktioner. Om du vill ge feedback, går du till Rapportera problem eller få hjälp med anslutningsappar och väljer typ av feedback.