Configurar e usar parâmetros na sua extensão

Os parâmetros são o mecanismo pelo qual um usuário personaliza cada instância instalada de uma extensão. Os parâmetros são como as variáveis de ambiente de uma extensão. Os valores dos parâmetros podem ser preenchidos automaticamente (fornecidos pelo Firebase após a instalação) ou configurados pelo usuário (especificados pelo usuário durante a instalação).

Esses parâmetros estão disponíveis para referência no código-fonte das funções da extensão, no arquivo extension.yaml e no arquivo POSTINSTALL.md. Confira a sintaxe de como fazer referência a um parâmetro chamado PARAMETER_NAME:

  • No código-fonte das funções, use o módulo params (por exemplo, params.defineInt("PARAMETER_NAME")) ou process.env.PARAMETER_NAME.

  • Em extension.yaml e POSTINSTALL.md, use ${param:PARAMETER_NAME}.

    Após a instalação, o console do Firebase exibe o conteúdo do arquivo POSTINSTALL.md e preenche todas as referências de parâmetro com os valores reais da instância instalada.

Parâmetros preenchidos automaticamente

Cada instância instalada de uma extensão tem acesso automático a vários parâmetros preenchidos automaticamente fornecidos pelo Firebase (consulte a tabela abaixo). Esses valores de parâmetro são os valores padrão do projeto do Firebase (como o intervalo de armazenamento padrão) ou são específicos da extensão (como o código da instância da extensão).

Todos os valores de parâmetros preenchidos automaticamente são imutáveis. Eles são definidos no momento da criação do projeto ou da instalação da extensão.

Mesmo que o Firebase preencha automaticamente esses valores de parâmetro para a extensão, o Firebase não provisiona automaticamente os produtos associados ao usuário durante a instalação. O usuário que instala a extensão precisa ativar os produtos associados e aplicáveis no projeto antes da instalação. Por exemplo, se sua extensão envolver Cloud Firestore, o usuário precisará configurou Cloud Firestore no em um projeto de IA. Recomendamos notificar seus usuários sobre esses requisitos no arquivo PREINSTALL.md.

Referência para o parâmetro preenchido automaticamente Descrição Valor do parâmetro (fornecido pelo Firebase)
Parâmetros com valores padrão do projeto do Firebase
PROJECT_ID Identificador exclusivo do projeto do Firebase em que a extensão está instalada

Formato generalizado:
project-id

Exemplo de valor:
project-123

DATABASE_URL O URL da instância Realtime Database padrão do projeto do Firebase

Formato geral:
https://project-id-default-rtdb.firebaseio.com
(instâncias nos EUA)
ou
https://project-id-default-rtdb.region-code.firebasedatabase.app
(instâncias fora dos EUA)

Exemplo de valor:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

O nome da instância Realtime Database padrão do projeto do Firebase

Normalmente, esse valor é o mesmo que o ID do projeto ou termina em -default-rtdb.

Formato geral:
project-id

Exemplo de valor:
project-123

STORAGE_BUCKET O nome do bucket do Cloud Storage padrão do projeto do Firebase

Formato generalizado:

Exemplo de valor:
project-123.firebasestorage.app

Parâmetro com valor padrão da instalação da extensão
EXT_INSTANCE_ID

Identificador exclusivo da instância de extensão instalada

Esse valor é gerado a partir do name campo especificado no arquivo extension.yaml.

Formato generalizado para a primeira instância instalada (atribuído automaticamente pelo Firebase; não pode ser modificado pelo usuário durante a instalação):
name-from-extension.yaml

Exemplo de valor:
my-awesome-extension


Formato generalizado para a segunda instância instalada e superior (atribuído automaticamente pelo Firebase; pode ser modificado pelo usuário durante a instalação):
name-from-extension.yaml-4-digit-alphanumeric-hash

Exemplo de valor:
my-awesome-extension-6m31

Parâmetros configurados pelo usuário

Para permitir que um usuário personalize cada instância instalada de uma extensão, solicite que o usuário especifique valores de parâmetro durante a instalação. Para solicitar esses valores, configure as solicitações na seção params do arquivo extension.yaml.

Veja um exemplo de seção params, seguida por uma tabela que descreve todos os campos de parâmetros disponíveis.

# 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

Na seção params do arquivo extension.yaml, use os seguintes campos para definir um parâmetro configurado pelo usuário:

Campo Tipo Descrição
param
(obrigatório) 		string Nome do parâmetro
label
(obrigatório) 		string

Breve descrição do parâmetro

Exibido ao usuário quando for solicitado o valor do parâmetro
description
(opcional) 		string

Descrição detalhada do parâmetro

Exibido ao usuário quando for solicitado o valor do parâmetro

Compatível com a marcação

type
(opcional) 		string

Mecanismo de entrada sobre como o usuário define o valor do parâmetro (por exemplo, insira o texto diretamente ou selecione na lista suspensa)

Os valores válidos incluem:

  • string: permite a entrada de texto em formato livre (conforme limitado por validationRegex)
  • select: permite a seleção de uma entrada de uma lista de opções predefinidas. Se você especificar esse valor, também precisará definir o campo options.
  • multiSelect: permite a seleção de uma ou mais entradas de uma lista de opções predefinidas. Se você especificar esse valor, também precisará definir o campo options.
  • selectResource: permite a seleção de um tipo específico de recurso do Firebase (como um bucket do Cloud Storage) no projeto do usuário.

    Quando você especifica um parâmetro desse tipo, os usuários recebem um widget de seleção mais intuitivo na interface de instalação. Por esse motivo, use os parâmetros selectResource sempre que possível.

    Se você especificar esse valor, também precisará definir o campo resourceType.

  • secret: permite o armazenamento de strings confidenciais, como chaves de API para serviços de terceiros. Esses valores serão armazenados no Cloud Secret Manager.

    O Cloud Secret Manager é um serviço pago que pode gerar cobranças para usuários que instalam sua extensão. Se você usar o tipo de parâmetro secret, documente no arquivo PREINSTALL que a extensão usa o Cloud Secret Manager.

