Skapa ett anpassat anslutningsprogram från grunden

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 från grunden, utan att använda Postman-samling eller en OpenAPI-definition för att beskriva API:et för attitydstextanalys i Cognitive Services (vårt exempel för den här serien). I stället beskrivs anslutningen helt i guiden för anpassad koppling.

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

• Skapa ett anpassat anslutningsprogram från en OpenAPI-definition
• Skapa ett anpassat anslutningsprogram från en Postman-samling

Förutsättningar

• En API-nyckel för API:et för textanalys i Cognitive Services
• En av följande prenumerationer:
  • Power Automate
  • Power Apps

Starta guiden för anpassad koppling

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

2. I navigeringsfönstret väljer du Data > Anpassade anslutningsprogram.

   

3. Välj Nytt anpassat anslutningsprogram och välj sedan Skapa från början.

   

4. Ange ett namn för det anpassade anslutningsprogrammet och välj sedan Fortsätt.

   

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

Steg 1: Uppdatera allmän information

Härifrån visar vi Power Automate-användargränssnittet men stegen är i stort sett desamma för alla tekniker. Vi pekar på alla skillnader.

1. PÅ sidan Allmänt:

   • Ange ett beskrivande värde för Beskrivning. Den här beskrivningen visas i den anpassade kopplingens information och den kan hjälpa andra att avgöra om kopplingen kan vara användbar för dem.

   • Uppdatera värd till adressen för textanalys-API. Anslutningsprogrammet använder API-värden och den grundläggande URL:en för att fastställa hur API:et ska anropas.

   

   Parameter	Värde
   Beskrivning	Använder API:et för attitydstextanalys i Cognitive Services för att fastställa om texten är positiv eller negativ.
   Värd	"westus.api.cognitive.microsoft.com"

   Anteckning

   Mer information om alternativet Anslut via lokal datagateway finns i Anslut till lokala API:er med datagateway.

Steg 2: Ange 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 för att det ska vara vad du anger för den här självstudien.

1. På sidan Säkerhet, under Autentiseringstyp väljer du API-nyckel.

   

2. Ange ett parameteretikett, namn och plats under API-nyckel. Ange en beskrivande etikett, eftersom den visas första gången som någon ansluter med det anpassade anslutningsprogrammet. Parameternamnet och sökvägen måste överensstämma med vad API:n förväntar sig. Välj Anslut.

   

   Parameter	Värde
   Parameteretikett	"API-nyckel"
   Parameternamn	"Ocp-Apim-Subscription-Key"
   Parameterplats	"Rubrik"

3. Längst upp i guiden, kontrollera att namnet är inställt på "SentimentDemo", välj sedan Skapa anslutning.

Steg 3: Skapa definition för anslutningsprogram

Den anpassade anslutningsguiden innehåller många alternativ för hur du definierar anslutningsprogrammets funktioner och hur den 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.

Skapa en åtgärd

Det första du gör är att skapa en åtgärd som anropar API:et för attitydstextanalys.

1. På sidan Definition visas i det vänstra området eventuella åtgärder, utlösare (för Logic Apps och Power Automate) och referenser som har definierats för kopplingen. Välj Ny åtgärd.

   

   Det finns inga utlösare i detta anslutningsprogram. Du lär dig mer om utlösare för anpassade anslutningsprogram i Använda webhooks med Azure Logic Apps och Power Automate.

2. I området Allmänt visas information om den markerade åtgärden eller utlösaren. Lägg till en sammanfattning, beskrivning och åtgärds-ID för den här åtgärden.

   

   Parameter	Värde
   Sammanfattning	"Returnerar ett numeriskt värde som representerar det sentiment som identifieras"
   Beskrivning	"API:n returnerar en numerisk poäng mellan 0 och 1. Poäng nära 1 visar en positiv attityd, medan en poäng nära 0 indikerar en negativ attityd."
   Åtgärds-ID	"IdentifieraSentiment"

   Låt egenskapen Synlighet anges till ingen. Egenskapen för åtgärder och parametrar i en logikapp eller flöde har följande alternativ:

   • inget: visas normalt i logikappen eller flödet.
   • avancerat: dold under en annan meny
   • internt: från användaren
   • viktigt: visas alltid först för användaren.

3. I området begäran visas information som baseras på HTTP-begäran för åtgärden. Välj Importera från exempel.

   

