拡張機能でパラメータを設定して使用する

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

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

  • 関数のソースコード内で、params モジュールparams.defineInt("PARAMETER_NAME") など)または process.env.PARAMETER_NAME を使用します。

  • extension.yamlPOSTINSTALL.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-id.appspot.com

値の例:
project-123.appspot.com

拡張機能のインストールからデフォルト値が設定されるパラメータ
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
(パラメータ typeselect または multiSelect の場合は必須)
list

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

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

  • label(文字列): 選択可能なオプションの簡単な説明
  • value(文字列): 選択可能なオプションの実際の値

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

resourceType
(パラメータ typeselectResource の場合は必須)
文字列

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

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

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

example
(省略可)
文字列

パラメータの値の例

validationRegex
(省略可)
(パラメータ typestring の場合にのみ使用)
文字列

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

正規表現は、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 拡張機能内のすべてのリソースに適用するラベル