Az Azure Logic Appsből hívható egyéni API-k létrehozása
A következőkre vonatkozik: Azure Logic Apps (Használat)
Bár az Azure Logic Apps több száz összekötőt kínál, amelyeket használhat a logikai alkalmazások munkafolyamataiban, érdemes lehet olyan API-kat, rendszereket és szolgáltatásokat meghí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, a dokumentáció Swagger metaadat-formátumát , a JSON-t pedig adatcsere-formátumké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, a Swagger metaadat-formátumát a dokumentációhoz, a JSON-t pedig adatcsere-formátumké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-Csatlakozás or-erőforrásokként regisztrálva az Azure-ban.
- A Logic Apps Tervező a Microsoft által felügyelt összekötők mellett ikonokkal jelenik meg.
- 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:
- Egyéni összekötők áttekintése
- Egyéni összekötők létrehozása webes API-kból
- Egyéni összekötők regisztrálása az Azure Logic Appsben
Hasznos eszközök
Az egyéni API akkor működik a legjobban a logikai alkalmazásokkal, ha az API egy Swagger-dokumentummal is rendelkezik, 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ítendő nevekhez, tulajdonságtípusokhoz és így tovább, 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űvelete egy műveletre 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.
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 időtúllépést hajt végre, és nem folytatja a munkafolyamat következő lépését, mielőtt az API befejeződik.
Az általános minta a következő:
- Győződjön meg arról, hogy a motor tudja, hogy az API elfogadta a kérést, és megkezdte a munkát.
- Amikor a motor további feladatállapot-kérelmeket küld, tudassa a motorral, hogy mikor fejeződik be a feladat az API-val.
- 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 pékség működik a tortán. 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 lekérdezé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.
Az API szemszögéből az alábbi lépéseket kell követnie:
Amikor az API HTTP-kérést kap a munka megkezdéséhez, azonnal küldjön egy HTTP-választ
202 ACCEPTEDalocationlé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 hasznos adatait (adatbevitel), és most már feldolgozásra kerül.A
202 ACCEPTEDválasznak tartalmaznia kell az alábbi fejléceket:Kötelező: Egy
locationfejlé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átNem kötelező: Egy
retry-afterfejléc, amely megadja, hogy hány másodpercig kell várnia a motornak a feladat állapotánaklocationellenőrzése előtt.Alapértelmezés szerint a motor egy másodperc után kérdezi le az
locationURL-címet. Másik időköz megadásához adja meg aretry-afterfejlécet és a következő szavazásig eltelt másodpercek számát.
A megadott idő elteltével az Azure Logic Apps motor lekérdezi az URL-címet a
locationfeladat á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, egy HTTP-választ
200 OKad vissza a válasz hasznos adataival együtt (a következő lépés bemenete).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-választ 202 ACCEPTED és érvényes location fejlécet kap, a motor tiszteletben tartja az aszinkron mintát, és addig ellenőrzi a location fejlécet, amíg az API nem 202-es 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ég analógiáját a webhook 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 pékség működik a tortán. 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
subscribevégpont: Amikor a végrehajtás eléri az API műveletét a munkafolyamatban, az Azure Logic Apps motor meghívja a végpontotsubscribe. 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.unsubscribevégpont: Ha a munkafolyamat futtatása megszakad, az Azure Logic Apps-motor meghívja a végpontotunsubscribe. 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.
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 mind a logikai alkalmazás erőforrása, mind az előfizetett szolgáltatás tulajdonosa, a visszahívási URL meghívása után nem kell meghívnia a
unsubscribevégpontot. Ellenkező esetben az Azure Logic Apps-futtatókörnyezetnek meg kell hívnia aunsubscribevé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.
Megjegyzé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álható | HTTP-állapotot 200 OK ad vissza a válasz hasznos adataival (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 élőfej retry-after és fejléc használatávallocation. 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 következő után DateTimetriggerStatehozzáadott fájlokat: . |
| A talált fájlok száma | API-válasz |
|---|---|
| Egyetlen fájl | Adja vissza a HTTP-állapotot 200 OK és a tartalom hasznos adatait, frissítsen triggerState a DateTime visszaadott fájlra, és állítsa be retry-after az időközt 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 | HTTP-állapotot 202 ACCEPTED ad vissza, ne változzon 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 ugyanúgy működnek, mint a jelen témakörben korábban ismertetett webhookműveletek , és beállításuk subscribe és unsubscribe végpontjaik vannak.
subscribevégpont: Amikor webhook-eseményindítót ad hozzá és ment a logikai alkalmazásban, az Azure Logic Apps motor meghívja a végpontotsubscribe. 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.unsubscribevé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égpontotunsubscribe. 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.
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 mind a logikai alkalmazás erőforrása, mind az előfizetett szolgáltatás tulajdonosa, a visszahívási URL meghívása után nem kell meghívnia a
unsubscribevégpontot. Ellenkező esetben a Logic Apps-futtatókörnyezetnek meg kell hívnia aunsubscribevé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.
Támogatás kérése
Az egyéni API-kkal kapcsolatos konkrét segítségért forduljon a következőhöz customapishelp@microsoft.com: .
Kérdéseit az Azure Logic Apps Microsoft Q&A kérdésoldalán talál.