Az Azure Logic Appsből hívható egyéni webes API-k és REST API-k mintái

A következőkre vonatkozik: Azure Logic Apps (Fogyasztás + Standard)

Bár az Azure Logic Apps több mint 1400 összekötőt kínál, amelyeket használhat a logikai alkalmazások munkafolyamataiban, érdemes lehet olyan API-kat, rendszereket és szolgáltatásokat hívni, amelyek nem érhetők el összekötőként. Létrehozhat saját API-kat, amelyek műveleteket és triggereket biztosítanak a munkafolyamatokban való használathoz. Az alábbiakban további okokat találhat arra, hogy miért érdemes létrehoznia a munkafolyamatokból meghívható saját API-kat:

  • A jelenlegi rendszerintegrációs és adatintegrációs munkafolyamatok kiterjesztése.
  • Segítsen az ügyfeleknek a szolgáltatás használatával kezelni a szakmai vagy személyes feladatokat.
  • Bontsa ki a szolgáltatás elérését, felderíthetőségét és használatát.

Az összekötők alapvetően olyan webes API-k, amelyek REST-et használnak a csatlakoztatható felületekhez, openAPI metaadat-formátumot a dokumentációhoz, és JSON-t az adatcsere formátumukként. Mivel az összekötők OLYAN REST API-k, amelyek HTTP-végpontokon keresztül kommunikálnak, bármilyen nyelven létrehozhat összekötőket, például .NET, Java, Python vagy Node.js. Az API-kat a Azure-alkalmazás Service-en is üzemeltetheti, amely egy szolgáltatásként nyújtott platform (PaaS) ajánlat, amely az API-üzemeltetés egyik legjobb, legegyszerűbb és legskálázhatóbb módját biztosítja.

Ahhoz, hogy az egyéni API-k a logikai alkalmazás munkafolyamatával működjenek, az API olyan műveleteket biztosíthat, amelyek meghatározott feladatokat hajtanak végre a munkafolyamatokban. Az API eseményindítóként is működhet, amely elindít egy munkafolyamatot, amikor az új adatok vagy egy esemény megfelel egy megadott feltételnek. Ez a témakör az API-ban végrehajtandó műveletek és eseményindítók készítéséhez követendő gyakori mintákat ismerteti az API által kívánt viselkedés alapján.

Az API-kat a Azure-alkalmazás Service-en, egy szolgáltatásként nyújtott platformon (PaaS) üzemeltetheti, amely nagy mértékben skálázható, egyszerű API-üzemeltetést biztosít.

Tipp.

Bár az API-kat webalkalmazásokként is üzembe helyezheti, érdemes API-kként üzembe helyeznie az API-kat, ami megkönnyíti a feladatát a felhőben és a helyszínen található API-k létrehozása, üzemeltetése és felhasználása során. Nem kell semmilyen kódot módosítania az API-kban – csak helyezze üzembe a kódot egy API-alkalmazásban. Megtudhatja például, hogyan hozhat létre az alábbi nyelvekkel létrehozott API-alkalmazásokat:

Miben különböznek az egyéni API-k az egyéni összekötőktől?

Az egyéni API-k és az egyéni összekötők olyan webes API-k, amelyek REST-et használnak a csatlakoztatható felületekhez, openAPI metaadat-formátumot a dokumentációhoz, és JSON-t az adatcsere formátumukként. Mivel ezek az API-k és összekötők OLYAN REST API-k, amelyek HTTP-végpontokon keresztül kommunikálnak, bármilyen nyelvet használhat, például .NET, Java, Python vagy Node.js egyéni API-k és összekötők létrehozásához.

