Файл спецификации вашего расширения ( 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 символов. Примечание. Это значение используется для создания идентификатора экземпляра расширения (который затем используется для создания имен учетной записи службы расширения и ресурсов, специфичных для расширения). | ||||||||
versionнить (необходимый) | Версия расширения. Должно соответствовать версии Semver (например, 1.2.0). | ||||||||
specVersionнить (необходимый) | Версия спецификации расширений Firebase. Текущее значение: | ||||||||
licenseнить (необязательный) | Лицензия на расширение. Ваше расширение должно быть лицензировано с использованием | ||||||||
billingRequiredлогическое значение (необязательный) | Требуется ли для служб, используемых расширением, учетная запись для выставления счетов Firebase платного уровня. Всегда устанавливайте значение | ||||||||
displayNameнить (необязательный) | Понятное отображаемое имя расширения (3–5 слов). Ограничение в 40 символов. | ||||||||
descriptionнить (необязательный) | Краткое описание задачи, которую выполняет ваше расширение (~1 предложение). | ||||||||
iconнить (необязательный) | Файл, который будет использоваться в качестве значка вашего расширения на Этот файл должен представлять собой квадратный PNG размером от 512x512 до 1024x1024 пикселей. Поместите файл в тот же каталог, что и При разработке значка для вашего расширения помните следующие рекомендации:
| ||||||||
tagsсписок строк (необязательный) | Теги, которые помогут пользователям обнаружить ваше расширение. Следующие теги соответствуют категориям в Extension Hub: marketing , messaging , payments , search , shipping , social , utilities , ai | ||||||||
sourceUrlнить (необязательный) | Публичный URL-адрес, по которому можно получить доступ к каталогу расширений. | ||||||||
releaseNotesUrlнить (необязательный) | Общедоступный URL-адрес, по которому можно получить доступ к примечаниям к выпуску расширения. | ||||||||
authorодин авторский объект (необязательный) | Основной автор и контактное лицо расширения. author: authorName: Your Company email: extensions@example.com url: https://example.com/
| ||||||||
contributorsсписок авторских объектов (необязательный) | Любые дополнительные авторы, участвовавшие в расширении.
contributors:
- authorName: Your Name
- authorName: Another Contributor
email: colleague@example.net
url: https://github.com/their-org/
| ||||||||
API Firebase и Google Cloud
В этих полях указаны API-интерфейсы Firebase и Google, которые использует расширение. Когда пользователи устанавливают расширение, они могут автоматически включить эти 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нить (необходимый) | Название API Google Должно соответствовать полю имени службы , указанному на странице обзора каждого API ( пример ) в библиотеке Google Cloud 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нить (необязательный) | Ограничьте область действия роли этим ресурсом. Если этот параметр опущен, по умолчанию используется |
Внешние услуги
В этих полях указаны службы, не относящиеся к 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логическое значение (необязательный) | Определяет, может ли пользователь изменить значение параметра после установки (например, если он переконфигурирует расширение). По умолчанию установлено значение Примечание. Если вы определяете параметр «местоположение» для развернутых функций вашего расширения, установите для этого поля значение |
typeнить (необязательный) | Тип параметра. Специальные типы параметров могут иметь дополнительные требования или другое представление пользовательского интерфейса. См. следующие разделы. |
Выбираемые и множественные выбираемые параметры
Выбираемые и множественные параметры предлагают пользователям выбирать из списка предопределенных параметров.
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нить | Указывает, что параметр может иметь одно значение ( | ||||||
optionsсписок опций (необходимый) | Варианты, из которых пользователь может выбирать
| ||||||
Выбираемые параметры ресурса
Выбираемые параметры ресурса предлагают пользователям выбрать ресурс (экземпляр базы данных, сегмент хранилища и т. д.) из своего проекта.
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нить | Указывает, что параметр представляет ресурс проекта. |
resourceTypeнить (необходимый) | Тип ресурса, который пользователю предлагается выбрать. Допустимые значения:
Однако в настоящее время только сегменты 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нить | Указывает, что параметр является секретным значением. |
Ресурсы облачных функций
В этих полях объявляются облачные функции, включенные в расширение. Синтаксис объявления ресурсов выглядит немного по-разному для функций 1-го и 2-го поколения, которые могут сосуществовать в расширении.
Облачные функции 1-го поколения
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нить (необходимый) | Понятное имя для экспортируемой функции. Если вы не укажете свойство Окончательное имя развернутой функции будет иметь следующий формат: | ||||||||||||||||
typeнить (необходимый) | Для функционального ресурса 1-го поколения: firebaseextensions.v1beta.function | ||||||||||||||||
descriptionнить (необходимый) | Краткое описание, какую задачу выполняет функция для расширения. | ||||||||||||||||
properties(необходимый) | Свойства облачных функций 1-го поколения. Наиболее важные свойства перечислены ниже, но полный список вы можете найти в справочнике по облачным функциям .
| ||||||||||||||||
Облачные функции 2-го поколения
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нить (необходимый) | Понятное имя для экспортируемой функции. Если вы не укажете свойство Окончательное имя развернутой функции будет иметь следующий формат: | ||||||||||||||||||||||||||||
typeнить (необходимый) | Для функционального ресурса 2-го поколения: firebaseextensions.v1beta.v2function | ||||||||||||||||||||||||||||
descriptionнить (необходимый) | Краткое описание, какую задачу выполняет функция для расширения. | ||||||||||||||||||||||||||||
properties(необходимый) | Свойства облачных функций 2-го поколения. Наиболее важные свойства перечислены ниже, но полный список вы можете найти в справочнике по облачным функциям .
Также есть три поля объектного типа со своими свойствами:
| ||||||||||||||||||||||||||||
События жизненного цикла
События жизненного цикла позволяют указать функции, которые будут выполняться, когда пользователь устанавливает, обновляет или настраивает экземпляр вашего расширения. См. раздел «Обработка событий жизненного цикла вашего расширения» .
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(необязательный) | Указывает функцию, которая запускается, когда пользователь устанавливает расширение.
| ||||||
onUpdate(необязательный) | Указывает функцию, которая запускается, когда пользователь обновляет расширение.
| ||||||
onConfigure(необязательный) | Указывает функцию, которая запускается, когда пользователь повторно настраивает расширение.
| ||||||
Пользовательские события (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нить (необходимый) | Идентификатор типа события. Составьте идентификатор из 3–4 полей, разделенных точками: поля идентификатора издателя, имени расширения и названия события являются обязательными; рекомендуется использовать поле версии. Выберите уникальное и описательное название мероприятия для каждого типа публикуемого вами мероприятия. |
descriptionнить (необходимый) | Описание события. |