Skapa ett anpassat anslutningsprogram från en OpenAPI-definition
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:
- 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
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
Gå till Azure Portal och öppna Logic Apps-anslutningsappen som du skapade tidigare i Skapa en anpassad Azure Logic Apps-anslutningsapp.
I anslutningsappens meny väljer du Logic Apps Connector 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.
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
Logga in på Power Apps eller Power Automate.
I den vänstra rutan väljer du Anpassade anslutningsappar> för data.
Välj Nytt anpassat anslutningsprogram och välj sedan Importera en OpenAPI fil.
Ange ett namn för det anpassade anslutningsprogrammet, gå till definitionen OpenAPI som du laddade ned eller skapade och välj sedan Fortsätt.
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.
Längst upp i guiden kontrollerar du att namnet är inställt på SentimentDemo och väljer sedan Skapa anslutningsapp.
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.
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 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.
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.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
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"
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
andscore
. Den innehåller deras datatyper och fältetx-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.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.
I området Begäran väljer du brödtext och sedan Redigera.
I området Parameter ser du nu de tre parametrar som API:et förväntar sig:
ID
,Language
, ochText
. Välj ID och välj sedan Redigera.I området Schemaegenskap uppdaterar du beskrivningen för parametern och väljer sedan Tillbaka.
Parameter Värde Description En numerisk identifierare för varje dokument som du skickar I området Parameter väljer du Tillbaka för att ta dig tillbaka till huvuddefinitionssidan.
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.
I Power Automate eller Power Apps laddar du ned från listan över anpassade anslutningsprogram.
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.
På sidan Test väljer du Ny anslutning.
Ange API-nyckeln från API:et för textanalys och välj sedan Skapa anslutning.
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 sedan Anpassade anslutningsappar. Välj den anslutningsapp som du skapade och gå sedan tillbaka till sidan Test .
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.
Anslutningsprogrammet anropar API och du kan granska svaret, vilket inkluderar sentimentpoäng.
Använda den anpassade anslutningsappen
Nu när du skapat ett anpassat anslutningsprogram och definierat dess beteenden kan du använda anslutningsprogrammet.
- Använda en anpassad anslutningsapp i Power Automate
- Använda en anpassad anslutningsapp i Power Apps
- Använda en anpassad anslutningsapp i en 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 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.