Firebase Extensions を Cloud Functions に移行する

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

これはおすすめの移行パスです。Firebase は、公式の npm に相当する拡張機能のリストを保持します。このガイドでは、独自の拡張機能を作成する手順について説明します。

このガイドでは、Stream Cloud Firestore to BigQuery 拡張機能(firestore-bigquery-export)を例として使用します。各セクションの最後には、移行前の拡張機能と移行後の拡張機能(@firebase-function-kits/firestore-bigquery-export パッケージ)を示す実例が記載されています。

登録して、拡張機能の移行に関する詳細情報とサポートを入手する

Firebase Extensions からの移行方法についてご不明な点がございましたら、firebase-extensions-migrator-support-external@google.com までお問い合わせください。また、第 2 世代の関数のパッケージ化、テスト、配布に関する詳細情報がガイドに追加された際には、このグループにメールでお知らせします。

このグループに参加するには、firebase-extensions-migrator-support-external+subscribe@google.com にメッセージを送信します。このメッセージに対して、メンバーシップ リクエスト メールが返信されます。[このグループに参加] ボタンをクリックするのではなく、そのメールに返信する必要があります。

始める前に

この移行を手順どおりに完了するには、Cloud Functions の次の機能を使用します。

  • パラメータ化された構成。extension.yaml で宣言した各パラメータは、パッケージ コードで定義されたパラメータになります。

  • 宣言型 IAM ロールと必要な API。extension.yaml で宣言した各ロールは requiresRole(...) 呼び出しになり、各 API はパッケージ コード内の requiresAPI(...) 呼び出しになります。デプロイ時に、Firebase CLI は宣言されたロールをマネージド ランタイム サービス アカウントに付与し、宣言された API を有効にします。

  • Cloud Functions コードベースのライフサイクル イベント。Cloud Functions コードベースで、Firebase Extensions と同様のライフサイクル イベントがサポートされるようになりました。ライフサイクル フック afterFirstDeploy(...) と afterRedeploy(...) を使用して、インストール時と更新時の設定を宣言します。これらは、extension.yaml で宣言する lifecycleEvents に代わるものです。

Firebase Extensions ソースを第 2 世代の関数に移行する

(省略可)Firebase エージェント スキルを使用した自動移行

ステップ 1 ~ 8(リソースのインベントリ作成、トリガーのアップグレード、パラメータとシークレットの変換、宣言型 IAM、ライフサイクル フック、パッケージ README の生成)は、公式の extension-to-functions-codebase AI エージェント スキルを使用して自動化できます。

スキルをインストールする

ユーザーまたは AI コーディング アシスタント(Firebase の Gemini、Cursor、Claude Code、GitHub Copilot)がスキルをまだインストールしていない場合は、スキル CLI を使用して次のコマンドを実行します。

npx skills add firebase/agent-skills --skill extension-to-functions-codebase

スキルがプロジェクトにインストールされると、AI コーディング アシスタントは移行ルールと変換手順を自動的に実行します。次のプロンプトを使用できます。

「この Firebase Extensions を、extension-to-functions-codebase スキルの手順に沿って、公開可能な第 2 世代 Functions Kit パッケージに移行してください。」

1. 拡張機能のインベントリを作成する

まず、拡張機能のインベントリを作成します。これは、拡張機能が宣言、提供、文書化するすべてのものの完全なリストです。これにより、すべての動作に第 2 世代の関数で定義された宛先があり、移行中に失われるものがないことを確認できます。

次の各項目を確認し、気づいた点をメモします。

  • extension.yaml。パラメータ、関数、イベント、IAM ロール、必要な API、シークレット、ライフサイクル フックを宣言します。

  • functions/。関数のコード、依存関係、ビルド構成、トリガー、タスクキュー関数が含まれます。

  • README.md、PREINSTALL.md、POSTINSTALL.md。設定手順、警告、請求に関する注意事項が含まれています。

  • scripts/。インポート、バックフィル、IAM、修復、移行のユーティリティ、拡張機能とともに提供するその他のツールが含まれます。

次に、extension.yaml の各アイテムについて、npm パッケージ内の配置場所を決定します。

  • ユーザー構成を Cloud Functions パラメータに変換します(ステップ 4)。

  • シークレットを Cloud Functions シークレットに変換します(ステップ 4)。

  • IAM ロールを requiresRole(...) 宣言に変換します(ステップ 6)。

  • 必要に応じて、必要な Google API を requiresAPI(...) 宣言に変換します(ステップ 6)。

  • インストール フックと更新フックを afterFirstDeploy(...) 宣言と afterRedeploy(...) 宣言に変換します(ステップ 7)。

  • インスタンス ID を EXT_INSTANCE_ID から FIREBASE_KIT_INSTANCE_ID に変換します(ステップ 4)。