Az egyéni API-k lehetővé teszik, hogy olyan API-kat hívjon meg, amelyek nem összekötők, és olyan végpontokat biztosít, amelyeket a HTTP + Swagger, az Azure API Management vagy az App Services használatával hívhat meg. Az egyéni összekötők az egyéni API-khoz hasonlóan működnek, de az alábbi attribútumokkal is rendelkeznek:

  • Logic Apps Connector-erőforrásokként regisztrálva az Azure-ban.
  • Ikonokkal és a Microsoft által felügyelt összekötőkkel együtt jelenik meg a Logic Apps Designerben.
  • Csak az összekötők szerzői és a logikai alkalmazás erőforrás-felhasználói számára érhető el, akik ugyanazt a Microsoft Entra-bérlőt és Azure-előfizetést rendelkeznek abban a régióban, ahol a logikai alkalmazásokat üzembe helyezik.

Regisztrált összekötőket is jelölhet a Microsoft minősítéséhez. Ez a folyamat ellenőrzi, hogy a regisztrált összekötők megfelelnek-e a nyilvános használatra vonatkozó feltételeknek, és elérhetővé teszik ezeket az összekötőket a Power Automate és a Microsoft Power Apps felhasználói számára.

További információkért tekintse át a következő dokumentációt:

Hasznos eszközök

Az egyéni API akkor működik a legjobban a logikai alkalmazásokkal, ha az API rendelkezik egy OpenAPI-dokumentummal is, amely leírja az API műveleteit és paramétereit. Számos kódtár, például a Swashbuckle, automatikusan létrehozhatja Önnek a Swagger-fájlt. A Swagger-fájl megjelenítési nevekhez, tulajdonságtípusokhoz és így tovább történő annotálásához a TRexet is használhatja, hogy a Swagger-fájl jól működjön a logikai alkalmazásokkal.

Műveleti minták

Ahhoz, hogy a logikai alkalmazások elvégezhessenek feladatokat, az egyéni API-nak műveleteket kell biztosítania. Az API minden működése egy cselekvésre van leképzve. Az alapműveletek olyan vezérlők, amelyek HTTP-kéréseket fogadnak el, és HTTP-válaszokat ad vissza. Így például egy munkafolyamat HTTP-kérelmet küld a webalkalmazásnak vagy az API-alkalmazásnak. Az alkalmazás ezután egy HTTP-választ ad vissza a munkafolyamat által feldolgozható tartalommal együtt.

Normál művelet esetén http-kérési metódust írhat az API-ban, és leírhatja ezt a metódust egy Swagger-fájlban. Ezután közvetlenül http-művelettel vagy HTTP + Swagger művelettel hívhatja meg az API-t. Alapértelmezés szerint a válaszokat a kérelem időtúllépési korlátja alatt kell visszaadni.

Standard műveleti minta

Ha meg szeretné várni a munkafolyamatot, amíg az API befejezi a hosszabb ideig futó feladatokat, az API követheti az aszinkron lekérdezési mintát vagy a jelen témakörben ismertetett aszinkron webhookmintát . Egy olyan analógia érdekében, amely segít ezeknek a mintáknak a különböző viselkedéseinek vizualizációjában, képzelje el az egyéni torta megrendelésének folyamatát egy pékségből. A lekérdezési minta azt a viselkedést tükrözi, amikor 20 percenként hívja a pékséget, hogy ellenőrizze, készen áll-e a torta. A webhook minta tükrözi a viselkedést, ahol a pékség kéri a telefonszámot, hogy felhívják, ha a torta készen áll.

Hosszú ideig futó feladatok végrehajtása a lekérdezési műveleti mintával

Ha azt szeretné, hogy az API a kérelem időtúllépési korlátjánál hosszabb ideig fusson, használhatja az aszinkron lekérdezési mintát. Ebben a mintában az API külön szálon működik, de aktív kapcsolatot tart az Azure Logic Apps-motorral. Így a munkafolyamat nem lépi túl az időkorlátot, és nem folytatja a munkafolyamat következő lépését, mielőtt az API befejezi működését.

Az általános minta a következő:

  1. Győződjön meg arról, hogy a motor tudja, hogy az API elfogadta a kérést, és megkezdte a munkát.
  2. Amikor a rendszer további feladatállapot-kérelmeket küld, értesítse a rendszert, amikor az API befejezte a feladatot.
  3. Adja vissza a releváns adatokat a motornak, hogy a munkafolyamat folytatódjon.

