Benachrichtigungen mit Webhooks einrichten

Sie lesen gerade die Dokumentation zu Apigee Edge.
Zur Dokumentation zu Apigee X. info

Was ist ein Webhook?

Ein Webhook definiert einen HTTP-Callback-Handler, der durch ein Ereignis ausgelöst wird. Sie können Webhooks erstellen und so konfigurieren, dass sie Ereignisbenachrichtigungen verarbeiten. Das ist eine Alternative zu den Vorlagen für Monetarisierungsbenachrichtigungen, wie unter Benachrichtigungen mit Benachrichtigungsvorlagen einrichten beschrieben.

So richten Sie Benachrichtigungen mit Webhooks ein: Führen Sie die folgenden Schritte über die Edge-Verwaltungs UI oder die Management and Monetization API aus:

  1. Fügen Sie Webhooks hinzu, die die Callback-Handler für die Benachrichtigungsereignisse definieren. Verwenden Sie dazu die UI oder die API.
  2. Richten Sie den Callback-Handler ein.
  3. Richten Sie die Benachrichtigung für ein anpassbares Tarifpaket über die UI oder API ein.

Webhooks verwalten

Fügen Sie Webhooks hinzu und verwalten Sie sie, die die Callback-Handler für die Benachrichtigungsereignisse definieren. Verwenden Sie dazu die UI oder API.

Webhooks über die UI verwalten

Fügen Sie Webhooks hinzu und verwalten Sie sie, die die Callback-Handler für die Benachrichtigungsereignisse definieren. Verwenden Sie dazu die UI, wie in den folgenden Abschnitten beschrieben.

Die Seite „Webhooks“

Rufen Sie die Seite „Webhooks“ wie unten beschrieben auf.

Edge

So greifen Sie über die Edge-Benutzeroberfläche auf die Seite „Webhooks“ zu:

  1. Melden Sie sich unter apigee.com/edge an.
  2. Wählen Sie in der linken Navigationsleiste Veröffentlichen > Monetarisierung > Webhooks aus.

Die Seite „Webhooks“ wird angezeigt.

Wie in der Abbildung hervorgehoben, können Sie auf der Seite „Webhooks“ Folgendes tun:

Classic Edge (Private Cloud)

So greifen Sie über die Classic Edge-Benutzeroberfläche auf die Seite „Webhooks“ zu:

  1. Melden Sie sich unter http://ms-ip:9000 an. Dabei ist „ms-ip“ die IP-Adresse oder der DNS-Name des Management Server-Knotens.

  2. Wählen Sie Admin > Webhooks aus.

Die Seite „Webhooks“ wird angezeigt.

Auf der Seite „Webhooks“ können Sie Folgendes tun:

Webhook über die UI hinzufügen

So fügen Sie einen Webhook über die UI hinzu:

  1. Rufen Sie die Seite „Webhooks“ auf.
  2. Klicken Sie auf + Webhook.
  3. Geben Sie die folgenden Informationen ein. Alle Felder sind erforderlich.
    Feld Beschreibung
    Name Name des Webhooks.
    URL URL des Callback-Handlers, der aufgerufen wird, wenn die Ereignisbenachrichtigung ausgelöst wird. Weitere Informationen finden Sie unter Callback-Handler einrichten.
  4. Klicken Sie auf Speichern.

Der Webhook wird der Liste hinzugefügt und ist standardmäßig aktiviert.

Webhook über die UI bearbeiten

So bearbeiten Sie einen Webhook über die UI:

  1. Rufen Sie die Seite „Webhooks“ auf.
  2. Bewegen Sie den Mauszeiger auf den Webhook, den Sie bearbeiten möchten, und klicken Sie im Aktionsmenü auf .
  3. Bearbeiten Sie die Webhook-Felder nach Bedarf.
  4. Klicken Sie auf Webhook aktualisieren.

Webhook über die UI aktivieren oder deaktivieren

So aktivieren oder deaktivieren Sie einen Webhook über die UI:

  1. Rufen Sie die Seite „Webhooks“ auf.
  2. Bewegen Sie den Mauszeiger auf den Webhook und aktivieren oder deaktivieren Sie ihn mit dem Schalter für den Status.

