Ereignisse veröffentlichen und empfangen, indem Sie einen Bus und eine Registrierung erstellen (gcloud CLI)

In dieser Kurzanleitung wird gezeigt, wie Sie Ereignisnachrichten veröffentlichen und empfangen. Dazu erstellen Sie einen Eventarc Advanced-Bus und registrieren sich in Ihrem Google Cloud-Projekt.

  • Ein Bus fungiert als zentraler Router, der Nachrichten von Ereignisquellen oder von Anbietern empfängt.

  • Bei einer Registrierung werden Nachrichten, die vom Bus empfangen werden, über eine Verarbeitungspipeline an ein oder mehrere Ziele weitergeleitet.

In dieser Kurzanleitung werden folgende Schritte erläutert:

  1. Erstellen Sie ein Artifact Registry-Standard-Repository.

  2. einen Ereignisempfängerdienst für Cloud Run bereitstellen

  3. Eventarc Advanced-Bus erstellen

  4. Eventarc Advanced-Registrierung erstellen

  5. Veröffentlichen Sie eine Ereignisnachricht im Bus.

  6. Rufen Sie die Ereignisdaten in den Cloud Run-Logs auf.

Sie können diese Kurzanleitung mit der gcloud CLI ausführen. Eine Anleitung zum Ausführen der Schritte mit der Google Cloud Console finden Sie unter Ereignisse veröffentlichen und empfangen, indem Sie einen Bus und eine Registrierung erstellen (Console).

Hinweis

Von Ihrer Organisation definierte Sicherheitsbeschränkungen verhindern möglicherweise, dass die folgenden Schritte ausgeführt werden. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud -Umgebung entwickeln.

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. Installieren Sie die Google Cloud CLI.

  3. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  4. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

  5. Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

    Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

    • Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
    • Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

    • So erstellen Sie ein Google Cloud Projekt:

      gcloud projects create PROJECT_ID

      Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.

    • Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:

      gcloud config set project PROJECT_ID

      Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

  6. Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.

  7. Aktivieren Sie die Artifact Registry, Cloud Build, Cloud Run, Compute Engine und Eventarc APIs:

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

  8. Installieren Sie die Google Cloud CLI.

  9. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  10. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

  11. Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

    Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

    • Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
    • Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

    • So erstellen Sie ein Google Cloud Projekt:

      gcloud projects create PROJECT_ID

      Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.

    • Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:

      gcloud config set project PROJECT_ID

      Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

  12. Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.

  13. Aktivieren Sie die Artifact Registry, Cloud Build, Cloud Run, Compute Engine und Eventarc APIs:

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com
    14.

  14. Aktualisieren Sie die gcloud-Komponenten: 
    gcloud components update

  15. Melden Sie sich mit Ihrem -Konto an: 
    gcloud auth login

  16. Legen Sie die in dieser Kurzanleitung verwendete Konfigurationsvariable fest: 
    REGION=REGION

    Ersetzen Sie REGION durch einen unterstützten Speicherort für den Bus.

  17. Wenn Sie der Projektersteller sind, wird Ihnen die einfache Owner-Rolle (roles/owner) zugewiesen. Standardmäßig enthält diese IAM-Rolle (Identity and Access Management) die Berechtigungen, die für den vollständigen Zugriff auf die meisten Google Cloud-Ressourcen erforderlich sind. Sie können diesen Schritt überspringen.

    Wenn Sie nicht der Project Creator sind, müssen dem entsprechenden Hauptkonto die erforderlichen Berechtigungen für das Projekt erteilt werden. Ein Hauptkonto kann beispielsweise ein Google-Konto (für Endnutzer) oder ein Dienstkonto (für Anwendungen und Computing-Arbeitslasten) sein.

    Beachten Sie, dass Cloud Build-Berechtigungen standardmäßig Berechtigungen zum Hochladen und Herunterladen von Artifact Registry-Artefakten enthalten.

    Erforderliche Berechtigungen

    Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Kurzanleitung benötigen:

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

  18. Erstellen Sie zu Testzwecken ein Dienstkonto und weisen Sie ihm die Rollen zu, die für diesen Schnellstart erforderlich sind.
    1. Erstellen Sie ein Dienstkonto: 
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
       Ersetzen Sie SERVICE_ACCOUNT_NAME durch einen Namen für Ihr Dienstkonto.
    2. Weisen Sie die Rollen zu, die zum Erstellen und Bereitstellen eines Container-Images und zum Darstellen der Identität einer Eventarc Advanced-Pipeline erforderlich sind: 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/artifactregistry.writer
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/logging.logWriter
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/storage.admin
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/run.invoker

    Sie können konfigurieren, wer auf Ihren Cloud Run-Dienst zugreifen kann, indem Sie eine der folgenden Methoden verwenden:

    • Erteilen Sie die Berechtigung zum Auswählen von Dienstkonten oder Gruppen, um den Zugriff auf den Dienst zu ermöglichen. Alle Anfragen müssen einen HTTP-Autorisierungs-Header mit einem von Google für eines der autorisierten Dienstkonten signierten OpenID Connect-Token enthalten. So wird der Zugriff in dieser Kurzanleitung konfiguriert.
    • Erteilen Sie allUsers die Berechtigung, den nicht authentifizierten Zugriff zuzulassen.

    Weitere Informationen finden Sie unter Zugriffssteuerung für Cloud Run.