Most alkalmazza az előző pékség analógiáját a lekérdezési mintára, és képzelje el, hogy meghív egy pékséget, és rendel egy egyéni tortát a kézbesítéshez. A torta elkészítésének folyamata időbe telik, és nem akarsz telefonon várni, amíg a cukrászda készíti a tortát. A pékség megerősíti a rendelését, és 20 percenként hívja fel a torta állapotát. 20 perc elteltével felhívod a pékséget, de azt mondják, hogy a torta még nem készült el, és hogy még 20 perc múlva hívd fel. Ez az előre-hátra folyamat addig folytatódik, amíg fel nem hív, és a pékség azt mondja, hogy a rendelés készen áll, és kézbesíti a tortát.

Tehát képezzük vissza ezt a szavazási mintát. A pékség az egyéni API-t képviseli, míg Ön, a torta ügyfele az Azure Logic Apps motorját képviseli. Amikor a motor kéréssel hívja meg az API-t, az API megerősíti a kérést, és azzal az időintervallummal válaszol, amikor a motor ellenőrizheti a feladat állapotát. A motor addig ellenőrzi a feladat állapotát, amíg az API nem válaszol a feladat befejezésére, és adatokat ad vissza a logikai alkalmazásnak, amely ezután folytatja a munkafolyamatot.

Lekérdezési műveleti minta

Íme az API által követendő konkrét lépések az API szemszögéből:

  1. Amikor az API HTTP-kérést kap a munka megkezdéséhez, azonnal küldjön egy HTTP-választ 202 ACCEPTED a location lépés későbbi részében ismertetett fejlécmel. Ez a válasz tudatja az Azure Logic Apps motorral, hogy az API megkapta a kérést, elfogadta a kérelem adatcsomagját (adatbevitel), és most már feldolgozás alatt van.

    A 202 ACCEPTED válasznak tartalmaznia kell az alábbi fejléceket:

    • Kötelező: Egy location fejléc, amely megadja az URL-cím abszolút elérési útját, ahol az Azure Logic Apps-motor ellenőrizheti az API feladatának állapotát

    • Nem kötelező: Olyan retry-after fejléc, amely meghatározza, hogy hány másodpercig kell várnia a motornak, mielőtt ellenőrzi a location URL-t a feladat állapotához.

      Alapértelmezés szerint a motor egy másodperc után kérdezi le az location URL-címet. Másik időköz megadásához adja meg a retry-after fejlécet és a következő szavazásig eltelt másodpercek számát.

  2. A megadott idő elteltével az Azure Logic Apps motor lekérdezi az URL-címet a location feladat állapotának ellenőrzéséhez. Az API-nak végre kell hajtania ezeket az ellenőrzéseket, és a következő válaszokat kell visszaadnia:

    • Ha a feladat elkészült, adjon vissza egy HTTP választ 200 OK, a válasz hasznos adataival együtt (ami a következő lépés bemenetét képezi).

    • Ha a feladat feldolgozása még folyamatban van, adjon vissza egy másik HTTP-választ 202 ACCEPTED , de ugyanazokkal a fejlécekkel, mint az eredeti válasz.

Ha az API követi ezt a mintát, nem kell semmit tennie a munkafolyamat-definícióban a feladat állapotának ellenőrzéséhez. Amikor a motor HTTP 202 ACCEPTED választ és érvényes location fejlécet kap, tiszteletben tartja az aszinkron mintát, és addig ellenőrzi a location fejlécet, amíg az API nem 202-esnél eltérő választ ad vissza.

Tipp.

Ha például aszinkron mintát használ, tekintse át ezt az aszinkron vezérlő válaszmintáját a GitHubon.

Hosszú ideig futó feladatok végrehajtása a webhook műveleti mintával

