Firebase で AI 搭載アプリを構築して実行する方法のデモを、2024 年の Demo Day でご覧ください。ぜひご覧ください。

拡張機能のパラメータの設定と使用

パラメータは、インストールされた拡張機能の各インスタンスをユーザーがカスタマイズするためのメカニズムです。パラメータは拡張機能の環境変数に似ています。パラメータの値は、自動入力（インストール後に Firebase が提供）またはユーザー構成（インストール時にユーザーが指定）で設定できます。

このようなパラメータは、拡張機能の関数のソースコード、extension.yaml ファイル、POSTINSTALL.md ファイルで参照できます。PARAMETER_NAME というパラメータを参照する構文は次のとおりです。

関数のソースコード内で、params モジュール（params.defineInt("PARAMETER_NAME") など）または process.env.PARAMETER_NAME を使用します。
extension.yaml と POSTINSTALL.md 内で、${param:PARAMETER_NAME} を使用します。

インストール後、Firebase コンソールに POSTINSTALL.md ファイルの内容が表示され、インストールされたインスタンスの実際の値がパラメータ参照に入力されます。

自動入力パラメータ

インストールされた拡張機能の各インスタンスは、Firebase が提供するデフォルトの自動入力パラメータへのアクセス権を自動的に取得します（下の表を参照）。これらのパラメータ値は、Firebase プロジェクトのデフォルト値（デフォルトの Storage バケットなど）、または拡張機能固有の値（拡張機能のインスタンス ID など）です。

すべての自動入力パラメータの値は不変です。プロジェクトの作成時または拡張機能のインストール時に設定されます。

Firebase は、以下の拡張機能のパラメータ値を自動入力しますが、インストール中に関連するプロダクトを自動プロビジョニングすることはありません。拡張機能をインストールするユーザーが、インストール前に関連するプロダクトをプロジェクトで有効にする必要があります。たとえば、拡張機能に Cloud Firestore が含まれる場合、ユーザーはプロジェクトで Cloud Firestore を設定する必要があります。こうした要件を、PREINSTALL.md ファイルでユーザーに通知することをおすすめします。

自動入力パラメータのリファレンス	説明	パラメータ値（Firebase が提供）
Firebase プロジェクトからデフォルト値が設定されるパラメータ
`PROJECT_ID`	拡張機能がインストールされた Firebase プロジェクトの一意の識別子	一般的な形式: `project-id` 値の例: `project-123`
`DATABASE_URL`	Firebase プロジェクトのデフォルトの Realtime Database インスタンス URL	一般的な形式: `https://project-id-default-rtdb.firebaseio.com` （米国のインスタンス） or `https://project-id-default-rtdb.region-code.firebasedatabase.app` （米国以外のインスタンス）値の例: `https://project-123-default-rtdb.firebaseio.com`
`DATABASE_INSTANCE`	Firebase プロジェクトのデフォルトの Realtime Database インスタンス名通常、この値はプロジェクト ID と同じか、末尾が `-default-rtdb` です。	一般的な形式: `project-id` 値の例: `project-123`
`STORAGE_BUCKET`	Firebase プロジェクトのデフォルトの Cloud Storage バケット名	一般的な形式: 値の例: `project-123.firebasestorage.app`
拡張機能のインストールからデフォルト値が設定されるパラメータ
`EXT_INSTANCE_ID`	インストールされた拡張機能インスタンスの一意の識別子この値は、`extension.yaml` ファイルで指定されている `name` フィールドから生成されます。	最初にインストールされたインスタンスの一般的な形式（Firebase によって自動的に割り当てられます。インストール時にユーザーが変更することはできません）。 `name-from-extension.yaml` 値の例: `my-awesome-extension` 2 番目以降にインストールされたインスタンスの一般的な形式（Firebase によって自動的に割り当てられます。インストール時にユーザーが変更できます）。 `name-from-extension.yaml-4-digit-alphanumeric-hash` 値の例: `my-awesome-extension-6m31`

