Настройте и используйте параметры в своем расширении

Параметры — это механизм, с помощью которого пользователь настраивает каждый установленный экземпляр расширения. Параметры подобны переменным среды для расширения. Значения параметров могут быть либо автоматически заполнены (предоставлены 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 .

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

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


Обобщенный формат для 2-го установленного экземпляра и выше (автоматически назначается 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
(необходимый)		 нить Имя параметра
label
(необходимый)		 нить

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

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

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

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

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

Поддерживает уценку

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

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

Допустимые значения включают следующее:

  • 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 )		 список

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

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

  • label (строка) : краткое описание выбираемой опции
  • value (строка) : фактическое значение выбираемой опции

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

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

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

Тип ресурса Тип идентификатора
Cloud Storage storage.googleapis.com/Bucket

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

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

Пример значения параметра

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

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

Regex скомпилирован с использованием библиотеки go: RE2

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

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

Сообщение об ошибке, которое будет отображаться в случае сбоя validationRegex

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

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

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

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

required
(необязательный)		 булев

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

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

immutable
(необязательный)		 булев

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

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

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

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

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

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

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

Однако когда расширение фактически развертывает свои ресурсы, консоль Firebase или Firebase CLI отобразят сообщение об ошибке, если указанная база данных или контейнер 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 Подключает облачные функции к указанному соединителю VPC.
firebaseextensions.v1beta.function/minInstances Минимальные экземпляры функций minInstances Минимальное количество экземпляров этой функции для одновременного запуска
firebaseextensions.v1beta.function/maxInstances Максимальное количество экземпляров функции maxInstances Максимальное количество экземпляров этой функции, которые можно запустить одновременно
firebaseextensions.v1beta.function/ingressSettings Настройки входа ingressSettings Контролирует, откуда принимается входящий трафик
firebaseextensions.v1beta.function/labels Этикетки labels Метки, применяемые ко всем ресурсам в расширении