Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Comece: escreva, teste e implante suas primeiras funções

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Para começar a usar o Cloud Functions, tente seguir este tutorial, que começa com as tarefas de configuração necessárias e passa pela criação, teste e implantação de duas funções relacionadas:

  • addMessage() , que expõe um URL que aceita um valor de texto e o grava no Cloud Firestore.
  • makeUppercase() , que aciona na gravação do Cloud Firestore e transforma o texto em letras maiúsculas.

Escolhemos Cloud Firestore e funções JavaScript acionadas por HTTP para este exemplo em parte porque esses acionadores em segundo plano podem ser completamente testados por meio do Firebase Local Emulator Suite . Este conjunto de ferramentas também oferece suporte a gatilhos de chamada Realtime Database, PubSub, Auth e HTTP. Outros tipos de acionadores em segundo plano, como Configuração remota, TestLab e acionadores analíticos, podem ser testados interativamente usando conjuntos de ferramentas não descritos nesta página.

As seções a seguir deste tutorial detalham as etapas necessárias para criar, testar e implantar o exemplo. Se preferir apenas executar o código e inspecioná-lo, pule para Review complete sample code .

Criar um projeto do Firebase

  1. No console do Firebase , clique em Adicionar projeto .

    • Para adicionar recursos do Firebase a um projeto existente do Google Cloud, insira o nome do projeto ou selecione-o no menu suspenso.

    • Para criar um novo projeto, digite o nome do projeto desejado. Você também pode, opcionalmente, editar o ID do projeto exibido abaixo do nome do projeto.

  2. Se solicitado, revise e aceite os termos do Firebase .

  3. Clique em Continuar .

  4. (Opcional) Configure o Google Analytics para seu projeto, o que permite que você tenha uma experiência ideal usando qualquer um dos seguintes produtos Firebase:

    Selecione uma conta existente do Google Analytics ou crie uma nova conta.

    Se você criar uma nova conta, selecione o local de relatório do Analytics e aceite as configurações de compartilhamento de dados e os termos do Google Analytics para seu projeto.

  5. Clique em Criar projeto (ou Adicionar Firebase , se estiver usando um projeto existente do Google Cloud).

O Firebase provisiona recursos automaticamente para seu projeto Firebase. Quando o processo for concluído, você será direcionado para a página de visão geral do seu projeto do Firebase no console do Firebase.

Configure o Node.js e a Firebase CLI

Você precisará de um ambiente Node.js para escrever funções e precisará da Firebase CLI para implantar funções no tempo de execução do Cloud Functions. Para instalar Node.js e npm , o Node Version Manager é recomendado.

Depois de instalar o Node.js e o npm, instale o Firebase CLI por meio de seu método preferido. Para instalar a CLI via npm, use:

npm install -g firebase-tools

Isso instala o comando firebase disponível globalmente. Se o comando falhar, pode ser necessário alterar as permissões do npm . Para atualizar para a versão mais recente do firebase-tools , execute novamente o mesmo comando.

Inicialize seu projeto

Ao inicializar o SDK do Firebase para Cloud Functions, você cria um projeto vazio contendo dependências e um código de amostra mínimo e escolhe TypeScript ou JavaScript para compor funções. Para os propósitos deste tutorial, você também precisará inicializar o Cloud Firestore.

Para inicializar seu projeto:

  1. Execute o login do firebase login para fazer login por meio do navegador e autenticar o Firebase CLI.
  2. Acesse o diretório do projeto Firebase.
  3. Execute firebase init firestore . Para este tutorial, você pode aceitar os valores padrão quando solicitado pelas regras do Firestore e arquivos de índice. Se você ainda não usou o Cloud Firestore neste projeto, também precisará selecionar um modo inicial e um local para o Firestore, conforme descrito em Introdução ao Cloud Firestore .
  4. Execute firebase init functions . A CLI solicita que você escolha uma base de código existente ou inicialize e nomeie uma nova. Quando você está apenas começando, uma única base de código no local padrão é adequada; posteriormente, à medida que sua implementação se expande, talvez você queira organizar as funções em bases de código .
  5. A CLI oferece duas opções para suporte a idiomas:

    Para este tutorial, selecione JavaScript .

  6. A CLI oferece a opção de instalar dependências com npm. É seguro recusar se você quiser gerenciar dependências de outra maneira, embora, se recusar, precisará executar npm install antes de emular ou implantar suas funções.

