Push-Benachrichtigungen

Überblick

Die Reseller API verwendet die Pub/Sub API, um Push-Benachrichtigungen zu verschiedenen Google Workspace-Aboereignissen zu senden. Du kannst beispielsweise Push-Benachrichtigungen einrichten, um benachrichtigt zu werden, wenn sich der Abostatus deiner Kunden ändert.

Voraussetzungen

  • Aktivieren Sie die Pub/Sub API für Ihr Google Cloud-Projekt.
  • Weisen Sie dem Dienstkonto in Ihrem Cloud-Projekt Pub/Sub-IAM-Rollen zu. Die Erteilung der Rolle roles/pubsub.editor stellt einen guten Kompromiss dar (einfach und nicht zu breit gefasst). Möglicherweise möchten Sie jedoch spezifischere Pub/Sub-Berechtigungen verwenden.

Thema erstellen

Zum Erstellen eines Themas müssen Sie sich mit der Methode resellernotify.register bei der Reseller API registrieren. Für die Methode resellernotify.register wird die E-Mail-Adresse eines Dienstkontos als Parameter verwendet. Nur Dienstkonten, die durch diese Methode autorisiert wurden, können das neu erstellte Thema abonnieren.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Bei einer erfolgreichen Antwort werden der HTTP-Statuscode 200 und eine JSON-Antwort mit dem Namen des Pub/Sub-Themas zurückgegeben.

Hier ist eine Beispielantwort:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Wenn Sie zusätzliche Dienstkonten für die Verwendung Ihres Themas autorisieren möchten, können Sie resellernotify.register noch einmal aufrufen.

Zugriff für ein Dienstkonto widerrufen

Die Reseller API bietet auch die Möglichkeit, die Registrierung von Dienstkonten über den Endpunkt resellernotify.unregister aufzuheben:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Ein Thema abonnieren

Nachdem Sie das Pub/Sub-Thema erstellt haben, müssen Sie festlegen, wie Ihre Anwendung Ihre Änderungsereignisse verarbeitet. Wählen Sie eine der folgenden Optionen aus:

  • Push-Abo: Sie geben einen HTTP-POST-Callback an. Pub/Sub verwendet diesen Callback, um Ihre Anwendung über neue Ereignisse zu informieren.
  • Pull-Abo: Ihre Anwendung führt regelmäßig einen HTTP-Aufruf aus, um alle Änderungen in der Warteschlange abzurufen.

Das folgende Beispiel zeigt eine Anfrage zum Abonnieren eines Themas:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Ersetzen Sie Folgendes:

  • PROJECT: Ihr Google Cloud-Projekt.
  • SUBSCRIPTION_NAME: Ein eindeutiger Name für Ihr Abo.
  • TOPIC_NAME: Das zuvor erstellte Pub/Sub-Thema.
  • PUSH_NOTIFICATION_ENDPOINT: Endpunkt Ihres Push-Benachrichtigungs-Handlers.

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Hier ist eine Beispielantwort:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Benachrichtigungsformate

Im Folgenden finden Sie ein Beispiel für eine Pub/Sub-Benachrichtigung. Die Nachrichtendaten werden als base64-codierter JSON-String übertragen.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Hier sehen Sie das message.data-Beispielobjekt nach der Decodierung:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Ereignistypen

