extension.yaml のリファレンス

拡張機能の仕様ファイル（extension.yaml）には拡張機能のメタデータが含まれています。拡張機能によって作成されるリソース、拡張機能に必要な API とアクセス権が宣言され、ユーザーによって提供されるユーザー構成パラメータが定義されています。

このページの表では、extension.yaml ファイルで使用できるフィールドについて説明します。

基本情報と識別情報

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/

基本フィールド

name
文字列
（必須）

拡張機能の識別子。

小文字、数字、ダッシュのみを使用できます。最大 40 文字。

注: この値は、拡張機能のインスタンス ID を生成するために使用されます（インスタンス ID は、拡張機能のサービスアカウント名と拡張機能固有のリソース名の生成に使用されます）。

version
文字列
（必須）

拡張機能のバージョン。

semver のバージョニングに従う必要があります（例: 1.2.0）

specVersion
文字列
（必須）

Firebase Extensions 仕様のバージョン。

現在の値: v1beta

license
文字列
（省略可）

拡張機能のライセンス。

拡張機能は、Apache-2.0 を使用してライセンスを取得する必要があります。

billingRequired
ブール値
（省略可）

拡張機能で使用するサービスに有料階層の Firebase 請求先アカウントが必要かどうか。

常に true に設定。

displayName
文字列
（省略可）

拡張機能のわかりやすい表示名（3～5 語）。

最大 40 文字。

description
文字列
（省略可）拡張機能で実行されるタスクの簡単な説明（1 文以内）。

icon
文字列
（省略可）

extensions.dev と Firebase コンソールで拡張機能のアイコンとして使用するファイル。

このファイルは、512x512～1024x1024 ピクセルの正方形の PNG にする必要があります。ファイルを extension.yaml と同じディレクトリに配置します。サブディレクトリは指定できません。

拡張機能のアイコンを設計する際は、次のガイドラインに注意してください。

ブランドに適した背景とアートワークの色を選択します。
アイコンの色をシンプルにします（2 色のみを使用）。複数の色を使用するとアイコンが見づらくなることがあります。
同じ理由で、アイコンにグラデーションを使用しないでください。小さなサイズではグラデーションを認識するのは困難で、アイコンが見づらくなります。
拡張機能の機能を伝えるシンプルな独自の画像を使用します。
会社で複数の拡張機能を作成する場合は、アイコンにロゴを使用しないでください。拡張機能の区別が難しくなります。
アートワークはグラフィックにし、太線で表します。繊細なアートや緻密なアートは使用しないでください。サイズが小さいと、うまくレンダリングされません。
拡張機能の動作を説明する単語は使用しないでください。サイズが小さいと、テキストが読みづらくなります。

tags
文字列のリスト
（省略可）拡張機能を見つけやすくするためのタグ。次のタグは、Extensions Hub のカテゴリにマッピングされています。marketing、messaging、payments、search、shipping、social、utilities、ai。

sourceUrl
文字列
（省略可）拡張機能ディレクトリにアクセスできる公開 URL。

releaseNotesUrl
文字列
（省略可）拡張機能のリリースノートにアクセスできる公開 URL。

author
1 つの作成者オブジェクト
（省略可）

拡張機能の主要な作成者と連絡先。

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/

作成者のフィールド

authorName
文字列
（必須）

作成者の名前。

個人、会社、組織などを指定できます。

email
文字列
（省略可）作成者のメールアドレス。

url
文字列
（省略可）作成者に関する情報にアクセスできる公開 URL。

contributors
作成者オブジェクトのリスト
（省略可）

拡張機能の作成に参加しているその他の作成者

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/

作成者のフィールド

authorName
文字列
（必須）

作成者の名前。

個人、会社、組織などを指定できます。

email
文字列
（省略可）作成者のメールアドレス。

url
文字列
（省略可）作成者に関する情報にアクセスできる公開 URL。

Firebase API と Google Cloud API

これらのフィールドには、拡張機能が使用する Firebase API と Google API を指定します。拡張機能をインストールするときに、これらの API をプロジェクトで自動的に有効にするかどうか選択できます。

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API

