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

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

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

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

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

Параметр со значением по умолчанию из установки расширения.
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 .

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 Метки, которые будут применяться ко всем ресурсам в расширении.