4. Ange den information som krävs för att ansluta till API:et, och begärans brödtext, välj sedan Import. Vi tillhandahåller den här informationen för dig (under bilden). För ett offentligt API-gränssnitt får du vanligtvis från dokumentationen, t.ex. API:et för attitydstextanalys.

   

   Parameter	Värde
   Verb	"SKICKA"
   URL	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Brödtext	Se nedan

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. I området Svar visas information som baseras på HTTP-svar för åtgärden. Välj Lägg till standardsvar.

   

6. Ange svarstexten och välj sedan importera. På samma sätt som med förfrågan tillhandahåller vi den här informationen åt dig, men finns oftast i API-dokumentationen.

   

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

7. I området Validering visas eventuella problem som identifierats i API-definitionen. Kontrollera status och välj sedan Uppdatera koppling längst upp till höger i guiden.

   

Uppdatera definitionen

Nu ska vi ändra några saker så att anslutningsappen är mer användarvänlig när någon använder den i en logikapp, ett flöde eller en app.

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

   

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

   

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

   

4. I området Parameter väljer du språk sedan Redigera. Upprepa processen som du använde för id med följande värden.

   Parameter	Värde
   Rubrik	"Språk"
   Beskrivning	”Språkkoden med 2 eller 4 tecken för texten”.
   Standardvärde	"en"
   Obligatoriskt	"Ja"

5. I området Parameter väljer du text sedan Redigera. Upprepa processen som du använde för id och language med följande värden.

   Parameter	Värde
   Rubrik	"Text"
   Beskrivning	”Text att analysera för attityd”.
   Standardvärde	Nej
   Obligatoriskt	"Ja"

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

7. Välj Uppdatera kopplingen längst upp i guiden.

Steg 4: (Valfritt) Använd anpassad kodsupport

Med anpassad kod omvandlas begärans- och svarsnyttolaster utanför omfånget för befintliga principmallar. Omvandlingar omfattar att skicka externa förfrågningar för att hämta ytterligare data. När kod används får den prioritet framför den kodlös definitionen. Det innebär att koden körs och vi skickar inte förfrågan till serverdel.

Du kan antingen klistra in koden eller överföra en fil med koden. Din kod måste uppfylla följande krav:

• Skrivas i C#.
• Ha en maximal körtid på 5 sekunder.
• Får inte vara mer än 1 MB (storleken på kodfilen).

Instruktioner och exempel på hur du skriver kod finns i Skriva kod i anpassade anslutningsprogram.

Vanliga frågor och svar om anpassad kod finns på Vanliga frågor och svar om anpassad kod.

1. Infoga din egen kod på sidan kod med något av följande alternativ:

   • Kopiera/klistra in eller
   • Välj knappen Ladda upp.

   Om du väljer att överföra din egen kod är endast filer med filnamnstillägget .cs eller .csx tillgängliga.

   
   

   Viktigt

   För tillfället finns det bara stöd för syntax som används i kodredigeraren. Kontrollera att du testar koden lokalt.

2. När du har klistrat in eller överför koden aktiverar du koden genom att markera låstangenten bredvid Kod inaktiverad. Växlingsnamnet ändras till Kod aktiverad.

   Du kan aktivera eller inaktivera koden när som helst. Om växlingen är Kod inaktiverad tas koden bort.

   

3. Välj de åtgärder och utlösare som ska tillämpas på din anpassade kod genom att välja ett alternativ i listrutan. Om ingen åtgärd har markerats tillämpas den på alla åtgärder.

   

Steg 5: 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.

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

   

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

   

3. Gå tillbaka till testsidan:

   • I Power Automate å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. I navigeringsfönstret väljer du Data > Anpassat anslutningsprogram. Välj kopplingen som du skapade och gå sedan tillbaka till sidan Test.

     

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.

   

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

   

(För CLI-användare) Bästa praxis

• Ladda ned alla anpassade anslutningsappar och använd git eller andra kodhanteringssystem för att spara filerna.

• Om det finns en felaktig uppdatering, distribuera om anslutningen genom att köra uppdateringskommandot igen med rätt uppsättning filer från källkodshanteringssystemet.

• Testa det anpassade anslutningsprogrammet och inställningsfilen i en testmiljö innan du distribuerar i produktionsmiljön.

• Kontrollera alltid att miljö- och anslutningsprogram-ID är korrekta.

Nästa steg

Nu när du skapat en anpassad anslutning och definierat dess beteenden kan använda du anslutningen från:

• Ett flöde.
• En app.
• En logisk app

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 koppling
• Certifiera ditt anslutningsprogram