Eventarc を使用して Pub/Sub から関数をトリガーする

---

プレビュー — Cloud Run functions

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

このチュートリアルでは、Pub/Sub トリガーを使用してイベント ドリブンの Cloud Run 関数を作成してトリガーする方法について説明します。

Eventarc トリガーのフィルタを指定すると、イベントソースやイベント ターゲットなど、イベントの転送を構成できます。このチュートリアルの例では、Pub/Sub トピックにメッセージをパブリッシュするとイベントがトリガーされ、リクエストが HTTP リクエストの形式で関数に送信されます。

Pub/Sub を初めて使用する場合、詳細については、Pub/Sub のドキュメントでクイックスタートと主要なリファレンスをご覧ください。

注: HTTP トリガー関数を使用して Pub/Sub push サブスクリプションをリッスンできます。HTTP 関数を使用すれば、1 つの関数で複数の Pub/Sub トピックに登録できます。

目標

このチュートリアルの内容は次のとおりです。

1. イベント ドリブン関数をデプロイする。
2. Eventarc トリガーを作成する。
3. Pub/Sub トピックにメッセージを公開して関数をトリガーする。

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Logging
• Eventarc
• Pub/Sub

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。 新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

始める前に

組織で定義されているセキュリティの制約により、次の手順を完了できない場合があります。トラブルシューティング情報については、制約のある Google Cloud 環境でアプリケーションを開発するをご覧ください。

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

   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.

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

10. Cloud Shell を使用していない場合は、Google Cloud CLI コンポーネントを更新し、自分のアカウントを使用してログインします。

    gcloud components update
    gcloud auth login

11. API を有効にします。

    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        logging.googleapis.com \
        pubsub.googleapis.com

12. このチュートリアルで使用する構成変数を設定します。

    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}

13. サービス アカウントを作成します。

    SERVICE_ACCOUNT=eventarc-trigger-sa
    
    gcloud iam service-accounts create $SERVICE_ACCOUNT

14. ドメイン制限の組織のポリシーでプロジェクトの未認証呼び出しが制限されている場合は、限定公開サービスのテストの説明に従って、デプロイされたサービスにアクセスする必要があります。

必要なロール

1. プロジェクト作成者には、オーナーロール（roles/owner）が付与されます。デフォルトでは、この Identity and Access Management（IAM）ロールには、ほとんどの Google Cloud リソースへの完全アクセス権に必要な権限が含まれており、この手順は省略できます。

   プロジェクト作成者でない場合は、プロジェクトで適切なプリンシパルに必要な権限を付与する必要があります。プリンシパルは Google アカウント（エンドユーザーの場合）やサービス アカウント（アプリケーションとコンピューティング ワークロードの場合）になることもあります。詳細については、イベントの宛先のロールと権限のページをご覧ください。

   必要な権限

   このチュートリアルを完了するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

   • Cloud Run ソース デベロッパー（roles/run.sourceDeveloper）
   • プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
   • サービス アカウント ユーザー（roles/iam.serviceAccountUser）
   • Service Usage 管理者 （roles/serviceusage.serviceUsageAdmin）
   • ログ表示アクセス者（roles/logging.viewAccessor）

   ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

   必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

2. Compute Engine のデフォルトのサービス アカウントをメモしておいてください。テスト目的で、Eventarc トリガーに関連付けて、トリガーの ID を示すためです。このサービス アカウントは、Compute Engine を使用する Google Cloud サービスを有効にするか、使用すると自動的に作成されます。メールアドレスの形式は次のとおりです。

   [e-mail]

   PROJECT_NUMBER は、実際の Google Cloud プロジェクトの番号に置き換えます。プロジェクト番号は、Google Cloud コンソールの [ようこそ] ページで確認できます。また、次のコマンドで確認することもできます。

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

   本番環境では、新しいサービス アカウントを作成して、必要最小限の権限を含む、最小権限の原則に従った 1 つ以上の IAM ロールを付与することを強くおすすめします。

   注:

   iam.automaticIamGrantsForDefaultServiceAccounts 組織のポリシーの制約により、編集者のロールはデフォルトのサービス アカウントに自動的に付与されません。2024 年 5 月 3 日より後に組織を作成した場合、この制約はデフォルトで適用されます。

   この制約を適用して、ロールの自動付与を無効にすることを強くおすすめします。ロールの自動付与を無効にする場合は、デフォルトのサービス アカウントに付与するロールを決定し、ご自身でこれらのロールを付与する必要があります。

   デフォルトのサービス アカウントにすでに編集者ロールが設定されている場合は、編集者ロールを権限の低いロールに置き換えることをおすすめします。サービス アカウントのロールを安全に変更するには、Policy Simulator を使用して変更の影響を確認してから、適切なロールを付与または取り消す操作を行います。

3. デフォルトでは、Cloud Run サービスを呼び出すことができるのは、プロジェクト オーナー、プロジェクト編集者、Cloud Run 管理者、起動元のみです。サービスごとにアクセスを制御できます。ただし、テスト目的の場合は、Google Cloud プロジェクトの Cloud Run 起動元ロール（run.invoker）を Compute Engine サービス アカウントに付与してください。これにより、プロジェクト内のすべての Cloud Run サービスとジョブにロールが付与されます。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/run.invoker

   Cloud Run 起動元ロールを付与せずに認証済みの Cloud Run サービスのトリガーを作成すると、トリガーは正常に作成され、アクティブになります。ただし、トリガーが期待どおりに機能せず、次のようなメッセージがログに記録されます。

   The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
4. プロジェクトの Eventarc イベント レシーバーのロール（roles/eventarc.eventReceiver）を Compute Engine のデフォルト サービス アカウントに付与して、Eventarc トリガーがイベント プロバイダからイベントを受信できるようにします。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/eventarc.eventReceiver

5. Cloud Storage からの直接イベントのトリガーを作成する前に、Cloud Storage サービス エージェントに Pub/Sub パブリッシャーのロール（roles/pubsub.publisher）を付与します。

   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. 2021 年 4 月 8 日以前に、認証済みの Pub/Sub push リクエストをサポートするために Cloud Pub/Sub サービス エージェントを有効にした場合は、サービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）をサービス エージェントに付与します。それ以外の場合、このロールはデフォルトで付与されます。

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Pub/Sub トピックの作成

Cloud Run functions では、関数をデプロイするときに Pub/Sub トピックが自動的に作成されません。関数をデプロイする前に、この Pub/Sub トピックにメッセージを公開して関数をトリガーします。

gcloud pubsub topics create YOUR_TOPIC_NAME

アプリケーションを準備する

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

   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. Pub/Sub にアクセスするための Cloud Run functions サンプルコードがあるディレクトリに移動します。

   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. サンプルコードを見てみましょう。

   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);
   }

注: Pub/Sub メッセージのデータは、base64 でエンコードされた文字列として PubsubMessage オブジェクトの data プロパティに保存されます。このデータを抽出するには、上の例のサンプルコードのようにデコードが必要になる場合があります。

イベント ドリブン関数をデプロイする

関数をデプロイするには、サンプルコードを含むディレクトリで次のコマンドを実行します。

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 \

FUNCTION は、デプロイする関数の名前に置き換えます。このパラメータを省略すると、コマンドを実行するときに名前の入力を求められます。

BASE_IMAGE は、関数のベースイメージ環境です。ベースイメージと各イメージに含まれるパッケージの詳細については、ランタイム ベースイメージをご覧ください。

指定したリージョンにリポジトリを作成するように求められたら、y を押して応答します。デプロイが完了すると、サービスが実行されている URL が Google Cloud CLI に表示されます。

Eventarc トリガーを作成する

Pub/Sub トリガーを使用して関数をデプロイするには、サンプルコードを含むディレクトリで次のコマンドを実行します。

1. Eventarc Pub/Sub トリガーを作成します。

   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=[e-mail]

   次のように置き換えます。

   • TRIGGER_NAME: トリガーの名前。
   • FUNCTION: 関数の名前。
   • PROJECT_NUMBER は、Google Cloud プロジェクト番号に置き換えます。

   Google Cloud プロジェクトで初めて Eventarc トリガーを作成する場合、Eventarc サービス エージェントのプロビジョニングに遅延が発生することがあります。この問題は通常、トリガーを再度作成することで解決できます。詳細については、権限拒否エラーをご覧ください。

2. トリガーが正常に作成されたことを確認します。トリガーはすぐに作成されますが、トリガーが完全に機能するまでに 2 分ほどかかることがあります。

   gcloud eventarc triggers list --location=${REGION}

   出力例を以下に示します。

   NAME: helloworld-events
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: helloworld-events
   ACTIVE: Yes
   LOCATION: us-central1
   

関数をトリガーする

Pub/Sub 関数をテストするには:

1. トピックを変数に割り当てます。

   TOPIC_ID=$(gcloud eventarc triggers describe TRIGGER_NAME --location $REGION --format='value(transport.pubsub.topic)')
   

2. トピックにメッセージをパブリッシュします。

   gcloud pubsub topics publish $TOPIC_ID --message="Hello World"
   

Cloud Run サービスは、受信したメッセージの本文をログに記録します。これは、Cloud Run インスタンスの [ログ] セクションで確認できます。

1. Google Cloud コンソールに移動します。
2. 関数をクリックします。

3. [ログ] タブを選択します。

   ログが表示されるまで少し時間がかかることがあります。すぐに表示されない場合は、しばらくしてからもう一度確認してください。

4. 「Hello World!」というメッセージを見つけます。

クリーンアップ

このチュートリアル用に新規プロジェクトを作成した場合は、そのプロジェクトを削除します。既存のプロジェクトを使用していて、このチュートリアルで行った変更を追加せずに残す場合は、チュートリアル用に作成したリソースを削除します。

プロジェクトを削除する

課金をなくす最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

注意: プロジェクトを削除すると、次のような影響があります。

• プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

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.

チュートリアル リソースの削除

1. このチュートリアルでデプロイした Cloud Run サービスを削除します。

   gcloud run services delete SERVICE_NAME

   SERVICE_NAME は、選択したサービス名です。

   Cloud Run サービスは Google Cloud コンソールから削除することもできます。

2. チュートリアルの設定時に追加した gcloud CLI のデフォルト構成を削除します。

   例:

   gcloud config unset run/region

   または

   gcloud config unset project

3. このチュートリアルで作成した他の Google Cloud リソースを削除します。

   • Eventarc トリガーを削除します。

     gcloud eventarc triggers delete TRIGGER_NAME
     

     TRIGGER_NAME は、実際のトリガー名に置き換えます。

次のステップ

• 他のイベントタイプの Eventarc トリガーを作成する
• 関数を管理する