Używanie elementu webhook jako wyzwalacza dla usług Azure Logic Apps i Microsoft Power Automate

Artykuł
06/23/2023

Elementy webhook to proste wywołania zwrotne HTTP używane do udostępniania powiadomień o zdarzeniach. Zarówno usługa Azure Logic Apps, jak i Power Automate, umożliwiają używanie elementów webhook jako wyzwalaczy. Aplikacja logiczna lub przepływ obserwuje ten wyzwalacz i wykonuje akcję przy każdym aktywowaniu wyzwalacza. W tym samouczku pokazano, jak użyć elementu webhook jako wyzwalacza.

Uwaga

Jako przykładowej usługi umożliwiającej wysyłanie powiadomień za pośrednictwem elementów webhook użyjemy usługi GitHub, ale techniki przedstawione w tym artykule mogą obejmować dowolną usługę korzystającą z elementów webhook.

Wymagania wstępne

Jedna z następujących subskrypcji:
- Azure, jeśli są używane usługi Logic Apps
- Power Automate
Podstawowe doświadczenie w towrzeniu aplikacji logicznych lub przepływów i łączników niestandardowych.
Jeśli używasz usługi Logic Apps, najpierw utwórz łącznik niestandardowy usługi Azure Logic Apps.
Podstawowa wiedza na temat elementów webhook.
Podstawowa znajomość specyfikacji OpenAPI (dawniej znanej jako Swagger).
Konto usługi GitHub.
Przykładowa definicja OpenAPI dla tego samouczka.

Definicja OpenAPI

Elementy webhook są implementowane w usługach Logic Apps i Power Automate jako część łącznika niestandardowego, dlatego w celu określenia postaci elementu webhook należy udostępnić definicję interfejsu OpenAPI. Jeśli chcesz utworzyć wyzwalacz, ale nie masz definicji OpenAPI, możesz użyć narzędzia UI wyzwalaczy w kreatorze łączników niestandardowych, aby zdefiniować wyzwalacze webhooków.

Interfejs OpenAPI zawiera definicję składającą się z trzech części, które mają kluczowe znaczenie dla działania elementu webhook:

Tworzenie elementu webhook
Definiowanie żądania punktu zaczepienia przychodzącego z interfejsu API (w tym przypadku usługi GitHub)
Usuwanie elementu webhook

Tworzenie elementu webhook

Po stronie usługi GitHub element webhook jest tworzony przez żądanie POST protokołu HTTP wysyłane na adres /repos/{owner}/{repo}/hooks. Kiedy tworzona jest nowa aplikacja logiczna lub przepływ, wysyła ona wiadomość na ten adres URL za pomocą wyzwalacza zdefiniowanego w definicji OpenAPI. W przypadku zmodyfikowania wyzwalacza wpisuje również do adresu URL. W poniższym przykładzie właściwość post zawiera schemat żądania, które jest publikowane do usługi GitHub.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
    "description": "Details for Webhook",
    "schema": {
        "$ref": "#/definitions/WebhookPushResponse"
    }
    },
    "post": {
    "description": "Creates a Github webhook",
    "summary": "Triggers when a PUSH event occurs",
    "operationId": "webhook-trigger",
    "x-ms-trigger": "single",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "Request body of webhook",
        "in": "body",
        "description": "This is the request body of the Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookRequestBody"
        }
        }
    ],
    "responses": {
        "201": {
        "description": "Created",
        "schema": {
            "$ref": "#/definitions/WebhookCreationResponse"
        }
        }
    }
    }
},

Ważne

Należy dołączyć właściwość "x-ms-trigger": "single", która jest rozszerzeniem schematu nakazującym usługom Logic Apps i Power Automate wyświetlenie tego elementu webhook na liście dostępnych wyzwalaczy w projektancie.

Zdefiniuj żądanie haka przychodzące z API

Postać przychodzącego żądania punktu zaczepienia (powiadomienia wysyłanego z usługi GitHub do usługi Logic Apps lub Power Automate) została zdefiniowana we właściwości niestandardowej x-ms-notification-content, jak pokazano w poprzednim przykładzie. Nie musi on zawierać całego żądania, a tylko te części, które mają być używane w aplikacjach logicznych lub przepływach.

Usuń webhook

Definicja OpenAPI musi zawierać definicję sposobu usuwania webhooka. Usługi Logic Apps i Power Automate podejmują próbę usunięcia elementu webhook w razie zaktualizowania wyzwalacza lub usunięcia aplikacji logiki bądź przepływu.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
    "description": "Deletes a Github webhook",
    "operationId": "DeleteTrigger",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "hook_Id",
        "in": "path",
        "description": "ID of the Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

W przypadku usuwania wywołania elementu webhook nie jest dołączony nagłówek związany z opłatą. To samo połączenie używane w łączniku jest również używane do usuwania wywołania sieci Web.

Ważne

Aby usługa Logic Apps lub Power Automate mogła usunąć element webhook, podczas jego tworzenia interfejs API musi dołączyć nagłówek Location HTTP do odpowiedzi 201. Nagłówek Location powinien zawierać ścieżkę do elementu webhook używanego przez żądanie DELETE protokołu HTTP. Na przykład nagłówek Location dołączony do odpowiedzi usługi GitHub ma następujący format: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Włączanie uwierzytelniania w GitHub

Interfejs API, który wysyła żądanie elementu webhook do usługi Logic Apps lub Power Automate, zazwyczaj używa jakiejś formy uwierzytelniania, a GitHub nie jest wyjątkiem pod tym względem. Usługa GitHub obsługuje kilka typów uwierzytelniania; w tym samouczku używamy tokenów osobistego dostępu.

Przejdź do usługi GitHub i zaloguj się, jeśli jeszcze tego nie zrobiono.
W prawym górnym rogu wybierz swój obraz profilu, a następnie kliknij pozycję Ustawienia w menu.
W menu po lewej stronie w obszarze Ustawienia dewelopera kliknij pozycję Osobiste tokeny dostępu.
Wybierz przycisk Generuj nowy token i w razie żądania potwierdź hasło.
W polu Opis tokenu wprowadź opis tokenu.
Zaznacz pole wyboru admin:repo_hook.
Wybierz Wygeneruj token.
Zanotuj wygenerowany token.

Ważne

Nie można ponownie uzyskać dostępu do tego tokenu. Należy go skopiować i wkleić na potrzeby użycia w kolejnych krokach tego samouczka.

Importuj definicję OpenAPI

Zacznij od zaimportowania definicji interfejsu OpenAPI dla usługi Logic Apps lub Power Automate.

Import definicji OpenAPI dla Logic Apps

Przejdź do witryny Azure Portal i otwórz łącznik usługi Logic Apps utworzony wcześniej w procedurze Tworzenie łącznika niestandardowego usługi Azure Logic Apps.
W menu swojego łącznika wybierz kolejno pozycje Łącznik usługi Logic Apps i wybierz Edytuj.
W obszarze Ogólne wybierz opcję Przekaż plik OpenAPI, a następnie przejdź do pobranego pliku OpenAPI.

Importuj definicję OpenAPI do Power Automate

Przejdź do flow.microsoft.com.
W prawym górnym rogu wybierz ikonę koła zębatego, a następnie wybierz pozycję Łączniki niestandardowe.
Wybierz pozycję Utwórz łącznik niestandardowy, a następnie wybierz pozycję Importuj kolekcję Postman.
Wprowadź nazwę łącznika niestandardowego, a następnie przejdź do pobranego pliku OpenAPI i wybierz pozycję Połącz.

Parametr Wartość

Tytuł łącznika niestandardowego „GitHubDemo”

Parametr	Wartość
Tytuł łącznika niestandardowego	„GitHubDemo”

Zakończ tworzenie łącznika niestandardowego

Na stronie Ogólne wybierz pozycję Kontynuuj.
Na stronie Zabezpieczenia w obszarze Typ uwierzytelniania wybierz opcję Uwierzytelnianie podstawowe.
W sekcji Uwierzytelnianie podstawowe wprowadź tekst Nazwa użytkownika i Hasło w polach etykiet. To są tylko etykiety, które będą wyświetlane, gdy wyzwalacz zostanie użyty w aplikacji logicznej lub przepływie.
Upewnij się, że w górnej części kreatora ustawiono nazwę „GitHubDemo”, a następnie wybierz pozycję Utwórz łącznik.

