Megosztás a következőn keresztül:

Egyéni összekötő létrehozása OpenAPI-definíció alapján

Feljegyzés

Ez a cikk egy oktatóanyag-sorozat része, amely az egyéni összekötők létrehozását és használatát Azure Logic Apps, Microsoft Power Automate valamint Microsoft Power Apps AI-kompatibilis összekötők használatát mutatja be Microsoft Copilot Studio. A folyamat megértéséhez olvassa el az egyéni összekötő áttekintését . Az Összekötők használata a következőben Power Platform című témakörből Copilot Studio megtudhatja, hogyan hívhatja meg az összekötőket összekötő-műveletekként az ügynökben Microsoft Copilot .

Egyéni összekötő létrehozásához le kell írnia az API-t, amelyhez csatlakozni kíván, hogy az összekötő megértse az API műveleteit és adatstruktúráját. Ebben a témakörben egy egyéni összekötőt hoz létre egy OpenAPI olyan definícióval, amely leírja a Cognitive Services Text Analytics Sentiment API-t (a sorozat példáját).

Az API-k leírásának másik módjáért tekintse meg az Egyéni összekötő létrehozása az alapoktól című témakört.

Előfeltételek

  • A OpenAPI példa API-t leíró definíció. Egyéni összekötő létrehozásakor a OpenAPI definíciónak 1 MB-nál kisebbnek kell lennie. A OpenAPI definíciónak 2.0 (korábbi nevén Swagger) formátumúnak OpenAPI kell lennie.

    Ha több biztonsági definíció van, az egyéni összekötő a felső biztonsági definíciót választja. Az egyéni összekötő létrehozása nem támogatja az ügyfél hitelesítő adatait (például az alkalmazást és a jelszót) a biztonsági definícióban OAuth .

  • Egy API-kulcs a Cognitive Services Text Analytics API-hoz.

  • Az alábbi előfizetések egyike:

  • Ha Logic Apps használ, először hozzon létre egy Azure Logic Apps egyéni összekötőt.

A definíció importálása OpenAPI

Most már készen áll a OpenAPI letöltött definíció használatára. Az összes szükséges információ szerepel a definícióban, és áttekintheti és frissítheti ezeket az adatokat az egyéni összekötő varázsló lépéseit követve.

Először importálja a Logic Apps OpenAPI definícióját, vagy a és a definícióját Power Automate . Power Apps

Feljegyzés

A OpenAPI definíciónak 2.0 (korábbi nevén Swagger) formátumúnak OpenAPI kell lennie. OpenAPI A 3.0 formátumú OpenAPI definíciók nem támogatottak.

A Logic Apps definíciójának OpenAPI importálása

  1. Nyissa meg a Azure Portal, és nyissa meg a korábban létrehozott Logic Apps-összekötőt az Egyéni Azure Logic Apps-összekötő létrehozása.

  2. Az összekötő menüjében válassza a Logic Apps Connector, majd a Szerkesztés lehetőséget.

    Logic Apps-összekötő szerkesztése.

  3. Az Általános alattválassza a Fájl feltöltése OpenAPI lehetőséget, majd lépjen a OpenAPI létrehozott definícióra.

    Fájl feltöltése OpenAPI .

Feljegyzés

Ez az oktatóanyag egy REST API-ra összpontosít, de SOAP API-t is használhat a Logic Apps.

A definíció importálása OpenAPI és Power Automate Power Apps

  1. Jelentkezzen be a Power Apps vagy Power Automate oldalra.

  2. A bal oldali panelen válassza az Egyéni adatösszekötők > lehetőséget.

  3. Válassza az Új egyéni összekötő, majd a Fájl importálása OpenAPI lehetőséget.

  4. Adja meg az egyéni összekötő nevét, lépjen a OpenAPI letöltött vagy létrehozott definícióra, majd válassza a Folytatás lehetőséget.

    Töltsön fel egy gyűjteményt.

    Paraméter Érték
    Egyéni összekötő neve SentimentDemo

Általános adatok áttekintése

