Configure e use parâmetros em 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 variáveis ​​de ambiente para 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 sua extensão, no arquivo extension.yaml e no arquivo POSTINSTALL.md . Esta é a sintaxe de como fazer referência a um parâmetro chamado PARAMETER_NAME :

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

• Dentro de 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 padrão 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 ID 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 instalação da extensão.

Embora o Firebase preencha automaticamente esses valores de parâmetro para a extensão, o Firebase não provisiona automaticamente os produtos associados para o usuário durante a instalação . O usuário que instala a extensão deve habilitar os produtos associados e aplicáveis ​​em seu projeto antes da instalação. Por exemplo, se sua extensão envolver o Cloud Firestore, o usuário deverá 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, você pode pedir ao usuário para especificar valores de parâmetros durante a instalação. Para solicitar esses valores, configure os prompts na seção params do seu arquivo extension.yaml .

Aqui está 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 seu 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 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 intervalo do Cloud Storage. Esteja ciente de que durante a instalação, reconfiguração ou atualização, o serviço de extensões não valida o seguinte no momento da entrada do valor do parâmetro:

• Se o banco de dados ou 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 do Firebase exibirá uma mensagem de erro se o banco de dados referenciado ou bucket do Cloud Storage ainda não estiver configurado no projeto.

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

Parâmetros do sistema

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

Normalmente você não precisa declarar nada para esses parâmetros em extension.yaml . Eles são definidos 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, você poderá definir valores específicos por recurso em extension.yaml . Essas definições de configuração por recurso substituirão as configurações de extensão da instância do 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 do sistema disponíveis são: