Файл спецификации вашего расширения ( 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-го поколения. Наиболее важные свойства перечислены ниже, но полный список вы можете найти в справочнике по облачным функциям .
|
Облачные функции второго поколения
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 нить (необходимый) | Описание события. |