Alternatív megoldásként használhatja a webhookmintát a hosszan futó feladatokhoz és az aszinkron feldolgozáshoz. Ez a minta szünetelteti a munkafolyamatot, és megvárja a "visszahívást" az API-ból, hogy befejezze a feldolgozást a munkafolyamat folytatása előtt. Ez a visszahívás egy HTTP POST, amely esemény bekövetkezésekor üzenetet küld egy URL-címre.

Most alkalmazza az előző pékségi analógiát a webhook mintára, és képzelje el, hogy felhív egy pékséget, és rendel egy egyedi tortát házhoz szállításra. A torta elkészítésének folyamata időbe telik, és nem akarsz telefonon várni, amíg a cukrászda készíti a tortát. A pékség megerősíti a rendelését, de ezúttal megadja a telefonszámát, hogy felhívhassák, amikor a torta elkészült. Ezúttal a pékség tájékoztatja, hogy mikor áll készen a rendelése, és kézbesíti a tortát.

Amikor ezt a webhookmintát visszaképezzük, a pékség az egyéni API-t jelöli, míg Ön, a torta ügyfele az Azure Logic Apps motorját képviseli. A motor kéréssel hívja meg az API-t, és tartalmaz egy "visszahívási" URL-címet. A feladat befejezése után az API az URL-cím használatával értesíti a motort, és adatokat ad vissza a logikai alkalmazásnak, amely ezután folytatja a munkafolyamatot.

Ehhez a mintához állítson be két végpontot a vezérlőn: subscribe és unsubscribe

  • subscribe végpont: Amikor a végrehajtás eléri az API műveletét a munkafolyamatban, az Azure Logic Apps motor meghívja a végpontot subscribe . Ez a lépés azt eredményezi, hogy a munkafolyamat létrehoz egy visszahívási URL-címet, amelyet az API tárol, majd várja meg a visszahívást az API-ból, amikor a munka befejeződött. Az API ezután egy HTTP POST-üzenettel visszahívja az URL-címet, és a visszaadott tartalmat és fejléceket bemenetként továbbítja a logikai alkalmazásnak.

  • unsubscribe végpont: Ha a munkafolyamat futtatása megszakad, az Azure Logic Apps-motor meghívja a végpontot unsubscribe . Az API ezután törölheti a visszahívási URL-címet, és szükség esetén leállíthatja a folyamatokat.

Webhook műveleti minta

A munkafolyamat-tervező jelenleg nem támogatja a webhookvégpontok Swaggeren keresztüli felderítését. Ehhez a mintához hozzá kell adnia egy Webhook-műveletet, és meg kell adnia a kérés URL-címét, fejléceit és törzsét. Lásd még a munkafolyamat-műveleteket és -eseményindítókat. Egy példa webhook-mintára, tekintse át ezt a webhook-eseményindító-mintát a GitHubon.

Íme néhány további tipp és megjegyzés:

  • A visszahívási URL-cím átadásához szükség szerint az @listCallbackUrl() előző mezők bármelyikében használhatja a munkafolyamat-függvényt.

  • Ha Ön a logikai alkalmazás erőforrásának és az előfizetett szolgáltatásnak is a tulajdonosa, akkor a visszahívási URL hívása után nem kell a unsubscribe végpontot hívnia. Ellenkező esetben az Azure Logic Apps-futtatókörnyezetnek meg kell hívnia a unsubscribe végpontot, hogy jelezhesse, nincs több hívás, és engedélyeznie kell az erőforrások törlését a kiszolgáló oldalán.

Triggerminták

Az egyéni API eseményindítóként működhet, amely elindít egy munkafolyamatot, amikor új adatok vagy események teljesülnek egy megadott feltételnek. Ez az eseményindító rendszeresen ellenőrizheti vagy figyelheti az új adatokat vagy eseményeket a szolgáltatásvégponton. Ha az új adatok vagy események megfelelnek a megadott feltételnek, az eseményindító elindítja és elindítja a logikai alkalmazást, amely figyeli az eseményindítót. Ha így szeretné elindítani a logikai alkalmazásokat, az API követheti a lekérdezési eseményindítót vagy a webhook-eseményindító mintáját. Ezek a minták hasonlóak a lekérdezési és webhookműveletek megfelelőihez. Emellett többet is megtudhat az eseményindítók használati méréséről.

