概要

Cloud Run functions は、Google Cloud データベース（Firestore、Cloud Spanner、Cloud SQL、Cloud Bigtable）や、Google Cloud のインメモリ データストア キャッシュ サービスである Memorystore と統合することで、アプリケーションやサービスを拡張できます。

このラボでは、Google Cloud のサーバーレス NoSQL ドキュメント データベースである Firestore と統合する Cloud Run functions の関数を作成します。Cloud Run functions フレームワークと、Node.js 用の Firestore クライアント ライブラリを使用して関数を作成し、データベースでイベントが発生したときに関数を実行するトリガーを設定します。

Firestore 関数のライフサイクルは通常、次のステップで構成されます。

• Firestore データベース内の特定のドキュメントが変更されるのを待つ。
• イベントが発生したときにトリガーする。
• 対象ドキュメントのスナップショットとともに受け取ったデータ オブジェクトを使用してタスクを実行する。

目標

このラボでは、次の作業を行います。

• Firestore データベースを設定する。
• Firestore でドキュメントが作成されたときに、ログに情報を記録するイベント ドリブン関数を開発してデプロイする。
• ドキュメントの内容を更新するイベント ドリブン関数を開発してデプロイする。
• Cloud Run functions の関数でシークレットにアクセスして使用する。
• Google Cloud コンソールを使用して、作成した関数によって生成されたログを確認する。

設定

[ラボを開始] ボタンをクリックする前に

注: 以下の説明をお読みください。

ラボには時間制限があり、一時停止することはできません。[ラボを開始] をクリックするとスタートするタイマーは、Google Cloud のリソースを利用できる時間を示しています。

この Google Skills ハンズオンラボでは、シミュレーションやデモ環境ではなく、実際のクラウド環境を使ってご自身でラボのアクティビティを実施できます。そのため、ラボの受講中に Google Cloud にログインおよびアクセスするための、新しい一時的な認証情報が提供されます。

必要なもの

このラボを完了するためには、下記が必要です。

• 標準的なインターネット ブラウザ（Chrome を推奨）
• ラボを完了するために十分な時間

注: すでに個人の Google Cloud アカウントやプロジェクトをお持ちの場合でも、ラボでは使用しないでください。 注: Pixelbook を使用している場合は、このラボをシークレット ウィンドウで実施してください。

Google Cloud Shell の有効化

Google Cloud Shell は、開発ツールと一緒に読み込まれる仮想マシンです。5 GB の永続ホーム ディレクトリが用意されており、Google Cloud で稼働します。

Google Cloud Shell を使用すると、コマンドラインで Google Cloud リソースにアクセスできます。

1. Google Cloud コンソールで、右上のツールバーにある [Cloud Shell をアクティブにする] ボタンをクリックします。

   

2. [続行] をクリックします。

環境がプロビジョニングされ、接続されるまでしばらく待ちます。接続した時点で認証が完了しており、プロジェクトに各自のプロジェクト ID が設定されます。次に例を示します。

gcloud は Google Cloud のコマンドライン ツールです。このツールは、Cloud Shell にプリインストールされており、タブ補完がサポートされています。

• 次のコマンドを使用すると、有効なアカウント名を一覧表示できます。

gcloud auth list

出力:

Credentialed accounts: - @.com (active)

出力例:

Credentialed accounts: - google1623327_student@qwiklabs.net

• 次のコマンドを使用すると、プロジェクト ID を一覧表示できます。

gcloud config list project

出力:

[core] project =

出力例:

[core] project = qwiklabs-gcp-44776a13dea667a6 注: gcloud ドキュメントの全文については、 gcloud CLI の概要ガイド をご覧ください。

タスク 1. 環境を設定する

このタスクでは、環境変数を設定し、このラボの実行に必要となる関連サービス API を有効にします。

環境変数を設定する

Cloud Run functions の関数を作成する前に、いくつかの環境変数を設定します。

1. ラボの認証情報を使用して Google Cloud コンソールにログインし、Cloud Shell ターミナル ウィンドウを開きます。

