Udostępnij za pośrednictwem

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

  • Artykuł

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

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.

  1. Przejdź do usługi GitHub i zaloguj się, jeśli jeszcze tego nie zrobiono.

  2. W prawym górnym rogu wybierz swój obraz profilu, a następnie kliknij pozycję Ustawienia w menu.

    Ustawienia

  3. W menu po lewej stronie w obszarze Ustawienia dewelopera kliknij pozycję Osobiste tokeny dostępu.

  4. Wybierz przycisk Generuj nowy token i w razie żądania potwierdź hasło.

    Generowanie nowego tokenu

  5. W polu Opis tokenu wprowadź opis tokenu.

  6. Zaznacz pole wyboru admin:repo_hook.

    admin:repo_hook

  7. Wybierz Wygeneruj token.

  8. Zanotuj wygenerowany token.

    Nowy 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

  1. 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.

  2. W menu swojego łącznika wybierz kolejno pozycje Łącznik usługi Logic Apps i wybierz Edytuj.

    Edytuj łącznik usługi Logic Apps

  3. W obszarze Ogólne wybierz opcję Przekaż plik OpenAPI, a następnie przejdź do pobranego pliku OpenAPI.

    Zrzut ekranu, który pokazuje opcję Prześlij plik OpenAPI.

Importuj definicję OpenAPI do Power Automate

  1. Przejdź do flow.microsoft.com.

  2. W prawym górnym rogu wybierz ikonę koła zębatego, a następnie wybierz pozycję Łączniki niestandardowe.

    Łączniki niestandardowe

  3. Wybierz pozycję Utwórz łącznik niestandardowy, a następnie wybierz pozycję Importuj kolekcję Postman.

    Tworzenie łącznika niestandardowego

  4. Wprowadź nazwę łącznika niestandardowego, a następnie przejdź do pobranego pliku OpenAPI i wybierz pozycję Połącz.

    Zrzut ekranu, który pokazuje pole do wpisania imienia.

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

Zakończ tworzenie łącznika niestandardowego

  1. Na stronie Ogólne wybierz pozycję Kontynuuj.

  2. Na stronie Zabezpieczenia w obszarze Typ uwierzytelniania wybierz opcję Uwierzytelnianie podstawowe.

  3. 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.

    Uwierzytelnianie podstawowe

  4. 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.

  1. Na stronie Ogólne podaj opis i adres URL.

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

  2. Na stronie Zabezpieczenia skonfiguruj uwierzytelnianie podstawowe, takie jak w poprzedniej sekcji.

  3. 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

  4. W obszarze Żądania są wyświetlane informacje na podstawie żądania HTTP dotyczącego akcji. Wybierz Importuj z próbki.

    Strona definicji — Importowanie z próbki

  5. 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.

    Tworzenie wyzwalacza 2

    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"
  }
}

  6. W obszarze Odpowiedź są wyświetlane informacje na podstawie odpowiedzi HTTP dotyczącego akcji. Wybierz Dodaj odpowiedź domyślną.

    Strona Definicja — odpowiedź

  7. 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"
    }
  }
}

  8. 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.

    Tworzenie wyzwalacza 4

  9. 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.

  1. W flow.microsoft.com w górnej części strony kliknij pozycję Moje przepływy.

  2. Wybierz Utwórz od podstaw, a następnie na następnej stronie wybierz pozycję Przeszukaj setki łączników i wyzwalaczy.

    Łączniki wyszukiwania

  3. W projektancie usługi Power Automate wyszukaj łącznik niestandardowy zarejestrowany wcześniej.

    Nowy wyzwalacz

    Wybierz element listy, który będzie używany jako wyzwalacz.

  4. 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.

    Nowe połączenie

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

  5. Wprowadź szczegóły dotyczące repozytorium, które ma być monitorowane. Zwróć uwagę na znane pola obiektu WebhookRequestBody z pliku OpenAPI.

    Informacje o repozytorium

    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.

  6. Wybierz + Nowy krok, a następnie wybierz Dodaj akcję.

  7. Wyszukaj akcję Powiadomienie push i ją wybierz.

    Powiadomienie push

  8. 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.

    Szczegóły powiadomienia push

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

  9. Nazwij przepływ w górnej części strony i kliknij pozycję Utwórz przepływ.

    Nazwa przepływu

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.