ユーザー構成パラメータ

インストールされる拡張機能のインスタンスをユーザーがカスタマイズできるように、インストール中にパラメータ値を指定するようユーザーに要求できます。これらの値をリクエストするには、extension.yaml ファイルの params セクションでプロンプトを設定します。

以下に params セクションの例を示し、その下に使用可能なすべてのパラメータフィールドの表を示します。

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

extension.yaml ファイルの params セクションで、次のフィールドを使用してユーザー構成パラメータを定義します。

フィールド 型説明

param
（必須）文字列パラメータの名前

label
（必須）

文字列

パラメータの簡単な説明

ユーザーにパラメータ値の入力を求めるときに表示されます

description
（省略可）

文字列

パラメータの詳細な説明

ユーザーにパラメータ値の入力を求めるときに表示されます

マークダウンがサポートされます

type
（省略可）

文字列

ユーザーがパラメータ値を設定するための入力メカニズム（テキストを直接入力するか、プルダウンリストから選択するかなど）

有効な値は次のとおりです。

string: 自由形式のテキストを入力できます（validationRegex による制限あり）。
select: 事前定義済みのオプションリストから 1 つのエントリを選択できます。この値を指定する場合は、options フィールドも定義する必要があります。
multiSelect: 事前定義済みのオプションのリストから 1 つ以上のエントリを選択できます。この値を指定する場合は、options フィールドも定義する必要があります。
selectResource: ユーザーのプロジェクトから特定のタイプの Firebase リソース（Cloud Storage バケットなど）を選択できます。
このタイプのパラメータを指定すると、インストール UI でよりユーザーフレンドリーな選択ウィジェットが表示されます。可能な限り selectResource パラメータを使用してください。

この値を指定する場合は、resourceType フィールドも定義する必要があります。
secret: サードパーティサービス用の API キーなど、機密性の高い文字列を格納できます。これらの値は Cloud Secret Manager に保存されます。
Cloud Secret Manager は有料サービスです。使用すると、拡張機能をインストールしたユーザーは課金される可能性があります。secret パラメータタイプを使用する場合は、拡張機能で Cloud Secret Manager を使用していることを PREINSTALL ファイルに記述してください。

このフィールドを省略すると、パラメータはデフォルトで string type になります。

options
（パラメータ type が select または multiSelect の場合は必須）

list

ユーザーが選択できる値のリスト

options フィールド内に label フィールドと value フィールドを含めます

label（文字列）: 選択可能なオプションの簡単な説明
value（文字列）: 選択可能なオプションの実際の値
意図しない型変換を防ぐため、これらの文字列を必ず引用符で囲んでください。

options フィールドでは value フィールドは必須です。
label を省略すると、デフォルトで value が表示されます。

構文の例

options:
  - label:
    value:
  - label:
    value:
  - label:
    value:

resourceType
（パラメータ type が selectResource の場合は必須）

文字列

ユーザーに選択を求める Firebase リソースのタイプ。現在、リソースセレクタは Cloud Storage バケットでのみサポートされています。

リソースの種類	タイプ ID
Cloud Storage個のバケット	`storage.googleapis.com/Bucket`

不明な resourceType 値は無視されます。UI は、パラメータを自由形式の string 入力フィールドとしてレンダリングします。

example
（省略可）

文字列

パラメータの値の例

validationRegex
（省略可）
（パラメータ type が string の場合にのみ使用）

文字列

パラメータのユーザー構成値を検証するための正規表現文字列

正規表現は、go ライブラリ RE2 を使用してコンパイルされます

検証の詳細については、下記の検証とエラーメッセージをご覧ください。

validationErrorMessage
（省略可）

文字列

validationRegex が失敗した場合に表示されるエラーメッセージ

エラーメッセージの詳細については、下記の検証とエラーメッセージをご覧ください。

default
（省略可）

文字列