A leírás innentől a Power Automate felhasználói felületére vonatkozik, azonban a lépések nagyjából megegyeznek mindhárom technológia esetében. Az esetleges különbségekre rámutatunk. A témakör ezen részében többnyire a felhasználói felületet tekintjük át, és bemutatjuk, hogy az értékek hogyan felelnek meg a OpenAPI fájl szakaszainak.

  1. A varázsló tetején győződjön meg arról, hogy a név SentimentDemo értékre van állítva, majd válassza az Összekötő létrehozása lehetőséget .

  2. Az Általános lapon tekintse át a OpenAPI definícióból importált információkat, beleértve az API-gazdagépet és az API alap URL-címét. Az összekötő az API-gazda és az alapvető URL-cím segítségével állapítja meg, hogyan hívja meg az API-t.

    Egyéni összekötő Általános lap.

    Feljegyzés

    A helyszíni API-khoz való csatlakozással kapcsolatos további információkért tekintse meg a Csatlakozás helyszíni API-khoz az adatátjáró használatával.

    A definíció következő szakasza OpenAPI a felhasználói felület ezen oldalára vonatkozó információkat tartalmazza:

      "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"
  ]

Hitelesítési típus áttekintése

Az egyéni összekötőkben többféle hitelesítési lehetőség is elérhető. A Cognitive Services API-k API-kulcsos hitelesítést használnak, így ez van megadva a definícióban OpenAPI .

A Biztonság lapon tekintse át az API-kulcs hitelesítési adatait.

API-kulcs paraméterei.

A címke akkor jelenik meg, amikor valaki először létesít kapcsolatot az egyéni összekötővel; válassza a Szerkesztés lehetőséget , és módosítsa ezt az értéket. A paraméter nevének és helyének meg kell egyeznie az API által elvárt értékkel, ebben az esetben Ocp-Apim-Subscription-Key és Header .

A definíció következő szakasza OpenAPI a felhasználói felület ezen oldalára vonatkozó információkat tartalmazza:

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

Az összekötő definíciójának áttekintése

Az egyéni összekötő varázsló Definíció lapján számos lehetőség található annak meghatározására, hogy az összekötő hogyan működik, és hogyan érhető el a logikai alkalmazásokban, folyamatokban és alkalmazásokban. Ismertetjük a felhasználói felületet, és bemutatunk néhány lehetőséget ebben a szakaszban, de arra is javasoljuk, hogy saját maga is fedezze fel. Az objektumok nulláról történő definiálásával kapcsolatos információkért tekintse meg az összekötő definíciójának létrehozását.

  1. A következő területen jelennek meg az összekötőhöz definiált műveletek, eseményindítók (a Logic Apps és a Power Automate esetében) és hivatkozások. Ebben az esetben a DetectSentiment definíció művelete OpenAPI jelenik meg. Ebben az összekötőben nincsenek eseményindítók, de az egyéni összekötők eseményindítóiról a Webhookok használata Azure Logic Apps és Power Automate.

    Definíciós oldal - műveletek és triggerek.

  2. Az Általános terület az aktuálisan kiválasztott művelet vagy eseményindító adatait jeleníti meg. Itt szerkesztheti az információkat, beleértve a logikai alkalmazás vagy folyamat műveleteinek és paramétereinek Láthatósági tulajdonságát:

    • Nincs: Normál módon jelenik meg a logikai alkalmazásban vagy a folyamatban

    • Speciális: egy kiegészítő menü alatt rejtve

    • belső: rejtett a felhasználó elől

    • FONTOS: Mindig először a felhasználó számára jelenik meg

      Definíciós oldal - általános.

  3. A Kérelem terület a definícióban szereplő OpenAPI HTTP-kérés alapján jeleníti meg az információkat. Ebben az esetben azt látja, hogy a HTTP-művelet POST , az URL-cím pedig a következő/ text/analytics/v2.0/sentiment (az API <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment> teljes URL-címe). Hamarosan közelebbről megvizsgáljuk a body paramétert.

    Definíciós oldal - kérés.

    A definíció következő szakasza OpenAPI a felhasználói felület Általános és Kérelemterületére vonatkozó információkat tartalmaz:

    "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. A Válasz terület a definícióban szereplő OpenAPI HTTP-válasz alapján jeleníti meg az információkat. Ebben az esetben az egyetlen definiált válasz a 200 (sikeres válasz), de további válaszokat is meghatározhat.

    Definíciós oldal - válasz.

    A definíció következő szakasza OpenAPI a válaszhoz kapcsolódó információk egy részét tartalmazza:

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

    Ez a szakasz az összekötő által visszaadott két értéket mutatja: id and score. Tartalmazza az adattípusaikat és a mezőt x-ms-summary, amely egy OpenAPI kiterjesztés. További információ erről és más bővítményekről: Definíció kiterjesztése OpenAPI egyéni összekötőhöz.

  5. Az Érvényesítés terület megjeleníti az API-definícióban észlelt problémákat. Az összekötő mentése előtt mindenképp tekintse át ezt a területet.

    Definíciós oldal - ellenőrzés.

A definíció frissítése