Jesteś już gotowy do użycia wyzwalacza w aplikacji logicznej lub przepływie albo można przeczytać, jak tworzyć wyzwalacze z poziomu interfejsu użytkownika.

Tworzenie wyzwalaczy elementu webhook z poziomu interfejsu użytkownika

W tej sekcji pokażemy, jak utworzyć w interfejsie użytkownika wyzwalacz bez żadnych definicji wyzwalania w definicji OpenAPI. Zacznij od bazowej definicji OpenAPI lub rozpocznij od zera w kreatorze niestandardowych łączników.

Na stronie Ogólne podaj opis i adres URL.

Parametr Wartość

Opis „GitHub to Repository The Social Code ds.”

Adres URL „api.github.com”
Na stronie Zabezpieczenia skonfiguruj uwierzytelnianie podstawowe, takie jak w poprzedniej sekcji.

Parametr	Wartość
Opis	„GitHub to Repository The Social Code ds.”
Adres URL	„api.github.com”

Na stronie Definicja wybierz opcję + Nowy wyzwalaczi wypełnij opis wyzwalacza. W tym przykładzie utworzysz wyzwalacz, który jest wyzwalany po wykonaniu żądania ściągnięcia do repozytorium.

Tworzenie wyzwalacza 1

Parametr	Wartość
Podsumowanie	„Wyzwala żądanie ściągnięcia do wybranego repozytorium”
Opis	„Wyzwala żądanie ściągnięcia do wybranego repozytorium”
Identyfikator operacji	„webhook-PR-trigger”
Widoczność	„brak” (więcej informacji poniżej)
Typ wyzwalacza	„Webhook”

Właściwość Widoczność dla operacji i parametrów w aplikacji lub przepływie logicznym ma następujące opcje:

brak: zazwyczaj wyświetlane w aplikacji logiki lub przepływie
zaawansowane: ukryte w dodatkowym menu
wewnętrzne: ukryte przed użytkownikiem
ważne: zawsze wyświetlane użytkownikowi w pierwszej kolejności

W obszarze Żądania są wyświetlane informacje na podstawie żądania HTTP dotyczącego akcji. Wybierz Importuj z próbki.
Zdefiniuj żądanie dla wyzwalacza elementu webhook, a następnie wybierz pozycję Importuj. W tym przykładzie przedstawiono przykład, który należy zaimportować (poniżej tego obrazu). Aby uzyskać więcej informacji, zobacz temat odniesienia do interfejsu API w Github. Usługi Logic Apps i Power Automate automatycznie dodają standardowe nagłówki content-type i zabezpieczeń, więc nie trzeba ich definiować podczas importowania przykładu.

Parametr Wartość

Czasownik „OPUBLIKUJ”

Adres URL „https://api.github.com/repos/{owner}/{repo}/hooks”

Treść Zobacz poniżej
```
{
  "name": "web",
  "active": true,
  "events": [
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook"
  }
}
```
W obszarze Odpowiedź są wyświetlane informacje na podstawie odpowiedzi HTTP dotyczącego akcji. Wybierz Dodaj odpowiedź domyślną.

Parametr	Wartość
Czasownik	„OPUBLIKUJ”
Adres URL	„https://api.github.com/repos/{owner}/{repo}/hooks”
Treść	Zobacz poniżej

Zdefiniuj odpowiedź dla wyzwalacza elementu webhook, a następnie wybierz pozycję Importuj. W tym przykładzie przedstawiono przykład, który należy zaimportować. Aby uzyskać więcej informacji, zobacz temat odniesienia do interfejsu API w Github.

Tworzenie wyzwalacza 3

{
  "action": "opened",
  "number": 1,
  "pull_request": {
    "html_url": "https://github.com/baxterthehacker/public-repo/pull/1",
    "state": "open",
    "locked": false,
    "title": "Update the README with new information",
    "user": {
      "login": "baxterthehacker",
      "type": "User"
    }
  }
}

W obszarze Konfiguracja wyzwalacza wybierz parametr, który powinien otrzymać wartość adresu zwrotnego URL z usługi GitHub. To własność url w objekcie config.
U ¿górnej części kreatora wprowadź nazwę, a następnie wybierz pozycję Utwórz łącznik.

Używanie elementu webhook jako wyzwalacza