ユーザーがパラメータの値を指定しなかった場合に使用されるデフォルト値

必要に応じて、default 値に自動入力パラメータの値を指定できます（例: 画像のサイズを変更する拡張機能の IMG_BUCKET パラメータ）。

required
（省略可）

ブール値

ユーザーがパラメータの値の入力を求められたときに空の文字列を送信できるかどうかを定義します

required を省略すると、この値はデフォルトで true（つまり必須パラメータ）になります。

immutable
（省略可）

ブール値

ユーザーがインストール後にパラメータの値を変更できるかどうかを定義します（拡張機能を再構成する場合など）

immutable を省略すると、この値はデフォルトで false になります。

注: デプロイされる拡張機能の関数の「location」パラメータを定義する場合は、この immutable フィールドを param オブジェクトに含める必要があります。

ユーザー構成の値の検証とエラーメッセージ

string type でパラメータを設定する場合は、パラメータの validationRegex フィールドで適切な正規表現検証を定義する必要があります。

また、多くの拡張機能では、一般的にリクエストされるパラメータ値はデータベースパスまたは Cloud Storage バケットです。インストール、再構成、更新の際、Extensions サービスは、パラメータ値が入力された時点では以下を検証しません。

指定したデータベースまたは Cloud Storage バケットがユーザーの Firebase プロジェクト内で設定されているかどうか
指定したデータベースパスがユーザーのデータベース内に存在するかどうか

ただし、拡張機能が実際にリソースをデプロイするときに、プロジェクトに参照データベースまたは Cloud Storage バケットがまだ設定されていない場合は、Firebase コンソールまたは Firebase CLI でエラーメッセージが表示されます。

拡張機能を正常にインストールして動作させるために、上記の要件を PREINSTALL ファイルでユーザーに通知することを強くおすすめします。

システムパラメータ

システムパラメータは、拡張機能のリソースの基本構成を制御します。リソース構成を制御するために、関数のコード内から環境変数としてアクセスすることはできません。

通常、これらのパラメータは extension.yaml で宣言する必要はありません。拡張機能のインスタンスごとに自動的に定義され、ユーザーは拡張機能のインストール時にカスタム値を設定できます。

ただし、拡張機能で特別なリソース要件がある場合は、extension.yaml でリソースごとに特定の値を設定できます。リソースごとの構成設定は、ユーザーの拡張機能インスタンス全体の設定をオーバーライドします。次に例を示します。

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

使用可能なシステムパラメータは次のとおりです。

名前	ラベル（人間が理解しやすい）	`properties` の対応フィールド	説明
firebaseextensions.v1beta.function/location	場所	`location`	Cloud Functions の関数のデプロイ先リージョン
firebaseextensions.v1beta.function/memory	関数のメモリ	`memory`	各関数に何メガバイトのメモリを割り当てるべきか。
firebaseextensions.v1beta.function/timeoutSeconds	関数のタイムアウト	`timeout`	関数の実行がタイムアウトするまでの秒数
firebaseextensions.v1beta.function/vpcConnectorEgressSettings	VPC コネクタの下り（外向き）	`vpcConnectorEgressSettings`	VPC コネクタが構成されている場合の送信トラフィックの制御
firebaseextensions.v1beta.function/vpcConnector	VPC コネクタ	`vpcConnector`	指定された VPC コネクタと Cloud Functions の接続
firebaseextensions.v1beta.function/minInstances	関数の最小インスタンス数	`minInstances`	この関数を一度に実行する場合のインスタンスの最小数
firebaseextensions.v1beta.function/maxInstances	関数インスタンスの最大数	`maxInstances`	この関数を一度に実行する場合のインスタンスの最大数
firebaseextensions.v1beta.function/ingressSettings	上り（内向き）設定	`ingressSettings`	受信トラフィックの送信元の制御
firebaseextensions.v1beta.function/labels	ラベル	`labels`	拡張機能内のすべてのリソースに適用するラベル