Как настроить и использовать параметры в расширении

Параметры – это механизм, с помощью которого пользователь настраивает каждый установленный экземпляр расширения. Параметры – это переменные среды для расширения. Значения параметров могут заполняться автоматически (предоставляются Firebase после установки) или настраиваться пользователем (указываются пользователем во время установки).

Эти параметры доступны для использования в исходном коде функций расширения, а также в файлах extension.yaml и POSTINSTALL.md. Вот синтаксис для ссылки на параметр PARAMETER_NAME:

  • В исходном коде функций используйте модуль params (например, params.defineInt("PARAMETER_NAME")) или process.env.PARAMETER_NAME.

  • Внутри extension.yaml и POSTINSTALL.md используйте ${param:PARAMETER_NAME}.

    После установки в консоли Firebase отображается содержимое файла POSTINSTALL.md, а ссылки на параметры заменяются фактическими значениями для установленного экземпляра.

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

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

Все автоматически заполненные значения параметров являются неизменяемыми. Они задаются при создании проекта или установке расширения.

Хотя Firebase автоматически заполняет значения этих параметров для расширения, Firebase не предоставляет пользователю связанные продукты автоматически во время установки. Пользователь, устанавливающий расширение, должен включить связанные и применимые продукты в своем проекте до установки. Например, если в расширении используется Cloud Firestore, пользователь должен настроить Cloud Firestore в своем проекте. Рекомендуем сообщить пользователям об этих требованиях в файле PREINSTALL.md.

Справочник по автоматически заполняемым параметрам Описание Значение параметра (предоставляется Firebase)
Параметры со значениями по умолчанию из проекта Firebase
PROJECT_ID Уникальный идентификатор проекта Firebase, в котором установлено расширение.

Общий формат:
project-id

Пример значения:
project-123

DATABASE_URL URL экземпляра Realtime Database по умолчанию для проекта Firebase.

Общий формат:
https://project-id-default-rtdb.firebaseio.com
(для США)
или
https://project-id-default-rtdb.region-code.firebasedatabase.app
(для других стран)

Пример значения:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Название экземпляра Realtime Database, используемого в проекте Firebase по умолчанию.

Обычно это значение совпадает с идентификатором проекта или заканчивается на -default-rtdb.

Общий формат:
project-id

Пример значения:
project-123

STORAGE_BUCKET Название сегмента Cloud Storage, используемого в проекте Firebase по умолчанию.

Общий формат:
PROJECT_ID.firebasestorage.app

Пример значения:
project-123.firebasestorage.app

Параметр со значением по умолчанию из установки расширения
EXT_INSTANCE_ID

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

Это значение генерируется на основе поля name, указанного в файле extension.yaml.

Общий формат для первого установленного экземпляра (назначается автоматически Firebase, не может быть изменен пользователем во время установки):
name-from-extension.yaml

Пример значения:
my-awesome-extension


Общий формат для второго и последующих установленных экземпляров (назначается Firebase автоматически, может быть изменен пользователем во время установки):
name-from-extension.yaml-4-digit-alphanumeric-hash

Пример значения:
my-awesome-extension-6m31

Параметры, настраиваемые пользователем

Чтобы пользователь мог настраивать каждый установленный экземпляр расширения, вы можете попросить его указать значения параметров во время установки. Чтобы запросить эти значения, настройте подсказки в разделе params файла extension.yaml.

Ниже приведен пример раздела params и таблица с описанием всех доступных полей параметров.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

В разделе params файла extension.yaml используйте следующие поля, чтобы определить параметр, настраиваемый пользователем:

Поле Тип Описание
param
(обязательно)
string Название параметра.
label
(обязательно)
string

Краткое описание параметра.

Показывается пользователю, когда ему предлагается ввести значение параметра.

description
(необязательно)
string

Подробное описание параметра

Показывается пользователю, когда ему предлагается ввести значение параметра.

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

type
(необязательно)
string

Способ ввода значения параметра (например, ввод текста или выбор из раскрывающегося списка).

Допустимые значения:

  • string – позволяет вводить текст в свободной форме (с учетом ограничений, заданных в validationRegex).
  • select – позволяет выбрать один вариант из заданного списка. Если вы указываете это значение, то также должны определить поле options.
  • multiSelect – позволяет выбрать один или несколько вариантов из списка. Если вы указываете это значение, то также должны определить поле options.
  • selectResource – позволяет выбрать определенный тип ресурса Firebase (например, сегмент Cloud Storage) из проекта пользователя.

    Если вы укажете параметр этого типа, пользователи увидят более удобный виджет выбора в интерфейсе установки. По этой причине мы рекомендуем по возможности использовать параметры selectResource.

    Если вы указываете это значение, то также должны определить поле resourceType.

  • secret – позволяет хранить конфиденциальные строки, например ключи API для сторонних сервисов. Эти значения будут храниться в Cloud Secret Manager.

    Cloud Secret Manager – это платный сервис, использование которого может привести к расходам для пользователей, установивших ваше расширение. Если вы используете тип параметра secret, обязательно укажите в файле PREINSTALL, что ваше расширение использует Cloud Secret Manager.

