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 a extensão envolver o Cloud Firestore, o usuário precisará configurar o Cloud Firestore no projeto. Recomendamos notificar seus usuários sobre esses requisitos no arquivo PREINSTALL.md.

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:

options:
  - label:
    value:
  - label:
    value:
  - label:
    value:

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 extensões 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 os recursos, o Console do Firebase ou a CLI do Firebase exibirá uma mensagem de erro se o banco de dados referenciado ou o bucket do 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
    memory: 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: