Übersicht
In der Reseller API wird die Pub/Sub API verwendet, um Push-Benachrichtigungen zu verschiedenen Google Workspace-Aboereignissen zu senden. Sie können beispielsweise Push-Benachrichtigungen einrichten, um benachrichtigt zu werden, wenn sich der Abo-Status 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
ist ein guter Kompromiss (einfach und nicht zu breit gefasst), aber Sie sollten eventuell spezifischere Pub/Sub-Berechtigungen verwenden.
Thema erstellen
Wenn Sie ein Thema erstellen möchten, müssen Sie sich mit der Reseller API über die resellernotify.register
-Methode registrieren.
Die Methode resellernotify.register
verwendet die E-Mail-Adresse eines Dienstkontos als Parameter. Nur Dienstkonten, die mit dieser Methode autorisiert wurden, 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 Ihres 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 Dienstkonten auch über den Endpunkt resellernotify.unregister
abmelden:
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, müssen Sie festlegen, wie Ihre Anwendung die Ä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 alle in der Warteschlange befindlichen Änderungen abzurufen.
Hier sehen Sie ein Beispiel für 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 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. 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" }
Das folgende Beispiel zeigt 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 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
: 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 Tarif mit Mindestlaufzeit 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. Weitere Informationen finden Sie im Feldsubscription_suspension_reasons
.SUBSCRIPTION_SUSPENSION_REVOKED
: Die Sperrung eines zuvor gesperrten Abos wurde aufgehoben.SUBSCRIPTION_CANCELLED
: Das Abo wurde gekündigt. Weitere Informationen finden Sie im Feldsubscription_cancellation_reason
. Kann auch zum Erkennen von Übertragungen verwendet werden.SUBSCRIPTION_CONVERTED
: Das Abo wurde umgestellt. Hier einige Beispiele für dieses Ereignis:- 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. Das Abo wurde beispielsweise von Google Workspace Business Starter auf Business Standard aktualisiert.SUBSCRIPTION_DOWNGRADE
: Die Abo-SKU wurde herabgestuft. Das Abo wurde beispielsweise von Google Workspace Business Standard auf Business Starter herabgestuft.LICENSE_ASSIGNMENT_CHANGED
: Eine Lizenz wurde einem Nutzer zugewiesen oder von einem Nutzer widerrufen. Mit diesem Ereignis können Sie Änderungen der Anzahl der Plätze für flexible Abos reaktiv erfassen.
Gründe für Abo-Kündigungen
Der Grund für die Kündigung des Abos wird angegeben, wenn event_type
SUBSCRIPTION_CANCELLED
ist. Mögliche Kündigungsgründe:
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 SKU durchgeführt, die eine andere überschreibt. Wenn ein Kunde mit Google Workspace Business Starter und Google Vault beispielsweise auf Google Workspace Business Plus upgradet, wird das Vault-Abo subsumiert, 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
SUBSCRIPTION_SUSPENDED
ist. Mögliche Gründe für eine Sperrung:
PENDING_TOS_ACCEPTANCE
: Der Kunde hat sich nicht angemeldet und die Google Workspace-Nutzungsbedingungen für Reseller nicht akzeptiert.RENEWAL_WITH_TYPE_CANCEL
: Die Vertragslaufzeit 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
: Die Testversion des Kunden ist abgelaufen und er hat kein Abo ausgewählt.OTHER
: Das Konto des Kunden 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, reseller.subscriptions.get
für alle geänderten Abos zu verwenden, um den aktuellen Status abzurufen.