Depois que esses comandos forem concluídos com sucesso, a estrutura do seu projeto ficará assim:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

O arquivo package.json criado durante a inicialização contém uma chave importante: "engines": {"node": "16"} . Isso especifica sua versão do Node.js para escrever e implantar funções. Você pode selecionar outras versões suportadas .

Importe os módulos necessários e inicialize um aplicativo

Depois de concluir as tarefas de configuração, você pode abrir o diretório de origem e começar a adicionar o código conforme descrito nas seções a seguir. Para esta amostra, seu projeto deve importar os módulos Cloud Functions e Admin SDK usando as instruções Node require . Adicione linhas como as seguintes ao seu arquivo index.js :

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

Essas linhas carregam os módulos firebase-functions e firebase-admin e inicializam uma instância de aplicativo admin a partir da qual as alterações do Cloud Firestore podem ser feitas. Onde quer que o suporte Admin SDK esteja disponível, como é para FCM, Authentication e Firebase Realtime Database, ele fornece uma maneira poderosa de integrar o Firebase usando o Cloud Functions.

A Firebase CLI instala automaticamente os módulos Firebase e Firebase SDK for Cloud Functions Node quando você inicializa seu projeto. Para adicionar bibliotecas de terceiros ao seu projeto, você pode modificar package.json e executar npm install . Para obter mais informações, consulte Lidar com dependências .

Adicione a função addMessage()

Para a função addMessage() , adicione estas linhas a index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

A função addMessage() é um endpoint HTTP. Qualquer solicitação para o endpoint resulta em objetos Request e Response no estilo ExpressJS passados ​​para o retorno de chamada onRequest() .

As funções HTTP são síncronas (semelhantes às funções chamáveis ​​), então você deve enviar uma resposta o mais rápido possível e adiar o trabalho usando o Cloud Firestore. A função HTTP addMessage() passa um valor de texto para o terminal HTTP e o insere no banco de dados no caminho /messages/:documentId/original .

Adicione a função makeUppercase()

Para a função makeUppercase() , adicione estas linhas a index.js :

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);
      
      const uppercase = original.toUpperCase();
      
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Firestore.
      // Setting an 'uppercase' field in Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

A função makeUppercase() é executada quando o Cloud Firestore é gravado. A função ref.set define o documento a ser escutado. Por motivos de desempenho, você deve ser o mais específico possível.

Chaves — por exemplo, {documentId} — cercam "parâmetros", curingas que expõem seus dados correspondentes no retorno de chamada.

O Cloud Firestore aciona o retorno de chamada onCreate() sempre que novas mensagens são adicionadas.

Funções orientadas a eventos, como eventos do Cloud Firestore, são assíncronas. A função de retorno de chamada deve retornar um null , um Object ou um Promise . Se você não retornar nada, a função expirará, sinalizando um erro, e será repetida. Consulte Sincronização, Assíncrona e Promessas .

Emule a execução de suas funções

O Firebase Local Emulator Suite permite que você crie e teste aplicativos em sua máquina local em vez de implantar em um projeto do Firebase. O teste local durante o desenvolvimento é altamente recomendado, em parte porque reduz o risco de erros de codificação que podem incorrer em custos em um ambiente de produção (por exemplo, um loop infinito).

