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

Текущее значение: v1beta

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

Лицензия на расширение.

Ваше расширение должно быть лицензировано с использованием Apache-2.0 .

billingRequired
логическое значение
(необязательный)

Требуется ли для служб, используемых расширением, учетная запись для выставления счетов Firebase платного уровня.

Всегда устанавливайте значение true .

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

Понятное отображаемое имя расширения (3–5 слов).

Ограничение в 40 символов.

description
нить
(необязательный)		 Краткое описание задачи, которую выполняет ваше расширение (~1 предложение).
icon
нить
(необязательный)

Файл, который будет использоваться в качестве значка вашего расширения на extensions.dev и консоли Firebase .

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

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

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

Ограничьте область действия роли этим ресурсом.

Если этот параметр опущен, по умолчанию используется 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 .

Примечание. Если вы определяете параметр «местоположение» для развернутых функций вашего расширения, установите для этого поля значение 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

Однако в настоящее время только сегменты 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

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

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

В этих полях объявляются облачные функции, включенные в расширение. Синтаксис объявления ресурсов выглядит немного по-разному для функций 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
нить
(необходимый)

Понятное имя для экспортируемой функции.

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

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

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

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

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

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

Характеристики
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
(необходимый)

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

Характеристики
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
(необязательный)		 Фильтры, которые еще больше ограничивают прослушиваемые события. Например, вы можете прослушивать только события, соответствующие определенному шаблону ресурса. Дополнительную информацию о фильтрации каждого типа событий см. в разделе «Функции записи облака» для расширения .
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 полей, разделенных точками: поля идентификатора издателя, имени расширения и названия события являются обязательными; рекомендуется использовать поле версии. Выберите уникальное и описательное название мероприятия для каждого типа публикуемого вами мероприятия.
description
нить
(необходимый)		 Описание события.