Konfigurowanie powiadomień za pomocą webhooków

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Co to jest webhook?

webhook definiuje moduł obsługi wywołania zwrotnego HTTP wywoływany przez zdarzenie. Możesz tworzyć webhooki i skonfigurować je do obsługi powiadomień o zdarzeniach zamiast używania szablonów powiadomień dotyczących zarabiania zgodnie z opisem w sekcji Konfigurowanie powiadomień za pomocą szablonów powiadomień.

Aby skonfigurować powiadomienia za pomocą webhooków, wykonaj te czynności w interfejsie zarządzania urządzeniami brzegowymi lub interfejsie Management and Monetization API:

  1. Dodaj webhooki, które definiują moduły obsługi wywołań zwrotnych dla zdarzeń powiadomień za pomocą interfejsu lub API.
  2. Skonfiguruj moduł obsługi wywołania zwrotnego.
  3. Skonfiguruj powiadomienie o planie z możliwością dostosowania za pomocą interfejsu lub API.

Zarządzanie webhookami

Dodaj webhooki, które definiują moduły obsługi wywołań zwrotnych dla zdarzeń powiadomień, i zarządzaj nimi za pomocą interfejsu lub API.

Zarządzanie webhookami za pomocą interfejsu użytkownika

Możesz dodawać webhooki, które definiują moduły obsługi wywołań zwrotnych zdarzeń powiadomień, korzystając z interfejsu użytkownika w sposób opisany w kolejnych sekcjach.

Eksplorowanie strony webhooków

Otwórz stronę webhooków w sposób opisany poniżej.

Edge

Aby uzyskać dostęp do strony webhooków przy użyciu interfejsu Edge:

  1. Zaloguj się na stronie apigee.com/edge.
  2. Na pasku nawigacyjnym po lewej stronie kliknij Opublikuj > Zarabianie > Webhooki.

Zostanie wyświetlona strona webhooków.

Jak zaznaczyliśmy na ilustracji, strona webhooków umożliwia:

Klasyczna wersja Edge (Private Cloud)

Aby uzyskać dostęp do strony webhooków w klasycznym interfejsie użytkownika Edge:

  1. Zaloguj się w http://ms-ip:9000, gdzie ms-ip to adres IP lub nazwa DNS węzła serwera zarządzania.

  2. Wybierz Administracja > Webhooki.

Zostanie wyświetlona strona webhooków.

Strona webhooków umożliwia:

Dodawanie webhooka przy użyciu interfejsu użytkownika

Aby dodać webhooka za pomocą interfejsu użytkownika:

  1. Otwórz stronę webhooków.
  2. Kliknij + Webhook.
  3. Wpisz poniższe informacje (wszystkie pola są wymagane).
    Pole Opis
    Nazwa Nazwa webhooka.
    URL Adres URL modułu obsługi wywołania zwrotnego, który zostanie wywołany po uruchomieniu powiadomienia o zdarzeniu. Zobacz Konfigurowanie modułu obsługi wywołania zwrotnego.
  4. Kliknij Zapisz.

Webhook zostanie dodany do listy i domyślnie włączony.

Edytowanie webhooka za pomocą interfejsu

Aby edytować webhooka za pomocą interfejsu użytkownika:

  1. Otwórz stronę webhooków.
  2. Najedź kursorem na webhooka, który chcesz edytować, i kliknij w menu czynności.
  3. Zmodyfikuj pola webhooka zgodnie z wymaganiami.
  4. Kliknij Zaktualizuj webhooka.

Włączanie i wyłączanie webhooka za pomocą interfejsu użytkownika

Aby włączyć lub wyłączyć webhooka za pomocą interfejsu:

  1. Otwórz stronę webhooków.
  2. Najedź kursorem na webhooka i przełącz przełącznik stanu, aby go włączyć lub wyłączyć.

Usuwanie webhooka za pomocą interfejsu użytkownika

Aby usunąć webhooka za pomocą interfejsu użytkownika:

  1. Otwórz stronę webhooków.
  2. Najedź kursorem na webhooka, który chcesz usunąć, i kliknij .

Webhook zostanie usunięty z listy.

Zarządzanie webhookami przy użyciu interfejsu API

Dodaj webhooki i zarządzaj nimi za pomocą interfejsu API w sposób opisany w sekcjach poniżej.

Wyświetlanie wszystkich webhooków za pomocą interfejsu API

Wyświetl wszystkie webhooki, wysyłając żądanie GET do usługi /mint/organizations/{org_name}/webhooks. Na przykład:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

Poniżej znajdziesz przykład zwróconej odpowiedzi:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Wyświetlanie webhooka przy użyciu interfejsu API

Wyświetl pojedynczego webhooka, wysyłając żądanie GET do strony /mint/organizations/{org_name}/webhooks/{webhook_id}.

Na przykład:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Poniżej znajdziesz przykładową odpowiedź:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Dodawanie webhooka za pomocą interfejsu API

Dodaj webhooka, wysyłając żądanie POST do: /mint/organizations/{org_name}/webhooks. Musisz przekazać nazwę webhooka i adres URL modułu obsługi wywołania zwrotnego, który zostanie wywołany po uruchomieniu powiadomienia o zdarzeniu.

Poniższy przykład tworzy webhooka o nazwie webhook3 i przypisuje mu callbackhandler3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

Poniżej znajdziesz przykładową odpowiedź:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Edytowanie webhooka za pomocą interfejsu API

Edytuj webhooka, wysyłając żądanie POST do: /mint/organizations/{org_name}/webhooks/{webhook_id}. Przekaż aktualizacje w treści żądania.

Na przykład w tym przykładzie aktualizujemy moduł obsługi wywołania zwrotnego powiązany z webhook1:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

Poniżej znajdziesz przykładową odpowiedź:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Włączanie i wyłączanie webhooka za pomocą interfejsu API

Włącz lub wyłącz webhooka, wysyłając żądanie POST do /mint/organizations/{org_name}/webhooks/{webhook_id}, tak jak przy aktualizacji webhooka, i ustaw włączony atrybut w treści żądania na wartość „true” (prawda) lub „false” (fałsz). Jeśli wyłączysz webhooka, nie będzie on wywoływany po wystąpieniu zdarzenia.

Na przykład w ten sposób można włączyć webhook3:

curl -X POST  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

Poniżej znajdziesz przykładową odpowiedź:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Usuwanie webhooka za pomocą interfejsu API

Usuń webhooka, wysyłając żądanie DELETE do /mint/organizations/{org_name}/webhooks/{webhook_id}.

Aby określić, czy chcesz wymuszać usunięcie webhooka w przypadku trwających procesów, ustaw parametr zapytania forceDelete na true lub false. Parametr zapytania forceDelete jest domyślnie włączony (true).

Na przykład spowoduje to usunięcie webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Konfigurowanie modułu obsługi wywołania zwrotnego

Poniżej przedstawiono format żądania JSON, które jest wysyłane do modułu obsługi wywołania zwrotnego zdefiniowanego przez webhooka po uruchomieniu powiadomienia o zdarzeniu. Musisz się upewnić, że moduł obsługi wywołania zwrotnego prawidłowo przetwarza żądanie.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Konfigurowanie powiadomień o planie z możliwością dostosowania

Skonfiguruj powiadomienia za pomocą webhooków na potrzeby abonamentu z możliwością dostosowania za pomocą interfejsu lub API.

Konfigurowanie powiadomień dotyczących abonamentu z możliwością dostosowania za pomocą interfejsu

Skonfiguruj powiadomienia za pomocą webhooków na potrzeby abonamentu z możliwością dostosowania w interfejsie w sposób opisany poniżej.

Otwórz okno Powiadomienia, aby uzyskać dostęp do planu taryfowego z możliwością dostosowania

Otwórz okno Powiadomienia, aby uzyskać dostęp do planu taryfowego z możliwością dostosowania, zgodnie z opisem poniżej.

Edge

Aby uzyskać dostęp do okna powiadomień w interfejsie Edge:

  1. Utwórz i opublikuj plan z możliwością dostosowania stawki powiadomień zgodnie z opisem w sekcji Określanie szczegółów dostosowywanego planu powiadomień.
  2. Aby otworzyć stronę Abonamenty, na pasku nawigacyjnym po lewej stronie kliknij Opublikuj > Zarabianie > Plany stawek.
  3. Aby wyświetlić działania, umieść kursor nad opublikowanym planem z możliwością dostosowania częstotliwości powiadomień.
  4. Kliknij +Powiadom.

    Pojawi się okno Powiadomienia.

    Uwaga: aby działanie „+Powiadom” wyświetlało się po opublikowaniu planu stawek, musi on zostać opublikowany.

Klasyczna wersja Edge (Private Cloud)

Aby otworzyć stronę Powiadomienia:

  1. Utwórz plan powiadomień z możliwością dostosowania zgodnie z opisem w sekcji Określanie szczegółów dostosowywanego planu powiadomień.
  2. Aby wyświetlić plany stawek, kliknij Opublikuj > Pakiety.
  3. Kliknij +Powiadom w kolumnie „Działania” wybranego abonamentu.

    Pojawi się okno Powiadomienia.

Dodawanie za pomocą interfejsu powiadomień dotyczących abonamentu z możliwością dostosowania