2. Cloud Shell で次のコマンドを実行して、プロジェクト ID とリージョンの環境変数を設定します。

   PROJECT_ID=$(gcloud config get-value project) REGION={{{project_0.default_region|set at lab start}}}

3. プロジェクト番号の環境変数を設定します。

   PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" \ --format="value(projectNumber)")

4. Cloud Run functions のデフォルト リージョンを設定します。

   gcloud config set functions/region {{{project_0.default_region|set at lab start}}}

API を有効にする

1. このラボで必要となるサービス API を有効にするには、次のコマンドを実行します。

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

タスク 2. Firestore を設定する

このラボのタスクを実行するには、Firestore データベースを設定する必要があります。Firestore では、ドキュメントとコレクションの形式でデータが保存されます。Cloud Run functions の関数を Firestore とともに使用するには、関数をデプロイする前に Firestore を設定する必要があります。

1. Google Cloud コンソールで、上部のナビゲーションにある検索バーをクリックし、「Firestore」と入力します。検索結果から [Firestore] を選択します。

2. [Firestore データベースを作成] をクリックします。

3. [Standard Edition] を選択します。

4. [構成オプション] で [ネイティブ モードの Firestore] を選択します。

5. [セキュリティ ルール] では [開く] を選択します。

6. [ロケーション タイプ] で [リージョン] をクリックし、リストから「set at lab start」リージョンを選択します。

   注: リージョンのリストが表示されない場合は、ブラウザを更新するか、Cloud コンソールのメニューからウィザードを再度実行してください。

7. その他の設定はデフォルトのままにして、[データベースを作成] をクリックします。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 Firestore を設定する。

タスク 3. 新しい Firestore ドキュメントのイベント ドリブン関数を開発する

Firestore データベースを作成したら、関数コードを開発できます。このタスクでは、データベースに新しいドキュメントが作成されたときに実行する関数のソースコードを記述します。この関数は、関数呼び出しで受け取ったデータに関する情報をログに記録するものです。

作業ディレクトリを設定する

Firestore の関数は、cloudevents データ構造を使用して呼び出されます。このデータ構造は、protobuf.js NPM モジュールでプロトコル バッファを使用してデコードできます。詳しくは、ラボの最後に記載されているリンクをご覧ください。

1. 必要な .proto ファイルと依存関係ファイルを Cloud Storage からコピーして、アーカイブからコンテンツを抽出するには、次のコマンドを実行します。

   gcloud storage cp gs://cloud-training/CBL493/firestore_functions.zip . && unzip firestore_functions && rm firestore_functions.zip

2. firestore_functions ディレクトリに移動します。

   cd firestore_functions

   firestore_functions ディレクトリには、空の node.js ファイルと package.json ファイルも含まれます。これらのファイルは次のサブタスクで更新します。

関数のコードを記述する

1. Cloud Shell ツールバーで [エディタを開く] をクリックします。

   Cloud Shell とコードエディタを切り替えるには、[エディタを開く] と [ターミナルを開く] を使用します。または、[新しいウィンドウで開く] をクリックして、別のタブでエディタを開いたままにすることもできます。

2. エディタで、firestore-functions/index.js ファイルに次のコードを追加します。

   /** * Cloud Event Function triggered by a change to a Firestore document. */ const functions = require('@google-cloud/functions-framework'); const protobuf = require('protobufjs'); functions.cloudEvent('newCustomer', async cloudEvent => { console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType('google.events.cloud.firestore.v1.DocumentEventData'); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); console.log('\nNew document:'); console.log(JSON.stringify(firestoreReceived.value, null, 2)); const documentData = firestoreReceived.value.fields; console.log('Document data:', documentData); }); このコードでは、関数フレームワークの Node.js ライブラリを使用して、cloudEvent 仕様で配信されるデータを処理する関数を作成しています。

