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

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

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

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

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

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

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

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

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

Совет. И Realtime Database и Cloud Storage позволяют использовать несколько экземпляров базы данных и сегментов соответственно в одном проекте 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 (необходимый)	нить	Имя параметра
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 . пример синтаксиса options: - label: value: - label: value: - 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 отобразит сообщение об ошибке, если указанная база данных или сегмент 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	В каком регионе следует развернуть облачные функции?
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	Ярлыки для применения ко всем ресурсам в расширении.