Po skonfigurowaniu wszystkich elementów możesz użyć elementu webhook w aplikacji logiki lub przepływie. Utworzysz przepływ, który przy każdym odebraniu wypchnięcia narzędzia Git przez repozytorium GitHub będzie wysyłał powiadomienie wypychane do aplikacji mobilnej Power Automate.

W flow.microsoft.com w górnej części strony kliknij pozycję Moje przepływy.
Wybierz Utwórz od podstaw, a następnie na następnej stronie wybierz pozycję Przeszukaj setki łączników i wyzwalaczy.
W projektancie usługi Power Automate wyszukaj łącznik niestandardowy zarejestrowany wcześniej.

Wybierz element listy, który będzie używany jako wyzwalacz.
Ponieważ jest to pierwsze użycie łącznika niestandardowego, należy nawiązać z nim połączenie. Wprowadź informacje o połączeniu i wybierz Utwórz.

Parametr Wartość

Nazwa połączenia Opisowa nazwa

Nazwa użytkownika Twoja nazwa użytkownika GitHub

Hasło Wcześniej utworzony osobisty token dostępu
Wprowadź szczegóły dotyczące repozytorium, które ma być monitorowane. Zwróć uwagę na znane pola obiektu WebhookRequestBody z pliku OpenAPI.

Parametr Wartość

owner Właściciel repozytorium do monitorowania

repozytorium Repozytorium do monitorowania

Ważne

Twoje konto musi mieć uprawnienia do monitorowanego repozytorium. Najprościej jest użyć własnego repozytorium.
Wybierz + Nowy krok, a następnie wybierz Dodaj akcję.
Wyszukaj akcję Powiadomienie push i ją wybierz.
Wprowadź tekst w polu Tekst i w innych polach przy użyciu wartości w oknie dialogowym zawartość dynamiczna. Zauważ, że wartości te pochodzą z obiektu WebhookPushResponse w pliku OpenAPI.

Parametr Wartość

Nazwa połączenia Opisowa nazwa

Nazwa użytkownika Twoja nazwa użytkownika GitHub

Hasło Wcześniej utworzony osobisty token dostępu
Nazwij przepływ w górnej części strony i kliknij pozycję Utwórz przepływ.

Parametr	Wartość
Nazwa połączenia	Opisowa nazwa
Nazwa użytkownika	Twoja nazwa użytkownika GitHub
Hasło	Wcześniej utworzony osobisty token dostępu

Parametr	Wartość
owner	Właściciel repozytorium do monitorowania
repozytorium	Repozytorium do monitorowania

Parametr	Wartość
Nazwa połączenia	Opisowa nazwa
Nazwa użytkownika	Twoja nazwa użytkownika GitHub
Hasło	Wcześniej utworzony osobisty token dostępu

Weryfikacja i rozwiązywanie problemów

Aby sprawdzić, czy wszystko jest prawidłowo skonfigurowane, wybierz Moje przepływy, a następnie wybierz ikonę informacji znajdującą się obok nowego przepływu w celu wyświetlenia historii przebiegu:

Powinien być widoczny co najmniej jeden przebieg „Zakończone powodzeniem” odpowiadający utworzeniu elementu webhook. Oznacza to, że po stronie usługi GitHub pomyślnie utworzono element webhook.
W przypadku przebiegu zakończonego niepowodzeniem dostępne są szczegóły umożliwiające sprawdzenie przyczyny takiej sytuacji. Jeśli przyczyną niepowodzenia jest odpowiedź „404 Nie znaleziono”, prawdopodobnie konto GitHub nie ma odpowiednich uprawnień do utworzenia elementu webhook w używanym repozytorium.

Podsumowanie

Jeśli wszystko zostało poprawnie skonfigurowane, przy każdym wystąpieniu wypchnięcia narzędzia Git w wybranym repozytorium GitHub aplikacja mobilna Power Automate otrzyma powiadomienie push. Powyższy proces umożliwia użycie dowolnej usługi z obsługą elementów webhook jako wyzwalacza we własnych przepływach.

Następne kroki

Przekazywanie opinii

Jesteśmy wdzięczni za opinie na temat problemów z platformą łączników oraz pomysły na nowe funkcje. Aby przekazać opinię, przejdź na stronę Przesyłanie problemów lub uzyskiwanie pomocy dotyczącej łączników i wybierz typ opinii.

Share via