Instalar uma extensão do Firebase

É possível instalar (e gerenciar) qualquer uma das extensões oficiais do Firebase usando o console Firebase, a CLI do Firebase (interface de linha de comando) ou um SDK gerado automaticamente.

Analise as diferenças nas ações compatíveis com cada método de instalação.

Console do Firebase CLI do Firebase SDK gerado automaticamente

A instalação usando um SDK gerado automaticamente é uma nova opção para instalar e gerenciar extensões. Com essa opção, você usa a CLI para gerar automaticamente um SDK do Node para uma versão específica da extensão, que pode ser importada como uma dependência comum nas suas funções do Cloud em JavaScript ou TypeScript.

Esse SDK gerado automaticamente contém:

• Uma interface que representa os parâmetros da extensão e declarações de tipo para a maioria dos tipos de parâmetros não primitivos.
• Uma função de construtor que inicializa uma instância da extensão
• Uma classe de extensão que contém acionadores do Eventarc para todos os eventos emitidos pela extensão.

Depois de gerar um SDK de extensão, toda a configuração da extensão acontece no código.

O uso dessa opção de instalação pode simplificar muito o gerenciamento de várias instâncias de extensão, principalmente em projetos que contêm funções do Cloud definidas fora das extensões.

Para testar uma extensão do Firebase Extension pela primeira vez, recomendamos que você instale a extensão em um projeto de teste ou desenvolvimento.

Para instalar ou gerenciar extensões, é necessário atribuir um destes papéis: Proprietário ou Editor ou Administrador do Firebase.

Para instalar uma extensão, o projeto precisa estar no plano Blaze (pagamento por utilização). A instalação de uma extensão é feita sem custos financeiros, mas você poderá receber cobranças pelo uso de serviços do Firebase ou do Cloud, como o Cloud Secret Manager, se o uso exceder o Nível sem custos financeiros dos serviços.

Antes de começar

1. Adicione o Firebase ao seu projeto, caso ainda não tenha feito isso.

2. Faça upgrade do seu projeto para o plano Blaze (pagamento por utilização), se ainda não tiver feito isso.

3. Instale ou atualize para a versão mais recente da CLI Firebase.

4. Anote o ID do projeto do Firebase ou o alias do projeto configurado anteriormente.

   • ID do projeto: execute firebase projects:list de qualquer lugar no computador.
   • Alias do projeto: execute firebase use no diretório local de apps.
   Observação: para instalar e gerenciar extensões usando comandos da CLI, você precisa ter um projeto do Firebase associado ao diretório local de apps. Execute firebase init para configurar um diretório local do Firebase caso ainda não tenha feito isso.

Etapa 1: visualizar informações detalhadas sobre uma extensão

Esta etapa é opcional, mas altamente recomendada.

Antes de instalar um Firebase Extension, recomendamos que você leia informações detalhadas sobre a extensão, incluindo:

• Como a extensão funciona, as tarefas de pré-instalação e os detalhes sobre ela
• Informações gerais de identificação e descrição
• Se as tarefas da extensão exigem uma conta de faturamento
• Serviços do Google (APIs) e papéis de acesso necessários para operação
• Recursos criados para a extensão (como funções)
• Descrições de parâmetros configuráveis pelo usuário

Para visualizar as informações detalhadas de uma extensão:

1. Verifique se você configurou seu ambiente e selecionou uma extensão.

2. Execute o comando extension-info em qualquer lugar no seu computador:

   firebase ext:info publisher-id/extension-id

   Os argumentos publisher-id e extension-id são obrigatórios e podem ser encontrados na página de detalhes da pré-instalação da extensão.

Observação: é possível também visualizar essas informações detalhadas no README incluído no diretório de extensão.

Etapa 2: instalar uma extensão

Antes da instalação, analise as especificações básicas da extensão (como APIs ativadas, recursos criados, acesso concedido etc.) e os requisitos de faturamento.

Antes de continuar, verifique se você configurou seu ambiente e selecionou uma extensão.

Inicializar o Cloud Functions para Firebase

Se você estiver iniciando um novo projeto ou se ele ainda não usa o Cloud Functions para Firebase, execute init functions:

cd your-project
firebase init functions

Escolha TypeScript ou JavaScript como a linguagem das funções.

Se o projeto já tiver o Cloud Functions inicializado, verifique se você está usando a versão 5.1.0 ou mais recente do pacote firebase-functions:

cd your-project/functions
npm upgrade --save firebase-functions

