Ereignisse veröffentlichen und empfangen, indem Sie einen Bus und eine Registrierung erstellen

Ereignisse veröffentlichen und empfangen, indem Sie einen Bus und eine Registrierung erstellen

Erweitert

Vorschau — Eventarc Advanced

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

In dieser Kurzanleitung erfahren Sie, wie Sie Ereignisnachrichten veröffentlichen und empfangen, indem Sie einen erweiterten Eventarc-Bus erstellen und sich in Ihrem Google Cloud-Projekt registrieren.

Mit einem Bus können Sie den Nachrichtenfluss durch Ihr System zentralisieren und er fungiert als Router. Er empfängt Ereignisse von einer Nachrichtenquelle oder von einem Anbieter und wertet sie gemäß einer Anmeldung aus.

Eine Registrierung identifiziert ein Abo für einen bestimmten Bus und definiert die Abgleichkriterien für Nachrichten, die entsprechend an ein oder mehrere Ziele weitergeleitet werden.

In dieser Kurzanleitung werden folgende Schritte erläutert:

1. Erstellen Sie ein Subnetz und aktivieren Sie den privater Google-Zugriff.

2. Netzwerkanhang erstellen

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

4. Erstellen Sie einen Eventarc Advanced-Bus.

5. Erstellen Sie eine Eventarc Advanced-Registrierung.

6. Eine Ereignisnachricht auf dem Bus veröffentlichen.

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

Sie können diese Kurzanleitung mit der Google Cloud CLI ausführen.

Hinweise

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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs:

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

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

10. Make sure that billing is enabled for your Google Cloud project.

11. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs:

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

12. Aktualisieren Sie die gcloud-Komponenten:

    gcloud components update

13. Melden Sie sich mit Ihrem -Konto an:

    gcloud auth login

14. Legen Sie die in dieser Kurzanleitung verwendete Konfigurationsvariable fest:

    REGION=REGION

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

15. 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:

    • Cloud Build-Bearbeiter (roles/cloudbuild.builds.editor)
    • Cloud Run-Administrator (roles/run.admin)
    • Eventarc-Entwickler (roles/eventarc.developer)
    • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
    • Zugriffsberechtigter für Logbetrachtung (roles/logging.viewAccessor)
    • Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin)
    • Service Account Admin (roles/iam.serviceAccountAdmin)
    • Service Account User (roles/iam.serviceAccountUser)
    • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

    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.

16. Weisen Sie dem Compute Engine-Standarddienstkonto die folgenden Rollen für das Projekt zu. Diese Rollen sind zum Erstellen und Bereitstellen Ihres Container-Images erforderlich:
    • Artifact Registry Writer: zum Hochladen von Artifact Registry-Artefakten
    • Logs Writer: zum Schreiben von Logs in Cloud Logging
    • Storage Object User: Zugriff auf Cloud Storage-Objekte

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/artifactregistry.writer
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/logging.logWriter
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/storage.objectUser

    Ersetzen Sie PROJECT_NUMBER durch Ihre Google Cloud-Projektnummer. Sie finden Ihre Projektnummer auf der Willkommensseite der Google Cloud Console oder durch Ausführen des folgenden Befehls:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

17. Standardmäßig können Cloud Run-Dienste nur von Projektinhabern, Projektbearbeitern, Cloud Run-Administratoren und Cloud Run-Aufrufern aufgerufen werden. Um die Authentifizierung einzurichten, weisen Sie einem Dienstkonto die Rolle Cloud Run Invoker (run.invoker) für Ihr Google Cloud-Projekt zu:
    1. Erstellen Sie ein Dienstkonto. Zu Testzwecken hängen Sie dieses Dienstkonto an eine Eventarc Advanced-Pipeline an, um die Identität der Pipeline darzustellen.

       gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

       Ersetzen Sie SERVICE_ACCOUNT_NAME durch einen Namen für das Dienstkonto.
    2. Weisen Sie dem Dienstkonto die IAM-Rolle roles/run.invoker zu:

       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 so konfigurieren, wer auf Ihren Cloud Run-Dienst zugreifen kann:

    • 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 enthalten, der ein von Google für ein autorisiertes Dienstkonto signiertes OpenID Connect-Token enthält. So wird der Zugriff in dieser Kurzanleitung konfiguriert.
    • Gewähren Sie allUsers die Berechtigung, um den nicht authentifizierten Zugriff zuzulassen.

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

Subnetz erstellen und privater Google-Zugriff aktivieren

Sofern Sie keine Organisationsrichtlinie erstellen, die dies verbietet, beginnen neue Google Cloud-Projekte mit einem standardmäßigen VPC-Netzwerk (Virtual Private Cloud) (einem VPC-Netzwerk im automatischen Modus), das in jeder Region ein Subnetzwerk (Subnetz) hat. Subnetzen sind IP-Adressbereiche zugeordnet.

Da Sie Nachrichten mithilfe einer DNS-Adresse an ein Cloud Run-Ziel weiterleiten, müssen Sie den privaten Google-Zugriff für das im Netzwerkanhang verwendete Subnetz aktivieren. Andernfalls kann die DNS-Adresse nicht aufgelöst werden. Weitere Informationen zu privaten Netzwerken und Cloud Run finden Sie unter Anfragen aus VPC-Netzwerken empfangen.