実施例: Cloud Firestore を BigQuery にストリーミングする

firestore-bigquery-export/extension.yaml と functions/ を読み取ると、次のインベントリが生成されます。

extension.yaml カウント / 値 データの行き先
params 25(COLLECTION_PATH、DATASET_ID、TABLE_ID、DATASET_LOCATION、VIEW_TYPE、…) Cloud Functions パラメータ(ステップ 4)
apis bigquery.googleapis.com requiresAPI(...)(ステップ 6)
roles bigquery.dataEditor、datastore.user、bigquery.user requiresRole(...)(ステップ 6)
resources 1 つのイベント トリガー(fsexportbigquery)+ タスクキュー関数(initBigQuerySync、setupBigQuerySync) エクスポートされたパッケージ関数(ステップ 3)
lifecycleEvents onInstall → initBigQuerySync、onUpdate / onConfigure → setupBigQuerySync afterFirstDeploy / afterRedeploy(ステップ 7)
インスタンス ID 不使用(EXT_INSTANCE_ID の読み取りなし) 移行するデータがありません
scripts/ import/(バックフィル)、gen-schema-view/ スクリプトとして保持(ここでは対象外)

分析。この拡張機能では type: secret パラメータが宣言されていないため、ステップ 4 でシークレットを移行する必要はありません。イベント トリガーはすでに第 2 世代であり、タスクキュー関数のみが第 1 世代である(ステップ 3 に関連)。

2. package.json を更新する

拡張機能の package.json ファイルを更新します。1 つの拡張機能を移行する場合は、ルート package.json にすることができます。1 つのリポジトリで多数の拡張機能を移行する場合は、拡張機能ごとに独自のパッケージを指定します。

最小 SDK バージョン: firebase-functions >= 7.4.0 と firebase-admin >= 14.2.0 を依存関係として宣言します。firebase-functions のバージョンをピア依存関係として宣言し、ユーザーの Cloud Functions プロジェクトに、ライブラリの作成に使用した SDK と同じバージョンが含まれるようにします。

{
  "name": "<package-name>",
  "version": "1.0.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": "22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.4.0"
  },
  "dependencies": {
    "firebase-functions": "^7.4.0",
    "firebase-admin": "^14.2.0"
  }
}

実施例: Cloud Firestore を BigQuery にストリーミングする

変更前。拡張機能の functions/package.json は非公開で、拡張機能 ID を指定し、firebase-functions を直接依存関係として宣言します。

{
  "name": "firestore-bigquery-export",
  "main": "lib/index.js",
  "private": true,
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^6.3.2"
  }
}

変更後。公開可能なパッケージ: スコープ名、exports マップ、peerDependencies に移動された firebase-functions:

{
  "name": "@firebase-function-kits/firestore-bigquery-export",
  "version": "0.1.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": "22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.4.0"
  },
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^7.4.0"
  }
}

3. 関数を第 1 世代から第 2 世代にアップグレードする

拡張機能がまだ第 1 世代の関数をエクスポートしている場合は、各トリガーを第 2 世代の同等のトリガーに変換します。firebase-functions/... モジュールからインポートし、トリガー オプションでランタイム設定を渡します。

Cloud Functions 第 2 世代のアップグレード ガイドをご覧ください。特に、第 2 世代のパッチ適用済みイベントの構造化解除を使用することで、書き換え作業を最小限に抑えることができます。第 2 世代の SDK は、v1 パラメータをイベント オブジェクトのフィールドとして公開するため、構造化解除されたパラメータや名前付きパラメータを使用でき、ビジネス ロジックを変更する必要がありません。

変更前。第 1 世代:

import * as functions from "firebase-functions/v1";

export const sync = functions.firestore
  .document("{collectionId}/{documentId}")
  .onWrite(async (change, context) => {
    await handleWrite(change.before, change.after, context.params);
  });

変更後。第 2 世代:

import { onDocumentWritten } from "firebase-functions/firestore";

export const syncV2 = onDocumentWritten(
  { document: "{collectionId}/{documentId}" },
  async ({ change, context }) =>
    await handleWrite(change.before, change.after, context.params)
);