Para emular suas funções:

  1. Execute firebase emulators:start e verifique a saída para o URL da IU do Emulator Suite. O padrão é localhost:4000 , mas pode estar hospedado em uma porta diferente em sua máquina. Digite esse URL em seu navegador para abrir a IU do Emulator Suite.

  2. Verifique a saída do comando firebase emulators:start para o URL da função HTTP addMessage() . Será semelhante a http://localhost:5001/MY_PROJECT/us-central1/addMessage , exceto que:

    1. MY_PROJECT será substituído pelo ID do seu projeto.
    2. A porta pode ser diferente em sua máquina local.
  3. Adicione a string de consulta ?text=uppercaseme ao final da URL da função. Isso deve ser algo como: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Opcionalmente, você pode alterar a mensagem "maiúsculo" para uma mensagem personalizada.

  4. Crie uma nova mensagem abrindo o URL em uma nova guia do navegador.

  5. Veja os efeitos das funções na IU do Emulator Suite:

    1. Na guia Logs , você deve ver novos logs indicando que as funções addMessage() e makeUppercase() foram executadas:

      Funções i: Início da execução de "addMessage"

      Funções i: Iniciando a execução de "makeUppercase"

    2. Na guia Firestore , você deve ver um documento contendo sua mensagem original, bem como a versão em maiúscula de sua mensagem (se originalmente era "maiúsculas", você verá "UPPERCASEME").

Implantar funções em um ambiente de produção

Depois que suas funções estiverem funcionando conforme desejado no emulador, você poderá implantar, testar e executá-las no ambiente de produção. Lembre-se de que, para implantar no ambiente de tempo de execução Node.js 14 recomendado, seu projeto deve estar no plano de preços Blaze . Consulte os preços do Cloud Functions .

Para concluir o tutorial, implante suas funções e execute addMessage() para acionar makeUppercase() .

  1. Execute este comando para implantar suas funções:

     firebase deploy --only functions
     

    Depois de executar esse comando, a Firebase CLI gera o URL para todos os endpoints de função HTTP. No seu terminal, você deve ver uma linha como a seguinte:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
    

    A URL contém o ID do seu projeto, bem como uma região para a função HTTP. Embora você não precise se preocupar com isso agora, algumas funções HTTP de produção devem especificar um local para minimizar a latência da rede.

    Se você encontrar erros de acesso, como "Não foi possível autorizar o acesso ao projeto", tente verificar o aliasing do projeto .

  2. Usando a saída de URL addMessage() pela CLI, adicione um parâmetro de consulta de texto e abra-o em um navegador:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
    

    A função executa e redireciona o navegador para o Firebase console no local do banco de dados onde a string de texto está armazenada. Esse evento de gravação aciona makeUppercase() , que grava uma versão em maiúscula da string.

Depois de implantar e executar funções, você pode visualizar os logs no Console do Google Cloud . Se você precisar excluir funções em desenvolvimento ou produção, use o Firebase CLI.

Na produção, convém otimizar o desempenho da função e controlar os custos definindo os números mínimo e máximo de instâncias a serem executadas. Consulte Controlar o comportamento de dimensionamento para obter mais informações sobre essas opções de tempo de execução.

Revise o código de exemplo completo

Aqui está o functions/index.js completo contendo as funções addMessage() e makeUppercase() . Essas funções permitem que você passe um parâmetro para um ponto de extremidade HTTP que grava um valor no Cloud Firestore e o transforma colocando todos os caracteres em maiúsculas na string.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);
      
      const uppercase = original.toUpperCase();
      
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Firestore.
      // Setting an 'uppercase' field in Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Próximos passos

Nesta documentação, você pode encontrar mais informações sobre conceitos gerais do Cloud Functions, bem como guias para escrever funções para lidar com os tipos de eventos compatíveis com o Cloud Functions.

Para saber mais sobre o Cloud Functions, você também pode fazer o seguinte:

Vídeo tutorial

Você pode aprender mais sobre o Cloud Functions assistindo a tutoriais em vídeo. Neste vídeo, você encontrará orientações detalhadas sobre como começar a usar o Cloud Functions, incluindo Node.js e configuração da CLI.