Die folgende Liste enthält alle möglichen Ereignistypen:

  • NEW_SUBSCRIPTION_CREATED: Ein neues Abo wurde erstellt.
  • SUBSCRIPTION_TRIAL_ENDED: Der Testzeitraum für ein Abo ist abgelaufen.
  • PRICE_PLAN_SWITCHED: Der Kunde ist vom flexiblen Tarif auf einen Jahrestarif umgestellt. Dieses Ereignis wird nicht ausgelöst, wenn der Kunde im Rahmen einer Verlängerung von einem Tarif mit Bindung in einen flexiblen Tarif wechselt.
  • COMMITMENT_CHANGED: Die jährliche Zusicherung wurde erhöht oder verringert.
  • SUBSCRIPTION_RENEWED: Ein Jahresabo wurde verlängert.
  • SUBSCRIPTION_SUSPENDED: Das Abo wurde gesperrt. Siehe Feld subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Die Sperrung wurde für ein zuvor gesperrtes Abo aufgehoben.
  • SUBSCRIPTION_CANCELLED: Abo wurde gekündigt. Siehe Feld subscription_cancellation_reason. Kann auch verwendet werden, um Übertragungen zu erkennen.

  • SUBSCRIPTION_CONVERTED: Abo wurde umgewandelt. Hier einige Beispiele für dieses Ereignis:

    • Direktes Abo in Reseller-Abo umwandeln.
    • Kostenpflichtiges Abo in Kulanzangebot umwandeln.
    • Online-Abo in Offline-Abo umwandeln

  • SUBSCRIPTION_UPGRADE: Abo-Artikelnummer wurde aktualisiert. Beispiel: Das Abo wurde von Google Workspace Business Starter auf Business Standard aktualisiert.

  • SUBSCRIPTION_DOWNGRADE: Downgrade des Abo-Artikels wurde ausgeführt. Beispielsweise wurde das Abo von Google Workspace Business Standard auf Business Starter herabgestuft.

  • LICENSE_ASSIGNMENT_CHANGED: Die Lizenz wurde einem Nutzer zugewiesen oder ihm entzogen. Sie können dieses Ereignis verwenden, um Änderungen an der Anzahl der Nutzerlizenzen bei flexiblen Abos reaktiv zu verfolgen.

Gründe für die Kündigung von Abos

Der Grund für die Kündigung des Abos wird angegeben, wenn event_type den Wert SUBSCRIPTION_CANCELLED hat. Mögliche Kündigungsgründe sind:

  • TRANSFERRED_OUT: Der Kunde hat zur direkten Abrechnung oder zu einem anderen Reseller gewechselt.
  • PURCHASE_OF_SUBSUMING_SKU: Der Kunde hat ein Upgrade auf eine Artikelnummer durchgeführt, die eine andere Artikelnummer überschreibt. Wenn z. B. ein Kunde mit Google Workspace Business Starter und Google Vault ein Upgrade auf Google Workspace Business Plus ausführt, wird das Vault-Abo auf das Vault-Abo angerechnet, da es in Google Workspace Business Plus enthalten ist.
  • RESELLER_INITIATED: Der Reseller hat das Abo gekündigt.
  • OTHER: Das Abo wurde aus einem anderen als den aufgeführten Gründen gekündigt.

Gründe für die Sperrung von Abos

Der Grund für die Sperrung des Abos wird angegeben, wenn event_type den Wert SUBSCRIPTION_SUSPENDED hat. Mögliche Gründe für eine Sperrung:

  • PENDING_TOS_ACCEPTANCE: Der Kunde hat sich nicht angemeldet und die Nutzungsbedingungen von Google Workspace-Resellern akzeptiert.
  • RENEWAL_WITH_TYPE_CANCEL: Die Zusicherung des Kunden ist abgelaufen und der Dienst wurde zum Ende der Laufzeit gekündigt.
  • RESELLER_INITIATED: Der Reseller hat das Abo manuell gesperrt.
  • TRIAL_ENDED: Der Testzeitraum des Kunden ist abgelaufen und der Kunde hat keinen anderen Tarif als Testzeitraum ausgewählt.
  • OTHER: Der Kunde wurde aus internen Google-Gründen gesperrt, z. B. wegen Missbrauchs.

Pub/Sub-Einschränkungen

Die Reihenfolge der Push-Benachrichtigungen ist nicht garantiert. Nachrichten können mehrfach und in extremen Situationen überhaupt nicht zugestellt werden. Wir empfehlen, reseller.subscriptions.get für alle geänderten Abos zu verwenden, um den aktuellen Status abzurufen.