Ссылка на расширение.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 символов.

Примечание: это значение используется для генерации идентификатора экземпляра расширения (который затем используется для генерации имен учетной записи службы расширения и ресурсов, специфичных для расширения).

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 .

Этот файл должен быть квадратным PNG-изображением размером от 512x512 до 1024x1024 пикселей. Поместите файл в тот же каталог, что и extension.yaml ; указать подкаталог нельзя.

При разработке значка для вашего расширения учитывайте следующие рекомендации:

  • Выберите цвета фона и оформления, соответствующие вашему бренду.
  • Используйте простые цвета значка, всего два. Использование нескольких цветов может сделать значок визуально перегруженным.
  • По той же причине не используйте градиенты в иконке. Градиенты трудно различимы на маленьких размерах и делают иконку визуально сложной.
  • Используйте простые и уникальные изображения, передающие функциональность вашего расширения.
  • Если ваша компания выпускает несколько расширений, не используйте свой логотип в качестве значка. Пользователям будет сложно различать ваши расширения.
  • Сделайте рисунок графичным и выразительным. Не используйте изящные или сложные рисунки, которые будут плохо смотреться в уменьшенном размере.
  • Не добавляйте слова, объясняющие назначение вашего расширения. Текст часто неразборчив при меньшем размере.
tags
список строк
(необязательный)
Теги, которые помогут пользователям найти ваше расширение. Следующие теги соответствуют категориям в Extensions 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/
Поля автора
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-адрес, по которому можно получить доступ к информации об авторе.

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 ( пример ) в библиотеке API Google Cloud.

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} . См. раздел Сокращение области действия ролей .

Внешние услуги

В этих полях указаны службы, не относящиеся к 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
нить
(необязательный)

Подробное описание параметра. Отображается пользователю при запросе значения параметра.

Поддерживает Markdown.

example
нить
(необязательный)
Пример значения параметра.
default
нить
(необязательный)
Значение по умолчанию для параметра, если пользователь оставляет значение параметра пустым.
validationRegex
нить
(необязательный)
Регулярное выражение для проверки заданного пользователем значения параметра. Синтаксис Google RE2 .
validationErrorMessage
нить
(необязательный)
Сообщение об ошибке, отображаемое в случае сбоя проверки регулярного выражения.
required
булев
(необязательный)
Определяет, может ли пользователь отправить пустую строку при запросе значения параметра. Значение по умолчанию — true .
immutable
булев
(необязательный)

Определяет, может ли пользователь изменить значение параметра после установки (например, при перенастройке расширения). Значение по умолчанию — false .

Примечание: Если вы определяете параметр «местоположение» для развернутых функций вашего расширения, установите для этого поля значение true .

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
нить

select или multiSelect

Указывает, что параметр может иметь одно значение ( select ) или несколько значений ( multiSelect ), выбранных из набора предопределенных вариантов.

options
список опций
(необходимый)

Варианты, из которых пользователь может выбирать

Поля параметров
value
нить
(необходимый)
Одно из значений, которое может выбрать пользователь. Это значение, которое вы получите при считывании значения параметра в коде.
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

Однако в настоящее время пользовательский интерфейс выбора имеется только для контейнеров облачного хранилища (другие типы ресурсов представлены в виде полей ввода текста в свободной форме).

Секретные параметры

Предоставляемые пользователем секретные значения (например, ключи API) обрабатываются по-разному:

  • Секретные значения хранятся в Cloud Secret Manager. Доступ к этим значениям имеют только авторизованные клиенты (например, установленный экземпляр расширения).
  • Когда пользователям предлагается ввести эти значения, введенные ими данные не отображаются.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Поля секретных параметров
type
нить

secret

Указывает, что параметр имеет секретное значение.

Ресурсы облачных функций

Эти поля объявляют облачные функции, включённые в расширение. Синтаксис объявления ресурсов немного различается для функций первого и второго поколений, которые могут существовать в одном расширении одновременно.

Облачные функции 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
нить
(необходимый)

Удобное для пользователя имя экспортируемой функции.

Если вы не укажете свойство entryPoint (см. ниже), это значение должно совпадать с именем функции в исходном коде вашей функции.

Окончательное имя развернутой функции будет иметь следующий формат: ext- extension-instance-id - name .

type
нить
(необходимый)
Для функционального ресурса 1-го поколения: firebaseextensions.v1beta.function
description
нить
(необходимый)

Краткое описание задачи, которую выполняет функция для расширения.

properties
(необходимый)

Свойства облачных функций первого поколения. Наиболее важные свойства перечислены ниже, но полный список можно найти в справочнике по облачным функциям .

Характеристики
location
(необязательный)

Место, куда будет развернута функция. По умолчанию — us-central1

entryPoint
(необязательный)
Имя экспортированной функции в исходном коде функций, которое должно искать расширение. По умолчанию используется значение name , указанное выше.
sourceDirectory
(необязательный)

Каталог, содержащий ваш package.json в корне. Файл с исходным кодом ваших функций должен находиться в этом каталоге. По умолчанию — functions

Примечание: main поле package.json указывает файл исходного кода ваших функций (например, index.js ).

timeout
(необязательный)

Максимальное время выполнения функции.

  • По умолчанию: 60s
  • Максимальное значение: 540s
availableMemoryMb
(необязательный)

Объем памяти в МБ, доступный для функции.

  • По умолчанию: 256
  • Допустимые значения: 128 , 256 , 512 , 1024 и 2048
runtime
(рекомендуется)

Среда выполнения функции.

httpsTrigger
или
eventTrigger
или
scheduleTrigger
или
taskQueueTrigger
(требуется один из этих типов триггера функции)
Подробную информацию о каждом типе триггера см. в разделе Запись облачных функций для расширения .

Облачные функции 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
нить
(необходимый)

Удобное для пользователя имя экспортируемой функции.

Если вы не укажете свойство entryPoint (см. ниже), это значение должно совпадать с именем функции в исходном коде вашей функции.

Окончательное имя развернутой функции будет иметь следующий формат: ext- extension-instance-id - name .

type
нить
(необходимый)
Для функционального ресурса 2-го поколения: firebaseextensions.v1beta.v2function
description
нить
(необходимый)

Краткое описание задачи, которую выполняет функция для расширения.

properties
(необходимый)

Свойства облачных функций второго поколения. Наиболее важные свойства перечислены ниже, но полный список можно найти в справочнике по облачным функциям .

Характеристики
location
(необязательный)

Место, куда будет развернута функция. По умолчанию — us-central1

sourceDirectory
(необязательный)

Каталог, содержащий ваш package.json в корне. Файл с исходным кодом ваших функций должен находиться в этом каталоге. По умолчанию — functions

Примечание: main поле package.json указывает файл исходного кода ваших функций (например, index.js ).

Также имеются три поля объектного типа со своими собственными свойствами:

свойства buildConfig
buildConfig.runtime
(рекомендуется)

Среда выполнения функции.

buildConfig.entryPoint
(необязательный)
Имя экспортированной функции в исходном коде функций, которое должно искать расширение. По умолчанию используется значение name , указанное выше.
свойства serviceConfig
serviceConfig.timeoutSeconds
(необязательный)

Максимальное время выполнения функции.

  • По умолчанию: 60
  • Максимальное значение: 540
serviceConfig.availableMemory
(необязательный)
Объём памяти, доступный для функции. По умолчанию 256M . Поддерживаемые единицы измерения: k , M , G , Mi , Gi . Если единица измерения не указана, значение интерпретируется как байты.
Свойства eventTrigger
eventTrigger.eventType
(необходимый)
Тип события, которое нужно отслеживать. Подробнее о типах событий, доступных для каждого продукта, см. в разделе «Запись облачных функций».
eventTrigger.eventFilters
(необязательный)
Фильтры, которые дополнительно ограничивают прослушиваемые события. Например, можно прослушивать только события, соответствующие определённому шаблону ресурса. Подробнее о фильтрации каждого типа событий см. в разделе Write 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
нить
(необходимый)
Идентификатор типа события. Составьте идентификатор из 3–4 полей, разделенных точками: поля «ID издателя», «Название расширения» и «Название события» являются обязательными; поле «Версия» рекомендуется. Выберите уникальное и описательное имя для каждого типа публикуемого события.
description
нить
(необходимый)
Описание события.