3. エディタで、firestore-functions/package.json ファイルに次のコードを追加します。

   { "name": "firestore_functions", "version": "0.0.1", "main": "index.js", "dependencies": { "@google-cloud/functions-framework": "^3.1.3", "protobufjs": "^7.2.2", "@google-cloud/firestore": "^6.0.0" } }

サービス アカウントの権限を更新する

関数をデプロイする前に、Cloud Run functions のサービス エージェントに特定の権限を付与します。Cloud Shell で次のコマンドを実行します。

1. [ターミナルを開く] をクリックします。

2. Cloud Run functions サービス エージェントのサービス アカウントの環境変数を設定します。

   SERVICE_ACCOUNT=service-$PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com

3. Artifact Registry のアーティファクトを表示して取得するには、Cloud Run functions サービス アカウントに artifactregistry.reader ロールを付与します。

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader 注: 前のステップで、サービス アカウントが存在しない、またはリクエストの認証情報が無効というエラーが表示された場合は、次の手順を実行します。

4. Cloud Functions API を無効にします。

   gcloud services disable cloudfunctions.googleapis.com

5. Cloud Functions API を再度有効にします。

   gcloud services enable cloudfunctions.googleapis.com

6. 数秒待ってから、Cloud Run functions サービス アカウントに artifactregistry.reader ロールを付与するコマンドを再実行します。

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader

関数をデプロイする

• 関数をデプロイするには、Cloud Shell で次のコマンドを実行します。

  gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' Firestore は created、updated、deleted、written の各イベントをサポートしています。これらを deploy コマンドの trigger-event-filter オプションとして指定します。パスパターンは、customers コレクション内のすべてのドキュメントをモニタリングするよう指定しています。

  コマンドが正常に実行されると、関数エンドポイントの URL が生成されます。コマンド出力例の一部を以下に示します。

  ... state: ACTIVE updateTime: '2024-03-19T21:38:04.917134057Z' url: https://{{{project_0.default_region|set at lab start}}}-{{{project_0.default_region}}}.cloudfunctions.net/newCustomer 関数のデプロイ中にエラーが発生した場合は、数分待ってから deploy コマンドを再試行してください。Eventarc のサービス アカウント権限は、反映されるまでに時間がかかる場合があります。

関数をテストする

1. Cloud コンソールで Firestore Studio に移動します。

2. 新しいドキュメント コレクションを作成するには、[コレクションを開始] をクリックします。

3. [コレクション ID] に「customers」と入力します。

4. このコレクションのドキュメントに ID を生成するには、[ドキュメント ID] をクリックします。

5. このドキュメントに、次のフィールドと値を追加します。

   フィールド名	フィールド タイプ	フィールド値
   firstname	string	Lucas

6. [保存] をクリックします。

7. Cloud Run functions の関数が呼び出されたことを確認するには、ナビゲーション メニュー（）で [Cloud Run] をクリックします。

8. 関数名「newCustomer」をクリックします。

9. [ログ] をクリックします。

10. 関数コードから生成されたログエントリが存在し、作成したデータベース ドキュメントのデータが表示されることを確認します。

    最新のログエントリを表示するには、必要に応じて [更新] をクリックします。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 新しい Firestore ドキュメントのイベント ドリブン関数を開発する。

タスク 4. ドキュメントを更新する Firestore のイベント ドリブン関数を開発する

このタスクでは、Firestore データベースでドキュメントが更新されたときにトリガーされる関数を開発します。この関数は、新しいフィールドをドキュメントに追加するものです。フィールドの値は、他のドキュメントのフィールドの値から取得します。

関数のコードを記述する

