Funktionen aus Pub/Sub mit Eventarc auslösen


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:

  1. Ereignisgesteuerte Funktion bereitstellen
  2. Eventarc-Trigger erstellen.
  3. Funktionen durch Veröffentlichen einer Nachricht in einem Pub/Sub-Thema auslösen

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. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

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.

  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.

    • 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. Install the Google Cloud CLI.
  7. To initialize the gcloud CLI, run the following command:

    gcloud init
  8. 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.

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

  10. 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
  11. APIs aktivieren:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        logging.googleapis.com \
        pubsub.googleapis.com
  12. 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}
  13. Erstellen Sie ein Dienstkonto:
    SERVICE_ACCOUNT=eventarc-trigger-sa
    
    gcloud iam service-accounts create $SERVICE_ACCOUNT
  14. 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

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

    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.

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

  3. 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.
  4. 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
  5. 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'
  6. 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

  1. 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
    
  2. 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/
    
  3. Sehen Sie sich den Beispielcode an:

    Node.js

    const functions = require('@google-cloud/functions-framework');
    
    // Register a CloudEvent callback with the Functions Framework that will
    // be executed when the Pub/Sub trigger topic receives a message.
    functions.cloudEvent('helloPubSub', cloudEvent => {
      // The Pub/Sub message is passed as the CloudEvent's data payload.
      const base64name = cloudEvent.data.message.data;
    
      const name = base64name
        ? Buffer.from(base64name, 'base64').toString()
        : 'World';
    
      console.log(`Hello, ${name}!`);
    });

    Python

    import base64
    
    from cloudevents.http import CloudEvent
    import functions_framework
    
    
    # Triggered from a message on a Cloud Pub/Sub topic.
    @functions_framework.cloud_event
    def subscribe(cloud_event: CloudEvent) -> None:
        # Print out the data from Pub/Sub, to prove that it worked
        print(
            "Hello, " + base64.b64decode(cloud_event.data["message"]["data"]).decode() + "!"
        )
    
    

    Go

    
    // Package helloworld provides a set of Cloud Functions samples.
    package helloworld
    
    import (
    	"context"
    	"fmt"
    	"log"
    
    	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
    	"github.com/cloudevents/sdk-go/v2/event"
    )
    
    func init() {
    	functions.CloudEvent("HelloPubSub", helloPubSub)
    }
    
    // MessagePublishedData contains the full Pub/Sub message
    // See the documentation for more details:
    // https://cloud.google.com/eventarc/docs/cloudevents#pubsub
    type MessagePublishedData struct {
    	Message PubSubMessage
    }
    
    // PubSubMessage is the payload of a Pub/Sub event.
    // See the documentation for more details:
    // https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
    type PubSubMessage struct {
    	Data []byte `json:"data"`
    }
    
    // helloPubSub consumes a CloudEvent message and extracts the Pub/Sub message.
    func helloPubSub(ctx context.Context, e event.Event) error {
    	var msg MessagePublishedData
    	if err := e.DataAs(&msg); err != nil {
    		return fmt.Errorf("event.DataAs: %w", err)
    	}
    
    	name := string(msg.Message.Data) // Automatically decoded from base64.
    	if name == "" {
    		name = "World"
    	}
    	log.Printf("Hello, %s!", name)
    	return nil
    }
    

    Java

    import com.google.cloud.functions.CloudEventsFunction;
    import com.google.gson.Gson;
    import functions.eventpojos.PubSubBody;
    import io.cloudevents.CloudEvent;
    import java.nio.charset.StandardCharsets;
    import java.util.Base64;
    import java.util.logging.Logger;
    
    public class SubscribeToTopic implements CloudEventsFunction {
      private static final Logger logger = Logger.getLogger(SubscribeToTopic.class.getName());
    
      @Override
      public void accept(CloudEvent event) {
        // The Pub/Sub message is passed as the CloudEvent's data payload.
        if (event.getData() != null) {
          // Extract Cloud Event data and convert to PubSubBody
          String cloudEventData = new String(event.getData().toBytes(), StandardCharsets.UTF_8);
          Gson gson = new Gson();
          PubSubBody body = gson.fromJson(cloudEventData, PubSubBody.class);
          // Retrieve and decode PubSub message data
          String encodedData = body.getMessage().getData();
          String decodedData =
              new String(Base64.getDecoder().decode(encodedData), StandardCharsets.UTF_8);
          logger.info("Hello, " + decodedData + "!");
        }
      }
    }

    .NET

    using CloudNative.CloudEvents;
    using Google.Cloud.Functions.Framework;
    using Google.Events.Protobuf.Cloud.PubSub.V1;
    using Microsoft.Extensions.Logging;
    using System.Threading;
    using System.Threading.Tasks;
    
    namespace HelloPubSub;
    
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;
    
        public Function(ILogger<Function> logger) =>
            _logger = logger;
    
        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }

    Ruby

    require "functions_framework"
    require "base64"
    
    FunctionsFramework.cloud_event "hello_pubsub" do |event|
      # The event parameter is a CloudEvents::Event::V1 object.
      # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
      name = Base64.decode64 event.data["message"]["data"] rescue "World"
    
      # A cloud_event function does not return a response, but you can log messages
      # or cause side effects such as sending additional events.
      logger.info "Hello, #{name}!"
    end

    PHP

    
    use CloudEvents\V1\CloudEventInterface;
    use Google\CloudFunctions\FunctionsFramework;
    
    // Register the function with Functions Framework.
    // This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
    // variable when deploying. The `FUNCTION_TARGET` environment variable should
    // match the first parameter.
    FunctionsFramework::cloudEvent('helloworldPubsub', 'helloworldPubsub');
    
    function helloworldPubsub(CloudEventInterface $event): void
    {
        $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');
    
        $cloudEventData = $event->getData();
        $pubSubData = base64_decode($cloudEventData['message']['data']);
    
        $name = $pubSubData ? htmlspecialchars($pubSubData) : 'World';
        fwrite($log, "Hello, $name!" . PHP_EOL);
    }

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:

  1. 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“.

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

  1. Weisen Sie das Thema einer Variablen zu:

    TOPIC_ID=$(gcloud eventarc triggers describe TRIGGER_NAME --location $REGION --format='value(transport.pubsub.topic)')
    
  2. 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:

  1. Öffnen Sie die Google Cloud Console.
  2. Klicken Sie auf die Funktion.
  3. 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.

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

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Anleitungsressourcen löschen

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

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

  3. Löschen Sie sonstige Google Cloud-Ressourcen, die in dieser Anleitung erstellt wurden:

    • Löschen Sie den Eventarc-Trigger:
      gcloud eventarc triggers delete TRIGGER_NAME
      
      Ersetzen Sie TRIGGER_NAME durch den Namen des Triggers.

Nächste Schritte