Aby dodać w interfejsie powiadomienia dotyczące planu taryfowego z możliwością dostosowania:

  1. Otwórz okno Powiadomienia.
  2. W sekcji Interwały powiadomień ustaw warunek powiadomienia, określając procent docelowej liczby transakcji, podczas których ma być wysyłane powiadomienie. W szczególności:
    • Aby ustawić dokładną wartość procentową, wpisz ją w polu At/Od % i pozostaw pole Do % puste.
    • Aby ustawić zakres wartości procentowej, wpisz wartość procentową początkową i końcową w polach Od: % i Do %, a w polu Krok % wpisz wartość przyrostową. Domyślnie powiadomienia są wysyłane w przyrostach co 10% w określonym zakresie.

    Pole Notify At jest aktualizowane tak, aby odzwierciedlić każdy odsetek docelowej liczby transakcji, które mają aktywować zdarzenie.

  3. Aby ustawić dodatkowe warunki powiadomień, kliknij +Dodaj i powtórz krok 4.
  4. W sekcji Webhooki wybierz co najmniej jeden webhook, by zarządzać obsługą wywołań zwrotnych po wygenerowaniu powiadomień.
  5. Kliknij Utwórz powiadomienie.

Edytowanie powiadomień dotyczących abonamentu z możliwością dostosowania za pomocą interfejsu

Aby edytować w interfejsie powiadomienia dotyczące planu taryfowego z możliwością dostosowania:

  1. Otwórz okno Powiadomienia.
  2. Kliknij +Powiadom w kolumnie „Działania” wybranego abonamentu.
  3. Kliknij Edytuj.
  4. W razie potrzeby zmień wartości.
  5. Kliknij Zapisz powiadomienie.

Usuwanie w interfejsie powiadomień dotyczących planu taryfowego z możliwością dostosowania

Aby usunąć warunek powiadomienia i czynność:

  1. Otwórz okno Powiadomienia.
  2. Kliknij +Powiadom w kolumnie „Działania” wybranego abonamentu.
  3. Kliknij Usuń powiadomienie.

Konfigurowanie za pomocą interfejsu API powiadomień o planie z możliwością dostosowania

Aby skonfigurować za pomocą interfejsu API powiadomienie dotyczące abonamentu z możliwością dostosowania stawek, wykonaj czynności opisane w sekcji Zarządzanie warunkami powiadomień i działaniami za pomocą interfejsu API i użyj atrybutów opisanych w tej sekcji.

Aby skonfigurować warunek powiadomienia (notificationCondition), użyj poniższych wartości atrybutów. Więcej informacji znajdziesz w sekcji Właściwości konfiguracji warunków powiadomień.

Atrybut Wartość
RATEPLAN Identyfikator planu regulowania częstotliwości powiadomień.
PUBLISHED TRUE, aby wskazać, że należy opublikować plan dostosowania częstotliwości powiadomień.
UsageTarget Procent docelowej liczby transakcji, dla których ma zostać aktywowane powiadomienie.

Ten atrybut pozwala powiadamiać deweloperów, gdy zbliżą się do docelowej liczby transakcji lub gdy osiągną ich docelową liczbę transakcji w przypadku zakupionego abonamentu z dostosowywanym arkuszem stawek powiadomień. Jeśli na przykład deweloper wykupił plan z możliwością dostosowania stawki powiadomień, a docelowa liczba transakcji dewelopera została ustawiona na 1000, możesz go powiadomić o osiągnięciu 800 transakcji (80% docelowej liczby transakcji), 1000 transakcji (100%) lub 1500 transakcji (150%).

  • Aby ustawić dokładną wartość procentową, wpisz %= n. Na przykład %= 80 będzie wysyłać powiadomienia, gdy odsetek docelowej liczby transakcji osiągnie 80%.
  • Aby ustawić zakres procentowy, wpisz wartość procentową początkową i końcową oraz wartość, o którą chcesz zwiększać w następujący sposób: %= start to end by n. Na przykład wartość %= 80 to 100 by 10 wysyła powiadomienia, gdy odsetek docelowej liczby transakcji osiągnie 80%, 90% i 100%.

Aby skonfigurować działanie związane z powiadomieniem, w obszarze actions ustaw te wartości. Więcej informacji znajdziesz w artykule o właściwościach konfiguracji działań związanych z powiadomieniami.

Atrybut Wartość
actionAttribute WEBHOOK, aby aktywować webhooka.
value Identyfikator webhooka zdefiniowanego w poprzedniej sekcji – Tworzenie webhooków przy użyciu interfejsu API.

Poniżej znajdziesz przykład tworzenia warunku powiadomienia, który aktywuje webhooka, gdy odsetek docelowej liczby transakcji osiągnie 80%, 90%, 100%, 110% i 120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

Więcej informacji o wyświetlaniu, aktualizowaniu i usuwaniu warunku powiadomienia i działania znajdziesz tutaj:

Kody odpowiedzi webhooka

Poniżej znajdziesz podsumowanie kodów odpowiedzi webhooka oraz informacje o sposobie ich interpretacji przez system.

Kod odpowiedzi Opis
2xx Gotowe
5xx

Nie udało się zrealizować prośby. System ponawia próbę żądania maksymalnie 3 razy w 5-minutowych odstępach.

Uwaga: limity czasu odczytu i połączenia dla żądań webhooka wynoszą 3 sekundy, co może prowadzić do nieudanych żądań.
Other response Nie udało się zrealizować prośby. System nie ponawia żądania.