Firebase Extensions を関数キットに移行する

このガイドでは、非推奨の Firebase Extensions 環境から、独自の Cloud Functions の Firebase（第 2 世代）コードベースにインストールしてデプロイできる関数キットに拡張機能を移行する方法について説明します。

Firebase Extensions は、拡張機能の作成、更新、削除のすべての側面を管理していました。関数キットは、拡張機能の機能を一般的な第 2 世代の Cloud Functions for Firebase としてパッケージ化します。関数キットは標準の Cloud Functions であるため、Firebase プロジェクト内の Firebase CLI を使用して、関数キットの作成、更新、削除、トラブルシューティングを行います。このガイドでは、関数を管理し、アップデートが利用可能になったらすぐに適用できるように準備する方法について説明します。

このガイドでは、移行の各ステップのコマンドとコマンド出力を示す例として、Stream Cloud Firestore to BigQuery 拡張機能（firestore-bigquery-export）を使用します。

移行パスを決定する

Firebase は、すべての Firebase Extensions パブリッシャーに対し、拡張機能の代替として npm で公開される関数キットを作成することを推奨しています。拡張機能で関数キットの置き換えが利用可能かどうかは、次の方法で確認できます。

  • プロジェクトの Firebase コンソールの [拡張機能] ページに移動します。インストールした各拡張機能には、利用可能な関数キットの代替があるかどうかが示されます。

  • ターミナルで Firebase プロジェクト内で firebase ext:list を実行して、インストールされている拡張機能のうち、公式の代替機能があるものを確認します。

    firebase ext:list --project my-project

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
✔  extensions: required API firebaseextensions.googleapis.com is enabled
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

拡張機能の公式の関数キットの代替品が利用可能な場合は、npm で関数キットに移行するセクションを使用して移行できます。

公開されている代替機能が見つからない場合は、すべての拡張機能がオープンソースであるため、拡張機能のコードをフォークして独自の代替機能を作成できます。これを行うには、自分で作成した関数キットに移行するガイドに沿って操作します。

移行パスを選択します。 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 の手順に沿って追加します。

CLI ワークフローを選択する

拡張機能インスタンスから npm で利用可能な関数キットに移行するには、次のいずれかのオプションを選択します。

  • （推奨）ext:migrate CLI コマンドを使用して移行します。このコマンドは、置き換える拡張機能をアンインストールする前に、関数キットの置き換えをデプロイします。
  • 関数キットの CLI コマンドを使用して移行します。個別のコマンドを使用して、拡張機能の更新、関数キットのインストール、拡張機能と同様の構成、キットのデプロイ、拡張機能のアンインストールを行うことができます。これにより、コマンドの順序を変更したり、ステップ間で追加の作業を行ったりする際の柔軟性が高まります。

ext:migrate を使用して移行する

拡張機能インスタンスごとに 1 回、次のコマンドを実行して移行を開始します。

firebase ext:migrate --project <project-id>

このコマンドは、次の手順をガイドします。

  1. 公式の関数キットの代替機能が利用可能な移行する拡張機能を選択する。
  2. その拡張機能の特定のインスタンスを選択する。
  3. 必要に応じて、拡張機能を最新バージョンに更新します。
  4. 関数キットをインストールし、拡張機能インスタンスの構成方法と同じ方法でインスタンスを構成します。
  5. 機能キットをデプロイします。
  6. 関数キットが正常にデプロイされ、ライフサイクル フック（存在する場合）がすべて実行されたことを確認します。
  7. 拡張機能インスタンスをアンインストールしています。

移行する特定の拡張機能または拡張機能インスタンスがわかっている場合は、次のコマンドライン フラグを使用して指定します。

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

移行先の特定のパッケージがわかっている場合は、特に Google がリストした公式の代替パッケージでない場合は、--package フラグを使用して指定します。

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

関数キットのデプロイを確認する

キットの 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>

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

関数キットの README を確認する

一部のキットでは、関数キットで自動的に処理される範囲を超えた追加の作業が必要になる場合があります。インストールするキットの README を確認し、追加の手順に沿って操作します。

関数キット CLI を使用して移行する

始める前に、キットに移行する拡張機能のインスタンス ID と、その代替キットの npm パッケージ名を特定して書き留めてください。これらは両方とも firebase ext:list の出力で確認できます。ext:list の使用例については、移行パスを決定するをご覧ください。

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

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

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

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

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

2. 交換用機能キット インスタンスを確認してインストールする

関数キットは、次の CLI コマンドを使用してインストールできます。

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

インストール時にキットのインスタンス ID を選択したら、移行手順で後で使用できるように必ず書き留めてください。

キットがインストールされると、Firebase プロジェクト内に function-kits/<kit-name>/source のような新しいディレクトリが作成されます。このディレクトリには、拡張機能を置き換えるキットを含む npm パッケージと、Firebase がデプロイしてカスタム構成を設定するためにこれらの関数をエクスポートする基本的な index.ts ファイルが含まれています。

キットの README を確認し、そこに記載されている追加の手順に沿って操作します。

同じプロジェクトにキットのインスタンスが複数ある場合は、このコマンドを繰り返して同じキットの新しいインスタンスを作成できます。また、単一のキット インスタンスを、構成が異なる 2 つの異なる Firebase プロジェクト（ステージング プロジェクトと本番環境プロジェクトなど）にデプロイすることもできます。これらの高度な設定の詳細については、高度な移行をご覧ください。

実施例:

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

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

このキット インスタンスは、置き換える拡張機能と同じ構成でカスタマイズする必要があります。拡張機能インスタンスの構成を .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>

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

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

キットで、移行元の拡張機能インスタンスに存在しなかった新しいパラメータを使用している場合、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>

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

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

デプロイされた関数キットを確認したら、拡張機能をアンインストールして、キットと拡張機能で動作が重複しないようにします。--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 つ目のインスタンスをインストールするかを選択するよう求められます。