Push-Benachrichtigungen

Auf dieser Seite wird beschrieben, wie Sie Push-Benachrichtigungen mit der Reseller API verwenden.

Übersicht

In der Reseller API wird die Pub/Sub API verwendet, um Push-Benachrichtigungen zu Google Workspace-Aboereignissen zu senden. Sie können beispielsweise Push-Benachrichtigungen einrichten, um benachrichtigt zu werden, wenn sich der Status von Kundenabos ändert.

Vorbereitung

Aktivieren Sie die Pub/Sub API für Ihr Google Cloud-Projekt.
Weisen Sie Ihrem Dienstkonto in Ihrem Cloud-Projekt Pub/Sub-IAM-Rollen zu. Die Zuweisung der Rolle roles/pubsub.editor wird empfohlen, aber Sie können auch spezifischere Pub/Sub-Berechtigungen verwenden.

Thema erstellen

Wenn Sie ein Thema erstellen möchten, registrieren Sie sich mit der Methode resellernotify.register bei der Reseller API. Diese Methode verwendet die E‑Mail-Adresse eines Dienstkontos als Parameter. Nur Dienstkonten, die mit dieser Methode autorisiert wurden, können Ihr Thema abonnieren.

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

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

Beispielantwort:

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

Wenn Sie weitere Dienstkonten autorisieren möchten, rufen Sie resellernotify.register noch einmal auf.

Zugriff für ein Dienstkonto widerrufen

Mit der Reseller API können Dienstkonten über den Endpunkt resellernotify.unregister abgemeldet werden:

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

Thema abonnieren

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

Push-Abo: Sie stellen einen HTTP-POST-Callback bereit. Pub/Sub verwendet diesen Callback, um Ihre Anwendung über neue Ereignisse zu benachrichtigen.
Pull-Abo: Ihre Anwendung führt regelmäßig einen HTTP-Aufruf aus, um in die Warteschlange gestellte Änderungen abzurufen.

Beispielanfrage 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 Name zur Identifizierung Ihres Abos.
TOPIC_NAME: Das Pub/Sub-Thema, das Sie zuvor erstellt haben.
PUSH_NOTIFICATION_ENDPOINT: Der Endpunkt Ihres Push-Benachrichtigungshandlers.

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. 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 sind ein base64-codierter JSON-String.

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

Beispiel für das message.data-Objekt 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 dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Ereignistypen

Mögliche Ereignistypen:

NEW_SUBSCRIPTION_CREATED: Ein neues Abo wurde erstellt.
SUBSCRIPTION_TRIAL_ENDED: Das Probeabo für ein Abo ist abgelaufen.
PRICE_PLAN_SWITCHED: Der Kunde hat von einem flexiblen Tarif zu einem Jahrestarif gewechselt. Dieses Ereignis wird nicht ausgelöst, wenn der Kunde im Rahmen einer Verlängerung von einem Jahrestarif zu einem 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 ausgesetzt. Siehe subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: Die Sperrung wurde aufgehoben.
SUBSCRIPTION_CANCELLED: Das Abo wurde gekündigt. Siehe subscription_cancellation_reason. Auch Übertragungen können erkannt werden.
SUBSCRIPTION_CONVERTED: Das Abo wurde umgestellt. Beispiele:
- Stellen Sie ein direktes Abo auf ein Reseller-Abo um.
- Kostenpflichtiges Abo in Kulanzangebot umwandeln
- Online-Abo in Offline-Abo umwandeln
SUBSCRIPTION_UPGRADE: Die Abo-SKU wurde aktualisiert. Beispiel: Google Workspace Business Starter zu Business Standard.
SUBSCRIPTION_DOWNGRADE: Die Abo-SKU wurde herabgestuft. Beispiel: Google Workspace Business Standard zu Business Starter
LICENSE_ASSIGNMENT_CHANGED: Die Lizenz wurde zugewiesen oder widerrufen. Wird verwendet, um Änderungen der Anzahl der Arbeitsplätze für flexible Abos zu erfassen.

Gründe für Abo-Kündigungen

Der Kündigungsgrund wird ausgefüllt, wenn event_type SUBSCRIPTION_CANCELLED ist. Mögliche Gründe:

TRANSFERRED_OUT: Der Kunde wurde auf die direkte Abrechnung oder einen anderen Reseller übertragen.
PURCHASE_OF_SUBSUMING_SKU: Der Kunde hat ein Upgrade auf eine SKU durchgeführt, die eine andere überschreibt. Beispiel: Ein Kunde mit Google Workspace Business Starter und Vault führt ein Upgrade auf Business Plus durch, das Vault enthält.
RESELLER_INITIATED: Der Reseller hat das Abo gekündigt.
OTHER: Das Abo wurde aus einem anderen Grund gekündigt.

Gründe für die Sperrung von Abos

Der Grund für die Sperrung wird angegeben, wenn event_type SUBSCRIPTION_SUSPENDED ist. Mögliche Gründe:

PENDING_TOS_ACCEPTANCE: Der Kunde hat die Nutzungsbedingungen für Google Workspace-Reseller nicht akzeptiert.
RENEWAL_WITH_TYPE_CANCEL: Die Zusicherung des Kunden ist abgelaufen und der Dienst wurde gekündigt.
RESELLER_INITIATED: Der Reseller hat das Abo manuell gesperrt.
TRIAL_ENDED: Das Probeabo des Kunden ist abgelaufen, ohne dass ein Abo ausgewählt wurde.
OTHER: Der Kunde wurde aus einem internen Google-Grund gesperrt, z. B. wegen Missbrauchs.

Pub/Sub-Einschränkungen

Die Reihenfolge von Push-Benachrichtigungen ist nicht immer sequenziell. Nachrichten werden möglicherweise mehrmals oder gar nicht zugestellt. Wir empfehlen, reseller.subscriptions.get für geänderte Abos zu verwenden, um den aktuellen Status abzurufen.