1. エディタで、firestore-functions/index.js ファイルに次のコードを追加します。

   const Firestore = require('@google-cloud/firestore'); const firestore = new Firestore({ projectId: process.env.GOOGLE_CLOUD_PROJECT, }); functions.cloudEvent('updateCustomer', async cloudEvent => { console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType( 'google.events.cloud.firestore.v1.DocumentEventData' ); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); const resource = firestoreReceived.value.name; const affectedDoc = firestore.doc(resource.split('/documents/')[1]); // Fullname already exists, so don't update again to avoid infinite loop. if (firestoreReceived.value.fields.hasOwnProperty('fullname')) { console.log('Fullname is already present in document.'); return; } if (firestoreReceived.value.fields.hasOwnProperty('lastname')) { const lname = firestoreReceived.value.fields.lastname.stringValue; const fname = firestoreReceived.value.fields.firstname.stringValue; const fullname = `${fname} ${lname}` console.log(`Adding fullname --> ${fullname}`); await affectedDoc.update({ fullname: fullname }); } }); 同じプロジェクトの main ファイルで、独自のエントリ ポイントを持つ複数の関数を定義し、それらを個別に Cloud Run functions にデプロイできます。

   このアプローチでは、すべての関数が同じ依存関係を共有しますが、一部の関数は依存関係を必要としない場合もあります。

   特定の関数に必要な依存関係の数を最小限に抑え、必要なメモリ量を減らすには、各関数のソースコードを専用の最上位ディレクトリに、専用のプロジェクト構成ファイルとともに保持することをおすすめします。

関数をデプロイする

1. 新しい関数をデプロイするには、Cloud Shell で次のコマンドを実行します。

   gcloud functions deploy updateCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=updateCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.updated \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}'

2. コマンド出力で、関数がデプロイされ、状態が Active であることを確認します。

関数をテストする

1. Cloud コンソールの Firestore Studio で、customers コレクション内の既存ドキュメントのうち、firstname フィールドの値が Lucas であるものを選択します。

2. このドキュメントで [フィールドを追加] をクリックします。

3. 次のフィールドと値を追加します。

   フィールド名	フィールド タイプ	フィールド値
   lastname	string	Sherman

4. [保存] をクリックします。

5. 数秒待ってから、ドキュメントに新しいフィールド fullname が追加されたことを確認します。

   これは、ドキュメントが更新されたときに関数 updateCustomer が呼び出されたことを示しています。

6. Cloud Run functions の関数が呼び出されたことを確認するには、ナビゲーション メニュー（）で [Cloud Run] をクリックします。

7. 関数名「updateCustomer」をクリックします。

8. [ログ] をクリックします。

9. 関数コードから生成されたログエントリが存在し、fullname フィールドがドキュメントに追加されたことを示していることを確認します。

   最新のログエントリを表示するには、必要に応じて [更新] をクリックします。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 ドキュメントを更新する Firestore のイベント ドリブン関数を開発する。

タスク 5. Cloud Run functions の関数でシークレットを使用する

Secret Manager は、API キー、パスワード、証明書、認証情報、その他の機密情報などのデータを安全に保存する Google Cloud サービスです。これらのシークレットは、Cloud Run functions の関数やその他のサービスからアクセスして、関数のロジックやサービスの実装に使用できます。

このタスクでは、Secret Manager で認証情報をシークレットとして作成して保存します。そして関数を開発し、関数のロジックでキーにアクセスします。

シークレットを作成する

1. シークレットを作成して使用するには、Cloud Shell で次のコマンドを実行して、Secret Manager API を有効にします。

   gcloud services enable secretmanager.googleapis.com

2. Secret Manager で、名前が api-cred で値が secret_api_key のシークレットを作成して保存します。

   echo -n "secret_api_key" | gcloud secrets create api-cred --replication-policy="automatic" --data-file=- replication-policy は、シークレットとそのバージョンを保存するリージョンを指定するために使用します。シークレットを複製できる 1 つまたは複数のリージョンを指定するには、replication-policy を user-managed に設定します。

アクセスを許可する

シークレットにアクセスするには、関数のランタイム サービス アカウントにシークレットへのアクセス権を付与する必要があります。