Artifact Registry-Standard-Repository erstellen

Erstellen Sie ein Artifact Registry-Standard-Repository zum Speichern des Container-Images.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Ersetzen Sie REPOSITORY durch einen eindeutigen Namen für das Artifact Registry-Repository, z. B. my-repo.

Ereignisempfängerdienst für Cloud Run bereitstellen

Stellen Sie einen Cloud Run-Dienst bereit, der den Inhalt eines Ereignisses protokolliert. Andere Ereignisziele wie ein Pub/Sub-Thema, Workflows oder ein HTTP-Endpunkt werden unterstützt. Weitere Informationen finden Sie unter Ereignisanbieter und -ziele.

  1. Klonen Sie das GitHub-Repository:

    git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

  2. Wechseln Sie in das Verzeichnis, das den Cloud Run-Beispielcode enthält:

    cd eventarc-samples/eventarc-advanced-quickstart/

  3. Erstellen Sie ein Docker-Container-Image und übertragen Sie es per Push in Ihr Repository:

    gcloud builds submit \
    --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
    --service-account=projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --default-buckets-behavior=regional-user-owned-bucket

  4. Stellen Sie das Container-Image in Cloud Run bereit:

    gcloud run deploy SERVICE_NAME \
    --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
    --platform managed \
    --ingress all \
    --no-allow-unauthenticated \
    --region=$REGION

    Ersetzen Sie SERVICE_NAME durch den Namen Ihres Dienstes, z. B. my-service.

    Die Ingress-Einstellung all lässt alle Anfragen zu, einschließlich Anfragen direkt aus dem Internet an die URL run.app. Weitere Informationen finden Sie unter Eingehenden Traffic für Cloud Run einschränken.

    Das Flag --no-allow-unauthenticated konfiguriert den Dienst so, dass nur authentifizierte Aufrufe zulässig sind.

Wenn die Cloud Run-Dienst-URL angezeigt wird, ist die Bereitstellung abgeschlossen. Notieren Sie sich diese URL, damit Sie sie in einem späteren Schritt verwenden können.

Eventarc Advanced-Bus erstellen

Ein Bus empfängt Ereignisnachrichten von einer Nachrichtenquelle oder von einem Anbieter und fungiert als Nachrichtenrouter.

Weitere Informationen finden Sie unter Bus zum Weiterleiten von Nachrichten erstellen.

Erstellen Sie mit dem Befehl gcloud eventarc message-buses create einen Eventarc Advanced-Bus in Ihrem Projekt:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

Ersetzen Sie BUS_NAME durch die ID oder die vollständig qualifizierte Kennzeichnung Ihres Busses, z. B. my-bus.

Eventarc Advanced-Registrierung erstellen

Eine Anmeldung bestimmt, welche Nachrichten an ein Ziel weitergeleitet werden, und gibt auch die Pipeline an, die zum Konfigurieren eines Ziels für die Ereignisnachrichten verwendet wird.

Weitere Informationen finden Sie unter Registrierung erstellen, um Ereignisse zu empfangen.