第 1 世代と第 2 世代の関数の違いの包括的なリストについては、Cloud Functions のバージョンの比較をご覧ください。

第 1 世代と第 2 世代の関数の大きな違いは、第 2 世代の関数はトリガー リソースと同じ場所に配置する必要があることです。ユーザーが第 1 世代の関数を使用する拡張機能から第 2 世代の関数を使用するキットに移行する場合、この要件を満たすために関数のロケーションを変更する必要がある場合があります。

ユーザーが選択した Cloud Functions の場所は、既存の場所が保持されるため、移行中に破損する可能性があります。拡張機能のイベント トリガー関数がユーザー指定の関数ロケーションに依存していた場合は、拡張機能に新しいパラメータを追加してイベント トリガー ロケーションを収集し、これを新しい関数ロケーションにマッピングすることをおすすめします。

実施例: Cloud Firestore を BigQuery にストリーミングする

defineString("DATABASE_REGION", {
  label: "Firestore Instance Location",
  description:
    "Where is the Firestore database located? You can check your current database location at https://console.cloud.google.com/firestore/databases. The functions in this kit deploy to the Cloud Run region closest to this location.",
  input: select({
    "Multi-region (Europe - Belgium and Netherlands)": "eur3",
    "Multi-region (United States)": "nam5",
    "Multi-region (Iowa, North Virginia, and Oklahoma)": "nam7",
    "Iowa (us-central1)": "us-central1",
    // More locations...
  })
});

// Firestore multi-region locations are not Cloud Run regions; deploying a
// function to one hard-fails, so they map to a region inside the multi-region.
const MULTI_REGION_TO_FUNCTION_REGION: Record<string, string> = {
  nam5: "us-central1",
  nam7: "us-central1",
  eur3: "europe-west1",
};

/**
 * Maps a Firestore database location to the Cloud Run region the functions
 * should deploy to. The lookup is case-insensitive and ignores surrounding
 * whitespace, as the CLI's own region handling is. Regional locations pass
 * through lowercased; an unset or blank location returns `undefined`, meaning
 * the functions declare no region.
 */
export function firestoreLocationToFunctionRegion(
  location: string | undefined
): string | undefined {
  const normalized = location?.trim().toLowerCase();
  if (!normalized) {
    return undefined;
  }
  return MULTI_REGION_TO_FUNCTION_REGION[normalized] ?? normalized;
}

const functionRegion = firestoreLocationToFunctionRegion(
  process.env.DATABASE_REGION
);

export const fsexportbigquery = onDocumentWritten(
  {
    region: functionRegion,
    // Other configuration
  },
  (event) => handleDocumentWrite(event, getHandlerContext())
);

キットの最初のデプロイ時に、ユーザーは DATABASE_REGION の入力を求められます。関数は上記の対応する functionRegion にデプロイされ、第 2 世代のイベント トリガー関数のロケーションの問題が修正されます。

4. 拡張機能のパラメータとシークレットを変換する

パラメータ

extension.yaml で宣言した各パラメータは、Cloud Functions パラメータになります。

環境の直接読み取りを変換します。

const collectionPath = process.env.COLLECTION_PATH;

を Cloud Functions パラメータに変換します。

import { defineString } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const collectionPath = defineString("COLLECTION_PATH");

// Pass the param directly when used as a placeholder (e.g. trigger path)
export const sync = onDocumentWritten(
  { document: collectionPath },
  async (event) => {
    // Call .value() to read the string inside a handler
    const path = collectionPath.value();
    await handleWrite(path, event);
  }
);

ハンドラ内の文字列を読み取るには collectionPath.value() を使用します。関数のトリガーパスなど、プレースホルダが必要な場所では collectionPath を直接使用します。

Firebase CLI は、パラメータを検出して、.env、.env.<projectId> から値を読み取るか、デプロイ中にユーザーにプロンプトを表示します。既存のインストールから値が引き継がれるように、同じパラメータ名を維持します。

コードで宣言されているパラメータ名は一切変更しないことが重要です。拡張機能の移行では、既存のエンドユーザー パラメータ値が自動的に保持されますが、これは名前が変更されていない場合に限られます。

実施例: Cloud Firestore を BigQuery にストリーミングする

変更前。extension.yaml で宣言されたパラメータ。config.ts で未加工の環境変数として読み取られます。

# extension.yaml
- param: COLLECTION_PATH
  label: Collection path
  type: string
  required: true
