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.

Dica: tanto Realtime Database quanto Cloud Storage permitem várias instâncias e buckets de banco de dados, respectivamente, em um único banco de dados em um projeto do Firebase. Portanto, convém configurar parâmetros configurados pelo usuário para solicitar que os usuários especifiquem qual instância ou bucket eles gostariam que a extensão usasse (em vez de presumir que os usuários querem a extensão para usar a instância ou o intervalo padrão do projeto).

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: project-id.appspot.com Exemplo de valor: project-123.appspot.com
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 Coloque aspas em volta dessas strings para evitar conversões de tipo não intencionais. O campo value é obrigatório para o campo options. Se label for omitido, a opção de lista exibirá value por padrão. exemplo de sintaxe options: - label: value: - label: value: - label: value:
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. Por 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