Ссылка на расширение.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 ; вы не можете указать подкаталог.

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

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

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

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

Эти поля объявляют функции Cloud, включенные в расширение. Синтаксис объявления ресурсов выглядит немного по-разному для функций 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
(необходимый)		 Тип события для прослушивания. См. Write Cloud Functions для расширения типов событий, доступных для каждого продукта.
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 полей, разделенных точками: поля идентификатора издателя, имени расширения и имени события являются обязательными; поле версии рекомендуется. Выберите уникальное и описательное имя события для каждого типа событий, которые вы публикуете.
description
нить
(необходимый)		 Описание события.