Eventarc を使用して Cloud Storage から関数をトリガーする

このチュートリアルでは、Cloud Run にイベントドリブン関数をデプロイし、Eventarc を使用して Google Cloud CLI で Cloud Storage イベントに応答して関数をトリガーする方法について説明します。

Eventarc トリガーのフィルタを指定すると、イベントソースやイベントターゲットなど、イベントの転送を構成できます。このチュートリアルの例では、Cloud Storage バケットが更新されるとイベントがトリガーされ、リクエストが HTTP リクエストの形式で関数に送信されます。

目標

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

イベントソースとなる Cloud Storage バケットを作成する。
イベントドリブン関数をデプロイする。
Eventarc トリガーを作成する。
Cloud Storage にファイルをアップロードして関数をトリガーする。

費用

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

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

始める前に

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

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.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

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

API を有効にします。

gcloud services enable artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    eventarc.googleapis.com \
    run.googleapis.com \
    storage.googleapis.com

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

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

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

必要なロールを設定する

ご自身または管理者が、デプロイ担当者アカウント、トリガー ID、さらに必要に応じて Pub/Sub サービスエージェントと Cloud Storage サービスエージェントに次の IAM ロールを付与する必要があります。

デプロイ担当者のアカウントに必要なロール

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

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

このチュートリアルを完了するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- Cloud Build 編集者（roles/cloudbuild.builds.editor）
- Cloud Run 管理者（roles/run.admin）
- Cloud Run ソースデベロッパー（roles/run.sourceDeveloper）
- Eventarc 管理者（roles/eventarc.admin）
- ログ表示アクセス者（roles/logging.viewAccessor）
- プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
- サービスアカウント管理者（roles/iam.serviceAccountAdmin）
- サービスアカウントユーザー（roles/iam.serviceAccountUser）
- Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）
- ストレージ管理者（roles/storage.admin）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

デフォルトでは、Cloud Build の権限には、Artifact Registry アーティファクトをアップロードおよびダウンロードするための権限が含まれています。

トリガー ID に必要なロール

Compute Engine のデフォルトのサービスアカウントをメモしておいてください。テスト目的で、Eventarc トリガーにこのサービスアカウントを関連付け、トリガーの ID として使用します。このサービスアカウントは、Compute Engine を使用する Google Cloud サービスを有効にするか使用すると自動的に作成されます。メールアドレスの形式は次のとおりです。
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
PROJECT_NUMBER は、使用する Google Cloudプロジェクト番号に置き換えます。プロジェクト番号は、 Google Cloud コンソールの [ようこそ] ページで確認できます。また、次のコマンドでも確認できます。
```
gcloud projects describe PROJECT_ID --format='value(projectNumber)'
```
本番環境では、新しいサービスアカウントを作成して、必要最小限の権限を含む、最小権限の原則に従った 1 つ以上の IAM ロールを付与することを強くおすすめします。

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

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

デフォルトのサービスアカウントにすでに編集者ロールが設定されている場合は、編集者ロールを権限の低いロールに置き換えることをおすすめします。サービスアカウントのロールを安全に変更するには、Policy Simulator を使用して変更の影響を確認してから、適切なロールを付与または取り消す操作を行います。
デフォルトでは、Cloud Run サービスを呼び出すことができるのは、プロジェクトオーナー、プロジェクト編集者、Cloud Run 管理者、起動元のみです。サービスごとにアクセスを制御できます。ただし、テスト目的の場合は、 Google Cloud プロジェクトの Cloud Run 起動元ロール（run.invoker）を Compute Engine サービスアカウントに付与してください。これにより、プロジェクト内のすべての Cloud Run サービスとジョブにロールが付与されます。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker
```
Cloud Run 起動元ロールを付与せずに認証済みの Cloud Run サービスのトリガーを作成すると、トリガーは正常に作成され、アクティブになります。ただし、トリガーが期待どおりに機能せず、次のようなメッセージがログに記録されます。
The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
プロジェクトの Eventarc イベントレシーバーのロール（roles/eventarc.eventReceiver）を Compute Engine のデフォルトサービスアカウントに付与して、Eventarc トリガーがイベントプロバイダからイベントを受信できるようにします。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
```