Új adatok vagy események rendszeres keresése a lekérdezési eseményindító mintával

A lekérdezési eseményindítók a jelen témakörben korábban ismertetett lekérdezési művelethez hasonlóan viselkednek. Az Azure Logic Apps-motor rendszeresen meghívja és ellenőrzi az eseményindító végpontját új adatok vagy események esetén. Ha a motor új adatokat vagy a megadott feltételnek megfelelő eseményt talál, az eseményindító aktiválódik. Ezután a motor létrehoz egy munkafolyamat-példányt, amely bemenetként dolgozza fel az adatokat.

Lekérdezési eseményindító mintája

Feljegyzés

Minden lekérdezési kérelem műveletvégrehajtásnak számít, még akkor is, ha nincs munkafolyamat-példány létrehozva. Ha meg szeretné akadályozni ugyanazon adatok többszöri feldolgozását, az eseményindítónak törölnie kell a már beolvasott és a logikai alkalmazásnak átadott adatokat.

A lekérdezési eseményindító konkrét lépéseit az API szemszögéből ismertetjük:

Új adatokat vagy eseményt talált? API-válasz
Talált HTTP-állapotkódot 200 OK adjon vissza a választartalommal (a következő lépés bemenete).
Ez a válasz létrehoz egy munkafolyamat-példányt, és elindítja a munkafolyamatot.
Nem található HTTP-állapotot 202 ACCEPTED ad vissza egy fejléc location és egy fejléc retry-after használatával.
Eseményindítók esetén a location fejlécnek tartalmaznia kell egy triggerState lekérdezési paramétert is, amely általában "időbélyeg". Az API ezt az azonosítót használhatja a munkafolyamat legutóbbi aktiválásának nyomon követésére.

Ha például rendszeresen ellenőrizni szeretné a szolgáltatást új fájlok keresésekor, létrehozhat egy lekérdezési eseményindítót, amely a következő viselkedéssel rendelkezik:

A kérelem tartalmazza a következőt triggerState: API-válasz
Nem Egy HTTP-állapotot 202 ACCEPTED és egy location fejlécet ad vissza, amely triggerState az aktuális időpontra és az retry-after intervallumra 15 másodpercre van állítva.
Igen Ellenőrizze a szolgáltatásban a fájlokat, amelyeket hozzáadtak a DateTime után a triggerState-ig.
A talált fájlok száma API-válasz
Egyetlen fájl Adjon vissza egy HTTP 200 OK állapotot és a tartalom hasznos adatait, frissítse a triggerState-t a DateTime-hez a visszaadott fájlhoz, és állítsa be a retry-after intervallumot 15 másodpercre.
Több fájl Egyszerre egy fájlt és egy HTTP-állapotot 200 OK ad vissza, frissíti triggerState, majd 0 másodpercre állítja az retry-after időközt.
Ezek a lépések tudatják a motorral, hogy több adat áll rendelkezésre, és hogy a motornak azonnal le kell kérnie az adatokat a location fejléc URL-címéről.
Nincsenek fájlok Adjon vissza egy HTTP-állapotot 202 ACCEPTED, ne változtassa meg triggerState, és állítsa az retry-after intervallumot 15 másodpercre.

Tipp.

A lekérdezési eseményindító mintájához tekintse át ezt a lekérdezési eseményindító vezérlőmintát a GitHubon.

Várjon és hallgassa meg az új adatokat vagy eseményeket a webhook eseményindító mintájával