API フィールド
`apiName` 文字列（必須）	Google API の名前 Google Cloud API ライブラリの各 API の概要ページ（例）で示されているサービス名フィールドに対応している必要があります。
`reason` 文字列（必須）	拡張機能でこの API を使用する必要がある理由の簡単な説明。

API フィールド

apiName
文字列
（必須）

Google API の名前

Google Cloud API ライブラリの各 API の概要ページ（例）で示されているサービス名フィールドに対応している必要があります。

reason
文字列
（必須）拡張機能でこの API を使用する必要がある理由の簡単な説明。

IAM ロール

これらのフィールドには、拡張機能に必要な Cloud IAM ロールを指定します。これらのロールは、拡張機能にプロビジョニングされたサービスアカウントに付与されます。

指定できるのは、サポートされているロールのみです。

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access

ロールのフィールド
`role` 文字列（必須）	拡張機能が動作するために必要な IAM ロールの名前。サポートされているロールのいずれかである必要があります。
`reason` 文字列（必須）	このロールによって付与されるアクセス権が拡張機能に必要な理由の簡単な説明。
`resource` 文字列（省略可）	ロールの範囲をこのリソースに制限します。省略された場合、デフォルトの `projects/${project_id}` になります。ロールの範囲を減らすをご覧ください。

ロールのフィールド

role
文字列
（必須）

拡張機能が動作するために必要な IAM ロールの名前。

サポートされているロールのいずれかである必要があります。

reason
文字列
（必須）このロールによって付与されるアクセス権が拡張機能に必要な理由の簡単な説明。

resource
文字列
（省略可）

ロールの範囲をこのリソースに制限します。

省略された場合、デフォルトの projects/${project_id} になります。ロールの範囲を減らすをご覧ください。

外部サービス

これらのフィールドには、拡張機能が使用する Firebase 以外のサービスと Google 以外のサービス（通常は REST API）を指定します。Firebase Extensions プラットフォームには、これらのサービスを自動的に有効にしたり認可する手段はありません。

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing

外部サービスフィールド
`name` 文字列（必須）	拡張機能の動作に必要な外部サービスの名前
`pricingUri` 文字列（必須）	サービスの料金情報の URI

ユーザー構成可能なパラメータ

これらのフィールドにより、ユーザーが構成できる拡張機能のパラメータが決まります。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true

パラメータフィールド
`param` 文字列（必須）	パラメータの名前。この名前は、コード内のパラメータ値を参照する際に使用します。
`label` 文字列（必須）	パラメータの簡単な説明。ユーザーにパラメータ値の入力を求めるときに表示されます。
`description` 文字列（省略可）	パラメータの詳細な説明。ユーザーにパラメータ値の入力を求めるときに表示されます。マークダウンがサポートされます。
`example` 文字列（省略可）	パラメータの値の例。
`default` 文字列（省略可）	ユーザーがパラメータの値を指定しなかった場合に使用されるデフォルト値。
`validationRegex` 文字列（省略可）	パラメータのユーザー構成値を検証するための正規表現。Google RE2 構文。
`validationErrorMessage` 文字列（省略可）	正規表現の検証に失敗した場合に表示されるエラーメッセージ。
`required` ブール値（省略可）	ユーザーがパラメータの値の入力を求められたときに空の文字列を送信できるかどうかを定義します。デフォルトは `true` です。
`immutable` ブール値（省略可）	ユーザーがインストール後にパラメータの値を変更できるかどうかを定義します（拡張機能を再構成する場合など）。デフォルトは `false` です。注: 拡張機能のデプロイ済み関数に location パラメータを定義する場合は、このフィールドを `true` に設定します。
`type` 文字列（省略可）	パラメータの型。特別なパラメータタイプがあると、追加の要件や UI の表示が異なる場合があります。次のセクションをご覧ください。

選択可能なパラメータと複数選択が可能なパラメータ

選択可能なパラメータと複数選択が可能なパラメータを使用すると、事前定義のオプションのリストから選択するようにユーザーに促すことができます。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiSelect
    options:
      - value: red
      - value: green
      - value: blue