Cloud Storage サービスエージェントのオプションのロール

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'

Pub/Sub サービスエージェントのオプションのロール

2021 年 4 月 8 日以前に、認証済みの Pub/Sub push リクエストをサポートするために Cloud Pub/Sub サービスエージェントを有効にした場合は、サービスアカウントトークン作成者のロール（roles/iam.serviceAccountTokenCreator）をサービスエージェントに付与します。それ以外の場合、このロールはデフォルトで付与されます。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator
```

Cloud Storage バケットを作成する

イベントソースとして使用する Cloud Storage バケットを作成します。

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

イベントドリブン関数を作成する

イベントドリブン関数の作成手順は次のとおりです。

Node.js

helloGCS という名前の新しいディレクトリを作成し、そのディレクトリに移動します。
```
   mkdir helloGCS
   cd helloGCS
```

helloGCS ディレクトリに package.json ファイルを作成して、Node.js の依存関係を指定します。

{
  "name": "nodejs-docs-samples-functions-v2-storage",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google LLC",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  "devDependencies": {
    "c8": "^10.0.0",
    "mocha": "^10.0.0",
    "sinon": "^18.0.0",
    "supertest": "^7.0.0"
  }
}

次の Node.js サンプルを使用して、helloGCS ディレクトリに index.js ファイルを作成します。

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent('helloGCS', cloudEvent => {
  console.log(`Event ID: ${cloudEvent.id}`);
  console.log(`Event Type: ${cloudEvent.type}`);

  const file = cloudEvent.data;
  console.log(`Bucket: ${file.bucket}`);
  console.log(`File: ${file.name}`);
  console.log(`Metageneration: ${file.metageneration}`);
  console.log(`Created: ${file.timeCreated}`);
  console.log(`Updated: ${file.updated}`);
});

Python

helloGCS という名前の新しいディレクトリを作成し、そのディレクトリに移動します。
```
   mkdir helloGCS
   cd helloGCS
```
Python の依存関係を指定するために、helloGCS ディレクトリに requirements.txt ファイルを作成します。
```
functions-framework==3.9.2
cloudevents==1.11.0
```
これにより、サンプルで必要なパッケージが追加されます。

helloGCS ディレクトリに、次の Python サンプルを含む main.py ファイルを作成します。

from cloudevents.http import CloudEvent

import functions_framework


# Triggered by a change in a storage bucket
@functions_framework.cloud_event
def hello_gcs(cloud_event: CloudEvent) -> tuple:
    """This function is triggered by a change in a storage bucket.

    Args:
        cloud_event: The CloudEvent that triggered this function.
    Returns:
        The event ID, event type, bucket, name, metageneration, and timeCreated.
    """
    data = cloud_event.data

    event_id = cloud_event["id"]
    event_type = cloud_event["type"]

    bucket = data["bucket"]
    name = data["name"]
    metageneration = data["metageneration"]
    timeCreated = data["timeCreated"]
    updated = data["updated"]

    print(f"Event ID: {event_id}")
    print(f"Event type: {event_type}")
    print(f"Bucket: {bucket}")
    print(f"File: {name}")
    print(f"Metageneration: {metageneration}")
    print(f"Created: {timeCreated}")
    print(f"Updated: {updated}")

    return event_id, event_type, bucket, name, metageneration, timeCreated, updated

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

サンプルコードを含むディレクトリで次のコマンドを実行し、helloworld-events という名前の関数をデプロイします。

Node.js

gcloud run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

BASE_IMAGE は、関数のベースイメージ環境に置き換えます（例: nodejs22）。ベースイメージと各イメージに含まれるパッケージの詳細については、サポートされている言語ランタイムとベースイメージをご覧ください。

Python

gcloud run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image BASE_IMAGE \
      --region us-central1

BASE_IMAGE は、関数のベースイメージ環境に置き換えます（例: python313）。ベースイメージと各イメージに含まれるパッケージの詳細については、サポートされている言語ランタイムとベースイメージをご覧ください。

デプロイが完了すると、サービスが実行されている URL が Google Cloud CLI に表示されます。

Eventarc トリガーを作成する

Eventarc トリガーは、Cloud Storage バケットから helloworld-events Cloud Run サービスにイベントを送信します。

Cloud Storage イベントをフィルタするトリガーを作成します。
```
gcloud eventarc triggers create TRIGGER_NAME  \
    --location=${REGION} \
    --destination-run-service=helloworld-events  \
    --destination-run-region=${REGION} \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
