Pub/Sub-Benachrichtigungen

• Führen Sie das Codelab zur API-Einrichtung aus, um einGoogle Cloud -Projekt einzurichten und ein Dienstkonto zum Aufrufen der Cloud Channel API zu erstellen.

• Wir empfehlen, für dieses Codelab Ihre Test-Partner Sales Console zu verwenden.

• Machen Sie sich mit den Pub/Sub-Konzepten vertraut.

Übersicht

Die Cloud Channel API verwendet Pub/Sub, um Benachrichtigungen zu verschiedenen Kunden- und Berechtigungsereignissen zu senden.

Das ist besonders nützlich für:

• Änderungen, die direkt in der Partner Sales Console vorgenommen wurden, in Ihren eigenen Systemen widerspiegeln (z. B. wenn jemand aus Ihrem Supportteam eine Google Workspace-Berechtigung storniert).
• Sie können kritische Ereignisse erkennen, die von Ihren Reseller-Kunden ausgelöst werden. Beispiel:
  • Ein Google Workspace-Kunde, der die Nutzungsbedingungen akzeptiert.
  • Ein Google Workspace-Kunde bestätigt seine Domain.
  • Ein Google Workspace-Kunde, der Nutzern eine flexible Berechtigung hinzufügt.
  • Ein Google Workspace-Kunde, der zu einem anderen Anbieter wechselt.

Die Einrichtung von Pub/Sub umfasst die folgenden drei Schritte:

1. Aktivieren Sie die Pub/Sub API und bereiten Sie Ihr Dienstkonto vor.

2. Pub/Sub-Thema erstellen Dieses Thema gehört zu Channel Services und du gibst ein Dienstkonto an, mit dem ein Abo erstellt werden kann.

3. Pub/Sub-Abonnement erstellen Dieses Abo kann mithilfe von Webhooks (bevorzugte Methode) gepusht oder gepullt werden.

Bei einem Push-Abo hostest du einen Webhook, der die von den Kanaldiensten gesendeten Ereignisse empfängt:

Benachrichtigungsformat

Im Folgenden finden Sie ein Beispiel für 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

Für dieses Codelab benötigen Sie Folgendes:

• Die E-Mail-Adresse eines Dienstkontos in Ihrem Projekt. Diese Adresse hat das Format „[e-mail]“.
• Zugriff auf ein Super Admin-Konto für eine Reseller-Domain (vorzugsweise Ihre Test-Partner Sales Console)
• Ihre Konto-ID. Sie finden diese in den Einstellungen Ihrer Partner Sales Console.

So bereiten Sie Ihr Dienstkonto vor:

• Rufen Sie in der Google Cloud Console den Bereich API-Bibliothek auf und aktivieren Sie die Pub/Sub API.
• Weisen Sie Ihrem Dienstkonto die Pub/Sub-IAM-Rolle für das Projekt zu. Die Zuweisung von roles/pubsub.editor (Rollenname = „Pub/Sub-Bearbeiter“) reicht für dieses Codelab aus. Für die Produktionsintegration sollten Sie jedoch detailliertere Berechtigungen 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 zum Erstellen von Abos gewähren.

Nach dem Anwenden dieser Rollen und Berechtigungen auf Ihr Konto kann es zu einer Verzögerung kommen.

Achtung :Wenn dem Dienstkonto keine IAM-Rollen zugewiesen sind, erhalten Sie 403-Fehler.

Schritt 2: Thema für Ihr Konto erstellen

Verwenden Sie die Methode accounts.register, um das Pub/Sub-Thema zu erstellen. Diese Methode nimmt eine E-Mail-Adresse für das Dienstkonto als Parameter entgegen. Nur Dienstkonten, die auf diese Weise autorisiert wurden, können sich für Ihr neues Thema abonnieren.

1. Rufen Sie die Dokumentation zu accounts.register auf und klicken Sie auf Jetzt ausprobieren.
2. Geben Sie im Feld account accounts/ACCOUNT_ID ein und ersetzen Sie ACCOUNT_ID durch Ihre Konto-ID.
3. Klicken Sie auf Add request body parameters (Anfragetextparameter hinzufügen), wählen Sie serviceAccount aus und geben Sie die E-Mail-Adresse Ihres Dienstkontos ein.
4. Klicken Sie auf Ausführen und melden Sie sich als Super Admin Ihrer Resellerdomain an.

Sie sollten eine Antwort mit dem Statuscode 200 erhalten, die in etwa so aussieht:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

Das ist das Pub/Sub-Thema, in dem die Ereignisse gepostet werden.

Hinweis: Dieser Wert wird in Schritt 3b benötigt.

Schritt 3: Thema abonnieren

Nachdem Sie das Pub/Sub-Thema erstellt haben, müssen Sie festlegen, wie Ihre Anwendung Änderungsereignisse verarbeitet. Es stehen zwei Optionen zur Verfügung:

• Push-Abo: Sie geben einen HTTP-POST-Callback an. Pub/Sub verwendet diese Informationen, um Ihre Anwendung über neue Ereignisse zu benachrichtigen.
• Pull-Abo: Ihre Anwendung führt regelmäßig HTTP-Aufrufe aus, um Änderungen abzurufen, die in der Warteschlange stehen.

