Konfigurowanie powiadomień za pomocą webhooków

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. Informacje

Co to jest webhook?

webhook określa moduł obsługi wywołania zwrotnego HTTP, który jest aktywowany przez zdarzenie. Możesz utworzyć webhooki i skonfigurować je do obsługi powiadomień o zdarzeniach jako alternatywy dla szablonów powiadomień o generowaniu przychodu, zgodnie z opisem w artykule Konfigurowanie powiadomień za pomocą szablonów powiadomień.

Aby skonfigurować powiadomienia za pomocą webhooków, wykonaj te czynności za pomocą interfejsu Edge Management lub interfejsu 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 abonamencie, który można dostosować, za pomocą interfejsu użytkownika 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

Dodaj webhooki, które definiują moduły obsługi wywołań zwrotnych dla zdarzeń powiadomień, i zarządzaj nimi za pomocą interfejsu użytkownika zgodnie z opisem w kolejnych sekcjach.

Informacje o stronie webhooki

Otwórz stronę webhooki zgodnie z opisem poniżej.

Edge

Aby uzyskać dostęp do strony webhooków za pomocą interfejsu Edge:

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

Zostanie wyświetlona strona webhooków.

Jak zaznaczono na ilustracji, strona Webhooki umożliwia:

Classic Edge (Private Cloud)

Aby uzyskać dostęp do strony webhooków za pomocą interfejsu użytkownika klasycznej wersji Edge:

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

  2. Wybierz Administracja > Webhooki.

Zostanie wyświetlona strona webhooków.

Strona Webhooki umożliwia:

Dodawanie webhooka za pomocą interfejsu użytkownika

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

  1. Otwórz stronę webhooków.
  2. Kliknij + Webhook.
  3. Wpisz te informacje (wszystkie pola są wymagane).
    Pole Opis
    Nazwa Nazwa webhooka.
    Adres URL Adres URL modułu obsługi wywołania zwrotnego, który będzie wywoływany po wywołaniu powiadomienia o zdarzeniu. Zapoznaj się z sekcją 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 użytkownika

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. Edytuj 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 użytkownika:

  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 przy użyciu interfejsu użytkownika

Aby usunąć webhooka za pomocą UI:

  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

Oto 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 usługi /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

Oto przykład takiej odpowiedzi:

