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

  • Cikk

Megjegyzés

Ez a témakör egy oktatóanyag-sorozat része, amely az egyéni összekötők az Azure Logic Apps, a Microsoft Power Automate és a Microsoft Power Apps szolgáltatásokban való létrehozását és használatát tárgyalja. A folyamat megértéséhez mindenképpen olvassa el az egyéni összekötők áttekintése című témakört.

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ör 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 sorozathoz készült példánk).

Az API-k leírásának egyéb módjaiért tekintse meg a következő témaköröket:

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átumban kell lennie OpenAPI .

    Ha több biztonsági definíció is van, az egyéni összekötő a legfontosabb biztonsági definíciót választja ki. 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) az OAuth biztonsági definícióban.

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

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

  • Logic Apps használata esetén először hozzon létre egy egyéni Azure Logic Apps-összekötőt.

A definíció importálása OpenAPI

Most már készen áll arra OpenAPI , hogy a letöltött definícióval dolgozzon. 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 definícióját a Logic Apps, vagy a OpenAPI és Power Automate . Power Apps

Megjegyzés

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

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

  1. Lépjen az Azure Portalra, és nyissa meg az Azure Logic Apps egyéni összekötőjének létrehozását ismertető szakaszban korábban létrehozott Logic Apps-összekötőt.

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

    Logic Apps összekötő szerkesztése.

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

    Fájl feltöltése OpenAPI lehetőségre.

Megjegyzés

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

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

  1. Nyissa meg make.powerapps.com vagy a flow.microsoft.com weboldalt.

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

    Válassza az egyéni összekötő lehetőséget.

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

    Importáljon egy OpenAPI fájlt.

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

    Töltse fel Postman-gyűjteményt.

    Paraméter Érték
    Egyéni összekötő címe 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 áttekintjük a felhasználói felületet, és megmutatjuk, 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 lapja.

    Megjegyzés

    A helyszíni API-khoz való csatlakozással kapcsolatos további információkért lásd: 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ával kapcsolatos információkat tartalmaz:

      "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 OpenAPI definícióban.

A Biztonság lapon tekintse át az API-kulcs hitelesítési információit.

API-kulcsparaméterek.

A címke akkor jelenik meg, amikor valaki először létesít kapcsolatot az egyéni összekötővel; kiválaszthatja a Szerkesztés lehetőséget, és módosíthatja 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 fejléc.

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

  "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ó lapja számos lehetőséget kínál az összekötő működésének és a logikai alkalmazásokban, folyamatokban és alkalmazásokban való elérhetővé tételének meghatározására. 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 teljes körű definiálásával kapcsolatos információkért ezen a felhasználói felületen az összekötő-definíció létrehozásacímű témakörben talál.

  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 OpenAPI definícióból származó művelet jelenik meg. Ebben az összekötőben nincsenek eseményindítók, az egyéni összekötőkben lévő eseményindítókról azonban a következő témakörben talál információkat: Webhookok használata az Azure Logic Apps és a Power Automate esetében.

    Definíciós oldal - műveletek és eseményindítók.

  2. Az Általános terület a kiválasztott művelettel vagy eseményindítóval kapcsolatos információkat jeleníti meg. Itt szerkesztheti is az információkat, beleértve műveletek és paraméterek Láthatóság tulajdonságát a logikai alkalmazásokban és folyamatokban:

    • nincs: normál esetben megjelenik a logikai alkalmazásban vagy folyamatban

    • fejlett: Egy további menü alatt elrejtve található

    • belső: A felhasználók elől rejtve van

    • fontos: mindig elsőként jelenik meg a felhasználó számára

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

  3. A Kérés terület a definícióban OpenAPI szereplő HTTP-kérésen alapuló információkat jeleníti meg. Ebben az esetben azt látja, hogy a HTTP-művelet POST , és az URL/text/analytics/v2.0/sentiment(az API teljes URL-címe <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). 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érés terü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ő HTTP-válasz alapján jeleníti meg az OpenAPI információkat. Ebben az esetben az egyetlen meghatározott válasz a 200-ra · vonatkozik (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 a csatlakozó által visszaadott két értéket jeleníti meg: id és score. Ez magában foglalja az adattípusokat é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ületen jelennek meg az API-definícióban észlelt problémák. Az összekötő mentése előtt mindenképp tekintse át ezt a területet.

    Definíciós oldal - érvényesíté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 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érés területen válassza a törzs lehetőséget, majd válassza a Szerkesztés lehetőséget ·.

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

  2. A Paraméter területen most az API által várt három paraméter látható: ID, Language és Text. Válassza az ID, majd a Edit lehetőséget.

    Kérés 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

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

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

A frissített OpenAPI fájl letöltése

Létrehozhat egyéni összekötőt egy OpenAPI fájlból, egy Postman-gyűjteményből vagy egy semmiből (az és-ben Power Automate Power Apps). Az összekötő létrehozásának módjától függetlenül 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 OpenAPI a definíciót a Logic Apps.

  • 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 OpenAPI a 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.

    Új kapcsolat.

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

    Kapcsolat létrehozása.

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

    • A Power Automate megoldásban a rendszer a Teszt lapra lépteti vissza. Válassza a frissítés ikont, és győződjön meg arról, hogy a kapcsolati adatok frissültek.

      Frissítse a kapcsolatot.

    • 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 adjon meg egy értéket a szövegmezőhöz (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.

    Vizsgálati művelet.

  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.

További lépések

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.

Az összekötőt a szervezeten belül is megoszthatja, vagy minősíttetheti 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 küldése vagy segítség kérése az összekötőkkel kapcsolatban részre, és válassza ki a visszajelzés típusát.