• デフォルトでは、Cloud Run functions は Compute Engine のデフォルト サービス アカウントを関数のランタイム サービス アカウントとして使用します。

  Secret Manager で認証するには、Compute Engine のデフォルト サービス アカウントに Secret Manager Secret Accessor ロールを付与します。

  gcloud secrets add-iam-policy-binding api-cred --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com --project=$PROJECT_ID --role='roles/secretmanager.secretAccessor' 注: 本番環境で使用する場合は、専用のユーザー管理サービス アカウントで認証を行うよう関数を構成し、このアカウントに関数のタスクの実行に必要な最小権限セットのロールを割り当てる必要があります。

関数からシークレットにアクセスする

このサブタスクでは、前に開発した newCustomer 関数を変更して、シークレットにアクセスできるようにします。

• エディタで、index.js ファイルの newCustomer 関数に次のコードを追加します。コードは、関数本体の最後にある console.log ステートメントの後の関数の末尾に追加します。

  // BEGIN access a secret const fs = require('fs/promises'); try { const secret = await fs.readFile('/etc/secrets/api_cred/latest', { encoding: 'utf8' }); // use the secret. For lab testing purposes, we log the secret. console.log('secret: ', secret); } catch (err) { console.log(err); } // End access a secret この関数コードは、関数がアクセスできるボリュームにマウントされたファイルからシークレットの値を読み取ります。このシークレットへのアクセス方法は、次のステップで関数をデプロイするときに構成します。

関数を再デプロイする

1. Cloud Shell で、シークレットを使用する newCustomer 関数を再デプロイします。

   gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' \ --set-secrets '/etc/secrets/api_cred/latest=api-cred:latest' deploy コマンドの set-secrets オプションは、マウントのパス /etc/secrets/api_cred とシークレットのパス /latest を指定しています。

   シークレットをボリュームとして参照することで、ファイルがディスクから読み取られるたびに、関数が Secret Manager の最新のシークレット値にアクセスすることになります。

   関数では、シークレットの特定のバージョンの値に環境変数としてアクセスすることもできます。詳細については、Cloud Run functions 関数でのシークレットの使用に関するドキュメントをご覧ください。

2. 関数をデプロイしたら、関数がシークレットにアクセスできることを確認します。

   gcloud functions describe newCustomer

   describe コマンドの出力には、シークレットに関する情報が含まれます。コマンド出力の一部を次に示します。

   ... secretVolumes: - mountPath: /etc/secrets/api_cred projectId: '{{{project_0.project_id|Project_ID}}}' secret: api-cred versions: - path: /latest version: latest ...

関数をテストする

1. 関数をテストするには、前のタスクのテストと同じように、Cloud コンソールの Firestore Studio から新規顧客ドキュメントを追加します。

2. Cloud コンソールで関数のログを表示するには、ナビゲーション メニュー（）で [Cloud Run] をクリックします。

3. 関数名「newCustomer」をクリックします。

4. 関数のログを表示するには、[ログ] をクリックします。

   シークレット キーの値をログに記録するエントリが存在することを確認します。

   secret: secret_api_key 注: シークレットの値をログに記録することは一般的ではありませんが、このステップは、関数がシークレットの値にアクセスし、コード内でシークレットを使用できることを確認するために使用しています。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 Cloud Run functions の関数でシークレットを使用する。

お疲れさまでした

このラボでは、Firestore データベースを設定し、データベースに新しいドキュメントが作成されたときにトリガーされる Cloud Run functions のイベント ドリブン関数を開発しました。また、ドキュメントが更新されたときに、そのドキュメントに新しいフィールドを追加する関数も開発しました。 さらに、シークレットを作成して Cloud Run functions の関数からアクセスし、ログを使用してシークレットの値を確認しました。

次のステップと詳細情報

Firestore 用の Cloud Run functions 関数やその他のトピックの詳細については、以下のドキュメントをご覧ください。

• Firestore トリガー
• プロトコル バッファ
• Cloud Functions for Firebase

Copyright 2026 Google LLC All rights reserved. Google および Google のロゴは、Google LLC の商標です。その他すべての社名および製品名は、それぞれ該当する企業の商標である可能性があります。