Webhook über die UI löschen

So löschen Sie einen Webhook über die UI:

  1. Rufen Sie die Seite „Webhooks“ auf.
  2. Bewegen Sie den Mauszeiger auf den Webhook, den Sie löschen möchten, und klicken Sie auf .

Der Webhook wird gelöscht und aus der Liste entfernt.

Webhooks mit der API verwalten

Fügen Sie Webhooks mit der API hinzu und verwalten Sie sie, wie in den folgenden Abschnitten beschrieben.

Alle Webhooks mit der API ansehen

Rufen Sie alle Webhooks auf, indem Sie eine GET-Anfrage an /mint/organizations/{org_name}/webhooks senden. Beispiel:

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

Im Folgenden finden Sie ein Beispiel für die zurückgegebene Antwort:

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

  ]
}

Webhook mit der API ansehen

Rufen Sie einen einzelnen Webhook auf, indem Sie eine GET-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id} senden.

Beispiel:

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

Im Folgenden finden Sie ein Beispiel für die Antwort:

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

Webhook mit der API hinzufügen

Fügen Sie einen Webhook hinzu, indem Sie eine POST-Anfrage an /mint/organizations/{org_name}/webhooks senden. Sie müssen den Namen des Webhooks und die URL des Callback-Handlers übergeben, der aufgerufen wird, wenn die Ereignisbenachrichtigung ausgelöst wird.

Im folgenden Beispiel wird ein Webhook mit dem Namen webhook3 erstellt und callbackhandler3 dem Webhook zugewiesen:

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

Im Folgenden finden Sie ein Beispiel für die Antwort:

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

Webhook mit der API bearbeiten

Bearbeiten Sie einen Webhook, indem Sie eine PUT-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id} senden. Übergeben Sie die Aktualisierungen im Anfragetext.

Im folgenden Beispiel wird der Callback-Handler aktualisiert, der mit webhook1 verknüpft ist:

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

Im Folgenden finden Sie ein Beispiel für die Antwort:

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

Webhook mit der API aktivieren oder deaktivieren

Aktivieren oder deaktivieren Sie einen Webhook, indem Sie eine POST-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id} senden, wie beim Aktualisieren eines Webhooks, und setzen Sie das Attribut „enabled“ im Anfragetext auf „true“ oder „false“. Wenn Sie den Webhook deaktivieren, wird er nicht ausgelöst, wenn ein Ereignis eintritt.

Im folgenden Beispiel wird webhook3 aktiviert:

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

Im Folgenden finden Sie ein Beispiel für die Antwort:

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

Webhook mit der API löschen

Löschen Sie einen Webhook, indem Sie eine DELETE-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id} senden.

Wenn Sie erzwingen möchten, dass der Webhook gelöscht wird, auch wenn Prozesse ausgeführt werden, setzen Sie den forceDelete Abfrageparameter auf true. Andernfalls setzen Sie ihn auf false. Der Abfrageparameter forceDelete ist standardmäßig aktiviert (true) .

Im folgenden Beispiel wird webhook3 gelöscht:

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

Callback-Handler einrichten

Im Folgenden sehen Sie das Format der JSON-Anfrage, die an den Callback-Handler gesendet wird, der von einem Webhook definiert wird, wenn eine Ereignisbenachrichtigung ausgelöst wird. Sie müssen dafür sorgen, dass der Callback Handler die Anfrage entsprechend verarbeitet.

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

Benachrichtigungen für ein anpassbares Tarifpaket einrichten

Richten Sie Benachrichtigungen mit Webhooks für ein anpassbares Tarifpaket über die UI oder API ein.

Benachrichtigungen für ein anpassbares Tarifpaket über die UI einrichten

Richten Sie Benachrichtigungen mit Webhooks für ein anpassbares Tarifpaket über die UI ein, wie unten beschrieben.

Dialogfeld „Benachrichtigungen“ für ein anpassbares Tarifpaket aufrufen

