このページは Cloud Translation API によって翻訳されました。

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

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

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

必要なロールを設定する

ご自身または管理者が、デプロイ担当者アカウント、トリガー 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 にアップロードされたときにトリガーされたイベントドリブン関数が正常にデプロイされています。

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

必要なロールを設定する

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

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

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

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

Cloud Storage バケットを作成する

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

Node.js

Python

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

Node.js

Python

Eventarc トリガーを作成する

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

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

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

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

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