Udostępnij za pośrednictwem

Wzorce niestandardowych interfejsów internetowych i REST API, które można wywoływać z usługi Azure Logic Apps

Dotyczy: Azure Logic Apps (Consumption + Standard)

Chociaż Azure Logic Apps oferuje ponad 1400 łączników, których można używać w przepływach pracy aplikacji logicznych, możesz chcieć wywoływać 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 przepływy pracy integracji systemu i danych w swoim bieżącym środowisku.
  • 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ą REST jako interfejsu plug-in, formatu metadanych OpenAPI dla dokumentacji i 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 Azure App 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 logicznej, interfejs API może udostępniać akcje wykonujące określone zadania w przepływie 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 — po prostu wdroż swój kod w aplikacji 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 niestandardowe łączniki to internetowe interfejsy API, które używają REST do tworzenia podłączanych interfejsów, formatu metadanych OpenAPI na potrzeby dokumentacji i 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.
  • Ikony pojawiają się obok łączników zarządzanych przez firmę Microsoft w projektancie aplikacji 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ą:

Przydatne narzędzia

Niestandardowy interfejs API działa najlepiej w przypadku aplikacji logiki, gdy interfejs API zawiera również dokument OpenAPI opisujący operacje i parametry interfejsu API. Wiele bibliotek, takich jak Swashbuckle, może automatycznie wygenerować plik 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 mapowana 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 API. Następnie aplikacja zwraca odpowiedź HTTP wraz z zawartością, którą może przetworzyć proces.

W przypadku standardowej akcji można napisać metodę HTTP w interfejsie API i opisać tę metodę w pliku 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 ramach limitu czasu żądania.

Standardowy wzorzec akcji

Aby workflow czekał na zakończenie dłużej trwających zadań przez API, Twoje API może zastosować opisywany w tym temacie wzorzec sondowania asynchronicznego lub wzorzec asynchronicznego webhooka. 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.

Wykonuj długotrwałe zadania za pomocą wzorca akcji opartego na sondowaniu

Aby interfejs API wykonywał zadania, które mogą trwać dłużej niż limit czasu oczekiwania żądania, możesz użyć asynchronicznego wzorca sondowania. To rozwiązanie powoduje, że interfejs API działa w osobnym wątku, ale jednocześnie utrzymuje aktywne połączenie z aparatem usługi Azure Logic Apps. Dzięki temu przepływ pracy nie zostanie przerwany ani nie przejdzie do następnego kroku, zanim interfejs API zakończy działanie.

Oto ogólny wzorzec:

  1. Upewnij się, że silnik wie, iż Twój interfejs API zaakceptował żądanie i rozpoczął działanie.
  2. Gdy silnik wysyła kolejne żądania dotyczące stanu zadania, poinformuj silnik, gdy Twoje API ukończyło zadanie.
  3. Zwróć odpowiednie dane do silnika, aby przepływ pracy mógł kontynuować.

Teraz zastosuj poprzednią analogię piekarni do wzorca ankietowego, wyobraź sobie, że dzwonisz do piekarni i zamawiasz niestandardowe ciasto na dostawę. 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 upływie 20 minut dzwonisz do piekarni, ale mówią ci, że twoje ciasto nie jest gotowe i że powinieneś zadzwonić za kolejne 20 minut. Ten proces wymiany informacji trwa dopóki nie zadzwonisz, a piekarnia informuje cię, że zamówienie jest gotowe i dostarcza ci tort.

Zamapujmy więc ten wzorzec sondowania z powrotem. Piekarnia reprezentuje twój niestandardowy interfejs API, natomiast ty, jako klient kupujący tort, reprezentujesz silnik platformy Azure Logic Apps. Gdy silnik wywołuje interfejs API z żądaniem, API potwierdza to żądanie, podając przedział czasowy, w którym silnik może sprawdzić status 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.

Wzorzec akcji sondowania

