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

Версия расширения.

Необходимо использовать семантическое версионирование (например, 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
список строк
(необязательный)		 Теги помогут пользователям найти ваше расширение. Следующие теги соответствуют категориям в Центре расширений: 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

These fields specify the Cloud IAM roles the extension requires. The service account provisioned for the extension is granted these roles.

Вы можете указать только одну из поддерживаемых ролей .

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
нить
(необязательный)		 Регулярное выражение для проверки заданного пользователем значения параметра. Синтаксис RE2 от Google .
validationErrorMessage
нить
(необязательный)		 Сообщение об ошибке, которое будет отображаться в случае неудачной проверки регулярного выражения.
required
логический
(необязательный)		 Определяет, может ли пользователь ввести пустую строку при запросе значения параметра. По умолчанию — true .
immutable
логический
(необязательный)

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

Примечание: Если вы определяете параметр "location" для развернутых функций вашего расширения, установите для этого поля значение 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. Доступ к этим значениям имеют только авторизованные клиенты (например, установленный экземпляр расширения).
  • When users are prompted to provide these values, their input is not displayed. 
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Секретные поля параметров
type
нить

secret

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

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

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

Облачные функции первого поколения 

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
нить
(необходимый)		 Для ресурса функции первого поколения: 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
нить
(необходимый)		 Для ресурса функции второго поколения: firebaseextensions.v1beta.v2function
description
нить
(необходимый)

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

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

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

Характеристики
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
(необязательный)		 Триггер будет получать только события, исходящие из этого региона. Это может быть тот же регион, что и функция, другой регион, многорегиональный регион или глобальный регион. Если регион не указан, по умолчанию используется тот же регион, что и функция.

События жизненного цикла

Lifecycle events let you specify functions that will run when a user installs, updates, or configure an instance of your extension. See Handle your extension's lifecycle events . 

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
нить
(необходимый)		 Описание события.