Rufen Sie das Dialogfeld „Benachrichtigungen“ für ein anpassbares Tarifpaket auf, wie unten beschrieben.

Edge

So rufen Sie das Dialogfeld „Benachrichtigungen“ über die Edge-Benutzeroberfläche auf:

  1. Erstellen und veröffentlichen Sie ein anpassbares Tarifpaket für Benachrichtigungen, wie unter Details für anpassbares Tarifpaket für Benachrichtigungen angeben beschrieben.
  2. Rufen Sie die Seite „Tarifpakete“ auf, indem Sie in der linken Navigationsleiste Veröffentlichen > Monetarisierung > Tarifpakete auswählen.
  3. Bewegen Sie den Mauszeiger auf das veröffentlichte anpassbare Tarifpaket für Benachrichtigungen, um Aktionen anzuzeigen.
  4. Klicken Sie auf \+ Benachrichtigen.

    Das Dialogfeld „Benachrichtigungen“ wird angezeigt.

    Hinweis: Das Tarifpaket muss veröffentlicht sein, damit die Aktion „\+ Benachrichtigen“ angezeigt wird.

Classic Edge (Private Cloud)

So rufen Sie die Seite „Benachrichtigungen“ auf:

  1. Erstellen Sie ein anpassbares Tarifpaket für Benachrichtigungen, wie unter Details für anpassbares Tarifpaket für Benachrichtigungen angeben beschrieben.
  2. Wählen Sie Veröffentlichen > Pakete aus, um die Tarifpakete aufzurufen.
  3. Klicken Sie in der Spalte „Aktionen“ für das Tarifpaket auf \+ Benachrichtigen.

    Das Dialogfeld „Benachrichtigungen“ wird angezeigt.

Benachrichtigungen für ein anpassbares Tarifpaket über die UI hinzufügen

So fügen Sie Benachrichtigungen für ein anpassbares Tarifpaket über die UI hinzu:

  1. Rufen Sie das Dialogfeld „Benachrichtigungen“ auf.
  2. Legen Sie die Benachrichtigungsbedingung unter Benachrichtigungsintervalle fest, indem Sie einen Prozentsatz der Zielanzahl der Transaktionen angeben, bei dem eine Benachrichtigung ausgelöst werden soll. Genauer gesagt:
    • Wenn Sie einen genauen Prozentsatz festlegen möchten, geben Sie den Prozentsatz in das Feld Bei/Ab % ein und lassen Sie das Feld Bis % leer.
    • Wenn Sie einen Prozentsatzbereich festlegen möchten, geben Sie den Start- und Endprozentsatz in die Bei/Ab % und Bis % Felder ein und einen Schrittwert in das Schritt % Feld. Standardmäßig werden Benachrichtigungen in Schritten von 10 % innerhalb des angegebenen Bereichs gesendet.

    Das Feld Notify At wird aktualisiert, um jeden Prozentsatz der Zielanzahl der Transaktionen widerzuspiegeln, der ein Ereignis auslöst.

  3. Wenn Sie weitere Benachrichtigungsbedingungen festlegen möchten, klicken Sie auf + Hinzufügen und wiederholen Sie Schritt 4.
  4. Legen Sie die Benachrichtigungsaktion unter Webhooks fest, indem Sie einen oder mehrere Webhooks auswählen, um die Callback-Verarbeitung zu verwalten, wenn Benachrichtigungen ausgelöst werden.
  5. Klicken Sie auf Benachrichtigung erstellen.

Benachrichtigungen für ein anpassbares Tarifpaket über die UI bearbeiten

So bearbeiten Sie Benachrichtigungen für ein anpassbares Tarifpaket über die UI:

  1. Rufen Sie das Dialogfeld „Benachrichtigungen“ auf.
  2. Klicken Sie in der Spalte „Aktionen“ für das Tarifpaket auf \+ Benachrichtigen.
  3. Klicken Sie auf Bearbeiten.
  4. Ändern Sie die Werte nach Bedarf.
  5. Klicken Sie auf Benachrichtigung speichern.

Benachrichtigungen für ein anpassbares Tarifpaket über die UI löschen