Poniżej przedstawiono konkretne kroki, które należy wykonać dla interfejsu API, opisane z perspektywy interfejsu API:

  1. Gdy Twój interfejs API otrzyma żądanie HTTP do rozpoczęcia pracy, niezwłocznie zwróć odpowiedź HTTP 202 ACCEPTED z nagłówkiem opisanym location w dalszej części tego kroku. Ta odpowiedź informuje silnik usługi Azure Logic Apps, że twoje API otrzymało żądanie, zaakceptowało ładunek żądania (dane wejściowe) i teraz przetwarza dane.

    Odpowiedź 202 ACCEPTED powinna zawierać następujące nagłówki:

    • Wymagane: location nagłówek określający pełny adres URL, pod którym aparat usługi Azure Logic Apps może sprawdzić stan zadania interfejsu API

    • Opcjonalnie: retry-after nagłówek określający liczbę sekund, jaką aparat powinien odczekać przed sprawdzeniem stanu zadania pod podanym adresem URL location.

      Domyślnie aparat sonduje location adres URL po jednej sekundzie. Aby określić inny interwał, dołącz retry-after nagłówek i liczbę sekund do następnego sondowania.

  2. Po upływie określonego czasu aparat Azure Logic Apps sonduje adres URL location, aby sprawdzić stan zadania. Interfejs API powinien wykonać te testy i zwrócić następujące odpowiedzi:

    • Jeśli zadanie zostanie wykonane, zwróć odpowiedź HTTP 200 OK wraz 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 silnik otrzymuje odpowiedź HTTP 202 ACCEPTED i prawidłowy nagłówek location, przestrzega wzorca asynchronicznego i sprawdza nagłówek location, dopóki 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 webhook

Alternatywnie można użyć schematu 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 webhook i wyobraź sobie, że dzwonisz do piekarni i zamawiasz niestandardowy tort z dostawą. 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 odzwierciedlania tego wzorca webhook, piekarnia reprezentuje Twój niestandardowy interfejs API, podczas gdy Ty, jako klient zamawiający tort, reprezentujesz silnik usługi Azure Logic Apps. Silnik wywołuje twoje API z żądaniem i dołącza adres URL wywołania zwrotnego. Po zakończeniu zadania Twój interfejs API używa adresu URL do powiadomienia silnika i przekazania 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

  • subscribe punkt końcowy: Gdy w przepływie pracy zostanie osiągnięta akcja interfejsu API, aparat usługi Azure Logic Apps wywołuje subscribe punkt końcowy. Ten krok w ramach przepływu pracy powoduje utworzenie adresu URL wywołania zwrotnego, który jest przechowywany przez Twój interfejs API, a następnie oczekiwanie na wywołanie zwrotne z interfejsu API po zakończeniu pracy. Następnie twój interfejs API wykonuje żądanie HTTP POST do adresu URL i przekazuje zwróconą zawartość oraz nagłówki jako dane wejściowe do aplikacji logicznej.

  • unsubscribe punkt końcowy: Jeśli przebieg przepływu pracy zostanie anulowany, mechanizm usługi Azure Logic Apps wywołuje unsubscribe punkt końcowy. Twój interfejs API może następnie wyrejestrować adres URL wywołania zwrotnego i w razie potrzeby zatrzymać procesy.

Wzorzec akcji webhooka

Obecnie projektant przepływu pracy nie obsługuje znajdowania punktów końcowych webhooków przy użyciu Swaggera. W przypadku tego wzorca musisz dodać akcję Webhook i określić adres URL, nagłówki oraz 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, możesz w razie potrzeby użyć funkcji @listCallbackUrl() przepływu pracy w dowolnym z poprzednich pól.

  • Jeśli jesteś właścicielem zarówno zasobu aplikacji logicznej, jak i usługi subskrybowanej, nie musisz wywoływać punktu końcowego unsubscribe po wywołaniu adresu URL wywołania zwrotnego. W przeciwnym razie środowisko uruchomieniowe usługi Azure Logic Apps musi wywołać unsubscribe punkt 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ć na nowe dane lub zdarzenia w punkcie końcowym usługi. Jeśli nowe dane lub zdarzenie spełniają określony warunek, wyzwalacz uruchamia się i uruchamia aplikację logiczną, która nasłuchuje na ten wyzwalacz. Aby uruchomić aplikacje logiki w ten sposób, interfejs API może korzystać z wyzwalacza sondowania lub wzorca wyzwalacza webhook. Te wzorce są podobne do ich odpowiedników dla akcji sondowania i akcji webhook. Dowiedz się również więcej o monitorowaniu zuż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. Silnik 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 silnik tworzy wystąpienie przepływu pracy, które przetwarza dane wejściowe.

Wzorzec wyzwalacza odpytywania

Uwaga

