Funktionen aus Pub/Sub mit Eventarc auslösen

In dieser Anleitung wird veranschaulicht, wie Sie eine ereignisgesteuerte Cloud Run Functions-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, lesen Sie die Pub/Sub-Dokumentation mit Kurzanleitungen und wichtigen Referenzen.

Erforderliche Rollen

Sie oder Ihr Administrator müssen dem Bereitstellerkonto, der Triggeridentität und optional dem Pub/Sub-Dienst-Agent und dem Cloud Storage-Dienst-Agent die folgenden IAM-Rollen zuweisen.

Erforderliche Rollen für das Bereitstellerkonto

  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.

    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.

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

Erforderliche Rollen für die Triggeridentität

  1. 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 die Google CloudProjektnummer. Sie finden Ihre Projektnummer auf der Willkommensseite der Google Cloud -Konsole 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.

  2. 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 Projekt Google Cloud 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.
  3. 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

Optionale Rolle für den Cloud Storage-Dienst-Agent

  • 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'

Optionale Rolle für den Pub/Sub-Dienst-Agent

  • 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 werden Pub/Sub-Themen nicht automatisch erstellt, wenn Sie eine Funktion bereitstellen. Bevor Sie die Funktion bereitstellen, veröffentlichen Sie 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 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 run deploy FUNCTION \
        --source . \
        --function helloPubSub \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. nodejs22. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Python 

  gcloud run deploy FUNCTION \
        --source . \
        --function subscribe \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. python313. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Go

  gcloud run deploy FUNCTION \
        --source . \
        --function HelloPubSub \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. go125. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Java

  gcloud run deploy FUNCTION \
        --source . \
        --function functions.SubscribeToTopic \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. java21. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

.NET

  gcloud run deploy FUNCTION \
        --source . \
        --function HelloPubSub.Function \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. dotnet8. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Ruby

  gcloud run deploy FUNCTION \
        --source . \
        --function hello_pubsub \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. ruby34. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

PHP

  gcloud run deploy FUNCTION \
        --source . \
        --function helloworldPubsub \
        --base-image BASE_IMAGE \

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 durch die Basis-Image-Umgebung für Ihre Funktion, z. B. php84. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Wenn Sie aufgefordert werden, ein Repository in der angegebenen Region zu erstellen, antworten Sie durch Drücken von y. Wenn die Bereitstellung abgeschlossen ist, 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 aus, das den Beispielcode enthält, 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:

    • Ersetzen Sie TRIGGER_NAME durch den Namen des Triggers.
    • Ersetzen Sie 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 Textkörper der eingehenden Nachricht. Sie können dies im Abschnitt „Logs“ Ihrer Cloud Run-Instanz sehen:

  1. Rufen Sie die Google Cloud Console auf.
  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 Nachricht „Hello World!“.