次のように置き換えます。
- TRIGGER_NAME: トリガーの名前。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- PROJECT_NUMBER: Google Cloud プロジェクト番号。
Google Cloud プロジェクトで初めて Eventarc トリガーを作成する場合は、Eventarc サービスエージェントのプロビジョニングに遅延が発生する可能性があります。この問題は通常、トリガーを再度作成することで解決できます。詳細については、権限拒否エラーをご覧ください。
トリガーが正常に作成されたことを確認します。トリガーはすぐに作成されますが、トリガーが完全に機能するまでに 2 分ほどかかることがあります。
```
gcloud eventarc triggers list --location=${REGION}
```
出力例を以下に示します。
```
NAME: helloworld-events
TYPE: google.cloud.storage.object.v1.finalized
DESTINATION: Cloud Run service: helloworld-events
ACTIVE: Yes
LOCATION: us-central1
```

イベントを生成して表示する

テキストファイルを Cloud Storage バケットにアップロードして、関数に転送されるイベントを生成します。このイベントは、Cloud Run 関数によってサービスログに記録されます。

イベントを生成するには、Cloud Storage にテキストファイルをアップロードします。
```
 echo "Hello World" > random.txt
 gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
```
アップロードによりイベントが生成され、Cloud Run 関数はイベントのメッセージをロギングします。
ログエントリを表示するには:
1. ログエントリをフィルタして、JSON 形式で出力を返します。
```
gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
```
2. 次のようなログエントリを探します。
```
[
  {
   ....
    "resource": {
      "labels": {
        ....
        "location": "us-central1",
        .....
        "service_name": "helloworld-events"
      },
    },
    "textPayload": "File: random.txt",
     .....
  }
]
```
  注: ログエントリが表示されない場合は、数分待ってから gcloud logging read コマンドを再試行してください。トリガーが作成されてからイベントのフィルタリングを開始するまでに、2 分ほどかかることがあります。
  ログが表示されるまで少し時間がかかることがあります。すぐに表示されない場合は、1 分後に再度確認してください。

ログエントリが表示されたら、テキストファイルが Cloud Storage にアップロードされたときにトリガーされたイベントドリブン関数が正常にデプロイされています。

クリーンアップ

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

プロジェクトを削除する

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

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

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

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

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

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
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.

チュートリアルリソースを削除する

このチュートリアルでデプロイした Cloud Run サービスを削除します。
```
gcloud run services delete SERVICE_NAME
```
SERVICE_NAME は、選択したサービス名です。

Cloud Run サービスは Google Cloud コンソールで削除することもできます。
チュートリアルの設定時に追加した gcloud CLI のデフォルト構成を削除します。

例:

gcloud config unset run/region

または

gcloud config unset project
このチュートリアルで作成した他の Google Cloud リソースを削除します。
- Eventarc トリガーを削除します。
```
gcloud eventarc triggers delete TRIGGER_NAME
```
  TRIGGER_NAME は、実際のトリガー名に置き換えます。

Eventarc を使用して Cloud Storage から関数をトリガーする

目標

費用

始める前に

必要なロールを設定する

デプロイ担当者のアカウントに必要なロール

トリガー ID に必要なロール

Cloud Storage サービス エージェントのオプションのロール

Pub/Sub サービス エージェントのオプションのロール

Cloud Storage バケットを作成する

イベント ドリブン関数を作成する

Node.js

Python

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

Node.js

Python

Eventarc トリガーを作成する

イベントを生成して表示する

クリーンアップ

プロジェクトを削除する

チュートリアル リソースを削除する

次のステップ

Cloud Storage サービスエージェントのオプションのロール

Pub/Sub サービスエージェントのオプションのロール

イベントドリブン関数を作成する

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

チュートリアルリソースを削除する