{
   "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 usługi /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 wywołaniu powiadomienia o zdarzeniu.

Poniższy przykład powoduje utworzenie webhooka o nazwie webhook3 i przypisanie do niego parametru 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

Oto przykład takiej odpowiedzi:

{
  "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 przy użyciu interfejsu API

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

Na przykład to ustawienie spowoduje zaktualizowanie modułu obsługi wywołania zwrotnego powiązanego z zasadą webhook1:

curl -X PUT "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

Oto przykład takiej odpowiedzi:

{
  "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 w przypadku aktualizacji webhooka, i ustaw włączony atrybut w treści żądania odpowiednio na „true” (prawda) lub „false” (fałsz). Jeśli wyłączysz webhooka, nie zostanie on aktywowany po wystąpieniu zdarzenia.

W ten sposób włączana jest na przykład usługa 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

Oto przykład takiej odpowiedzi:

{
  "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 przy użyciu interfejsu API

Usuń webhooka, wysyłając żądanie DELETE do usługi /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).

Przykładowe polecenie usuwa element 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 pokazujemy format żądania JSON, które jest wysyłane do modułu obsługi wywołania zwrotnego zdefiniowanego przez webhooka po wywołaniu powiadomienia o zdarzeniu. Musisz się upewnić, że moduł obsługi wywołań zwrotnych 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ń w przypadku abonamentu z możliwością dostosowania

Skonfiguruj powiadomienia za pomocą webhooków na potrzeby abonamentu, które można dostosować za pomocą interfejsu lub API.

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

Skonfiguruj powiadomienia za pomocą webhooków na potrzeby planu stawek z możliwością dostosowania za pomocą interfejsu użytkownika w sposób opisany poniżej.

Otwórz okno Powiadomienia, aby uzyskać informacje o planie stawek z możliwością dostosowania

Otwórz okno Powiadomienia dotyczące abonamentu z możliwością dostosowania w sposób opisany poniżej.

Edge

Aby uzyskać dostęp do okna powiadomień za pomocą interfejsu Edge:

  1. Utwórz i opublikuj plan stawek za powiadomienia z możliwością dostosowania zgodnie z opisem w sekcji Określanie szczegółów planu powiadomień z możliwością dostosowania.
  2. Otwórz stronę Plany stawek, wybierając Opublikuj > Zarabianie > Plany stawek na pasku nawigacyjnym po lewej stronie.
  3. Aby wyświetlić działania, najedź kursorem na opublikowany plan częstotliwości powiadomień z możliwością dostosowania.
  4. Kliknij +Powiadom.

    Pojawi się okno Powiadomienia.

    Uwaga: aby możliwe było wyświetlenie działania +Powiadom, plan stawek musi zostać opublikowany.

Classic Edge (Private Cloud)

Aby uzyskać dostęp do strony Powiadomienia:

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

    Pojawi się okno Powiadomienia.

Dodawanie powiadomień dotyczących planu dostosowywanych stawek za pomocą interfejsu użytkownika

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

  1. Otwórz okno Powiadomienia.
  2. Ustaw warunek powiadamiania w sekcji Częstotliwość powiadomień, określając odsetek docelowej liczby transakcji, w przypadku których ma być wysyłane powiadomienie. W szczególności:
    • Aby ustawić dokładną wartość procentową, wpisz ją w polu Od %, a pole Do % pozostaw puste.
    • Aby ustawić zakres procentowy, wpisz wartość procentową początku i końca w polach Od % i Do % oraz wartość przyrostu w polu Krok %. Domyślnie powiadomienia są wysyłane co 10% w określonym zakresie.

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

  3. Aby ustawić dodatkowe warunki powiadomień, kliknij +Dodaj i powtórz krok 4.
  4. Ustaw działanie powiadomienia w sekcji Webhooki, wybierając co najmniej 1 webhooka do zarządzania obsługą wywołań zwrotnych po aktywowaniu powiadomień.
  5. Kliknij Utwórz powiadomienie.

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

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

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

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

Aby usunąć warunek i działanie związane z powiadomieniem:

  1. Otwórz okno Powiadomienia.
  2. Kliknij +Powiadom w kolumnie Działania przy planie stawek.
  3. Kliknij Usuń powiadomienie.

Konfigurowanie powiadomień dotyczących abonamentu z możliwością dostosowania przy użyciu interfejsu API

Aby skonfigurować za pomocą interfejsu API powiadomienie o dostosowywanym planie stawek, wykonaj procedurę opisaną w sekcji Zarządzanie warunkami powiadomień i działaniami dotyczącymi powiadomień 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 artykule o właściwościach konfiguracji warunków powiadomień.

Atrybut Wartość
RATEPLAN Identyfikator dostosowywanego planu stawek za powiadomienia.
PUBLISHED TRUE wskazuje, że plan dotyczący dostosowanych stawek powiadomień musi zostać opublikowany.
UsageTarget Odsetek docelowej liczby transakcji, kiedy ma być wywoływane powiadomienie.

Ten atrybut umożliwia powiadamianie deweloperów, gdy zbliżą się do docelowej liczby transakcji lub osiągną docelową liczbę transakcji w ramach zakupionego przez nich planu arkusza stawek z możliwością dostosowania. Jeśli na przykład deweloper wykupił abonament z możliwością dostosowania powiadomień, a jego docelowa liczba transakcji została ustawiona na 1000, możesz powiadomić go, gdy osiągnął 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ść początkową i końcową oraz wartość, o którą chcesz zwiększać wartość: %= start to end by n. Na przykład wartość %= 80 to 100 by 10 będzie wysyłać powiadomienia, gdy odsetek docelowej liczby transakcji osiągnie 80%, 90% i 100%.

Aby skonfigurować działanie powiadomienia, w sekcji actions ustaw poniższe wartości. Więcej informacji znajdziesz w artykule Właściwości konfiguracji działań związanych z powiadomieniami.

Atrybut Wartość
actionAttribute WEBHOOK, aby aktywować webhooka.
value Identyfikator webhooka określonego 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",
        }]
  }

Informacje o wyświetlaniu, aktualizowaniu i usuwaniu warunku oraz działania związanego z powiadomieniami znajdziesz w tych artykułach:

Kody odpowiedzi webhooka

Poniżej znajdziesz podsumowanie kodów odpowiedzi webhooka i sposób ich interpretacji przez system.

Kod odpowiedzi Opis
2xx Gotowe
5xx

Żądanie nie powiodło się. System ponawia żądanie maksymalnie 3 razy w 5-minutowych przedziałach czasowych.

Uwaga: limity czasu odczytu i połączenia żądań webhooka wynoszą 3 sekundy, co może prowadzić do nieudanych żądań.
Other response Żądanie nie powiodło się. System nie spróbuje ponownie przesłać prośby.