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

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

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

Несмотря на то, что 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 .

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

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

При настройке параметра с 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 Сколько мегабайт памяти следует выделить каждой функции?
firebaseextensions.v1beta.function/timeoutСекунды Тайм-аут функции 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 Метки, применяемые ко всем ресурсам в расширении