In diesem Codelab verwenden wir Push und senden alle Ereignisse an eine Cloud Run-Funktion, die sie in Cloud Logging protokolliert.

Schritt 3a: Cloud Run-Funktion erstellen

In diesem Schritt erstellen wir eine Cloud Run-Funktion, die die empfangenen Nachrichten protokolliert.

1. Gehen Sie in derGoogle Cloud Console zum Abschnitt Cloud Run-Funktionen. Möglicherweise müssen Sie die Cloud Run Functions API aktivieren.
2. Klicken Sie auf Funktion erstellen.
3. Auf dem Bildschirm Konfiguration:
   1. Ändern Sie den Namen der Funktion. Optional können Sie eine andere Region auswählen.
   2. Ändern Sie im HTTP-Trigger Authentifizierung in Nicht authentifizierte Aufrufe zulassen und klicken Sie auf Speichern.
   3. Notieren Sie sich die Trigger-URL. Sie benötigen sie im nächsten Schritt.
   4. Klicken Sie auf Weiter.

4. Auf dem Bildschirm Code:

   1. Node.js-Laufzeit auswählen
   2. Ändern Sie den Einstiegspunkt in log.
   3. Ersetzen Sie in der Datei index.js den Beispielcode durch Folgendes:

   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 Run-Funktion bereitgestellt wird.

Schritt 3b: Abo erstellen

Nur Dienstkonten, die für das Thema „Channel Services“ registriert sind (siehe Schritt 2), können ein Abo erstellen.

Sie können dies mit Code tun, indem Sie die Pub/Sub API mit den Anmeldedaten Ihres Dienstkontos aufrufen. Achten Sie darauf, sich nicht als Super Admin Ihrer Resellerdomain auszugeben. Dies ist beim Aufrufen der Cloud Channel API erforderlich.

In diesem Codelab verwenden Sie das gcloud CLI-Tool in Cloud Shell.

1. Klicken Sie oben in der Google Cloud consoleauf Cloud Shell aktivieren.

2. Führen Sie nach der Vorbereitung der Shell den folgenden Befehl aus. Ersetzen Sie die Werte für SERVICE_ACCOUNT durch die E-Mail-Adresse Ihres Dienstkontos, TOPIC durch das in Schritt 2 erstellte Thema und PUSH_ENDPOINT durch die Trigger-URL der in Schritt 3a erstellten Cloud Run-Funktion:

   SERVICE_ACCOUNT=[e-mail]
   TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
   PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
   

3. 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
   

4. So erstellst du 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 ausgeführt 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 Workspace abgeschlossen haben, können Sie einen Kunden mit einer Google Workspace-Umgebung erstellen, indem Sie den Beispielcode ausführen.

Rufen Sie in der Google Cloud Console Ihre Funktion auf und öffnen Sie den Tab Protokolle. Das folgende Beispiel zeigt, wie das aussehen sollte.

Hinweis: In seltenen Fällen kann es einige Minuten dauern, bis das Pub/Sub-Abo Ereignisse vom Thema empfängt.

Bereinigen

• Cloud Run-Funktion löschen
• Abo löschen

Das Thema wird automatisch gelöscht, wenn es keine Abonnenten mehr hat.

Nächste Schritte

In diesem Codelab haben Sie erfahren, wie Channel Services Pub/Sub nutzt, um Ihre Integration auf reaktive und skalierbare Weise zu erstellen.

Ereignisreferenz

Eine Liste der von Channel Services generierten Ereignisse findest du in der RPC-Referenz.

API-Referenz

In diesem Codelab wird die Google Cloud -Konsole verwendet. Sie können diese Schritte aber auch programmatisch ausführen. Anleitung:

• Verwenden Sie accounts.register, um das Thema zu erstellen.
• Verwenden Sie die subscriptions.create der Pub/Sub API, um das Pub/Sub-Abo zu erstellen.
• Unter accounts.listSubscribers und accounts.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 der Benachrichtigung darüber kann nicht garantiert werden. Die Reihenfolge der Benachrichtigungen ist ebenfalls nicht garantiert. Außerdem 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 Ihr Endpunkt idempotent sein und customers.get und entitlements.get verwenden.

• Das standardmäßige Pub/Sub-Zeitlimit für Push-Nachrichten beträgt 10 Sekunden. Es kann über die ackDeadline des Pub/Sub-Abos erhöht werden. Wir empfehlen jedoch, eine nachrichtbasierte Architektur zu verwenden und den Endpunkt so zu konfigurieren, dass er so schnell wie möglich reagiert.

• Wenn Ihr Endpunkt ausgefallen ist oder 5xx-Fehler zurückgibt, wird der Vorgang von Pub/Sub wiederholt. Weitere Informationen zum Empfangen von Nachrichten per Push finden Sie in der Pub/Sub-Dokumentation.

Wenn Sie lieber Pull verwenden möchten, finden Sie in der Pub/Sub-Dokumentation Informationen dazu, wie Sie Nachrichten per Pull empfangen.

Ereignisfilter

Da die Benachrichtigungen von Channel Services attributes enthalten, kannst du detaillierte Abos erstellen, indem du bestimmte Pub/Sub-Abos mit Pub/Sub-Filterung erstellst.

Wenn Sie beispielsweise mit attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" filtern, können Sie alle Änderungen an Google Workspace-Lizenzen im Blick behalten.