Wenn Sie die gcloud CLI verwenden, erstellen Sie zuerst eine Pipeline und dann eine Registrierung:

  1. Erstellen Sie eine Pipeline mit dem Befehl gcloud eventarc pipelines create:

    gcloud eventarc pipelines create PIPELINE_NAME \
    --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --location=$REGION

    Ersetzen Sie Folgendes:

    • PIPELINE_NAME: die ID der Pipeline oder ein voll qualifizierter Name.
    • CLOUD_RUN_SERVICE_URL: die voll qualifizierte URL Ihres Cloud Run-Dienstes, z. B. https://SERVICE_NAME-abcdef-uc.a.run.app. Dies ist das Ziel für Ihre Ereignisnachrichten.

    Der google_oidc_authentication_service_account-Schlüssel gibt eine E-Mail-Adresse für das Dienstkonto an, die zum Generieren eines OIDC-Tokens verwendet wird.

  2. Erstellen Sie eine Registrierung mit dem Befehl gcloud eventarc enrollments create:

    gcloud eventarc enrollments create ENROLLMENT_NAME \
    --cel-match=MATCH_EXPRESSION \
    --destination-pipeline=PIPELINE_NAME \
    --message-bus=BUS_NAME \
    --message-bus-project=PROJECT_ID \
    --location=$REGION

    Ersetzen Sie Folgendes:

    • ENROLLMENT_NAME: die ID der Registrierung oder ein voll qualifizierter Name.

    • MATCH_EXPRESSION: Der Abgleichsausdruck für diese Registrierung mit CEL, z. B.:

      "message.type == 'hello-world-type'"

Ereignisnachricht im Bus veröffentlichen

Wenn Sie eine Nachricht direkt in Ihrem Bus veröffentlichen möchten, können Sie den Befehl gcloud eventarc message-buses publish verwenden oder eine Anfrage an die Eventarc Publishing REST API senden. Weitere Informationen finden Sie unter Ereignisse direkt veröffentlichen.

Die Nachricht muss im CloudEvents-Format vorliegen, einer Spezifikation zum allgemeinen Beschreiben von Ereignisdaten. Das data-Element ist die Nutzlast Ihres Ereignisses. In dieses Feld kann beliebiger wohlgeformter JSON-Code eingefügt werden. Weitere Informationen zu CloudEvents-Kontextattributen finden Sie unter Ereignisformat.

Im Folgenden finden Sie Beispiele für das direkte Veröffentlichen eines Ereignisses in einem Eventarc Advanced-Bus:

Beispiel 1

Sie können ein Ereignis mit der gcloud CLI und einem --event-data-Flag sowie anderen Attribut-Flags für Ereignisse in einem Bus veröffentlichen:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Beispiel 2

Sie können ein Ereignis als JSON-Nachricht mit der gcloud CLI und dem Flag --json-message in einem Bus veröffentlichen:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Nachdem Sie ein Ereignis veröffentlicht haben, sollten Sie die Meldung „Event published successfully“ (Ereignis erfolgreich veröffentlicht) erhalten.

Ereignisdaten in den Cloud Run-Logs ansehen

Nachdem Sie ein Ereignis in Ihrem Eventarc Advanced-Bus veröffentlicht haben, können Sie in den Logs Ihres Cloud Run-Dienstes prüfen, ob das Ereignis wie erwartet empfangen wurde.

  1. Filtern Sie die Logeinträge und geben Sie die Ausgabe mit dem Befehl gcloud logging read zurück:

    gcloud logging read 'textPayload: "hello-world-data"'

  2. Suchen Sie nach einem Logeintrag wie dem Folgenden:

    insertId: 670808e70002b5c6477709ae
labels:
instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
resource:
labels:
...
type: cloud_run_revision
textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
  }'"
timestamp: '2024-10-10T17:03:35.177606Z'

Sie haben einen Eventarc Advanced-Bus und eine Registrierung erstellt, eine Ereignisnachricht im Bus veröffentlicht und das erwartete Ergebnis in den Logs des Ereignisempfängerdienstes überprüft.

Bereinigen

Nach Abschluss der in dieser Kurzanleitung beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen:

  1. Artifact Registry-Repository löschen

  2. Cloud Run-Dienst löschen

  3. Eventarc Advanced-Ressourcen löschen:

    1. Registrierung löschen

    2. Pipeline löschen

    3. Bus löschen

Alternativ können Sie Ihr Google Cloud -Projekt löschen, um wiederkehrende Gebühren zu vermeiden. Durch das Löschen des Google Cloud -Projekts wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.

Google Cloud -Projekt löschen:

gcloud projects delete PROJECT_ID

Nächste Schritte