So löschen Sie eine Benachrichtigungsbedingung und -aktion:

  1. Rufen Sie das Dialogfeld „Benachrichtigungen“ auf.
  2. Klicken Sie in der Spalte „Aktionen“ für das Tarifpaket auf \+ Benachrichtigen.
  3. Klicken Sie auf Benachrichtigung löschen.

Benachrichtigungen für ein anpassbares Tarifpaket mit der API einrichten

Wenn Sie eine Benachrichtigung für ein anpassbares Tarifpaket mit der API einrichten möchten, folgen Sie der Anleitung unter Benachrichtigungsbedingungen und -aktionen mit der API verwalten und verwenden Sie die in diesem Abschnitt beschriebenen Attribute.

Verwenden Sie die folgenden Attributwerte, um die Benachrichtigungsbedingung (notificationCondition) festzulegen. Weitere Informationen finden Sie unter Konfigurations attribute für Benachrichtigungsbedingungen.

Attribut Wert
RATEPLAN ID des anpassbaren Tarifpakets für Benachrichtigungen.
PUBLISHED TRUE, um anzugeben, dass das anpassbare Tarifpaket für Benachrichtigungen veröffentlicht werden muss.
UsageTarget Prozentsatz der Zielanzahl der Transaktionen, bei dem eine Benachrichtigung ausgelöst werden soll.

Mit diesem Attribut können Sie Entwickler benachrichtigen, wenn sie sich der Zielanzahl der Transaktionen für ein anpassbares Tarifpaket für Benachrichtigungen nähern oder diese erreicht haben das sie erworben haben. Wenn ein Entwickler beispielsweise ein anpassbares Tarifpaket für Benachrichtigungen erworben hat und die Zielanzahl der Transaktionen für den Entwickler auf 1.000 festgelegt wurde, können Sie ihn benachrichtigen, wenn er 800 Transaktionen (80% der Zielanzahl der Transaktionen), 1.000 Transaktionen (100%) oder 1.500 Transaktionen (150%) erreicht hat.

  • Wenn Sie einen genauen Prozentsatz festlegen möchten, geben Sie %= n ein. Beispiel: %= 80 sendet Benachrichtigungen, wenn der Prozentsatz der Zielanzahl der Transaktionen 80 % erreicht.
  • Wenn Sie einen Prozentsatzbereich festlegen möchten, geben Sie den Start- und Endprozentsatz sowie den Wert ein, um den der Prozentsatz erhöht werden soll: %= start to end by n. Beispiel: Der Wert %= 80 to 100 by 10 sendet Benachrichtigungen, wenn der Prozentsatz der Zielanzahl der Transaktionen 80%, 90 % und 100 % erreicht.

Legen Sie die Benachrichtigungsaktion unter actions mit den folgenden Werten fest. Weitere Informationen finden Sie unter Konfigurationsattribute für Benachrichtigungsaktionen.

Attribut Wert
actionAttribute WEBHOOK, um einen Webhook auszulösen.
value ID des Webhooks, den Sie im vorherigen Abschnitt Webhooks mit der API erstellen definiert haben.

Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Benachrichtigungsbedingung erstellen, die einen Webhook auslöst, wenn der Prozentsatz der Zielanzahl der Transaktionen 80%, 90%, 100%, 110%, und 120 % erreicht.

{
    "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",
        }]
  }

Informationen zum Ansehen, Aktualisieren und Löschen einer Benachrichtigungsbedingung und -aktion, finden Sie unter:

Webhook-Antwortcodes

Im Folgenden finden Sie eine Zusammenfassung der Webhook-Antwortcodes und ihrer Interpretation durch das System.

Antwortcode Beschreibung
2xx Erfolgreich
5xx

Fehlgeschlagene Anfrage. Das System wiederholt die Anfrage bis zu dreimal in Abständen von 5 Minuten.

Hinweis: Die Lese- und Verbindungszeitüberschreitungen für Webhook-Anfragen betragen jeweils 3 Sekunden. Das kann zu fehlgeschlagenen Anfragen führen.
Other response Fehlgeschlagene Anfrage. Das System wiederholt die Anfrage nicht.