Firebase Extensions を自分で作成した関数キットに移行する

移行パスを選択します。 npm の関数キットに移行する 自分で作成した関数キットに移行する

パブリッシャーが npm で配布される公式の代替キットを作成していない場合は、このガイドに沿って拡張機能をフォークし、ローカル関数キットとして設定してください。

既知の移行の制限事項を確認する

拡張機能インスタンスの移行を開始する前に、回避策が必要な機能や、関数キットでまだサポートされていない機能が設定で使用されているかどうかを確認します。

  • カスタム Docker リポジトリと KMS 鍵には手動の回避策が必要 Cloud Functions for Firebase は、カスタム Docker リポジトリまたは顧客管理の暗号鍵（KMS 鍵）を構成するための置換システム パラメータをサポートしていません。拡張機能でこれらのパラメータのいずれかを構成する場合は、FAQ の回避策を参照してください。

始める前に

Firebase CLI を設定し、Firebase プロジェクトを初期化する必要があります。CLI を使用する場合は、新しい移行コマンドと関数キット コマンドを含む firebase-tools バージョン >= 15.32.0 を使用していることを確認してください。

必要なアカウントの権限とロール

移行中に Firebase CLI で作成および構成する必要がある内容に応じて、Firebase と Google Cloud で認証するために使用するアカウントには、次のロールが必要です。

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin（パブリック エンドポイントで setIamPermissions を行う必要がある場合）
  • roles/secretmanager.admin（シークレットを使用している場合）
  • roles/serviceusage.serviceUsageAdmin（新しい API を有効にする必要がある場合）

これらの権限のほとんどはすでに付与されているため、拡張機能をインストールして関数をデプロイしたことがあるアカウントを使用することをおすすめします。移行するアカウントにさらにロールが必要な場合は、Google Cloud IAM の手順に沿って追加します。

拡張機能インスタンスを最新バージョンにアップグレードする

拡張機能インスタンスと交換キットの差を最小限に抑えるには、拡張機能を最新バージョンに更新する必要があります。拡張機能をアップグレードしないと、拡張機能インスタンスとそのキットの置き換えの間に、互換性を損なう大きな変更が生じる可能性があります。バージョン間でパラメータが変更されているため、エクスポートされた構成がキットで想定されているものと一致しない場合があります。

拡張機能のインストール場所に応じて、次のいずれかのオプションを使用して拡張機能を更新します。

  • Firebase コンソールから
  • Firebase CLI から次のコマンドを使用します。
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

この手順をスキップすると、拡張機能が最新バージョンでない場合に、構成をエクスポートするときに CLI からアップグレードを求めるメッセージが表示されます。

拡張機能をローカル関数キットにフォークする

拡張機能をローカル関数キットに変換する前に、拡張機能のソースコードが Firebase プロジェクト内にあることを確認してください。これを行うには、GitHub から拡張機能リポジトリのクローンを作成し、Firebase プロジェクト ルート内にディレクトリを作成して、拡張機能の functions/ フォルダと extension.yaml をそのディレクトリにコピーします。

mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.

パブリッシャーの移行ガイドの手順 1 ～ 8 に沿って、拡張機能のソースコードを第 2 世代の関数に移行します。その後、次の手順に進みます。

ローカルキットでエクスポートされた関数リージョンと高度なパラメータをサポートする

ローカル関数キットでは、Firebase CLI は、パッケージを設定し、移行されたシステム パラメータを使用するように構成するための index.ts ファイルを生成しません。拡張機能用に構成された関数リージョンと詳細パラメータを使用するには、firebase ext:export --mode functions によってエクスポートされた形式を環境変数ファイルに読み取るように index.ts ファイルを設定します。

具体的には、関数をエクスポートするトップレベルの index.ts ファイルで、FUNCTION_DEFAULT_REGION のパラメータを定義し、CLI で使用される index-kit-migration.ts テンプレートと同様に、EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION> 形式の環境変数を使用して setGlobalOptions を呼び出します。

import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";

export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
  input: { text: { nonEmpty: true } },
  description: "Global default region where functions should be deployed. Can be overridden per-function.",
});

setGlobalOptions({
  region: regionParam,
  memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
  timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
    ? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
    : undefined,
  vpcConnectorEgressSettings:
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
      ? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
      : undefined,
  vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
  maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
    : undefined,
  minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
    : undefined,
  ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
  // Parses a comma-separated string of key:value pairs into a key-value object
  // (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
  labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
    ? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
        (acc, curr) => {
          const [key, value] = curr.split(":");
          const trimmedKey = key?.trim();
          const trimmedValue = value?.trim();
          if (!trimmedKey || !trimmedValue) {
            return acc;
          }
          acc = acc ?? {};
          acc[trimmedKey] = trimmedValue;
          return acc;
        },
        undefined,
      )
    : undefined,
});

// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";

移行前にキットをテストする

これで、デプロイ時に拡張機能の新規インストールと同じ動作をするローカル関数キットが作成されました。次のステップでは、本番環境の拡張機能インスタンスを移行する前に、誤って導入された問題を検証して修正します。

まず、フォークをローカルキットとして追加し、構成して、テスト プロジェクトにデプロイします。ローカル関数キットは Firebase プロジェクト内に存在する必要があります。クローン作成された拡張機能リポジトリが Firebase プロジェクトの外部にある場合は、プロジェクト ディレクトリ内に移動します。次のキット インストール コマンドを実行して、ローカル キットとしてインストールします。

firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>

このコマンドは、最初のテスト インスタンスのキット ID、インスタンス ID、構成を選択する手順を説明します。次に、firebase.json ファイルを変更して、フォークされたディレクトリを指すローカルキットを登録します。各インスタンスの構成は function-kits/<kit-id>/config-<instance-id> の .env ファイルに保存されます。

ローカルキットを適切なリソースを含むテスト プロジェクトにデプロイして、その動作をテストします。拡張機能をテストするためにテスト プロジェクトをすでに設定している場合は、次のコマンドを実行します。

firebase deploy --only functions:<kit-instance-id> --project <test-project-id>

例: Cloud Firestore を BigQuery にストリーミングする（firestore-bigquery-export）

Cloud Firestore から BigQuery への同期がエンドツーエンドで機能していることを確認します。

  1. Firebase コンソールの Cloud Firestore ページで、COLLECTION_PATH（users）として設定したコレクションを作成します（まだ存在しない場合）。
  2. 任意のフィールドと値を含む bigquery-mirror-test という名前のドキュメントを作成します。

  3. Google Cloud コンソールの BigQuery ページで、未加工の変更ログ テーブルをクエリします。ドキュメントの作成を記録する単一行が含まれている必要があります。

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. 最新のビューをクエリします。これにより、存在する唯一のドキュメント（bigquery-mirror-test）の最新の変更イベントが返されます。

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Cloud Firestore の bigquery-mirror-test ドキュメントを削除します。最新のビューから消え、DELETE イベントが未加工の変更ログ テーブルに追加されます。

    単一のドキュメントの履歴全体を調べるには、次のコマンドを使用します。

    SELECT *
   FROM `PROJECT_ID.analytics.users_raw_changelog`
   WHERE document_name = "bigquery-mirror-test"
   ORDER BY timestamp ASC

拡張機能のテストとの違い:

  • トリガーは ext-<instanceId>-fsexportbigquery ではなく kit-<kit-instance-id>-fsexportbigquery としてデプロイされます。Cloud Functions ダッシュボードとログでその名前を探します。
  • コードは Firebase Local Emulator Suite で標準関数として実行されます。.env.local を使用して、エミュレータで使用するパラメータ値を設定できます。Cloud Functions の単体テストで説明されているように、firebase-functions-test SDK を使用してコードの単体テストを行うこともできます。
  • プロビジョニングは Extensions ランタイムによって行われなくなりました。デプロイ後に変更ログ テーブルが見つからない場合は、設定タスク firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id> を手動で再実行します。このタスクはべき等であるため、再実行するとデータセット、テーブル、ビューが調整されます。
  • パラメータ値はインストール フォームではなく .env から取得されるため、.env が完了すると firebase deploy の再実行はインタラクティブではなくなります。

（省略可）テスト後のクリーンアップ

テスト後にこのテスト インスタンスを削除する場合は、アンインストールします。

firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>

これにより、キットのデプロイによって作成されたすべてのクラウド リソースが削除され、インスタンス構成が削除されます。キットのインスタンスが 1 つしかない場合は、firebase.json からキットのエントリも削除されます。ローカルのソースコード ディレクトリは削除されません。本番環境移行用のキットをインストールするときに、キット ID を再度選択できます。

拡張機能からローカルキットに移行する

ローカルキットのテストが完了したら、本番環境にデプロイされた拡張機能インスタンスを移行できます。

1. 交換用機能キット インスタンスをインストールする

--no-configure を渡してローカル関数キットをインストールし、手動構成をスキップします。これにより、次のステップで既存の拡張機能構成をこのキット インスタンスに直接エクスポートできます。

firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>

2. 関数キット インスタンスを拡張機能と同じように構成する

このキット インスタンスは、置き換える拡張機能と同じ構成でカスタマイズする必要があります。拡張機能インスタンスの構成を .env ファイルにエクスポートできます。このファイルには、キットを含むすべての Cloud Functions のパラメータ、環境変数、シークレット参照の構成データが保存されます。キットの構成ファイルに直接エクスポートするには、次のコマンドを実行します。

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

この手順の最後に、このインスタンスの構成情報が、インスタンス構成ディレクトリ内のプロジェクト固有の .env ファイルに保存されます。例: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

3. キットの交換をデプロイして確認する

キットがインストールされ、一連の関数として使用できるようになったので、キットの交換をデプロイできます。関数キットは標準関数と同様に機能します。各キット インスタンスは、関数を整理するための個別のコードベースとして機能します。すべての関数をデプロイすることも、特定のキット インスタンスのみをデプロイすることもできます。単一の拡張機能インスタンスを移行する場合は、そのキット インスタンスのみをデプロイします。

キットで、移行元の拡張機能インスタンスに存在しなかった新しいパラメータを使用している場合、Firebase CLI はデプロイ プロセスの開始時にこれらのパラメータの入力を求めます。最新の firestore-bigquery-export 拡張機能のこの例では想定されていませんが、多くのキットでは、キットで使用されるイベント トリガー ソースの新しいパラメータが求められます。この移行の一環として、更新されたキットでは、以前に拡張機能で第 1 世代の関数が使用されていた箇所で第 2 世代の関数が使用されます。第 2 世代では、関数はイベントソースの近くに配置され、追加のパラメータとして追加されます。今後のアップデートで新しいパラメータが追加された場合、次のデプロイ時に CLI からプロンプトが表示されます。

実施例:

firebase deploy --only functions:firestore-bigquery-export --project my-project

出力:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

キットの firebase deploy にエラーがないことを確認するには、デプロイログを調べて、ライフサイクル フックがトリガーされたかどうかを確認します。Stream Cloud Firestore to BigQuery などの一般的な拡張機能は、ライフサイクル フックを使用します。ライフサイクル フックがトリガーされたときの例を次に示します。

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

これらのログメッセージは、次のことを確認します。

  • ライフサイクル フックが見つかり、実行されました。
  • タスクがライフサイクル フックに関連付けられたタスクキューにキューに追加されました。
  • Cloud Logging へのリンクが提供されているため、エラーなくタスクが完了したことを確認できます。

ログのリンクをたどって Google Cloud コンソールに移動し、ログにエラーがなく、タスクキュー イベントが正常に処理されたことを確認します。ライフサイクル イベントが正常に実行されなかった場合は、次のコマンドを実行して再トリガーできます。

firebase functions:lifecycle:run <hook-name> <codebase>

関数キット インスタンスを初めてデプロイする場合は、次のコマンドを実行します。

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

検証中に移行を停止または元に戻す場合は、拡張機能をアンインストールするの手順に沿ってキットをアンインストールできます。

4. 拡張機能をアンインストールする

デプロイされた関数キットを確認したら、拡張機能をアンインストールして、キットと拡張機能で動作が重複しないようにします。--immediate フラグを渡すと、インストール方法に関係なく、Firebase CLI からすべての拡張機能をアンインストールできます。

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

実施例:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

出力:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

高度な移行

単一のコードベースで管理する複数の Firebase プロジェクトに拡張機能を含めることができます。たとえば、同じインフラストラクチャを testing 環境と production 環境にデプロイし、それぞれに BigQuery にエクスポートする documents Cloud Firestore インスタンスがある場合、firestore-bigquery-export 拡張機能のインスタンスが 2 つインストールされている可能性があります。

  • export-documents-testing
  • export-documents-production

Firebase CLI を使用して、これらの 2 つの拡張機能インスタンスを単一のコードベース内の 2 つの関数キット インスタンスに移行し、firebase deploy --project testing と firebase deploy --project production を使用してデプロイした場合、デプロイごとに testing 環境と production 環境の両方に 2 つのインスタンスが作成されます。

代わりに、2 つの拡張機能インスタンスを、複数のプロジェクトにデプロイされた firestore-bigquery-export の 1 つの関数キット インスタンスに置き換えます。各プロジェクトには独自の構成があります。インスタンスの構成ディレクトリは次のようになります。

  • config-export-documents/
    • .env.testing
    • .env.production

testing と production へのデプロイごとに、対応する構成でキットのインスタンスが 1 つ作成されます。既存の CLI コマンドは、ext:migrate または functions:kits:install の各呼び出しで --project フラグを渡す限り、この設定を作成します。

実施例:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

これで、それぞれの構成で testing プロジェクトと production プロジェクトにデプロイするように構成された単一のキット インスタンスが作成されました。testing プロジェクトにインスタンスを作成し、production プロジェクトの同じパッケージに対して functions:kits:install コマンドを実行すると、testing 用に構成されたインスタンスを再利用するか、2 つ目のインスタンスをインストールするかを選択するよう求められます。