Tworzenie niestandardowych interfejsów API, które można wywoływać z poziomu usługi Azure Logic Apps
Dotyczy: Azure Logic Apps (Zużycie)
Mimo że usługa Azure Logic Apps oferuje 1400 łączników, których można używać w przepływach pracy aplikacji logiki, możesz wywołać interfejsy API, systemy i usługi, które nie są dostępne jako łączniki. Możesz utworzyć własne interfejsy API, które udostępniają akcje i wyzwalacze do użycia w przepływach pracy. Oto inne powody, dla których warto utworzyć własne interfejsy API, które można wywołać z przepływów pracy:
- Rozszerz bieżące przepływy pracy integracji systemu i integracji danych.
- Pomaganie klientom w zarządzaniu zadaniami zawodowymi lub osobistymi.
- Rozwiń zasięg, możliwość odnajdywania i używania usługi.
Zasadniczo łączniki to internetowe interfejsy API, które używają interfejsów REST do podłączania interfejsów, formatu metadanych struktury Swagger na potrzeby dokumentacji i formatu JSON jako formatu wymiany danych. Ponieważ łączniki to interfejsy API REST komunikujące się za pośrednictwem punktów końcowych HTTP, można użyć dowolnego języka do tworzenia łączników, takich jak .NET, Java, Python lub Node.js. Możesz również hostować swoje interfejsy API w usłudze aplikacja systemu Azure Service, ofercie typu platforma jako usługa (PaaS), która zapewnia jeden z najlepszych, najłatwiejszych i najbardziej skalowalnych sposobów hostowania interfejsów API.
Aby niestandardowe interfejsy API działały z przepływem pracy aplikacji logiki, interfejs API może udostępniać akcje wykonujące określone zadania w przepływach pracy. Interfejs API może również działać jako wyzwalacz , który uruchamia przepływ pracy, gdy nowe dane lub zdarzenie spełnia określony warunek. W tym temacie opisano typowe wzorce, które można wykonać na potrzeby tworzenia akcji i wyzwalaczy w interfejsie API, na podstawie zachowania, które ma zapewnić interfejs API.
Interfejsy API można hostować w usłudze aplikacja systemu Azure Service, czyli ofercie typu "platforma jako usługa" (PaaS), która zapewnia wysoce skalowalne, łatwe hostowanie interfejsów API.
Napiwek
Mimo że możesz wdrażać interfejsy API jako aplikacje internetowe, rozważ wdrożenie interfejsów API jako aplikacji interfejsu API, co może ułatwić pracę podczas kompilowania, hostowania i korzystania z interfejsów API w chmurze i lokalnie. Nie musisz zmieniać żadnego kodu w interfejsach API — wystarczy wdrożyć kod w aplikacji interfejsu API. Dowiedz się na przykład, jak tworzyć aplikacje interfejsu API utworzone przy użyciu następujących języków:
Jak niestandardowe interfejsy API różnią się od łączników niestandardowych?
Niestandardowe interfejsy API i łączniki niestandardowe to internetowe interfejsy API, które używają interfejsów REST do podłączania interfejsów, formatu metadanych struktury Swagger na potrzeby dokumentacji i formatu JSON jako formatu wymiany danych. Ponieważ te interfejsy API i łączniki to interfejsy API REST komunikujące się za pośrednictwem punktów końcowych HTTP, można użyć dowolnego języka, takiego jak .NET, Java, Python lub Node.js, do tworzenia niestandardowych interfejsów API i łączników.
Niestandardowe interfejsy API umożliwiają wywoływanie interfejsów API, które nie są łącznikami, i udostępnianie punktów końcowych, które można wywoływać za pomocą protokołu HTTP + Swagger, usługi Azure API Management lub App Services. Łączniki niestandardowe działają jak niestandardowe interfejsy API, ale także mają następujące atrybuty:
- Zarejestrowane jako zasoby łącznika usługi Logic Apps na platformie Azure.
- Wyświetlane są ikony obok łączników zarządzanych przez firmę Microsoft w Projektancie aplikacji usługi Logic Apps.
- Dostępne tylko dla autorów łączników i użytkowników zasobów aplikacji logiki, którzy mają tę samą dzierżawę Firmy Microsoft Entra i subskrypcję platformy Azure w regionie, w którym są wdrażane aplikacje logiki.
Możesz również nominować zarejestrowane łączniki do certyfikacji firmy Microsoft. Ten proces sprawdza, czy zarejestrowane łączniki spełniają kryteria użytku publicznego i udostępnia te łączniki użytkownikom w usługach Power Automate i Microsoft Power Apps.
Aby uzyskać więcej informacji, zapoznaj się z następującą dokumentacją:
- Omówienie łączników niestandardowych
- Tworzenie łączników niestandardowych na podstawie internetowych interfejsów API
- Rejestrowanie łączników niestandardowych w usłudze Azure Logic Apps
Przydatne narzędzia
Niestandardowy interfejs API działa najlepiej w przypadku aplikacji logiki, gdy interfejs API zawiera również dokument struktury Swagger, który opisuje operacje i parametry interfejsu API. Wiele bibliotek, takich jak Swashbuckle, może automatycznie wygenerować plik Struktury Swagger. Aby dodać adnotację do pliku Swagger dla nazw wyświetlanych, typów właściwości itd., możesz również użyć TRex , aby plik Swagger dobrze współdziałał z aplikacjami logiki.
Wzorce akcji
Aby aplikacje logiki wykonywały zadania, niestandardowy interfejs API powinien udostępniać akcje. Każda operacja w interfejsie API jest mapowania na akcję. Podstawowa akcja to kontroler, który akceptuje żądania HTTP i zwraca odpowiedzi HTTP. Na przykład przepływ pracy wysyła żądanie HTTP do aplikacji internetowej lub aplikacji interfejsu API. Następnie aplikacja zwraca odpowiedź HTTP wraz z zawartością, którą może przetworzyć przepływ pracy.
W przypadku akcji standardowej można napisać metodę żądania HTTP w interfejsie API i opisać tę metodę w pliku struktury Swagger. Następnie możesz wywołać interfejs API bezpośrednio za pomocą akcji HTTP lub akcji HTTP + Swagger. Domyślnie odpowiedzi muszą być zwracane w limicie limitu czasu żądania.
Aby zaczekać na zakończenie dłuższych zadań przez interfejs API, interfejs API może postępować zgodnie ze wzorcem sondowania asynchronicznego lub asynchronicznego wzorca elementu webhook opisanego w tym temacie. W przypadku analogii, która pomaga wizualizować różne zachowania tych wzorców, wyobraź sobie proces zamawiania niestandardowego ciasta z piekarni. Wzorzec sondowania odzwierciedla zachowanie, w którym nazywasz piekarnię co 20 minut, aby sprawdzić, czy ciasto jest gotowe. Wzorzec elementu webhook odzwierciedla zachowanie, w którym piekarnia prosi o twój numer telefonu, aby móc zadzwonić do Ciebie, gdy ciasto jest gotowe.
Wykonywanie długotrwałych zadań za pomocą wzorca akcji sondowania
Aby interfejs API wykonywał zadania, które mogą być uruchamiane dłużej niż limit limitu czasu żądania, możesz użyć asynchronicznego wzorca sondowania. Ten wzorzec zawiera interfejs API, który działa w osobnym wątku, ale utrzymuje aktywne połączenie z aparatem usługi Azure Logic Apps. Dzięki temu przepływ pracy nie zostanie przekroczony lub przejdzie do następnego kroku w przepływie pracy, zanim interfejs API zakończy pracę.
Oto ogólny wzorzec:
- Upewnij się, że aparat wie, że interfejs API zaakceptował żądanie i zaczął działać.
- Gdy aparat wysyła kolejne żądania dotyczące stanu zadania, poinformuj aparat o zakończeniu zadania.
- Zwróć odpowiednie dane do aparatu, aby przepływ pracy mógł kontynuować.
Teraz zastosuj poprzednią analogię piekarni do wzorca sondowania, i wyobraź sobie, że nazywasz piekarnię i zamawiasz niestandardowe ciasto do dostawy. Proces tworzenia ciasta zajmuje trochę czasu, a nie chcesz czekać na telefon, podczas gdy piekarnia pracuje na ciasto. Piekarnia potwierdza zamówienie i dzwoni co 20 minut na stan ciasta. Po 20 minutach mijasz, dzwonisz do piekarni, ale mówią, że ciasto nie jest zrobione i że powinieneś zadzwonić w kolejne 20 minut. Ten proces back-and-forth trwa do czasu wezwania, a piekarnia mówi, że zamówienie jest gotowe i dostarcza ciasto.
Zamapujmy więc ten wzorzec sondowania z powrotem. Piekarnia reprezentuje niestandardowy interfejs API, podczas gdy ty, klient tortu, reprezentuje aparat usługi Azure Logic Apps. Gdy aparat wywołuje interfejs API z żądaniem, interfejs API potwierdza żądanie i odpowiada z interwałem czasu, kiedy aparat może sprawdzić stan zadania. Aparat kontynuuje sprawdzanie stanu zadania, dopóki interfejs API nie odpowie na to, że zadanie zostanie wykonane i zwróci dane do aplikacji logiki, która następnie kontynuuje przepływ pracy.
Poniżej przedstawiono konkretne kroki, które należy wykonać dla interfejsu API, opisane z perspektywy interfejsu API:
Gdy interfejs API pobiera żądanie HTTP do rozpoczęcia pracy, natychmiast zwróć odpowiedź HTTP
202 ACCEPTEDz nagłówkiem opisanymlocationw dalszej części tego kroku. Ta odpowiedź pozwala aparatowi usługi Azure Logic Apps dowiedzieć się, że twój interfejs API otrzymał żądanie, zaakceptował ładunek żądania (dane wejściowe) i jest teraz przetwarzany.Odpowiedź
202 ACCEPTEDpowinna zawierać następujące nagłówki:Wymagane:
locationnagłówek określający ścieżkę bezwzględną do adresu URL, pod którym aparat usługi Azure Logic Apps może sprawdzić stan zadania interfejsu APIOpcjonalnie:
retry-afternagłówek określający liczbę sekund oczekiwania aparatu przed sprawdzeniem adresu URL pod kątemlocationstanu zadania.Domyślnie aparat sonduje
locationadres URL po jednej sekundzie. Aby określić inny interwał, dołączretry-afternagłówek i liczbę sekund do następnego sondowania.
Po upływie określonego czasu aparat usługi Azure Logic Apps sonduje adres URL w
locationcelu sprawdzenia stanu zadania. Interfejs API powinien wykonać te testy i zwrócić następujące odpowiedzi:Jeśli zadanie zostanie wykonane, zwróć odpowiedź HTTP
200 OKwraz z ładunkiem odpowiedzi (dane wejściowe dla następnego kroku).Jeśli zadanie jest nadal przetwarzane, zwróć kolejną odpowiedź HTTP
202 ACCEPTED, ale z tymi samymi nagłówkami co oryginalna odpowiedź.
Gdy interfejs API jest zgodny z tym wzorcem, nie musisz wykonywać żadnych czynności w definicji przepływu pracy, aby kontynuować sprawdzanie stanu zadania.
Gdy aparat otrzymuje odpowiedź HTTP 202 ACCEPTED i prawidłowy location nagłówek, aparat uwzględnia wzorzec asynchroniczny i sprawdza location nagłówek, dopóki interfejs API nie zwróci odpowiedzi innej niż 202.
Napiwek
Aby zapoznać się z przykładem asynchronicznego wzorca, zapoznaj się z tym przykładem odpowiedzi asynchronicznego kontrolera w usłudze GitHub.
Wykonywanie długotrwałych zadań za pomocą wzorca akcji elementu webhook
Alternatywnie można użyć wzorca elementu webhook do długotrwałych zadań i przetwarzania asynchronicznego. Ten wzorzec wstrzymuje przepływ pracy i czeka na "wywołanie zwrotne" z interfejsu API, aby zakończyć przetwarzanie przed kontynuowaniem przepływu pracy. To wywołanie zwrotne jest postem HTTP, który wysyła komunikat do adresu URL po wystąpieniu zdarzenia.
Teraz zastosuj poprzednią analogię piekarni do wzorca elementu webhook i wyobraź sobie, że nazywasz piekarnię i zamawiasz niestandardowy tort do dostawy. Proces tworzenia ciasta zajmuje trochę czasu, a nie chcesz czekać na telefon, podczas gdy piekarnia pracuje na ciasto. Piekarnia potwierdza twoje zamówienie, ale tym razem, daj im swój numer telefonu, aby mogli zadzwonić do Ciebie po zakończeniu tortu. Tym razem piekarnia informuje, kiedy zamówienie jest gotowe i dostarcza ciasto.
Podczas mapowania tego wzorca elementu webhook piekarnia reprezentuje niestandardowy interfejs API, podczas gdy klient tortu reprezentuje aparat usługi Azure Logic Apps. Aparat wywołuje interfejs API z żądaniem i zawiera adres URL wywołania zwrotnego. Po zakończeniu zadania interfejs API używa adresu URL do powiadamiania aparatu i zwracania danych do aplikacji logiki, która następnie kontynuuje przepływ pracy.
Dla tego wzorca skonfiguruj dwa punkty końcowe na kontrolerze: subscribe i unsubscribe
subscribepunkt końcowy: po osiągnięciu akcji interfejsu API w przepływie pracy aparat usługi Azure Logic Apps wywołujesubscribepunkt końcowy. Ten krok powoduje utworzenie przez przepływ pracy adresu URL wywołania zwrotnego przechowywanego przez interfejs API, a następnie oczekiwanie na wywołanie zwrotne z interfejsu API po zakończeniu pracy. Następnie interfejs API wywołuje kod HTTP POST do adresu URL i przekazuje dowolną zwróconą zawartość i nagłówki jako dane wejściowe do aplikacji logiki.unsubscribepunkt końcowy: Jeśli przebieg przepływu pracy zostanie anulowany, aparat usługi Azure Logic Apps wywołujeunsubscribepunkt końcowy. Interfejs API może następnie wyrejestrować adres URL wywołania zwrotnego i w razie potrzeby zatrzymać wszystkie procesy.
Obecnie projektant przepływu pracy nie obsługuje odnajdywania punktów końcowych elementu webhook za pośrednictwem programu Swagger. W przypadku tego wzorca musisz dodać akcję elementu webhook i określić adres URL, nagłówki i treść żądania. Zobacz również Akcje i wyzwalacze przepływu pracy. Aby zapoznać się z przykładowym wzorcem elementu webhook, zapoznaj się z tym przykładem wyzwalacza elementu webhook w usłudze GitHub.
Oto kilka innych porad i uwag:
Aby przekazać adres URL wywołania zwrotnego, w razie potrzeby możesz użyć
@listCallbackUrl()funkcji przepływu pracy w dowolnym z poprzednich pól.Jeśli jesteś właścicielem zarówno zasobu aplikacji logiki, jak i subskrybowanej usługi, nie musisz wywoływać
unsubscribepunktu końcowego po wywołaniu adresu URL wywołania zwrotnego. W przeciwnym razie środowisko uruchomieniowe usługi Azure Logic Apps musi wywołaćunsubscribepunkt końcowy, aby zasygnalizować, że nie oczekuje się więcej wywołań i zezwolić na czyszczenie zasobów po stronie serwera.
Wzorce wyzwalaczy
Niestandardowy interfejs API może działać jako wyzwalacz , który uruchamia przepływ pracy, gdy nowe dane lub zdarzenie spełnia określony warunek. Ten wyzwalacz może regularnie sprawdzać lub czekać i nasłuchiwać nowych danych lub zdarzeń w punkcie końcowym usługi. Jeśli nowe dane lub zdarzenie spełnia określony warunek, wyzwalacz jest wyzwalany i uruchamia aplikację logiki, która nasłuchuje tego wyzwalacza. Aby uruchomić aplikacje logiki w ten sposób, interfejs API może postępować zgodnie z wyzwalaczem sondowania lub wzorcem wyzwalacza elementu webhook. Te wzorce są podobne do ich odpowiedników w przypadku akcji sondowania i akcji elementu webhook. Dowiedz się również więcej o pomiarach użycia dla wyzwalaczy.
Regularne sprawdzanie nowych danych lub zdarzeń za pomocą wzorca wyzwalacza sondowania
Wyzwalacz sondowania działa podobnie jak akcja sondowania opisana wcześniej w tym temacie. Aparat usługi Azure Logic Apps okresowo wywołuje i sprawdza punkt końcowy wyzwalacza pod kątem nowych danych lub zdarzeń. Jeśli aparat znajdzie nowe dane lub zdarzenie spełniające określony warunek, wyzwalacz zostanie wyzwolony. Następnie aparat tworzy wystąpienie przepływu pracy, które przetwarza dane jako dane wejściowe.
Uwaga
Każde żądanie sondowania jest liczone jako wykonanie akcji, nawet jeśli nie zostanie utworzone żadne wystąpienie przepływu pracy. Aby zapobiec wielokrotnemu przetwarzaniu tych samych danych, wyzwalacz powinien wyczyścić dane, które zostały już odczytane i przekazane do aplikacji logiki.
Poniżej przedstawiono konkretne kroki wyzwalacza sondowania opisane z perspektywy interfejsu API:
| Znaleziono nowe dane lub zdarzenie? | Odpowiedź interfejsu API |
|---|---|
| Założyć | Zwróć stan HTTP 200 OK z ładunkiem odpowiedzi (dane wejściowe dla następnego kroku). Ta odpowiedź tworzy wystąpienie przepływu pracy i uruchamia przepływ pracy. |
| Nie znaleziono | Zwraca stan HTTP 202 ACCEPTED z nagłówkiem location i nagłówkiem retry-after . W przypadku wyzwalaczy location nagłówek powinien również zawierać parametr zapytania, który jest zwykle "sygnaturą triggerState czasową". Interfejs API może użyć tego identyfikatora do śledzenia czasu ostatniego wyzwolenia przepływu pracy. |
Na przykład aby okresowo sprawdzać usługę pod kątem nowych plików, możesz utworzyć wyzwalacz sondowania, który ma następujące zachowania:
Żądanie zawiera triggerState? |
Odpowiedź interfejsu API |
|---|---|
| Nie. | Zwróć stan HTTP 202 ACCEPTED oraz location nagłówek z triggerState ustawionym bieżącym czasem i retry-after interwałem na 15 sekund. |
| Tak | Sprawdź usługę pod kątem plików dodanych po pliku DateTime dla triggerState. |
| Liczba znalezionych plików | Odpowiedź interfejsu API |
|---|---|
| Pojedynczy plik | Zwróć stan HTTP 200 OK i ładunek zawartości, zaktualizuj triggerState element dla DateTime zwróconego pliku i ustaw retry-after interwał na 15 sekund. |
| Wiele plików | Zwróć jeden plik jednocześnie i stan HTTP 200 OK , zaktualizuj triggerStatewartość i ustaw retry-after interwał na 0 sekund. Te kroki pozwalają aparatowi dowiedzieć się, że więcej danych jest dostępnych, a aparat powinien natychmiast zażądać danych z adresu URL w nagłówku location . |
| Brak plików | Zwróć stan HTTP 202 ACCEPTED , nie zmieniaj triggerStatewartości i ustaw retry-after interwał na 15 sekund. |
Napiwek
Aby zapoznać się z przykładowym wzorcem wyzwalacza sondowania, zapoznaj się z przykładem kontrolera wyzwalacza sondowania w usłudze GitHub.
Oczekiwanie i nasłuchiwanie nowych danych lub zdarzeń za pomocą wzorca wyzwalacza elementu webhook
Wyzwalacz elementu webhook to wyzwalacz wypychania, który czeka i nasłuchuje nowych danych lub zdarzeń w punkcie końcowym usługi. Jeśli nowe dane lub zdarzenie spełnia określony warunek, wyzwalacz jest wyzwalany i tworzy wystąpienie przepływu pracy, które następnie przetwarza dane jako dane wejściowe.
Wyzwalacze elementu webhook działają podobnie jak akcje elementu webhook opisane wcześniej w tym temacie i są konfigurowane przy użyciu subscribe elementów i unsubscribe punktów końcowych.
subscribepunkt końcowy: po dodaniu i zapisaniu wyzwalacza elementu webhook w aplikacji logiki aparat usługi Azure Logic Apps wywołujesubscribepunkt końcowy. Ten krok powoduje utworzenie adresu URL wywołania zwrotnego przechowywanego przez interfejs API. Jeśli istnieją nowe dane lub zdarzenie spełniające określony warunek, interfejs API wywołuje z powrotem adres HTTP POST do adresu URL. Ładunek zawartości i nagłówki są przekazywane jako dane wejściowe do aplikacji logiki.unsubscribepunkt końcowy: jeśli wyzwalacz elementu webhook lub cały zasób aplikacji logiki zostanie usunięty, aparat usługi Azure Logic Apps wywołujeunsubscribepunkt końcowy. Interfejs API może następnie wyrejestrować adres URL wywołania zwrotnego i w razie potrzeby zatrzymać wszystkie procesy.
Obecnie projektant przepływu pracy nie obsługuje odnajdywania punktów końcowych elementu webhook za pośrednictwem programu Swagger. Dlatego dla tego wzorca należy dodać wyzwalacz elementu webhook i określić adres URL, nagłówki i treść żądania. Zobacz też wyzwalacz HTTPWebhook. Aby zapoznać się z przykładowym wzorcem elementu webhook, zapoznaj się z tym przykładem kontrolera wyzwalacza elementu webhook w usłudze GitHub.
Oto kilka innych porad i uwag:
Aby przekazać adres URL wywołania zwrotnego, w razie potrzeby możesz użyć
@listCallbackUrl()funkcji przepływu pracy w dowolnym z poprzednich pól.Aby zapobiec wielokrotnemu przetwarzaniu tych samych danych, wyzwalacz powinien wyczyścić dane, które zostały już odczytane i przekazane do aplikacji logiki.
Jeśli jesteś właścicielem zarówno zasobu aplikacji logiki, jak i subskrybowanej usługi, nie musisz wywoływać
unsubscribepunktu końcowego po wywołaniu adresu URL wywołania zwrotnego. W przeciwnym razie środowisko uruchomieniowe usługi Logic Apps musi wywołaćunsubscribepunkt końcowy, aby zasygnalizować, że nie oczekuje się więcej wywołań i umożliwić czyszczenie zasobów po stronie serwera.
Zwiększanie zabezpieczeń wywołań interfejsów API z poziomu aplikacji logiki
Po utworzeniu niestandardowych interfejsów API skonfiguruj uwierzytelnianie dla interfejsów API, aby umożliwić bezpieczne wywoływanie ich z poziomu aplikacji logiki. Dowiedz się , jak zwiększyć bezpieczeństwo wywołań niestandardowych interfejsów API z poziomu aplikacji logiki.
Wdrażanie i wywoływanie interfejsów API
Po skonfigurowaniu uwierzytelniania skonfiguruj wdrożenie dla interfejsów API. Dowiedz się , jak wdrażać i wywoływać niestandardowe interfejsy API z poziomu aplikacji logiki.
Publikowanie niestandardowych interfejsów API na platformie Azure
Aby udostępnić niestandardowe interfejsy API innym użytkownikom usługi Azure Logic Apps, należy dodać zabezpieczenia i zarejestrować je jako łączniki usługi Azure Logic Apps. Aby uzyskać więcej informacji, zobacz Omówienie łączników niestandardowych.
Aby udostępnić niestandardowe interfejsy API wszystkim użytkownikom w usługach Logic Apps, Power Automate i Microsoft Power Apps, należy dodać zabezpieczenia, zarejestrować swoje interfejsy API jako łączniki usługi Azure Logic Apps i wyznaczyć łączniki dla programu certyfikowanego platformy Microsoft Azure.
Uzyskiwanie pomocy technicznej
Aby uzyskać konkretną pomoc dotyczącą niestandardowych interfejsów API, skontaktuj się z .customapishelp@microsoft.com
W przypadku pytań odwiedź stronę pytań i odpowiedzi firmy Microsoft dotyczącą usługi Azure Logic Apps.