A webhook-eseményindító egy leküldéses eseményindító , amely várakozik, és figyeli az új adatokat vagy eseményeket a szolgáltatásvégponton. Ha az új adatok vagy események megfelelnek a megadott feltételnek, az eseményindító aktiválódik, és létrehoz egy munkafolyamat-példányt, amely ezután bemenetként dolgozza fel az adatokat. A Webhook-eseményindítók hasonló módon működnek, mint a korábban ebben a témakörben ismertetett webhook műveletek, és subscribe és unsubscribe végpontokkal lettek beállítva.

  • subscribe végpont: Amikor a logikai alkalmazásban hozzáad és elment egy webhook-eseményindítót, az Azure Logic Apps motor meghívja a subscribe végpontot. Ez a lépés azt eredményezi, hogy a munkafolyamat létrehoz egy visszahívási URL-címet, amelyet az API tárol. Ha új adatok vagy a megadott feltételnek megfelelő esemény van, az API egy HTTP POST-üzenettel hívja vissza az URL-címet. A tartalom hasznos adatai és fejlécei bemenetként továbbítva lesznek a logikai alkalmazásnak.

  • unsubscribe végpont: Ha a webhook-eseményindító vagy a logikai alkalmazás teljes erőforrása törlődik, az Azure Logic Apps-motor meghívja a végpontot unsubscribe . Az API ezután törölheti a visszahívási URL-címet, és szükség esetén leállíthatja a folyamatokat.

Webhook eseményindító mintája

A munkafolyamat-tervező jelenleg nem támogatja a webhookvégpontok Swaggeren keresztüli felderítését. Ehhez a mintához hozzá kell adnia egy Webhook-eseményindítót, és meg kell adnia a kérés URL-címét, fejléceit és törzsét. Lásd még : HTTPWebhook eseményindító. Egy példa webhook mintájára tekintse át ezt a webhook-eseményindító vezérlőmintát a GitHubon.

Íme néhány további tipp és megjegyzés:

  • A visszahívási URL-cím átadásához szükség szerint az @listCallbackUrl() előző mezők bármelyikében használhatja a munkafolyamat-függvényt.

  • Ha meg szeretné akadályozni ugyanazon adatok többszöri feldolgozását, az eseményindítónak törölnie kell a már beolvasott és a logikai alkalmazásnak átadott adatokat.

  • Ha Ön a logikai alkalmazás erőforrásának és az előfizetett szolgáltatásnak is a tulajdonosa, akkor a visszahívási URL hívása után nem kell a unsubscribe végpontot hívnia. Ellenkező esetben a Logic Apps-futtatókörnyezetnek meg kell hívnia a unsubscribe végpontot, hogy jelezhesse, nincs több hívás, és engedélyeznie kell az erőforrás-karbantartást a kiszolgáló oldalán.

Az API-k logikai alkalmazásokból történő hívásainak biztonságának javítása

Az egyéni API-k létrehozása után állítsa be az API-k hitelesítését, hogy biztonságosan hívhassa meg őket a logikai alkalmazásokból. Megtudhatja , hogyan javíthatja a logikai alkalmazásokból érkező egyéni API-k hívásainak biztonságát.

API-k üzembe helyezése és meghívása

A hitelesítés beállítása után állítsa be az API-k üzembe helyezését. Megtudhatja , hogyan helyezhet üzembe és hívhat meg egyéni API-kat logikai alkalmazásokból.

Egyéni API-k közzététele az Azure-ban

Ahhoz, hogy az egyéni API-kat elérhetővé tegye más Azure Logic Apps-felhasználók számára, hozzá kell adnia a biztonságot, és regisztrálnia kell őket Azure Logic Apps-összekötőkként. További információért lásd az egyéni összekötők áttekintését.

Ahhoz, hogy egyéni API-jait elérhetővé tegye a Logic Apps, a Power Automate és a Microsoft Power Apps összes felhasználója számára, hozzá kell adnia a biztonságot, regisztrálnia kell az API-kat Azure Logic Apps-összekötőkként, és ki kell jelölnie összekötőit a Microsoft Azure Certified programhoz.

Következő lépések

  • Last updated on