Führen Sie das Codelab zur API-Einrichtung durch, um ein Google Cloud-Projekt einzurichten und ein Dienstkonto zum Aufrufen der Cloud Channel API zu erstellen.
Wir empfehlen, für dieses Codelab die Test Partner Sales Console zu verwenden.
Machen Sie sich mit den Pub/Sub-Konzepten vertraut.
Überblick
Die Cloud Channel API verwendet Pub/Sub, um Benachrichtigungen über verschiedene Kunden- und Berechtigungsereignisse zu übermitteln.
Das ist besonders nützlich für:
- Änderungen, die direkt in der Partner Sales Console in Ihren eigenen Systemen vorgenommen wurden, müssen berücksichtigt werden (z. B. wenn jemand aus Ihrem Supportteam eine Google Workspace-Berechtigung storniert hat).
- Sie können kritische Ereignisse erkennen, die von Kunden eines Resellers ausgelöst werden. Beispiel:
- Ein Google Workspace-Kunde, der die Nutzungsbedingungen akzeptiert.
- Ein Google Workspace-Kunde, der seine Domain bestätigt.
- Ein Google Workspace-Kunde fügt Nutzer mit einer flexiblen Berechtigung hinzu.
- Ein Google Workspace-Kunde wechselt weg.
Die Einrichtung von Pub/Sub umfasst die folgenden drei Schritte:
Pub/Sub API aktivieren und Dienstkonto vorbereiten
Pub/Sub-Thema erstellen Dieses Thema gehört zu Channel Services. Sie geben ein Dienstkonto an, das ein Abo erstellen kann.
Pub/Sub-Abonnement erstellen Dieses Abo kann ein push-Abo mit Webhooks (bevorzugte Methode) oder push sein.
Bei einem push-Abo hosten Sie einen Webhook, der die von den Channel Services ausgegebenen Ereignisse empfängt:
Benachrichtigungsformat
Das folgende Beispiel zeigt eine Pub/Sub-Benachrichtigung. Die Nachrichtendaten werden als base64-codierter JSON-String übertragen.
{
"message": {
"attributes": {
"event_type": "LICENSE_ASSIGNMENT_CHANGED",
"subscriber_event_type": "ENTITLEMENT_EVENT"
},
"data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
"message_id": 1918124788439510,
"publish_time": "2021-01-14T01:23:45.678Z"
},
"subscription": "projects/project/subscriptions/channel-pubsub-test"
}
Dies sind dieselben Nachrichtendaten, decodiert:
{
"entitlement_event": {
"event_type": "LICENSE_ASSIGNMENT_CHANGED",
"entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
}
}
Schritt 1: Pub/Sub API aktivieren und Dienstkonto vorbereiten
Zum Ausführen dieses Codelabs benötigen Sie Folgendes:
- Die E-Mail-Adresse eines Dienstkontos in Ihrem Projekt. Diese Adresse hat folgendes Format: service-account@project.iam.gserviceaccount.com.
- Zugriff auf ein Super Admin-Konto für eine Reseller-Domain (vorzugsweise Ihr Test Partner Sales Console).
- Ihre Konto-ID. Sie finden sie in der Partner Sales Console in den Einstellungen.
So bereiten Sie Ihr Dienstkonto vor:
- Rufen Sie in der Google Cloud Console den Abschnitt API-Bibliothek auf und aktivieren Sie die Pub/Sub API.
- Gewähren Sie Ihrem Dienstkonto die Pub/Sub-IAM-Rolle für das Projekt.
Die Erteilung von
roles/pubsub.editor
(Rollenname = 'Pub/Sub-Bearbeiter') ist für dieses Codelab ausreichend. Möglicherweise möchten Sie jedoch detailliertere Berechtigungen in Ihrer Produktionsintegration verwenden. Ausführliche Informationen zu IAM-Rollen finden Sie auf der Seite Pub/Sub-Zugriffssteuerung. - Wenn Sie stattdessen eine benutzerdefinierte Rolle anwenden möchten, müssen Sie dieser Rolle die Berechtigung
pubsub.subscriptions.create
erteilen, um Abos zu erstellen.
Nach dem Anwenden dieser Rollen und Berechtigungen auf Ihr Konto kann es zu einer Verzögerung kommen.
Schritt 2: Thema für Ihr Konto erstellen
Zum Erstellen des Pub/Sub-Themas müssen Sie die Methode accounts.register
verwenden. Diese Methode verwendet die E-Mail-Adresse eines Dienstkontos als Parameter. Nur Dienstkonten, die über diese Methode autorisiert wurden, können das neue Thema abonnieren.
- Rufen Sie die Dokumentation zu accounts.register auf und klicken Sie auf Jetzt testen.
- Geben Sie im Feld
account
accounts/ACCOUNT_ID
ein und ersetzen SieACCOUNT_ID
durch Ihre Konto-ID. - Klicken Sie auf Anfragetextparameter hinzufügen, wählen Sie
serviceAccount
aus und geben Sie die E-Mail-Adresse Ihres Dienstkontos ein. - Klicken Sie auf Ausführen und melden Sie sich als Super Admin Ihrer Reseller-Domain an.
Sie sollten eine 200-Antwort ähnlich der folgenden erhalten:
{
"topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}
Dies ist das Pub/Sub-Thema, in dem die Ereignisse gepostet werden.
Schritt 3: Thema abonnieren
Nachdem Sie das Pub/Sub-Thema erstellt haben, müssen Sie festlegen, wie Ihre Anwendung Änderungsereignisse verarbeitet. Es gibt zwei Möglichkeiten:
- Push-Abo: Sie geben einen HTTP POST-Callback an. Pub/Sub benachrichtigt damit Ihre Anwendung über neue Ereignisse.
- Pull-Abo: Ihre Anwendung führt regelmäßig HTTP-Aufrufe durch, um Änderungen in der Warteschlange abzurufen.
In diesem Codelab verwenden wir Push und senden alle Ereignisse an eine Cloud Functions-Funktion, die in Cloud Logging protokolliert wird.
Schritt 3a: Cloud Functions-Funktion erstellen
In diesem Schritt erstellen wir eine Cloud Functions-Funktion, die die empfangenen Nachrichten protokolliert.
- Rufen Sie in der Google Cloud Console den Abschnitt Cloud Functions auf. Möglicherweise müssen Sie die Cloud Functions API aktivieren.
- Klicken Sie auf Funktion erstellen.
- Gehen Sie auf dem Bildschirm Konfiguration so vor:
- Ändern Sie den Namen der Funktion. Wählen Sie optional eine andere Region aus.
- Ändern Sie im HTTP-Trigger die Option Authentifizierung in Nicht authentifizierte Aufrufe zulassen und klicken Sie auf Speichern.
- Notieren Sie sich die Trigger-URL. Sie benötigen sie im nächsten Schritt.
- Klicken Sie auf Next (Weiter).
Auf dem Bildschirm Code:
- Beliebige Node.js-Laufzeit auswählen
- Ändere den Einstiegspunkt in
log
- Ersetzen Sie den Beispielcode in der Datei
index.js
durch:
exports.log = (req, res) => { if (req.body && req.body.message) { console.log(req.body); const message = req.body.message; // data is base64-encoded JSON const data = new Buffer.from(message.data, 'base64').toString(); console.log(data); } res.status(200).send('OK'); };
Sie können mit dem nächsten Schritt fortfahren, während die Cloud Functions-Funktion bereitgestellt wird.
Schritt 3b: Abo erstellen
Nur Dienstkonten, die für das Channel Services-Thema registriert sind (siehe Schritt 2), können ein Abo erstellen.
Dazu können Sie Code verwenden, indem Sie die Pub/Sub API mit den Anmeldedaten Ihres Dienstkontos aufrufen. Achten Sie darauf, dass Sie sich nicht als Super Admin Ihrer Reseller-Domain ausgeben – dies ist beim Aufrufen der Cloud Channel API erforderlich.
Für dieses Codelab verwenden Sie das gcloud CLI-Tool in Cloud Shell.
Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
Wenn die Shell bereit ist, führen Sie den folgenden Befehl aus. Ersetzen Sie die Werte von
SERVICE_ACCOUNT
durch die E-Mail-Adresse Ihres Dienstkontos,TOPIC
durch das in Schritt 2 erstellte Thema undPUSH_ENDPOINT
durch die Trigger-URL der in Schritt 3a erstellten Cloud Function:SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
Aktivieren Sie das Dienstkonto in der Shell:
gcloud iam service-accounts keys create sa-keys.json \ --iam-account=$SERVICE_ACCOUNT gcloud auth activate-service-account --key-file=sa-keys.json
Erstellen Sie das Abo:
gcloud pubsub subscriptions create channel-pubsub-test \ --topic=$TOPIC \ --push-endpoint=$PUSH_ENDPOINT
Im Abschnitt Pub/Sub-Abos können Sie prüfen, ob das Abo eingerichtet ist.
Daten generieren
Nachdem Sie die vorherigen Schritte abgeschlossen haben, können Sie Daten empfangen.
Am einfachsten ist es, einen Kunden in der Partner Sales Console zu erstellen und ein Produkt bereitzustellen. Wenn Sie das Codelab zur End-to-End-Bereitstellung von Arbeitsbereichen abgeschlossen haben, können Sie einen Kunden mit einem Google Workspace erstellen, indem Sie den Beispielcode ausführen.
Rufen Sie in der Google Cloud Console Ihre Funktion auf und öffnen Sie den Tab Logs. Im Folgenden finden Sie ein Beispiel dafür, was Sie sehen sollten.
Bereinigen
- Cloud Functions-Funktion löschen
- Abo löschen
Das Thema wird automatisch bereinigt, wenn es keine verbleibenden Abonnenten hat.
Nächste Schritte
In diesem Codelab wurde erläutert, wie Channel Services mithilfe von Pub/Sub Ihre Integration reaktiv und im großen Maßstab erstellen kann.
Ereignisreferenz
Eine Liste der von Channel Services generierten Ereignisse finden Sie in der RPC-Referenz.
API-Referenz
In diesem Codelab wird die Google Cloud Console verwendet, aber Sie können diese Schritte auch programmatisch ausführen. Anleitung:
- Verwenden Sie
accounts.register
, um das Thema zu erstellen. - Verwenden Sie
subscriptions.create
der Pub/Sub API, um das Pub/Sub-Abo zu erstellen. - Unter
accounts.listSubscribers
undaccounts.unregister
finden Sie weitere Endpunkte, die Sie in Ihrer Integration verwenden können.
Pub/Sub-Garantien und Best Practices
Die Verzögerung zwischen einem Ereignis und seiner Benachrichtigung ist nicht garantiert. Auch die Reihenfolge der Benachrichtigungen ist nicht garantiert. Schließlich können Nachrichten mehrmals zugestellt werden.
Best Practices für Push-Endpunkte:
Da Nachrichten verzögert, in falscher Reihenfolge oder mehrmals gesendet werden können, sollte der Endpunkt idempotent sein. Verwenden Sie
customers.get
undentitlements.get
Das standardmäßige Pub/Sub-Zeitlimit für Push beträgt 10 Sekunden (kann über das
ackDeadline
des Pub/Sub-Abos erhöht werden). Es empfiehlt sich jedoch, eine nachrichtenbasierte Architektur zu verwenden und dafür zu sorgen, dass der Endpunkt so schnell wie möglich reagiert.Wenn Ihr Endpunkt ausgefallen ist oder 5xx-Fehler zurückgibt, versucht Pub/Sub es noch einmal. Weitere Informationen zum Empfang von Nachrichten per Push finden Sie in der Pub/Sub-Dokumentation.
Wenn Sie lieber pull verwenden, finden Sie in der Pub/Sub-Dokumentation Informationen zum Empfang von Nachrichten per Pull.
Ereignisfilterung
Da die Benachrichtigungen von Channel Services attributes
enthalten, können Sie durch das Erstellen bestimmter Pub/Sub-Abos mit Pub/Sub-Filtern präzisere Abos erstellen.
Wenn Sie beispielsweise mit attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED"
filtern, können Sie alle Sitzänderungen in Google Workspace erfassen.