複数選択パラメータのフィールド

type
文字列

select または multiSelect

パラメータを事前定義のオプションから選択した 1 つの値（select）または複数の値（multiSelect）にできることを指定します。

options
オプションのリスト
（必須）

ユーザーが選択できるオプション

省略可能なフィールド
`value` 文字列（必須）	ユーザーが選択できる値の 1 つ。これは、コードでパラメータ値を読み取るときに取得される値です。
`label` 文字列（省略可）	選択可能なオプションの簡単な説明。省略した場合、デフォルトの `value` になります。

選択可能なリソースパラメータ

選択可能なリソースパラメータを使用すると、プロジェクトからリソース（データベースインスタンス、ストレージバケットなど）を選択するように求められます。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType

リソースパラメータフィールド
`type` 文字列	`selectresource` パラメータがプロジェクトリソースを表すことを指定します。
`resourceType` 文字列（必須）	ユーザーに選択を求めるリソースのタイプ。有効な値: `storage.googleapis.com/Bucket` `firestore.googleapis.com/Database` `firebasedatabase.googleapis.com/DatabaseInstance` 現在、選択 UI があるのは Cloud Storage バケットのみです（他のリソースタイプは自由形式のテキスト入力フィールドとして表示されます）。

リソースパラメータフィールド

type
文字列

selectresource

パラメータがプロジェクトリソースを表すことを指定します。

resourceType
文字列
（必須）

ユーザーに選択を求めるリソースのタイプ。

有効な値:

storage.googleapis.com/Bucket
firestore.googleapis.com/Database
firebasedatabase.googleapis.com/DatabaseInstance

現在、選択 UI があるのは Cloud Storage バケットのみです（他のリソースタイプは自由形式のテキスト入力フィールドとして表示されます）。

シークレットパラメータ

ユーザーが指定したシークレット値（API キーなど）は異なる方法で処理されます。

シークレット値は Cloud Secret Manager を使用して保存されます。これらの値にアクセスできるのは、承認済みのクライアント（インストールされている拡張機能のインスタンスなど）だけです。
ユーザーがプロンプトに従ってこれらの値を入力するときに、入力値は表示されません。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret

シークレットパラメータフィールド
`type` 文字列	`secret` パラメータがシークレット値であることを指定します

シークレットパラメータフィールド

type
文字列

secret

パラメータがシークレット値であることを指定します

Cloud Functions の関数のリソース

これらのフィールドでは、拡張機能に含まれる Cloud Functions の関数を宣言します。リソース宣言の構文は第 1 世代と第 2 世代の関数で若干異なりますが、これらの関数は拡張機能内で共存できます。

第 1 世代の Cloud Functions の関数

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier

リソースフィールド

name
文字列
（必須）

エクスポートされた関数のわかりやすい名前。

entryPoint プロパティ（下記参照）を指定しない場合、この値は関数のソースコード内の関数の名前と一致する必要があります。

デプロイされた関数の最終的な名前は、ext-extension-instance-id-name の形式になります。

type
文字列
（必須）第 1 世代の関数のリソースの場合: firebaseextensions.v1beta.function

description
文字列
（必須）

関数が拡張機能に対して実行するタスクの簡単な説明。

properties
（必須）

第 1 世代の Cloud Functions の関数のプロパティ。以下に最も重要なプロパティを示します。すべてのリストについては、Cloud Functions のリファレンスをご覧ください。