Erstellen Sie ein Subnetz im Standardnetzwerk Ihres Projekts und aktivieren Sie mit dem Flag --enable-private-ip-google-access den privater Google-Zugriff:

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

Ersetzen Sie SUBNET_NAME durch den Namen Ihres Subnetzes, z. B. my-subnet.

IP-Bereiche von Subnetzwerken müssen eindeutig sein und dürfen sich innerhalb eines VPC-Netzwerks und eines Peering-VPC-Netzwerk nicht überschneiden. Weitere Informationen zu Subnetztypen und gültigen Subnetzbereichen finden Sie unter Subnetze.

Netzwerkanhang erstellen

Ein Netzwerkanhang ist eine Ressource, mit der ein VPC-Netzwerk (Virtual Private Cloud) eines Erstellers Verbindungen zu einem Nutzer-VPC-Netzwerk initiieren kann. Eventarc Advanced verwendet zum Veröffentlichen von Ereignissen den Netzwerkanhang, um eine Verbindung zum Endpunkt herzustellen, der in einem VPC-Netzwerk gehostet wird.

Erstellen Sie einen Netzwerkanhang im selben Netzwerk und in derselben Region wie der Ereigniszielendpunkt, der automatisch Verbindungen von jeder Private Service Connect-Schnittstelle akzeptiert, die auf den Netzwerkanhang verweist:

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

Ersetzen Sie ATTACHMENT_NAME durch den Namen der Netzwerkverbindung, z. B. my-network-attachment.

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 in Cloud Run bereitstellen

Stellen Sie einen Cloud Run-Dienst bereit, der den Inhalt eines Ereignisses protokolliert. Auf diesen Dienst kann nur von VPC-Netzwerken innerhalb desselben Projekts zugegriffen werden. Die Dienst-URL ist nicht direkt zugänglich, da der Dienst nur authentifizierte Aufrufe zulässt.

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

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 internal \
       --no-allow-unauthenticated \
       --region=$REGION

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

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

Eventarc Advanced-Bus erstellen

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

gcloud beta 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.

Hinweis: Sie können nur einen Bus pro Google Cloud-Projekt erstellen.

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

Eventarc Advanced-Registrierung erstellen

Eine Anmeldung bestimmt, welche Nachrichten an ein Ziel weitergeleitet werden. Außerdem wird die Pipeline angegeben, über die Nachrichten weitergeleitet werden sollen. Mit der Pipeline wird ein Ziel für die Ereignisnachrichten konfiguriert.

Weitere Informationen finden Sie unter Registrierung zum Empfangen von Ereignissen erstellen.

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

Hinweis: Das Erstellen einer Pipeline kann länger als 10 Minuten dauern.

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

   gcloud beta eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,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 Schlüssel google_oidc_authentication_service_account gibt eine E-Mail-Adresse für das Dienstkonto an, die zum Generieren eines OIDC-Tokens verwendet wird.

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

   gcloud beta 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 Abgleichsexpression für diese Registrierung in CEL, z. B. "message.type == 'hello-world-type'".

Ereignisnachricht an den Bus senden

Wenn du eine Nachricht direkt auf deinem Bus veröffentlichen möchtest, kannst du den Befehl gcloud beta 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. Das ist eine Spezifikation zum allgemeinen Beschreiben von Ereignisdaten. Das data-Element ist die Nutzlast Ihres Ereignisses. Dieses Feld kann beliebige korrekt formatierte JSON-Daten enthalten. Weitere Informationen zu CloudEvents-Kontextattributen finden Sie unter Ereignisformat.

Im Folgenden finden Sie Beispiele für die direkte Veröffentlichung eines Ereignisses auf einem Eventarc Advanced-Bus:

Beispiel 1

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

gcloud beta 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 mit der gcloud CLI und einem --json-message-Flag als JSON-Nachricht an einen Bus veröffentlichen:

gcloud beta 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"}}'

Nach der Veröffentlichung eines Ereignisses sollten Sie die Meldung „Ereignis wurde 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 Protokollen 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'
   

   Hinweis: Wenn kein Logeintrag angezeigt wird, warten Sie einige Minuten und führen Sie den Befehl gcloud logging read noch einmal aus.

Sie haben einen Eventarc Advanced-Bus und eine Anmeldung erstellt, eine Ereignisnachricht auf dem Bus veröffentlicht und das erwartete Ergebnis in den Protokollen des Ereignisempfängerdiensts ü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. VPC-Subnetz löschen

2. VPC-VPC-Netzwerk löschen

3. Artifact Registry-Repository löschen

4. Löschen Sie einen Cloud Run-Dienst.

5. So löschen Sie Eventarc Advanced-Ressourcen:

   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. Wenn Sie Ihr Google Cloud-Projekt löschen, wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Nächste Schritte

• Ereignisse aus Google-Quellen veröffentlichen
• Ereignisse direkt veröffentlichen
• Empfangene Ereignisse transformieren
• Empfangene Ereignisse formatieren