Se você usa o ESLint, também é possível excluir os SDKs gerados da configuração (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Gerar um SDK de extensão

No diretório local do Firebase, execute o comando ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

Por exemplo, para instalar a versão 0.1.34 da extensão firestore-send-email:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

Os argumentos publisher-id e extension-id são obrigatórios e podem ser encontrados na página de detalhes de pré-instalação da extensão em extensions.dev. A parte @version é opcional. Se você omiti-la, a ferramenta vai instalar a versão mais recente.

Há duas opções que você pode especificar:

• --force: faça o seguinte sem mais confirmações:

  • Gere automaticamente o SDK, mesmo que um já tenha sido gerado para a mesma extensão e versão.
  • Instale o pacote do SDK gerado automaticamente no projeto do Node do Cloud Functions.

• --codebase: o nome da base de código para adicionar o SDK. Se não for especificado, o comando vai adicionar o SDK à base de código padrão, functions.

Esse comando cria um pacote do Node que contém um SDK gerado automaticamente para a extensão e o adiciona a uma das bases de código do Cloud Functions do projeto. Na base de código padrão (functions), o SDK é salvo no seguinte local:

functions/generated/extensions/publisher-id/extension-id/version

Depois de gerar o SDK, o comando vai perguntar se você também quer instalar o SDK no seu projeto do Node para a API Cloud Functions. Responda Sim a esse comando.

Configurar instâncias de extensão

Para configurar a extensão, importe o SDK e, para cada instância de extensão que você quer instalar, chame a função do construtor, transmitindo um ID de instância exclusivo do projeto e os parâmetros de configuração exigidos pela extensão.

1. Na origem do Cloud Functions, importe o construtor usando a instrução gerada pelo comando ext:sdk:install.

   TypeScript

   Por exemplo, se você gerou um SDK para a extensão firestore-send-email, a instrução import vai ser semelhante a esta:

   import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";
   

   Se a extensão exigir valores de secrets, como senhas, você também vai precisar da função defineSecret do SDK do Cloud Functions:

   import { defineSecret } from "firebase-functions/params";
   

   JavaScript

   Por exemplo, se você gerou um SDK para a extensão firestore-send-email, a instrução require vai ser semelhante a esta:

   const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");
   

   Se a extensão exigir valores de secrets, como senhas, você também vai precisar da função defineSecret do SDK do Cloud Functions:

   const { defineSecret } = require('firebase-functions/params');
   

2. Para cada instância que você quer configurar, chame a função do construtor e exporte o resultado.

   Dê a cada instância um ID exclusivo, contendo apenas letras minúsculas, números e hifens.

   TypeScript

   export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
       SMTP_CONNECTION_URI: "smtps://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       TTL_EXPIRE_VALUE: "1",
       TTL_EXPIRE_TYPE: "day",
   });
   

   JavaScript

   exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
       SMTP_CONNECTION_URI: "smtps://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       TTL_EXPIRE_VALUE: "1",
       TTL_EXPIRE_TYPE: "day",
   });
   

   Os valores secretos precisam ser especificados usando a função defineSecret.

3. Em seguida, para implantar as extensões configuradas, execute:

   firebase deploy --only functions --project=projectId-or-alias

   Todas as opções usuais de implantação do Cloud Functions se aplicam. Por exemplo, para implantar uma única instância de extensão de uma base de código específica:

   firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

   Observação: a instalação e o provisionamento de uma extensão podem levar de três a cinco minutos.

Etapa 3: concluir a configuração pós-instalação

Algumas extensões têm etapas obrigatórias ou opcionais para você concluir antes de usá-las. Encontre essas instruções na página de detalhes de pós-instalação da extensão no painel "Extensions" do Console do Firebase (o link específico para o painel é exibido no terminal após a instalação).

Essas instruções também podem ser encontradas no arquivo POSTINSTALL.md incluído no diretório de origem da extensão.

Criar recursos do Firebase

Se você configurou a extensão para usar recursos do Firebase (coleções do Cloud Firestore, caminhos do Realtime Database e buckets do Cloud Storage) que ainda não existem, crie-os antes de usar a extensão.

Criar manipuladores de eventos do Eventarc

Algumas extensões são publicadas no Eventarc quando eventos importantes acontecem durante a execução. Se uma extensão publicar eventos, você poderá escrever funções que reagem a esses eventos com sua própria lógica personalizada. Isso pode ser útil, por exemplo, para notificar os usuários quando tarefas de longa duração forem concluídas ou para pós-processar a saída de uma função de extensão.

Se você quiser definir gerenciadores para qualquer um dos eventos emitidos pela extensão, faça isso usando os métodos de acionamento de cada instância:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Você precisa exportar o manipulador de eventos com a instância da extensão.

Depois de definir um manipulador de eventos e sempre que fizer mudanças nele, reimplante a extensão e o gerenciador.

Importante: a ativação de eventos poderá resultar em cobranças se você exceder a cota sem custos financeiros. Consulte Preços do Eventarc.

Instalar várias instâncias de extensões

É possível instalar a mesma extensão mais de uma vez no mesmo projeto. Cada instância instalada pode ter sua própria configuração personalizada e recursos de extensão. Identifique e faça referência a cada instância instalada usando o ID da instância exclusivo do projeto.

Chame a função de construtor do SDK gerado automaticamente uma vez para cada instância que você quer instalar e configurar.

Próximas etapas

• Veja os detalhes e a configuração da extensão instalada no Console do Firebase.

• Monitore a atividade da extensão instalada, incluindo verificações de integridade, uso e registros.

• Usando o Console do Firebase, gerencie sua extensão instalada. Para extensões oficiais do Firebase, é possível reconfigurar ou desinstalar sua extensão, além de atualizá-la para a versão mais recente.

• Como prática recomendada para todos os projetos, configure alertas de orçamento para seu projeto e monitore o Painel de uso e faturamento no Console do Firebase.