Push-Benachrichtigungen

Übersicht

Die Reseller API verwendet die Pub/Sub API, um Push-Benachrichtigungen zu verschiedenen Aboereignissen in Google Workspace zu senden. Sie können beispielsweise Push-Benachrichtigungen einrichten, um benachrichtigt zu werden, wenn sich der Abostatus Ihrer Kunden ä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 Rolle roles/pubsub.editor zu gewähren, ist ein guter Kompromiss (einfach und nicht zu weit gefasst). Sie können aber auch spezifischere Pub/Sub-Berechtigungen verwenden.

Thema erstellen

Wenn Sie ein Thema erstellen möchten, müssen Sie sich mit der Reseller API registrieren. Verwenden Sie dazu die Methode resellernotify.register. Die Methode resellernotify.register nimmt eine E-Mail-Adresse des Dienstkontos als Parameter an. Nur Dienstkonten, die mit dieser Methode autorisiert sind, können Ihr neu erstelltes 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 des Pub/Sub-Themas zurückgegeben.

Hier ist ein Beispiel für eine Antwort:

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

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

Zugriff für ein Dienstkonto widerrufen

Mit der Reseller API können Sie auch Dienstkonten über den resellernotify.unregister-Endpunkt unregistern:

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

Themen abonnieren

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

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

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 Pub/Sub-Thema, das Sie zuvor erstellt haben.
  • PUSH_NOTIFICATION_ENDPOINT: Der Endpunkt Ihres Push-Benachrichtigungs-Handlers.

Bei einer erfolgreichen Antwort wird der Statuscode „HTTP 200“ zurückgegeben. Hier ist ein Beispiel für eine Antwort: 

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

Im Folgenden ist das Beispiel-message.data-Objekt nach der Dekodierung aufgeführt:

{
  "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: Es wurde ein neues Abo erstellt.
  • SUBSCRIPTION_TRIAL_ENDED: Das Probeabo für ein Abo ist abgelaufen.
  • PRICE_PLAN_SWITCHED: Der Kunde ist von einem flexiblen Tarif zu einem Jahrestarif gewechselt. Dieses Ereignis wird nicht ausgelöst, wenn der Kunde im Rahmen einer Verlängerung von einem Laufzeittarif 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 ist gesperrt. Sehen Sie sich das Feld subscription_suspension_reasons an.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Die Sperrung eines zuvor gesperrten Abos wurde aufgehoben.
  • SUBSCRIPTION_CANCELLED: Das Abo wurde gekündigt. Sehen Sie sich das Feld subscription_cancellation_reason an. Kann auch zum Erkennen von Übertragungen verwendet werden.

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

    • Direktes Abo in ein Reseller-Abo umwandeln
    • Kostenpflichtiges Abo in Kulanzzeitraum-Angebot umwandeln
    • Online-Abo in ein Offline-Abo umwandeln.

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

  • SUBSCRIPTION_DOWNGRADE: Die Abo-SKU wurde auf ein niedrigeres Abo umgestellt. Beispiel: Das Abo wurde von Google Workspace Business Standard auf Business Starter umgestellt.

  • LICENSE_ASSIGNMENT_CHANGED: Eine Lizenz wurde einem Nutzer zugewiesen oder von ihm widerrufen. Mit diesem Ereignis können Sie Änderungen der Sitzplatzanzahl für flexible Abos reaktiv erfassen.

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

Der Grund für die Kündigung des Abos wird angegeben, wenn event_type SUBSCRIPTION_CANCELLED ist. Folgende Gründe können zu einer Kündigung führen:

  • TRANSFERRED_OUT: Der Kunde ist zur direkten Abrechnung oder zu einem anderen Reseller gewechselt.
  • PURCHASE_OF_SUBSUMING_SKU: Der Kunde hat ein Upgrade auf eine SKU durchgeführt, die eine andere überschreibt. Wenn ein Kunde mit Google Workspace Business Starter und Google Vault beispielsweise auf Google Workspace Business Plus umsteigt, wird das Vault-Abo übernommen, 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 dem angegebenen Grund gekündigt.

Gründe für die Sperrung von Abos

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

  • PENDING_TOS_ACCEPTANCE: Der Kunde hat sich nicht angemeldet und die Nutzungsbedingungen für den Weiterverkauf von Google Workspace nicht akzeptiert.
  • RENEWAL_WITH_TYPE_CANCEL: Die Bindung des Kunden ist abgelaufen und der Dienst wurde am Ende der Laufzeit gekündigt.
  • RESELLER_INITIATED: Der Reseller hat das Abo manuell gesperrt.
  • TRIAL_ENDED: Das Probeabo des Kunden ist abgelaufen und er hat keinen anderen Tarif ausgewählt.
  • OTHER: Der Kunde wurde aus einem internen Google-Grund gesperrt, z. B. wegen Missbrauchs.

Pub/Sub-Einschränkungen

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