プロパティ
`location` （省略可）	関数のデプロイ先。デフォルトは `us-central1` です。
`entryPoint` （省略可）	拡張機能が検索する関数のソースコード内にエクスポートされた関数の名前。デフォルトは、上の `name` の値です。
`sourceDirectory` （省略可）	ルートに `package.json` を含むディレクトリ。関数のソースコードのファイルは、このディレクトリに配置する必要があります。デフォルトは `functions` です。注: `package.json` の `main` フィールドには、関数のソースコードのファイル（`index.js` など）を指定します。
`timeout` （省略可）	関数の最大実行時間。デフォルト: `60s` 最大値: `540s`
`availableMemoryMb` （省略可）	関数で使用可能なメモリ量（MB 単位）。デフォルト: `256` 有効な値: `128`、`256`、`512`、`1024`、`2048`
`runtime` （推奨）	関数のランタイム環境。デフォルトは、現在 Cloud Functions でサポートされている Node.js バージョンの最新バージョンです。有効な値: `nodejs14`、`nodejs16`、`nodejs18`
`httpsTrigger` または `eventTrigger` または `scheduleTrigger` または `taskQueueTrigger` （これらの関数トリガータイプの 1 つが必要）	各トリガータイプの詳細については、拡張機能の Cloud Functions の関数を作成するをご覧ください。

第 2 世代の Cloud Functions の関数

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue

リソースフィールド

name
文字列
（必須）

エクスポートされた関数のわかりやすい名前。

entryPoint プロパティ（下記参照）を指定しない場合、この値は関数のソースコード内の関数の名前と一致する必要があります。

デプロイされた関数の最終的な名前は、ext-extension-instance-id-name の形式になります。

type
文字列
（必須）第 2 世代の関数のリソースの場合: firebaseextensions.v1beta.v2function

description
文字列
（必須）

関数が拡張機能に対して実行するタスクの簡単な説明。

properties
（必須）

第 2 世代の Cloud Functions の関数プロパティ。以下に最も重要なプロパティを示します。すべてのリストについては、Cloud Functions のリファレンスをご覧ください。

プロパティ

location
（省略可）

関数のデプロイ先。デフォルトは us-central1 です。

sourceDirectory
（省略可）

ルートに package.json を含むディレクトリ。関数のソースコードのファイルは、このディレクトリに配置する必要があります。デフォルトは functions です。

注: package.json の main フィールドには、関数のソースコードのファイル（index.js など）を指定します。

また、独自のプロパティを持つオブジェクトタイプフィールドが 3 つあります。

buildConfig プロパティ

buildConfig.runtime
（推奨）

関数のランタイム環境。

デフォルトは、現在 Cloud Functions でサポートされている Node.js バージョンの最新バージョンです。
有効な値: nodejs14、nodejs16、nodejs18

buildConfig.entryPoint
（省略可）拡張機能が検索する関数のソースコード内にエクスポートされた関数の名前。デフォルトは、上の name の値です。

serviceConfig プロパティ

serviceConfig.timeoutSeconds
（省略可）

関数の最大実行時間。

デフォルト: 60
最大値: 540

serviceConfig.availableMemory
（省略可）関数で使用できるメモリの量。デフォルトは 256M です。サポートされている単位は k、M、G、Mi、Gi です。単位を指定しない場合、値はバイトとして解釈されます。

eventTrigger プロパティ
`eventTrigger.eventType` （必須）	リッスンするイベントのタイプ。各プロダクトで使用できるイベントタイプについては、拡張機能の Cloud Functions の関数を作成するをご覧ください。
`eventTrigger.eventFilters` （省略可）	リッスンするイベントをさらに制限するフィルタ。たとえば、特定のリソースパターンに一致するイベントのみをリッスンできます。各タイプのイベントのフィルタリングについては、拡張機能の Cloud Functions の関数を作成するをご覧ください。
`eventTrigger.channel` （省略可）	トリガーに関連付けられたチャネルの名前（`projects/{project}/locations/{location}/channels/{channel}` 形式）。このプロパティを省略すると、関数はプロジェクトのデフォルトチャネルでイベントをリッスンします。
`eventTrigger.triggerRegion` （省略可）	トリガーは、このリージョンで発生したイベントのみを受信します。関数と同じリージョン、異なるリージョンまたはマルチリージョン、グローバルリージョンのいずれかになります。指定しない場合、デフォルトは関数と同じリージョンになります。

ライフサイクルイベント

ライフサイクルイベントを使用すると、ユーザーが拡張機能のインスタンスをインストール、更新、または構成する際に実行する関数を指定できます。拡張機能のライフサイクルイベントを処理するをご覧ください。

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed

ライフサイクルイベントフィールド

onInstall
（省略可）

ユーザーが拡張機能をインストールしたときに実行する関数を指定します。

関数の仕様

function
文字列
（必須）

イベントを処理するタスクキューでトリガーされる関数の名前。

この関数は、resources セクションで宣言し、taskQueue を定義する必要があります。

processingMessage
文字列
（必須）タスクの進行中に Firebase コンソールに表示されるメッセージ。

onUpdate
（省略可）

ユーザーが拡張機能を更新したときに実行する関数を指定します。

関数の仕様

function
文字列
（必須）

イベントを処理するタスクキューでトリガーされる関数の名前。

この関数は、resources セクションで宣言し、taskQueue を定義する必要があります。

processingMessage
文字列
（必須）タスクの進行中に Firebase コンソールに表示されるメッセージ。

onConfigure
（省略可）

ユーザーが拡張機能を再構成したときに実行される関数を指定します。

関数の仕様

function
文字列
（必須）

イベントを処理するタスクキューでトリガーされる関数の名前。

この関数は、resources セクションで宣言し、taskQueue を定義する必要があります。

processingMessage
文字列
（必須）タスクの進行中に Firebase コンソールに表示されるメッセージ。

カスタムイベント（Eventarc）

カスタムイベントは、ユーザーが拡張機能に独自のロジックを挿入できるように拡張機能が出力するイベントです。拡張機能にユーザーフックを追加するの Eventarc セクションをご覧ください。

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event

カスタムイベントフィールド
`type` 文字列（必須）	イベントのタイプ ID。3～4 個のドット区切りフィールドの ID を作成します。ID、拡張機能名、イベント名のフィールドは必須です。バージョンのフィールドは推奨です。公開するイベントタイプごとに、一意でわかりやすいイベント名を選択します。
`description` 文字列（必須）	イベントの説明。

パラメータフィールド
`param` 文字列（必須）	パラメータの名前。この名前は、コード内のパラメータ値を参照する際に使用します。
`label` 文字列（必須）	パラメータの簡単な説明。ユーザーにパラメータ値の入力を求めるときに表示されます。
`description` 文字列（省略可）	パラメータの詳細な説明。ユーザーにパラメータ値の入力を求めるときに表示されます。マークダウンがサポートされます。
`example` 文字列（省略可）	パラメータの値の例。
`default` 文字列（省略可）	ユーザーがパラメータの値を指定しなかった場合に使用されるデフォルト値。
`validationRegex` 文字列（省略可）	パラメータのユーザー構成値を検証するための正規表現。Google RE2 構文。
`validationErrorMessage` 文字列（省略可）	正規表現の検証に失敗した場合に表示されるエラーメッセージ。
`required` ブール値（省略可）	ユーザーがパラメータの値の入力を求められたときに空の文字列を送信できるかどうかを定義します。デフォルトは `true` です。
`immutable` ブール値（省略可）	ユーザーがインストール後にパラメータの値を変更できるかどうかを定義します（拡張機能を再構成する場合など）。デフォルトは `false` です。注: 拡張機能のデプロイ済み関数に location パラメータを定義する場合は、このフィールドを `true` に設定します。
`type` 文字列（省略可）	パラメータの型。特別なパラメータタイプがあると、追加の要件や UI の表示が異なる場合があります。次のセクションをご覧ください。

extension.yaml のリファレンス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

基本情報と識別情報

Firebase API と Google Cloud API

IAM ロール

外部サービス

ユーザー構成可能なパラメータ

選択可能なパラメータと複数選択が可能なパラメータ

選択可能なリソース パラメータ

シークレット パラメータ

Cloud Functions の関数のリソース

第 1 世代の Cloud Functions の関数

第 2 世代の Cloud Functions の関数

ライフサイクル イベント

カスタム イベント（Eventarc）

extension.yaml のリファレンス

選択可能なリソースパラメータ

シークレットパラメータ

ライフサイクルイベント

カスタムイベント（Eventarc）