Firebase Extensions のインストール

公式の Firebase 拡張機能は、Firebase コンソール、Firebase CLI（コマンドライン インターフェース）を使用して、または自動生成された SDK を使用してインストール（および管理）できます。

各インストール方法でサポートされるアクションの違いを必ず確認してください。


自動生成された SDK を使用したインストールは、拡張機能のインストールと管理の新しいオプションです。このオプションでは、CLI を使用して特定の拡張機能バージョンの Node SDK を自動生成します。これは、JavaScript または TypeScript の Cloud Functions で通常の依存関係としてインポートできます。

この自動生成された SDK には、次のものが含まれています。

  • 拡張機能のパラメータを表すインターフェースと、ほとんどの非プリミティブ パラメータ型の型宣言。
  • 拡張機能のインスタンスを初期化するコンストラクタ関数。
  • 拡張機能によって出力されるすべてのイベントの Eventarc トリガーを含む拡張機能クラス。

拡張機能 SDK を生成すると、拡張機能のすべての構成がコード内で行われます。

このインストール オプションを使用すると、複数の拡張機能インスタンスの管理、特に拡張機能の外部で定義された Cloud Functions を含むプロジェクトでの管理が大幅に簡素化できます。


拡張機能のインストールや管理を行うには、オーナーまたは編集者、あるいは Firebase 管理者のいずれかのロールが割り当てられている必要があります。

拡張機能をインストールするには、プロジェクトが Blaze（従量課金制）プランを利用している必要があります。拡張機能のインストールは無料ですが、Firebase サービス、または Cloud Secret Manager などのクラウド サービスの使用に対しては、使用量がサービスの無料枠を超えた場合に請求されることがあります。

始める前に

  1. まだ追加していない場合は、Firebase をプロジェクトに追加します。

  2. まだアップグレードしていない場合は、プロジェクトを Blaze（従量課金制）プランにアップグレードします。

  3. Firebase CLI の最新バージョンをインストールするか、最新バージョンに更新します。

  4. Firebase プロジェクト ID または構成済みのプロジェクトのエイリアスをメモします。

ステップ 1: 拡張機能の詳細情報を表示する

この手順は省略可能ですが、行うことを強くおすすめします。

Firebase Extension をインストールする前に、次のような拡張機能の詳細情報を確認することをおすすめします。

  • 拡張機能の仕組み、プリインストール タスク、拡張機能の詳細
  • 一般的な識別情報と説明
  • 拡張機能のタスクに請求先アカウントが必要かどうか
  • 動作に必要な Google サービス（API）とアクセスロール
  • 拡張機能用に作成されたリソース（関数など）
  • ユーザー構成可能なパラメータの説明

拡張機能の詳細情報を表示するには:

  1. 環境を設定し、拡張機能を選択していることを確認します。

  2. パソコンの任意の場所から、extension-info コマンドを実行します。

    firebase ext:info publisher-id/extension-id

    publisher-id 引数と extension-id 引数は必須で、拡張機能のプリインストールの詳細ページで確認できます。

ステップ 2: 拡張機能をインストールする

インストールする前に、拡張機能の基本仕様（有効になる API、作成されるリソース、付与されるアクセス権など）とその課金要件を確認します。

続行する前に、環境を設定し、拡張機能を選択していることを確認します。

Cloud Functions for Firebase を初期化する

新しいプロジェクトを開始する場合、またはプロジェクトでまだ Cloud Functions for Firebase を使用していない場合は、init functions を実行します。

cd your-project
firebase init functions

関数言語として TypeScript または JavaScript を選択します。

プロジェクトで Cloud Functions がすでに初期化されている場合は、firebase-functions パッケージのバージョン 5.1.0 以降を使用していることを確認します。

cd your-project/functions
npm upgrade --save firebase-functions

ESLint を使用している場合は、生成された SDK を構成から除外することもできます（.eslintrc.js）。

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

拡張機能 SDK を生成する

ローカルの Firebase ディレクトリから ext:sdk:install コマンドを実行します。

firebase ext:sdk:install publisher-id/extension-id@version

たとえば、firestore-send-email 拡張機能のバージョン 0.1.34 をインストールするには、次の手順を実行します。

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id と extension-id は必須で、extensions.dev の拡張機能のプリインストールの詳細ページで確認できます。@version 部分は省略可能です。省略すると、ツールは最新バージョンをインストールします。

指定できるオプションは次の 2 つです。

  • --force: 追加の確認なしで次の操作をすべて行います。

    • 同じ拡張機能とバージョンの SDK がすでに 1 つ生成されている場合でも、SDK を自動生成します。
    • 自動生成された SDK パッケージを Cloud Functions Node プロジェクトにインストールします。

  • --codebase: SDK を追加するコードベースの名前。指定しない場合、このコマンドは SDK をデフォルトのコードベースである functions に追加します。

