拡張機能のマニフェストを使用してプロジェクトの構成を管理する

拡張機能のマニフェストとは、拡張機能のインスタンスとその構成のリストです。マニフェストを使用すると、次のことができます。

  • 拡張機能の構成を他のユーザーと共有する
  • 異なるプロジェクト間で拡張機能の構成をコピーする（例: ステージング プロジェクトから本番環境プロジェクトへ）
  • すべての拡張機能を一度にデプロイする
  • Firebase Local Emulator Suite を使用して、拡張機能がアプリとどのように連携するかをテストする
  • 拡張機能の構成をソース管理に commit する
  • CI / CD パイプラインに拡張機能を含める

拡張機能のマニフェストには、次の 2 つの部分があります。

  • firebase.json の extensions セクション（拡張機能バージョン リファレンスに対するインスタンス ID のマップ）。次に例を示します。

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • .env ファイル。Firebase プロジェクト ディレクトリの extensions/ サブディレクトリに置かれ、拡張機能の個々のインスタンスの構成が含まれます。たとえば、storage-resize-images のインスタンスの .env ファイルは次のようになります。

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.appspot.com
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

拡張機能のマニフェストを作成する

拡張機能のマニフェストを作成するには、次の 3 つの方法があります。

  • Firebase CLI を使用して拡張機能のマニフェストを管理する
  • プロジェクトの拡張機能の構成をエクスポートする
  • マニフェスト ファイルを手動で編集する

最初の 2 つの方法を以下で説明します。

Firebase CLI を使用して拡張機能のマニフェストを管理する

Firebase CLI のほとんどの ext: コマンドでは、--local オプションを指定して実行することで、プロジェクトの現在の構成を実際に変更せずに拡張機能のマニフェストを更新できます。

例:

firebase ext:install --local firebase/firestore-bigquery-export

上記のコマンドを実行すると、最新バージョンの firebase/firestore-bigquery-export 拡張機能の構成と、マニフェストへの構成の保存を促すプロンプトが表示されますが、構成はプロジェクトにはデプロイされません。

以下に、拡張機能のマニフェストを変更するコマンドの例をさらにいくつか示します。

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

プロジェクトの拡張機能の構成をエクスポートする

プロジェクトの現在の拡張機能の構成をマニフェストに保存する手順は次のとおりです。

  1. まだ設定していない場合は、Firebase CLI を設定します。
  2. シェル プロンプトでプロジェクト ディレクトリに移動します（プロジェクト ディレクトリには firebase.json ファイルが含まれています）。
  3. ext:export コマンドを実行します。 
    firebase ext:export

ext:export コマンドを実行すると、firebase.json ファイルに extensions セクションが追加されます。また、ext:export コマンドを実行すると、extensions ディレクトリが作成され、インストールされているそれぞれの拡張機能インスタンスの .env ファイルが格納されます。これらのファイルには、各インスタンスの構成パラメータが含まれています。

Firebase Local Emulator Suite を使用して拡張機能の構成をテストする

拡張機能のマニフェストにいくつかの拡張機能インスタンスを追加した後、Local Emulator Suite を使用してテストできます。

  1. Local Emulator Suite をインストールして構成します。

  2. Local Emulator Suite を起動します。

    • Emulator Suite をインタラクティブに実行するには、firebase emulators:start を実行します。
    • Emulator Suite でテスト スクリプトを実行するには、firebase emulators:exec my-test.sh を実行します。

マニフェストのリストに拡張機能のインスタンスが含まれている場合、Local Emulator Suite はそれらの拡張機能のソースコードを ~/.cache/firebase/extensions にダウンロードします。ダウンロードが完了すると Local Emulator Suite が開始されます。これにより、拡張機能のバックグラウンドでトリガーされる任意の関数をトリガーしたり、アプリを Emulator Suite に接続して、そのアプリとの統合をテストしたりできるようになります。

拡張機能の構成をプロジェクトにデプロイする

拡張機能のマニフェストにいくつかの拡張機能のインスタンスを追加した後、Firebase CLI を使用してプロジェクトにデプロイできます。拡張機能のマニフェストを使用してデプロイする場合は、マニフェストに指定されているすべての拡張機能のインスタンスについて、プロジェクトへのそれらのインストール、更新、構成が一度に行われます。

拡張機能のマニフェストをデプロイするには:

  1. シェル プロンプトで、拡張機能の構成が保存されているディレクトリに移動します（これは firebase.json を含むディレクトリです。ext:export を実行したばかりの場合は、すでに目的のディレクトリにいます）。
  2. deploy コマンドを実行します。現在のプロジェクト以外のプロジェクトに拡張機能をデプロイする場合は、--project= も指定します。 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

deploy コマンドを実行すると、各インスタンスの構成が検証され、firebase.json にリストされていない拡張機能インスタンスを宛先プロジェクトから削除するかどうかが尋ねられます。その後、すべての拡張機能インスタンスがデプロイされます。

プロジェクト固有の拡張機能の構成

保存した拡張機能の構成は、複数の異なるプロジェクト（ステージング用プロジェクトと本番環境プロジェクトなど）にデプロイできます。これを行う場合は、一部のパラメータ値を、プロジェクトごとに異なる値にする必要が生じることがあります。プロジェクト固有の .env ファイルを使用すると、次が可能となります。

  • プロジェクト間で異なるパラメータ値を extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID に設定する
  • 共有パラメータ値を extensions/EXTENSION_INSTANCE_ID.env に設定する。

拡張機能をエミュレートするときに、別のパラメータ値を使用したい場合があります。たとえば、本番環境の API キーではなくテスト用の API キーを指定する場合などです。次のパラメータを .local ファイルに設定します。

  • エミュレーション中に使用するシークレット以外のパラメータを extensions/EXTENSION_INSTANCE_ID.env.local に設定する
  • シークレットのパラメータ値を extensions/EXTENSION_INSTANCE_ID.secret.local に設定する