In dieser Anleitung wird veranschaulicht, wie Sie eine ereignisgesteuerte Cloud Run-Funktion mit einem Pub/Sub-Trigger schreiben und auslösen.
Sie können das Routing von Ereignissen konfigurieren, einschließlich der Ereignisquelle und des Ereignisziels, indem Sie Filter für einen Eventarc-Trigger angeben. Im Beispiel in dieser Anleitung wird das Ereignis durch das Veröffentlichen einer Nachricht in einem Pub/Sub-Thema ausgelöst und eine Anfrage in Form einer HTTP-Anfrage an Ihre Funktion gesendet.
Wenn Sie Pub/Sub noch nicht kennen und weitere Informationen erhalten möchten, finden Sie in der Pub/Sub-Dokumentation Kurzanleitungen und wichtige Referenzen.
Lernziele
In dieser Anleitung wird Folgendes beschrieben:
Kosten
In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:
Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.
Vorbereitung
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.
- 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.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud 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.
-
-
Make sure that billing is enabled for your Google Cloud project.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud 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.
-
-
Make sure that billing is enabled for your Google Cloud project.
- Wenn Sie Cloud Shell nicht verwenden, aktualisieren Sie die Komponenten der Google Cloud-Befehlszeile und melden Sie sich mit Ihrem Konto an:
gcloud components update gcloud auth login
- APIs aktivieren:
gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ logging.googleapis.com \ pubsub.googleapis.com
- Legen Sie die in dieser Anleitung verwendeten Konfigurationsvariablen fest:
export REGION=us-central1 gcloud config set run/region ${REGION} gcloud config set run/platform managed gcloud config set eventarc/location ${REGION}
- Erstellen Sie ein Dienstkonto:
SERVICE_ACCOUNT=eventarc-trigger-sa gcloud iam service-accounts create $SERVICE_ACCOUNT
Wenn Sie einer Domaineinschränkung zur Organisation nicht eingeschränkter Aufrufe für Ihr Projekt unterliegen, müssen Sie auf Ihren bereitgestellten Dienst zugreifen, wie unter Private Dienste testen beschrieben.
Erforderliche Rollen
-
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. Weitere Informationen finden Sie auf der Seite Rollen und Berechtigungen für Ihr Ereignisziel.
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 dieser Anleitung benötigen:
- Cloud Run Source Developer (
roles/run.sourceDeveloper
) -
Projekt-IAM-Administrator (
roles/resourcemanager.projectIamAdmin
) -
Service Account User (
roles/iam.serviceAccountUser
) -
Service Usage Admin (
roles/serviceusage.serviceUsageAdmin
) -
Zugriffsberechtigter für Logbetrachtung (
roles/logging.viewAccessor
)
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.
- Cloud Run Source Developer (
Notieren Sie sich das Compute Engine Standarddienstkonto, das Sie an einen Eventarc-Trigger anhängen, um die Identität des Triggers zu Testzwecken darzustellen. Dieses Dienstkonto wird automatisch nach der Aktivierung oder Verwendung eines Google Cloud-Dienstes, der Compute Engine verwendet, mit dem folgenden E-Mail-Format erstellt:
PROJECT_NUMBER-compute@developer.gserviceaccount.com
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)'
Für Produktionsumgebungen empfehlen wir dringend, ein neues Dienstkonto zu erstellen und ihm eine oder mehrere IAM-Rollen zuzuweisen, die die erforderlichen Mindestberechtigungen enthalten und dem Grundsatz der geringsten Berechtigung folgen.
- Standardmäßig können Cloud Run-Dienste nur von Nutzern mit der Rolle „Project Owner“, „Project Editor“, „Cloud Run Admin“ oder „Cloud Run Invoker“ aufgerufen werden.
Sie können den Zugriff für einzelne Dienste steuern. Weisen Sie jedoch zu Testzwecken dem Compute Engine-Dienstkonto die Rolle „Cloud Run-Aufrufer” (
run.invoker
) für das Google Cloud-Projekt zu. Dadurch wird die Rolle für alle Cloud Run-Dienste und -Jobs in einem Projekt zugewiesen.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/run.invoker
Wenn Sie einen Trigger für einen authentifizierten Cloud Run-Dienst erstellen, ohne die Rolle "Cloud Run Invoker" zuzuweisen, wird der Trigger erfolgreich erstellt und ist aktiv. Der Trigger funktioniert jedoch nicht wie erwartet und in den Logs wird eine Meldung wie die folgende angezeigt:
The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
- Weisen Sie dem Compute Engine-Standarddienstkonto die Rolle „Eventarc-Ereignisempfänger“ (
roles/eventarc.eventReceiver
) für das Projekt zu, damit der Eventarc-Trigger Ereignisse vom Ereignisanbieter empfangen kann.gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/eventarc.eventReceiver
- Bevor Sie einen Trigger für direkte Ereignisse aus Cloud Storage erstellen, weisen Sie dem Cloud Storage-Dienst-Agent die Pub/Sub-Publisher-Rolle (
roles/pubsub.publisher
) zu:SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)" gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:${SERVICE_ACCOUNT}" \ --role='roles/pubsub.publisher'
- Wenn Sie den Cloud Pub/Sub-Dienst-Agent am oder vor dem 8. April 2021 aktiviert haben, um authentifizierte Pub/Sub-Push-Anfragen zu unterstützen, weisen Sie dem von Google verwalteten Dienstkonto die Rolle „Ersteller von Dienstkonto-Tokens“ (
roles/iam.serviceAccountTokenCreator
) zu. Andernfalls wird diese Rolle standardmäßig zugewiesen:gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator
Pub/Sub-Thema erstellen
In Cloud Run-Funktionen werden Pub/Sub-Themen nicht automatisch erstellt, wenn Sie eine Funktion bereitstellen. Veröffentlichen Sie vor dem Bereitstellen Ihrer Funktion eine Nachricht in diesem Pub/Sub-Thema, um die Funktion auszulösen:
gcloud pubsub topics create YOUR_TOPIC_NAME
Anwendung vorbereiten
Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
.NET
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
PHP
git clone https://github.com/GoogleCloudPlatform/php-docs-samples.git
Wechseln Sie in das Verzeichnis mit dem Cloud Run Functions-Beispielcode für den Zugriff auf Pub/Sub:
Node.js
cd nodejs-docs-samples/functions/v2/helloPubSub/
Python
cd python-docs-samples/functions/v2/pubsub/
Go
cd golang-samples/functions/functionsv2/hellopubsub/
Java
cd java-docs-samples/functions/v2/pubsub/
.NET
cd dotnet-docs-samples/functions/helloworld/HelloPubSub/
Ruby
cd ruby-docs-samples/functions/helloworld/pubsub/
PHP
cd php-docs-samples/functions/helloworld_pubsub/
Sehen Sie sich den Beispielcode an:
Node.js
Python
Go
Java
.NET
Ruby
PHP
Ereignisgesteuerte Funktion bereitstellen
Führen Sie den folgenden Befehl im Verzeichnis aus, das den Beispielcode enthält, um die Funktion bereitzustellen:
Node.js
gcloud beta run deploy FUNCTION \
--source . \
--function helloPubSub \
--base-image nodejs22 \
Python
gcloud beta run deploy FUNCTION \
--source . \
--function subscribe \
--base-image python312 \
Go
gcloud beta run deploy FUNCTION \
--source . \
--function HelloPubSub \
--base-image go122 \
Java
gcloud beta run deploy FUNCTION \
--source . \
--function functions.SubscribeToTopic \
--base-image java21 \
.NET
gcloud beta run deploy FUNCTION \
--source . \
--function HelloPubSub.Function \
--base-image dotnet8 \
Ruby
gcloud beta run deploy FUNCTION \
--source . \
--function hello_pubsub \
--base-image ruby33 \
PHP
gcloud beta run deploy FUNCTION \
--source . \
--function helloworldPubsub \
--base-image php83 \
Ersetzen Sie FUNCTION durch den Namen der Funktion, die Sie bereitstellen. Wenn Sie diesen Parameter weglassen, werden Sie beim Ausführen des Befehls aufgefordert, einen Namen einzugeben.
BASE_IMAGE ist die Basis-Image-Umgebung für Ihre Funktion. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Laufzeit-Basis-Images.
Wenn Sie aufgefordert werden, ein Repository in der angegebenen Region zu erstellen, antworten Sie durch Drücken von y
.
Nach Abschluss der Bereitstellung wird in der Google Cloud CLI eine URL angezeigt, unter der der Dienst ausgeführt wird.
Eventarc-Trigger erstellen
Führen Sie den folgenden Befehl in dem Verzeichnis mit dem Beispielcode aus, um die Funktion mit einem Pub/Sub-Trigger bereitzustellen:
So erstellen Sie einen Pub/Sub-Trigger für Eventarc:
gcloud eventarc triggers create TRIGGER_NAME \ --location=${REGION} \ --destination-run-service=FUNCTION \ --destination-run-region=${REGION} \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
Ersetzen Sie:
- TRIGGER_NAME durch den Namen des Triggers.
- FUNCTION durch den Namen Ihrer Funktion.
- PROJECT_NUMBER durch Ihre Google Cloud-Projektnummer.
Beachten Sie, dass das Erstellen eines Eventarc-Triggers in einem Google Cloud-Projekt möglicherweise zu einer Verzögerung bei der Bereitstellung des Eventarc-Dienst-Agents kommt. Dieses Problem lässt sich normalerweise durch erneutes Erstellen des Triggers beheben. Weitere Informationen finden Sie unter Fehler „Berechtigung verweigert“.
Prüfen Sie, ob der Trigger korrekt erstellt wurde. Der Trigger wird zwar sofort erstellt, es kann jedoch bis zu zwei Minuten dauern, bis ein Trigger vollständig funktioniert.
gcloud eventarc triggers list --location=${REGION}
Die Ausgabe sollte in etwa so aussehen:
NAME: helloworld-events TYPE: google.cloud.pubsub.topic.v1.messagePublished DESTINATION: Cloud Run service: helloworld-events ACTIVE: Yes LOCATION: us-central1
Funktion auslösen
So testen Sie die Pub/Sub-Funktion:
Weisen Sie das Thema einer Variablen zu:
TOPIC_ID=$(gcloud eventarc triggers describe TRIGGER_NAME --location $REGION --format='value(transport.pubsub.topic)')
Nachricht zum Thema veröffentlichen:
gcloud pubsub topics publish $TOPIC_ID --message="Hello World"
Der Cloud Run-Dienst protokolliert den Text der eingehenden Nachricht. Sie finden diese Informationen im Bereich „Protokolle“ Ihrer Cloud Run-Instanz:
- Öffnen Sie die Google Cloud Console.
- Klicken Sie auf die Funktion.
Wählen Sie den Tab Logs aus.
Es kann einige Momente dauern, bis Logs angezeigt werden. Falls sie nicht sofort angezeigt werden, warten Sie kurz ab und sehen Sie dann noch einmal nach.
Suchen Sie nach der Meldung „Hello World!“.
Bereinigen
Wenn Sie ein neues Projekt für diese Anleitung erstellt haben, löschen Sie das Projekt. Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, ohne die Änderungen in dieser Anleitung hinzuzufügen, löschen Sie die für die Anleitung erstellten Ressourcen.
Projekt löschen
Am einfachsten vermeiden Sie weitere Kosten durch Löschen des für die Anleitung erstellten Projekts.
So löschen Sie das Projekt:
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Anleitungsressourcen löschen
Löschen Sie den Cloud Run-Dienst, den Sie in dieser Anleitung bereitgestellt haben:
gcloud run services delete SERVICE_NAME
Dabei ist
SERVICE_NAME
der von Ihnen ausgewählte Dienstname.Sie können Cloud Run-Dienste auch über die Google Cloud Console löschen.
Entfernen Sie gcloud CLI-Standardkonfigurationen, die Sie während der Einrichtung der Anleitung hinzugefügt haben.
Beispiel:
gcloud config unset run/region
oder
gcloud config unset project
Löschen Sie sonstige Google Cloud-Ressourcen, die in dieser Anleitung erstellt wurden:
- Löschen Sie den Eventarc-Trigger:
Ersetzen Siegcloud eventarc triggers delete TRIGGER_NAME
TRIGGER_NAME
durch den Namen des Triggers.
- Löschen Sie den Eventarc-Trigger: