Push-Benachrichtigungen

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

Übersicht

Die Reseller API verwendet die Pub/Sub API, 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. Es wird empfohlen, die Rolle roles/pubsub.editor zuzuweisen, Sie können aber auch spezifischere Pub/Sub-Berechtigungen verwenden.

Thema erstellen

Wenn Sie ein Thema erstellen möchten, registrieren Sie sich mit der resellernotify.register Methode 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 dem Endpunkt resellernotify.unregister kann die Reseller API die Registrierung von Dienstkonten aufheben:

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 geben einen HTTP-POST Callback an. 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 zuvor erstellte Pub/Sub-Thema.
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 sehen 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 Objekt message.data 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: Die Testphase 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 gesperrt. Weitere Informationen finden Sie unter subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: Die Sperrung wurde aufgehoben.
SUBSCRIPTION_CANCELLED: Das Abo wurde gekündigt. Weitere Informationen finden Sie unter subscription_cancellation_reason. Übertragungen können auch erkannt werden.
SUBSCRIPTION_CONVERTED: Das Abo wurde umgestellt. Beispiele:
- Direktes Abo in ein Reseller-Abo umstellen.
- Kostenpflichtiges Abo in ein Kulanzangebot umstellen.
- Online-Abo in ein Offline-Abo umstellen.
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: Eine Lizenz wurde zugewiesen oder widerrufen. Verwenden Sie diese Option, um Änderungen der Anzahl der Arbeitsplätze für flexible Abos zu verfolgen.

Gründe für Abo-Kündigungen

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

TRANSFERRED_OUT: Der Kunde hat zu einer direkten Abrechnung oder einem anderen Reseller gewechselt.
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 Abo-Sperrungen

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

PENDING_TOS_ACCEPTANCE: Der Kunde hat die Nutzungsbedingungen für Google Workspace-Reseller noch 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: Die Testphase des Kunden ist abgelaufen, ohne dass ein kostenpflichtiger Tarif 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.