Pub/Sub-Benachrichtigungen

• Führen Sie das Codelab zur API-Einrichtung aus, um ein Google 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.

• Mit Pub/Sub vertraut machen Konzepten.

Übersicht

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

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 ein Mitglied Ihres Supportteams eine Google Workspace-Berechtigung storniert)
• Kritische Ereignisse erkennen, die von Ihren Reseller-Kunden ausgelöst werden Für Beispiel:
  • Ein Google Workspace-Kunde, der die Nutzungsbedingungen akzeptiert.
  • Ein Google Workspace-Kunde, der seine Domain bestätigt.
  • Ein Google Workspace-Kunde, der Nutzer mit einer flexiblen 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 push mit Webhooks (bevorzugte Methode) oder Pull.

Bei einem Push-Abo hosten Sie einen Webhook, der die Ereignisse, die von den Channel Services ausgegeben werden:

Benachrichtigungsformat

Im Folgenden finden Sie ein Beispiel für eine Pub/Sub-Benachrichtigung. Die Nachrichtendaten sind als base64-codierten 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 für Ihr Projekt. Diese Adresse hat folgendes 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 sie 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.
• Gewähren Sie Ihrem Dienstkonto die Pub/Sub-IAM-Rolle für das Projekt. Es reicht aus, roles/pubsub.editor (Rollenname = „Pub/Sub-Bearbeiter“) zu gewähren. für dieses Codelab. Sie können aber detailliertere Berechtigungen in deiner Produktionsintegration. 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.

Nachdem Sie diese Rollen und Berechtigungen auf Ihr Konto angewendet haben, 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

Zum Erstellen des Pub/Sub-Themas müssen Sie die Methode accounts.register-Methode. Diese Methode nimmt eine E-Mail-Adresse für das Dienstkonto als Parameter an. 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 stellen einen HTTP POST-Callback bereit. Pub/Sub verwendet diese Informationen, um Ihre Anwendung über neue Ereignisse zu benachrichtigen.
• Pull-Abo: Ihre Anwendung führt regelmäßig HTTP-Aufrufe durch, um Änderungen in der Warteschlange.

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

1. Rufen Sie in der Google Cloud Console den Bereich Cloud Run-Funktionen auf. 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. Sie können auch eine andere Region auswählen.
   2. Ändern Sie im HTTP-Trigger Authentication (Authentifizierung) zu Lassen Sie nicht authentifizierte Aufrufe zu 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. Gehen Sie auf dem Bildschirm Code so vor:

   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.

Dazu können Sie mit Code die Pub/Sub API mit Ihrem Dienst aufrufen Anmeldedaten des Kontos. Achten Sie darauf, sich nicht als Super Admin Ihrer Resellerdomain auszugeben. Dies ist beim Aufrufen der Cloud Channel API erforderlich.

Für dieses Codelab verwenden Sie das gcloud CLI-Tool auf Cloud Shell

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.

2. Sobald 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, und PUSH_ENDPOINT durch die Trigger-URL der Cloud Run-Funktion die in Schritt 3a erstellt wurden:

   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 die Bereitstellung eines Produkts. 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 die Pub/Sub- um Ereignisse aus dem Thema zu erhalten.

Bereinigen

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

Das Thema wird automatisch bereinigt, wenn es keine verbleibenden Abonnenten.

Nächste Schritte

In diesem Codelab haben Sie erfahren, wie Channel Services mit Pub/Sub, damit Sie Ihre Integration reaktiv erstellen können. und im großen Maßstab.

Ereignisreferenz

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

API-Referenz

In diesem Codelab wird die Google Cloud Console verwendet, aber Sie können diese programmieren können. Anleitung:

• accounts.register verwenden um das Thema zu erstellen.
• Verwenden Sie die subscriptions.create der Pub/Sub API, um das Pub/Sub-Abo zu erstellen.
• Weitere Informationen finden Sie unter accounts.listSubscribers und accounts.unregister für zusätzliche Endpunkte, die Sie in Ihrer Integration verwenden können.

Pub/Sub-Garantien und Best Practices

Die Verzögerung zwischen einem Ereignis und der zugehörigen Benachrichtigung 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 versendet werden können, Endpunkt idempotent sein und customers.get und entitlements.get

• Während das Pub/Sub-Standardzeitlimit für Push 10 Sekunden beträgt (kann über das Pub/Sub-Abo erhöht werden ackDeadline) empfehlen, eine nachrichtenbasierte Architektur zu verwenden und der Endpunkt 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 zu wie erhalte ich Nachrichten per Push in der Pub/Sub-Dokumentation.

Wenn Sie Pull bevorzugen, finden Sie dort wie Nachrichten per Pull empfangen werden in der Pub/Sub-Dokumentation.

Ereignisfilterung

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.