このコマンドは、拡張機能用に自動生成された SDK を含む Node パッケージを作成し、それをプロジェクトの Cloud Functions コードベースのいずれかに追加します。デフォルトのコードベース（functions）では、SDK は次の場所に保存されます。

functions/generated/extensions/publisher-id/extension-id/version

SDK の生成後、SDK を Cloud Functions Node プロジェクトにもインストールするかどうかをコマンドで尋ねられます。このプロンプトに [はい] と回答します。

拡張機能インスタンスを構成する

拡張機能を構成するには、SDK をインポートし、インストールする拡張機能インスタンスごとにコンストラクタ関数を呼び出して、プロジェクト固有のインスタンス ID と拡張機能に必要な構成パラメータを渡します。

  1. Cloud Functions ソースで、ext:sdk:install コマンドで出力されたステートメントを使用してコンストラクタをインポートします。

    TypeScript

    たとえば、firestore-send-email 拡張機能の SDK を生成した場合、import ステートメントは次のようなものになります。

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    拡張機能でパスワードなどのシークレット値が必要な場合は、Cloud Functions SDK の defineSecret 関数も必要です。

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

    JavaScript

    たとえば、firestore-send-email 拡張機能の SDK を生成した場合、require ステートメントは次のようなものになります。

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    拡張機能でパスワードなどのシークレット値が必要な場合は、Cloud Functions SDK の defineSecret 関数も必要です。

    const { defineSecret } = require('firebase-functions/params');

  2. 構成するインスタンスごとにコンストラクタ関数を呼び出して結果をエクスポートします。

    各インスタンスに一意の ID を割り当てます。この ID には、小文字、数字、ハイフンのみを使用します。

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    シークレット値は defineSecret 関数を使用して指定する必要があります。

  3. 次に、構成した拡張機能をデプロイするために、以下を実行します。

    firebase deploy --only functions --project=projectId-or-alias

    通常の Cloud Functions のデプロイ オプションがすべて適用されます。たとえば、特定のコードベースから単一の拡張機能インスタンスをデプロイするには、次の操作を行います。

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

ステップ 3: インストール後の設定を完了する

拡張機能によっては、使用する前に行っておかなければならない必須の手順があるものや、オプションの手順があるものがあります。それらの手順は、Firebase コンソールの Extensions ダッシュボードに表示されるインストール後の詳細ページで確認できます（インストール後、ターミナルにダッシュボードへのリンクが表示されます）。

それらの手順は、拡張機能のソース ディレクトリにある POSTINSTALL.md ファイルでも確認できます。

Firebase リソースを作成する

Firebase リソース（Cloud Firestore コレクション、Realtime Database パス、Cloud Storage バケット）を使用するように拡張機能が構成されていて、それらのリソースがまだ存在していない場合は、拡張機能を使用する前にそれらを作成してください。

Eventarc イベント ハンドラを作成する

拡張機能の中には、実行中に重要なイベントが発生すると Eventarc に公開されるものがあります。拡張機能がイベントを公開する場合、独自のカスタム ロジックを使用してこれらのイベントに応答する関数を作成できます。これは、たとえば、長時間実行タスクが完了したときにユーザーに通知する場合や、拡張機能の出力を後処理する場合に役立ちます。

拡張機能から出力されるイベントのいずれかにハンドラを定義する場合は、各インスタンスのトリガー メソッドを使用します。

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

拡張機能インスタンスとともにイベント ハンドラをエクスポートする必要があります。

イベント ハンドラを定義した後、およびそれを変更するたびに、拡張機能とハンドラの両方を再デプロイします。

複数の拡張機能インスタンスをインストールする

同じプロジェクトに同じ拡張機能を複数回インストールできます。インストールされたインスタンスごとに、カスタマイズされた独自の設定と独自の拡張機能リソースを設定できます。インストールされた各インスタンスは、プロジェクト内で一意のインスタンス ID を使用して識別し、参照します。

自動生成された SDK のコンストラクタ関数は、インストールして構成するインスタンスごとに 1 回呼び出します。

次のステップ

  • Firebase コンソールで、インストールした拡張機能の詳細と構成を表示する。

  • インストールした拡張機能のアクティビティをモニタリングする。これには、拡張機能の健全性、使用状況、ログの確認が含まれます。

  • Firebase コンソールを使用して、インストールした拡張機能を管理します。Firebase の公式拡張機能の場合は、拡張機能の再構成、アンインストール、最新バージョンへの更新ができます。

  • すべてのプロジェクトのベスト プラクティスとして、プロジェクトの予算アラートを設定し、Firebase コンソールで[使用量と請求額] ダッシュボードをモニタリングする。