Se esse campo for omitido, o padrão do parâmetro será type de string.

options
(obrigatório se o parâmetro type for select ou multiSelect) 		list

Lista de valores a partir de que o usuário pode selecionar

Inclua os campos label e value no campo options:

  • label (string): breve descrição da opção selecionável
  • value (string): valor real da opção selecionável

O campo value é obrigatório para o campo options.
Se label for omitido, a opção de lista exibirá value por padrão.
resourceType
(obrigatório se o parâmetro type for selectResource) 		string

O tipo de recurso do Firebase para pedir ao usuário a seleção. No momento, apenas buckets Cloud Storage são compatíveis com seletores de recursos:

Tipo de recurso ID do tipo
Cloud Storage bucket storage.googleapis.com/Bucket

Valores resourceType desconhecidos serão ignorados, e a interface renderizará o parâmetro como um campo de entrada string de formato livre.
example
(opcional) 		string

Exemplo de valor para o parâmetro
validationRegex
(opcional)
(aplicável somente quando o parâmetro type é string)		 string

String de regex para validação do valor configurado pelo usuário do parâmetro

O Regex é compilado usando a biblioteca go: RE2

Para detalhes sobre validação, consulte Mensagens de validação e erro abaixo.

validationErrorMessage
(opcional) 		string

Mensagem de erro a ser exibida se o validationRegex falhar

Para detalhes sobre mensagens de erro, consulte Validação e mensagens de erro abaixo.

default
(opcional) 		string

Valor padrão do parâmetro se o usuário deixar o valor do parâmetro em branco

Se aplicável, especifique um valor Parâmetro preenchido automaticamente para o valor default (para ver um exemplo, consulte o parâmetro IMG_BUCKET da extensão Redimensionar imagens).

required
(opcional) 		booleano

Define se o usuário pode enviar uma string vazia quando for solicitado o valor do parâmetro

Se required for omitido, o valor padrão será true (ou seja, um parâmetro obrigatório).
immutable
(opcional) 		booleano

Define se o usuário pode alterar o valor do parâmetro após a instalação (por exemplo, se ele reconfigurar a extensão)

Se immutable for omitido, o valor padrão será false.

Observação: se você definir um parâmetro "location" para as funções implantadas da extensão, inclua esse campo immutable no objeto de parâmetro.

Validação e mensagens de erro para valores configurados pelo usuário

Ao configurar um parâmetro com o type de string, você precisa definir a validação de regex apropriada por meio do campo validationRegex do parâmetro.

Além disso, para muitas extensões, um valor de parâmetro comumente solicitado é um caminho de banco de dados ou bucket do Cloud Storage. Durante a instalação, reconfiguração ou atualização, o serviço de Extensions não valida o seguinte no momento do valor do parâmetro entry:

  • Se o banco de dados ou o bucket do Cloud Storage especificado está configurado no projeto do Firebase do usuário
  • Se o caminho do banco de dados especificado existe no banco de dados do usuário

No entanto, quando a extensão estiver realmente implantando seus recursos, o console do Firebase ou a CLI Firebase exibirá uma mensagem de erro se o banco de dados referenciado ou o bucket Cloud Storage ainda não estiver configurado no projeto.

Recomendamos que você notifique os usuários no arquivo PREINSTALL sobre esses requisitos para que, quando instalarem sua extensão, ela seja instalada e funcione conforme esperado.

Parâmetros do sistema

Os parâmetros do sistema controlam a configuração básica dos recursos de uma extensão. Como eles se destinam a controlar a configuração de recursos, eles não são acessíveis como variáveis de ambiente do código da função.

Normalmente, não é necessário declarar nada para esses parâmetros em extension.yaml. Elas são definidas automaticamente para cada instância de extensão, e os usuários têm a oportunidade de definir valores personalizados ao instalar sua extensão.

No entanto, se sua extensão tiver requisitos de recursos especiais, será possível definir valores específicos em um nível por recurso em extension.yaml. Essas definições de configuração por recurso vão modificar as definições da extensão para todo o usuário. Exemplo:

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

Os parâmetros de sistema disponíveis são os seguintes:

Nome Rótulo (de fácil entendimento) Campo correspondente em properties Descrição
firebaseextensions.v1beta.function/location Local location Em qual região o Cloud Functions precisa ser implantado?
firebaseextensions.v1beta.function/memory Memória da função memory Quantos megabytes de memória devem ser alocados para cada função?
firebaseextensions.v1beta.function/timeoutSeconds Tempo limite da função timeout Por quantos segundos as funções devem ser executadas antes de expirar?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Saída do conector de VPC vpcConnectorEgressSettings Controla o tráfego de saída quando um conector de VPC está configurado
firebaseextensions.v1beta.function/vpcConnector Conector de VPC vpcConnector Conecta o Cloud Functions ao conector de VPC especificado.
firebaseextensions.v1beta.function/minInstances Instâncias mínimas da função minInstances O número mínimo de instâncias dessa função a serem executadas de uma vez
firebaseextensions.v1beta.function/maxInstances Máximo de instâncias de função maxInstances O número máximo de instâncias dessa função a serem executadas de uma vez
firebaseextensions.v1beta.function/ingressSettings Configurações de entrada ingressSettings Controla de onde o tráfego de entrada é aceito
firebaseextensions.v1beta.function/labels Marcadores labels Rótulos para aplicar a todos os recursos na extensão