// functions/src/config.ts
collectionPath: process.env.COLLECTION_PATH,

変更後。1 つの defineString。CLI がこれを検出して .env から読み取ります。

// src/config.ts
import { defineString } from "firebase-functions/params";

collectionPath: defineString("COLLECTION_PATH", {
  label: "Collection path",
  // We now support "nonEmpty: true" to ensure a value other than the empty string
  // is entered, analogous to "required: true" in extension.yaml
  input: { text: { nonEmpty: true } }
}),

パラメータ名は変更されていないため、既存の .env は引き続き機能します。

インスタンス ID

拡張機能は、拡張機能ランタイムによって挿入された EXT_INSTANCE_ID からインスタンス ID を読み取ります。関数キットは、FIREBASE_KIT_INSTANCE_ID からインスタンス ID を読み取ります。Firebase CLI は、各キット インスタンスのインスタンス ID を、firebase.json の instances マップ内のインスタンスのキーに設定します。CLI は、デプロイ時の検出中、エミュレータ内、デプロイされた関数にこの情報を提供します。

インスタンス ID はパラメータではないため、defineString で宣言しないでください。実際、FIREBASE_... は .env ファイルの予約済み接頭辞であるため、ユーザーはそこで設定またはオーバーライドできません。CLI が挿入する値は、params システムには表示されません。環境から直接読み取ります。

// Before
const instanceId = process.env.EXT_INSTANCE_ID;

// After
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;

この変数は、パッケージがキットとしてデプロイされている場合にのみ設定されます。コードがスタンドアロンのコードベースとしてもデプロイされている場合(ステップ 9 を参照)、オプションとして扱うか、欠落している場合は明確なメッセージを表示してフェイルファストします。拡張機能がインスタンス ID をユーザー向けのパラメータとして公開していた場合は、Firebase CLI が値を所有するようになったため、そのパラメータを削除する必要があります。

実例: ユーザーデータを削除する

(Stream Cloud Firestore to BigQuery 拡張機能はインスタンス ID を読み取らないため、移行するものはありません。Delete User Data 拡張機能は、この ID を使用して Pub/Sub トピックに名前を付けます。

変更前。拡張機能がリソースに使用した ext- 接頭辞を使用して、config.ts の未加工の環境変数として読み取ります。

// functions/src/config.ts
discoveryTopic: `ext-${process.env.EXT_INSTANCE_ID}-discovery`,
deletionTopic: `ext-${process.env.EXT_INSTANCE_ID}-deletion`,

変更後。FIREBASE_KIT_INSTANCE_ID の単純な process.env 読み取り。2 つの通常のパラメータに使用され、ユーザーがトピック名をオーバーライドできるようにします。

// src/config.ts
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;

// Non-empty defaults so Pub/Sub trigger bindings resolve during deploy
// discovery without freezing an empty topic name into the manifest.
discoveryTopicName: defineString("DISCOVERY_TOPIC_NAME", {
  default: `kit-${instanceId}-discovery`,
}),
deletionTopicName: defineString("DELETION_TOPIC_NAME", {
  default: `kit-${instanceId}-deletion`,
}),

トリガー バインディングは検出時に解決されるため、デフォルトは空にできません。空のデフォルトがトピック名としてデプロイ マニフェストに書き込まれます。このキットは、キットのコンテキスト外での実行に対しても防御します。変数が存在しない場合、モジュール レベルのデフォルトは kit-undefined-discovery と評価されるため、構成ローダーは失敗し、代わりに説明的なエラーが表示されます。

// ...
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
if (!instanceId) {
  throw new Error(
    "FIREBASE_KIT_INSTANCE_ID is not set. It is provided automatically to " +
      "kit instances by firebase-tools >= 15.32.0; deploy or emulate this " +
      "kit with a supported CLI version."
  );
}
// ...

このチェックは、ハンドラが最初に構成を解決するときに実行されます。そのため、変数が欠落していると、関数が kit-undefined-* トピックにサイレントにバインドされるのではなく、明確なランタイム エラーが発生します。デプロイ自体を拒否するには、モジュール スコープでチェックを実行して、検出中に実行されるようにします。CLI は firebase.json からインスタンス ID を取得するため、構成可能な INSTANCE_ID はなく、複数のインスタンス間で同期を維持する必要もありません。

シークレット

extension.yaml では、type: secret を使用してシークレットを宣言します。Extensions ランタイムは、これらを保存してバインドするため、拡張機能コードは process.env.PARAM_NAME を直接読み取ることができます。一般的な Cloud Functions コードベースでは、各シークレットを明示的に宣言してバインドします。

import { defineSecret } from "firebase-functions/params";
import { onRequest } from "firebase-functions/https";

const apiKey = defineSecret("API_KEY");
export const fn = onRequest({ secrets: [apiKey] }, handler);

拡張機能が npm パッケージ / キットに移行されると、シークレット参照はエンドユーザーの .env ファイルで管理されます。コードで宣言されているシークレット名は一切変更しないことが重要です。移行中、エンドユーザーのシークレットはそれに応じて移行されます。

実施例: Cloud Firestore からメールをトリガーする

変更前。MAIL_COLLECTION と SMTP_PASSWORD は、config.ts で未加工の環境変数として読み取られます。

# extension.yaml
- param: MAIL_COLLECTION
  label: Email documents collection
  type: string
  default: mail
  required: true

- param: SMTP_PASSWORD
  label: SMTP password
  type: secret
// functions/src/config.ts
mailCollection: process.env.MAIL_COLLECTION,
smtpPassword: process.env.SMTP_PASSWORD,

変更後。1 つの defineString と 1 つの defineSecret。CLI は両方を検出し、.env から読み取ります。

import { defineString, defineSecret } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const mailCollection = defineString("MAIL_COLLECTION", {
  label: "Email documents collection",
  default: "mail"
});

const smtpPassword = defineSecret("SMTP_PASSWORD", { label: "SMTP password" });

export const processQueue = onDocumentWritten(
  { document: `${mailCollection}/{documentId}`, secrets: [smtpPassword] },
  async (event) => {
    const collection = mailCollection.value();
    const password = smtpPassword.value();
    // ...
  }
);

5. 内部タスクキュー呼び出しを移行する

一部の拡張機能は、Firebase Admin SDK を使用して、関数コード内から独自のタスクキューに作業をキューに入れます。これは、ディスパッチされたタスクの受信とは異なります(関数のアップグレードとライフサイクル フックの変換のセクションを参照)。この場合、コードは queue.enqueue(...) を呼び出すプロデューサーです。

以前のバージョンの Admin SDK では、同じ拡張機能のタスクキュー関数をターゲットにするために、拡張機能が独自の拡張機能インスタンス ID を 2 番目のパラメータとして渡す必要がありました。firebase-admin 14.2.0 以降、これは必須ではなく、推奨もされていません。Task Queue API は、デフォルトで同じコンテキスト(拡張機能やキットなど)のタスクキューをターゲットにするようになりました。このパラメータは、拡張機能としてもスタンドアロン関数としても、コードから削除しても問題ありません。削除することをおすすめします。このパラメータを削除すると、ポータビリティと上位互換性が確保されます。

enqueue 呼び出しのその他の部分(locations/<region>/functions/<name> リソースパス、タスク ペイロード、再試行ロジック)は変更されません。

Cloud Tasks で関数をキューに追加する方法の詳細については、Cloud Tasks で関数をキューに追加するをご覧ください。

変更前。第 1 世代の拡張機能:

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${config.location}/functions/syncBigQuery`,
  process.env.EXT_INSTANCE_ID, // extension instance ID, injected by the runtime
);
await queue.enqueue(taskData);

変更後。第 2 世代の延長ケーブル:

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${process.env.FUNCTION_REGION}/functions/syncBigQuery`
);
await queue.enqueue(taskData);

enqueue 呼び出しが接頭辞付きのコードベースをターゲットとしている場合、検出された関数名にも接頭辞が付きます(例: orders-syncBigQuery)。置換関数キット インスタンスを確認してインストールすると関数キットとしてテストするをご覧ください。

6. 必要な API と IAM ロールを宣言する

拡張機能の IAM と API の要件を extension.yaml からコードに移動します。

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");

宣言型セキュリティを使用すると、Firebase CLI はコードベースのマネージド ランタイム サービス アカウントを作成または更新し、宣言されたすべてのロールの和集合を付与します。最終的な API がより狭いモデルをサポートしていない限り、コードベースのすべての関数がこれらのロールで実行されることをユーザーにドキュメント化します。

実施例: Cloud Firestore を BigQuery にストリーミングする

変更前。extension.yaml で宣言。Extensions ランタイムが API を有効にし、マネージド アカウントにロールを付与しました。

apis:
  - apiName: bigquery.googleapis.com
roles:
  - role: bigquery.dataEditor
  - role: datastore.user
  - role: bigquery.user

変更後。requiresAPI と requiresRole を使用してコードで宣言します。

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI(
  "bigquery.googleapis.com",
  "Needed to write changelog rows and views"
);
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/datastore.user");
requiresRole("roles/bigquery.user");

拡張機能が Eventarc イベントを公開する場合は、イベントの公開に必要なロールと API も設定する必要があります。これは以前は拡張機能によって処理されており、extensions.yaml での変更は必要ありませんでした。これは、カスタム Eventarc チャンネルが使用されている場合にのみキットがこれらの権限をリクエストするように、コード内で条件付きで行うことができます。

if (!!process.env.EVENTARC_CHANNEL) {
  requiresRole("roles/eventarc.publisher");
  requiresAPI(
    "eventarcpublishing.googleapis.com",
    "Publishes the extension's custom events to its Eventarc channel."
  );
}

7. ライフサイクル フックを変換する

拡張機能が getExtensions().runtime()(setProcessingState や setFatalError など)を呼び出す場合は、それらの呼び出しを削除します。通常デプロイされた第 2 世代の関数から呼び出されると、エラーがスローされるためです。ライフサイクル状態は afterFirstDeploy と afterRedeploy によって駆動されるようになり、この状態トラッキングは使用されません。

Firebase Extensions は、ユーザーが拡張機能をインストール、更新、または再構成するときにセットアップを実行できます。npm パッケージで、同等のライフサイクル アクションをコードで宣言します。

1 回限りの設定:

import { afterFirstDeploy } from "firebase-functions/lifecycle";
import { onTaskDispatched } from "firebase-functions/tasks";

export const runInitialSetup = onTaskDispatched(async (request) => {
  await initializeResources(request.data);
});

afterFirstDeploy({
  task: {
    function: "runInitialSetup",
    body: {}
  }
});

構成またはコードの更新の場合:

import { afterRedeploy } from "firebase-functions/lifecycle";

afterRedeploy({
  task: {
    function: "runInitialSetup",
    body: { reconcile: true }
  }
});

ライフサイクル アクションをべき等にします。ディスパッチまたは実行が失敗した場合、ユーザーは手動で再実行する必要がある場合があります。

firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME

実施例: Cloud Firestore を BigQuery にストリーミングする

変更前。lifecycleEvents(extension.yaml)、要因: 拡張機能ランタイム

lifecycleEvents:
  onInstall:
    function: initBigQuerySync
    processingMessage: Configuring BigQuery Sync.
  onUpdate:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync
  onConfigure:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync

変更後。コードで宣言。タスクは最初のデプロイ時に BigQuery をプロビジョニングします。

import { afterFirstDeploy, afterRedeploy } from "firebase-functions/lifecycle";

afterFirstDeploy({ task: { function: "initBigQuerySync" } });
afterRedeploy({ task: { function: "setupBigQuerySync" } });

プロビジョニングはべき等であるため、再実行するとデータセット、テーブル、ビューが調整されます。ユーザーは firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME を使用して手動で再実行できます。

8. ユーザー向けのドキュメントの設定

少なくとも次の内容を説明するパッケージ README を作成します。

  • パッケージに必要な .env 値。
  • パッケージに必要なシークレットと、既存のシークレット値を移行する方法。
  • パッケージが requiresRole(...) で宣言する IAM ロール。
  • パッケージが有効にする、または必要とする Google API。
  • パッケージが宣言するライフサイクル フックと、それらを手動で再実行する方法。
  • 請求に関するメモ。
  • 元の拡張機能と比較して変更された点。
  • パッケージがインスタンス ID(CLI によって設定された FIREBASE_KIT_INSTANCE_ID)を取得する方法と、インスタンスのすべての関数が kit-<instanceId>- 接頭辞付きでデプロイされる方法。

実施例: Cloud Firestore を BigQuery にストリーミングする

README パッケージには、具体的な「変更内容」の表が含まれています。

懸念事項 拡張機能として @firebase-function-kits/firestore-bigquery-export の場合
Config 拡張機能のパラメータ .env を介した Cloud Functions パラメータ
IAM 拡張機能によって付与 requiresRole(...)、デプロイ時に適用
プロビジョニング 拡張機能によるライフサイクル タスク afterFirstDeploy / afterRedeploy 件のタスク
関数名 ext-<instanceId>-fsexportbigquery fsexportbigquery(オプションで接頭辞付き)
インスタンス ID 拡張機能によって挿入された EXT_INSTANCE_ID FIREBASE_KIT_INSTANCE_ID。CLI によって firebase.json から設定されます。

9. 第 2 世代の関数をテストする

これで、デプロイ時に拡張機能の新規インストールと同じように動作する第 2 世代の関数が作成されました。次のステップは、その過程で誤って発生した問題を検証して修正することです。

setGlobalOptions を呼び出して、デフォルトのリージョンや CPU などのグローバル オプションを設定するには、キットをスタンドアロンの第 2 世代関数としてデプロイする場合にのみ行う必要があります。キットが npm パッケージとしてインストールされている場合、ユーザーはラッパーコードで setGlobalOptions を呼び出してこれらのパラメータを構成します。これが 2 回発生すると、警告が表示されます。この呼び出しは、FIREBASE_KIT_INSTANCE_ID 環境変数を確認することで保護できます。

import { setGlobalOptions } from "firebase-functions";

if (!process.env.FIREBASE_KIT_INSTANCE_ID) {
  setGlobalOptions({
    region: "us-east1",
    maxInstances: 10,
  });
}

firebase-tools >= 15.32.0 を使用していることを確認し、変換した第 2 世代の関数を適切なリソースを含むテスト プロジェクトにデプロイして、その動作をテストします。拡張機能のテスト用にテスト プロジェクトがすでに設定されている場合は、次のコマンドを実行します。

firebase deploy --only functions

拡張機能の Firebase コンソールでインストール フォームに入力したときと同じように、パラメータ値を求めるウィザードに入力します。

実施例: Cloud Firestore を BigQuery にストリーミングする

Cloud Firestore から BigQuery への同期をエンドツーエンドで検証します。

  1. Firebase コンソールの Cloud Firestore ページで、COLLECTION_PATH(users)として設定したコレクションを作成します(まだ作成していない場合)。
  2. 任意のフィールドと任意の値を含む bigquery-mirror-test という名前のドキュメントを作成します。
  3. Google Cloud コンソールの BigQuery ページで、未加工の変更ログテーブルをクエリします。ドキュメントの作成をロギングする 1 つの行が含まれている必要があります。

    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 イベントが未加工の変更履歴テーブルに追加されます。

    1 つのドキュメントの完全な履歴を調べるには、次のコマンドを使用します。

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

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

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

10. npm で関数キットを公開する

拡張機能から第 2 世代の関数への変換を検証したら、次のいずれかのガイドを使用して、エンドツーエンドのテスト用にリリース候補版を npm に公開できます。

キットが npm に公開されると、firebase functions:kits:install でインストールできるようになり、拡張機能の公式な代替としてリストされます。

最初にリリース候補版を公開することを強くおすすめします。キットはパッケージ名とバージョンでインストールされるため、プレリリース版を使用すると、デフォルトの latest タグでインストールするユーザーに未完成のパッケージを公開することなく、レジストリに対して実際のインストール フローをテストできます。

公開前の確認事項:

  1. パッケージ名を選択します。スコープ付きの名前とスコープなしの名前の両方が機能します(上記のガイドを参照)。スコープ付きパッケージはデフォルトで非公開であるため、--access public を渡します。
  2. ビルドして、出荷されるものを確認します。main と types はコンパイルされた出力(この例では lib/)を指しているため、そのディレクトリを公開された tar ファイルに含める必要があります。.npmignore または files 許可リストを使用し、npm pack --dry-run で結果を検査します。ビルドを実行する prepublishOnly スクリプトは、古い出力の公開を防ぎます。

デフォルトで安全に公開できるようにする package.json の追加機能:

{
  "files": ["lib", "README.md", "CHANGELOG.md"],
  "publishConfig": { "access": "public", "tag": "next" },
  "scripts": {
    "build": "tsc -b",
    "prepublishOnly": "npm run build && npm test"
  }
}

"publishConfig": { "tag": "next" } フィールドにより、プレーンな npm publish が latest を上書きしないようにします。

リリース候補版の作成:

たとえば、ローカルでバージョンを 0.0.2-rc.3 から 0.0.2-rc.4 にインクリメントするには、次のようにします(package.json がリポジトリのルートにある場合、Git で commit とタグ付けが行われます)。

npm version prerelease --preid rc

リリース候補版を公開し、next タグで npm に @your-org/your-kit@0.0.2-rc.4 を登録するには:

npm publish

npm ウェブサイトに新しいバージョンが表示されるまでに数分かかることがあります。npm view はレジストリを直接読み取ります。

npm view @your-org/your-kit versions dist-tags

このガイドのステップ 11 とステップ 12 が完了したら、パッケージを安定版に昇格できます。

npm version 0.0.2
npm publish --tag latest
npm dist-tag add @your-org/your-kit@0.0.2 next

npm-shrinkwrap.json に関する注: パッケージに npm-shrinkwrap.json ファイルを含めることを強くおすすめします。含めないと、インストール時に CLI がユーザーに警告します。これにより、ユーザーはテスト済みの依存関係を正確に使用でき、サプライ チェーン攻撃から保護できます。ただし、シュリンクラップは、Cloud Functions ビルド(npm ci)中も含め、ユーザーのプロジェクトにそのまま適用されます。この場合、開発専用のエントリは EBADPLATFORM で失敗する可能性があります。公開されたシュリンクラップ コピーから "dev": true エントリと devDependencies を削除する必要がある場合があります。

実施例: Cloud Firestore を BigQuery にストリーミングする

4 番目のリリース候補版の時点でのキットの package.json:

{
  "name": "@firebase-function-kits/firestore-bigquery-export",
  "version": "0.0.2-rc.4",
  "repository": {
    "type": "git",
    "url": "https://github.com/firebase/extensions.git",
    "directory": "kits/firestore-bigquery-export"
  },
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "engines": { "node": "22" },
  "scripts": { "build": "tsc -b" }
}

この場合、キットは monorepo に存在するため、npm レジストリ リンクが正しいフォルダを指すように repository.directory を含めることが重要です。CHANGELOG.md には、保留中のリリースのメモが格納されます。

11. 関数キットとしてテストする

キットを公開したら、npm を使用してキットをテストすることをおすすめします。

firebase-tools バージョン >= 15.32.0 を使用していることを確認し、キットをインストールします。

firebase functions:kits:install --package <your-package-name>@<your-prerelease-version>

これにより、npm からパッケージがダウンロードされ、キットの新しいソース ディレクトリ内に設定されます。また、拡張機能のインストール フローと同様に、最初のインスタンスを構成する手順が表示されます。パッケージをローカルにインストールして設定したら、デプロイを実行して Google Cloud プロジェクトにリソースを作成します。

firebase deploy --only functions:<your-kit-instance-id>

インストール後、Firebase CLI は、インストール時に選択した正確なインスタンス ID を含む同様のデプロイ コマンドを出力します。

ステップ 9第 2 世代の関数をテストします。キットを使用してデプロイするようになったため、関数には接頭辞が付けられ、kit-<instance-id>-<method-name> という名前になります。これにより、キットに複数のインスタンスを設定し、プロジェクト内で同じ関数を複数回デプロイできます。各インスタンスには一意の名前が付けられます。

12. 移行の置き換えをテストする

動作する拡張機能インスタンスを設定してから、ユーザー移行ガイド(firebase ext:migrate --package または関数キットの CLI コマンドを使用)に沿って、移行の代替として関数キットのテストを完了します。

13. 公式の拡張機能の代替についてユーザーと Google に通知する

関数キットの代替品が準備でき、ユーザーが移行先として使用できる npm パッケージとして利用可能になったら、この公式の代替品についてユーザーと Google の両方に通知します。拡張機能をホストする GitHub リポジトリの README.md ファイルを次の情報で更新します。

<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="<your-extesion-id>" package="<your-npm-package-name>" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `<your-extension>` is deprecated. Migrate to the [<your-npm-package-name>](<link-to-your-npm-package>) package.

Google は、既知の拡張機能の README で <!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" --> などのコメントをスキャンし、これを使用して、firebase-tools リポジトリに replacements.json として保存されている置換の公式レジストリにデータを入力します。replacements.json を確認して、拡張機能でスキャンされる README.md を確認することもできます。交換品の公式リストは毎週更新されます。

実施例: Cloud Firestore を BigQuery にストリーミングする

firestore-bigquery-export 拡張機能 README.md には、次のものが含まれています。

<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `firebase/firestore-bigquery-export` is deprecated. Please migrate to the [`@firebase-function-kits/firestore-bigquery-export`](https://www.npmjs.com/package/@firebase-function-kits/firestore-bigquery-export) package.