Если это поле не заполнено, по умолчанию используется значение type из string.

options
(обязательно, если параметр type имеет значение select или multiSelect)
list

Список значений, из которых пользователь может выбрать нужное

Включите поля label и value в поле options:

  • label (string): краткое описание доступного варианта.
  • value (string) – фактическое значение выбираемого варианта.

Поле value является обязательным для поля options.
Если параметр label не указан, по умолчанию используется значение value.

resourceType
(обязательно, если параметр type равен selectResource)
string

Тип ресурса Firebase, который пользователю будет предложено выбрать. В настоящее время селекторы ресурсов поддерживаются только в следующих сегментах Cloud Storage:

Тип ресурса Идентификатор типа
Сегментов: Cloud Storage storage.googleapis.com/Bucket

Неизвестные значения resourceType будут игнорироваться, а параметр будет отображаться в интерфейсе как поле ввода string в свободной форме.

example
(необязательно)
string

Примеры значений параметров

validationRegex
(необязательно)
(применяется, только если параметр type имеет значение string)
string

Строка регулярного выражения для проверки значения параметра, заданного пользователем.

Регулярное выражение компилируется с помощью библиотеки RE2.

Подробные сведения о проверке приведены в разделе Проверка и сообщения об ошибках ниже.

validationErrorMessage
(необязательно)
string

Сообщение об ошибке, которое будет показано, если validationRegex не сработает.

Подробную информацию о сообщениях об ошибках можно найти в разделе Проверка и сообщения об ошибках ниже.

default
(необязательно)
string

Значение параметра по умолчанию, если пользователь не указал его.

При необходимости вы можете указать значение автоматически заполняемого параметра для значения default (например, см. параметр IMG_BUCKET расширения Resize Images).

required
(необязательно)
Логическое значение

Определяет, может ли пользователь отправить пустую строку, когда ему предлагается ввести значение параметра.

Если параметр required не указан, по умолчанию используется значение true (то есть параметр является обязательным).

immutable
(необязательно)
Логическое значение

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

Если параметр immutable не указан, по умолчанию используется значение false.

Примечание. Если вы определяете параметр "location" для развернутых функций расширения, то вам следует включить это поле immutable в объект param.

Проверка и сообщения об ошибках для значений, настроенных пользователем

Если вы задаете параметр с типом type, равным string, вам нужно определить подходящую проверку регулярного выражения в поле validationRegex параметра.

Кроме того, для многих расширений часто запрашиваемым значением параметра является путь к базе данных или сегмент Cloud Storage. Обратите внимание, что во время установки, изменения конфигурации или обновления сервис Extensions не проверяет следующие значения параметров при их вводе:

  • Настроена ли указанная база данных или сегмент Cloud Storage в проекте Firebase пользователя.
  • Существует ли указанный путь к базе данных в базе данных пользователя.

Однако при развертывании ресурсов расширения в консоли Firebase или интерфейсе командной строки Firebase появится сообщение об ошибке, если в проекте ещё не настроена база данных или сегмент Cloud Storage.

Настоятельно рекомендуем сообщить пользователям об этих требованиях в файле PREINSTALL, чтобы они могли успешно установить расширение и оно работало должным образом.

Системные параметры

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

Обычно в extension.yaml не нужно ничего объявлять для этих параметров. Они автоматически определяются для каждого экземпляра расширения, и пользователи могут задавать собственные значения при установке расширения.

Однако если вашему расширению требуются особые ресурсы, вы можете задать определенные значения на уровне ресурсов в файле extension.yaml. Эти настройки переопределят настройки расширения на уровне экземпляра. Пример:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

Доступны следующие системные параметры:

Имя Ярлык (в понятном формате) Соответствующее поле в properties Описание
firebaseextensions.v1beta.function/location Местоположение location В каком регионе следует развернуть Cloud Functions?
firebaseextensions.v1beta.function/memory Память функции memory Сколько мегабайт памяти нужно выделить для каждой функции?
firebaseextensions.v1beta.function/timeoutSeconds Время ожидания функции истекло timeout Сколько секунд должны выполняться функции до истечения времени ожидания?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Исходящий трафик коннектора VPC vpcConnectorEgressSettings Управляет исходящим трафиком, когда настроен коннектор VPC.
firebaseextensions.v1beta.function/vpcConnector Коннектор VPC vpcConnector Подключает Cloud Functions к указанному коннектору VPC.
firebaseextensions.v1beta.function/minInstances Минимальное количество экземпляров функции minInstances Минимальное количество экземпляров этой функции, которые могут выполняться одновременно.
firebaseextensions.v1beta.function/maxInstances Максимальное число экземпляров функции maxInstances Максимальное количество экземпляров этой функции, которые могут выполняться одновременно.
firebaseextensions.v1beta.function/ingressSettings Настройки Ingress ingressSettings Управляет тем, откуда принимается входящий трафик.
firebaseextensions.v1beta.function/labels Ярлыки labels Ярлыки, которые нужно применить ко всем ресурсам в расширении.