Każde żądanie odpytywania jest liczone jako wykonanie działania, 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
Znaleziono Zwróć stan HTTP 200 OK z ładunkiem odpowiedzi (dane wejściowe dla następnego kroku).
Ta odpowiedź tworzy instancję przepływu pracy i rozpoczyna przepływ pracy.
Nie znaleziono Zwraca stan HTTP 202 ACCEPTED z nagłówkiem location i nagłówkiem retry-after .
W przypadku wyzwalaczy nagłówek location powinien także zawierać parametr zapytania triggerState, który jest zazwyczaj znacznikiem czasowym. Twój interfejs API może użyć tego identyfikatora do śledzenia, kiedy przepływ pracy został ostatnio wyzwolony.

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 nagłówek location z ustawionym bieżącym czasem w triggerState i interwałem retry-after ustawionym na 15 sekund.
Tak Sprawdź usługę pod kątem plików dodanych po DateTime dla triggerState.
Liczba znalezionych plików Odpowiedź interfejsu API
Pojedynczy plik Zwróć stan HTTP 200 OK i ładunek zawartości, zaktualizuj triggerState do DateTime dla zwróconego pliku i ustaw interwał retry-after na 15 sekund.
Wiele plików Zwracaj po jednym pliku na raz i stan HTTP 200 OK, zaktualizuj triggerState, i ustaw interwał retry-after 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 triggerState, i ustaw interwał retry-after 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.

Czekaj i nasłuchuj nowych danych lub zdarzeń z wykorzystaniem wzorca wyzwalacza webhook.

Wyzwalacz 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, to wyzwalacz się uruchamia i tworzy instancję przepływu pracy, która następnie przetwarza dane wejściowe. Wyzwalacze webhook działają podobnie jak opisywane wcześniej w tym temacie akcje webhook i są konfigurowane z użyciem subscribe i unsubscribe punktów końcowych.

  • subscribe punkt dostępu: Po dodaniu i zapisaniu wyzwalacza webhooku w aplikacji logiki, aparat Azure Logic Apps wywołuje subscribe punkt dostępu. Ten krok powoduje utworzenie adresu URL wywołania zwrotnego przechowywanego przez interfejs API. Jeśli pojawią się nowe dane lub zdarzenie spełniające określony warunek, Twój interfejs API wysyła żądanie HTTP POST na podany adres URL. Ładunek zawartości i nagłówki są przekazywane jako dane wejściowe do aplikacji logicznej.

  • unsubscribe punkt końcowy: jeśli wyzwalacz webhooku lub cały zasób aplikacji Logic zostanie usunięty, silnik Azure Logic Apps wywołuje unsubscribe punkt końcowy. Twój interfejs API może następnie wyrejestrować adres URL wywołania zwrotnego i w razie potrzeby zatrzymać procesy.

Wzorzec wyzwalania webhooka

Obecnie projektant przepływu pracy nie obsługuje znajdowania punktów końcowych webhooków przy użyciu Swaggera. Dlatego dla tego wzorca należy dodać wyzwalacz webhook i określić adres URL, nagłówki oraz treść dla żądania. Zobacz też Wyzwalacz HTTPWebhook. Aby zobaczyć przykładowy wzorzec webhooka, sprawdź ten przykład kontrolera wyzwalania webhooka na GitHubie.

Oto kilka innych porad i uwag:

  • Aby przekazać adres URL wywołania zwrotnego, możesz w razie potrzeby użyć funkcji @listCallbackUrl() 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 logicznej, jak i usługi subskrybowanej, nie musisz wywoływać punktu końcowego unsubscribe po wywołaniu adresu URL wywołania zwrotnego. W przeciwnym razie środowisko uruchomieniowe usługi Logic Apps musi wywołać unsubscribe punkt końcowy, aby zasygnalizować, że nie oczekuje się więcej wywołań i umożliwić czyszczenie zasobów po stronie serwera.

Poprawa zabezpieczeń wywołań twoich API z aplikacji logicznych

Po utworzeniu niestandardowych interfejsów API skonfiguruj uwierzytelnianie dla tych interfejsów API, aby umożliwić ich bezpieczne wywoływanie z poziomu aplikacji Logic Apps. Dowiedz się , jak zwiększyć bezpieczeństwo wywołań niestandardowych interfejsów API w logice aplikacji.

Wdrażaj i wywołuj interfejsy API

Po skonfigurowaniu uwierzytelniania, skonfiguruj wdrożenie dla API. Dowiedz się, jak wdrażać i wywoływać niestandardowe 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.

Następne kroki