A OpenAPI letöltött definíció jó alapszintű példa, de előfordulhat, hogy olyan definíciókkal is dolgozik, amelyek sok frissítést igényelnek, hogy az összekötő barátságosabb legyen, ha valaki logikai alkalmazásban, folyamatban vagy alkalmazásban használja. Megmutatjuk, hogyan módosíthatja a definíciót.

  1. A Kérelem területen válassza a törzset, majd a Szerkesztés lehetőséget.

    Kérelem törzsének szerkesztése.

  2. A Paraméter területen megjelenik az API által várt három paraméter: ID,, Language és Text. Válassza az Azonosító, majd a Szerkesztés lehetőséget.

    Kérelem törzsének azonosítójának szerkesztése.

  3. A Sématulajdonság területen frissítse a paraméter leírását, majd válassza a Vissza lehetőséget.

    Sématulajdonság szerkesztése.

    Paraméter Érték
    Description Minden beküldött dokumentum numerikus azonosítója

  4. A Paraméter területen válassza a Vissza lehetőséget , hogy visszatérjen a fő definíciós oldalra.

  5. A varázsló jobb felső sarkában válassza az Összekötő frissítése lehetőséget.

Töltse le a frissített OpenAPI fájlt

Létrehozhat egyéni összekötőt fájlból OpenAPI vagy teljesen (in Power Automate és Power Apps). Függetlenül attól, hogy hogyan hozza létre az összekötőt, letöltheti a OpenAPI szolgáltatás által belsőleg használt definíciót.

  • A Logic Appsben az egyéni összekötőből töltheti le.

    Töltse le a OpenAPI Logic Apps definícióját.

  • A Power Automate vagy Power Apps szolgáltatásban töltse le az egyéni összekötők listájából.

    Töltse le a OpenAPI definíciót Power Automate.

Az összekötő tesztelése

Most, hogy létrehozta az összekötőt, tesztelje, hogy megfelelően működik-e. A tesztelés jelenleg csak a Power Automate és a Power Apps szolgáltatásokban érhető el.

Fontos

API-kulcs használata esetén javasoljuk, hogy ne tesztelje az összekötőt közvetlenül a létrehozása után. Eltarthat néhány percig, amíg a csatlakozó készen áll az API-hoz való kapcsolódásra.

  1. A Teszt lapon válassza az Új kapcsolat lehetőséget .

  2. Adja meg az API-kulcsot a Text Analytics API-ból, majd válassza a Kapcsolat létrehozása lehetőséget.

  3. Térjen vissza a Teszt lapra, és tegye a következők egyikét:

    • A rendszer Power Automate visszakerül a Teszt oldalra . Válassza a frissítés ikont, hogy megbizonyosodjon arról, hogy a kapcsolati adatok frissülnek.

      Kapcsolat frissítése.

    • A Power Apps szolgáltatásban a rendszer az aktuális környezetben elérhető kapcsolatok listájára lépteti vissza. A jobb felső sarokban válassza a fogaskerék ikont, majd az Egyéni összekötők lehetőséget. Válassza ki a létrehozott összekötőt, majd térjen vissza a Teszt lapra.

      Fogaskerék ikon a szolgálatban.

  4. A Teszt lapon adja meg a szövegmező értékét (a többi mező a korábban beállított alapértelmezett értékeket használja), majd válassza a Művelet tesztelése lehetőséget .

    Tesztelje a működést.

  5. Az összekötő meghívja az API-t, és Ön áttekintheti a választ, amely tartalmazza a hangulati pontszámot is.

    Összekötő válasza.

Az egyéni összekötő használata

Most, hogy létrehozott egy egyéni összekötőt, és definiálta annak működését, használatba is veheti az összekötőt.

Egyéni összekötő és összekötő művelet létrehozása a Microsoft 365 Copilot for Sales számára

Létrehozhat egy egyéni összekötőt egy OpenAPI definícióból Power Apps Power Automate , amely ezután használható a Copilot for Sales Microsoft 365 szolgáltatásban. Az első lépésekért tekintse meg az Egyéni összekötő és összekötő művelet létrehozását.

Megoszthat egy összekötőt a szervezeten belül, vagy minősítheti az összekötőt, hogy a szervezeten kívüli személyek is használhassák.

Visszajelzés küldése

Nagyra értékeljük az összekötőplatform problémáival kapcsolatos visszajelzéseket és az új funkciókkal kapcsolatos ötleteket. Ha visszajelzést szeretne küldeni, lépjen a Problémák elküldése vagy az összekötőkkel kapcsolatos segítség kérése elemre, és válassza ki a visszajelzés típusát.