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


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:

  • Uma função de "adicionar mensagem" que expõe um URL que aceita um valor de texto e o grava no Cloud Firestore.
  • Uma função "tornar maiúsculas" que é acionada em uma gravação do Cloud Firestore e transforma o texto em maiúsculas.

Escolhemos o Cloud Firestore e as funções JavaScript acionadas por HTTP para este exemplo, em parte porque esses acionadores em segundo plano podem ser testados exaustivamente por meio do Firebase Local Emulator Suite . Este conjunto de ferramentas também oferece suporte a gatilhos que podem ser chamados de Realtime Database, PubSub, Auth e HTTP. Outros tipos de acionadores em segundo plano, como Configuração remota, TestLab e acionadores de análise, 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 você preferir apenas executar o código e inspecioná-lo, vá para Review complete sample code .

Crie um projeto 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, insira o nome do projeto desejado. Opcionalmente, você também pode 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 do Firebase:

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

    Se você criar uma nova conta, selecione o local dos relatórios 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 você estiver usando um projeto existente do Google Cloud).

O Firebase provisiona recursos automaticamente para seu projeto do 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 CLI do Firebase

Você precisará de um ambiente Node.js para escrever funções e da CLI do Firebase para implantar funções no ambiente 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 do método de sua preferência. 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 alguns códigos de amostra mínimos e escolhe TypeScript ou JavaScript para compor funções. Para os fins deste tutorial, você também precisará inicializar o Cloud Firestore.

Para inicializar seu projeto:

  1. Execute firebase login para fazer login pelo navegador e autenticar a CLI do Firebase.
  2. Vá para o diretório do projeto do Firebase.
  3. Execute firebase init firestore . Para este tutorial, você pode aceitar os valores padrão quando solicitado a fornecer regras e arquivos de índice do Firestore. Se você ainda não usou o Cloud Firestore neste projeto, também precisará selecionar um modo de início e um local para o Firestore, conforme descrito em Primeiros passos com o 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; mais tarde, à medida que sua implementação se expande, talvez você queira organizar funções em bases de código .

  5. A CLI oferece duas opções de 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, mas se você recusar, precisará executar npm install antes de emular ou implantar suas funções.

Após a conclusão bem-sucedida desses comandos, 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ê poderá abrir o diretório de origem e começar a adicionar código conforme descrito nas seções a seguir. Para este exemplo, seu projeto precisa importar os módulos Cloud Functions e Admin SDK usando instruções require do Node. 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/v1');

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

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

A Firebase CLI instala automaticamente os módulos Firebase e Firebase SDK para 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.` });
});
index.js

A função addMessage() é um terminal 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 que podem ser chamadas ), portanto, 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 endpoint 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 });
  });
index.js

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} — circundam "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 null , Object ou Promise . Se você não retornar nada, a função expirará, sinalizando um erro, e será tentada novamente. Consulte Sincronização, Assíncrono e Promessas .

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

O Firebase Local Emulator Suite permite criar e testar aplicativos em sua máquina local em vez de implantá-los em um projeto do Firebase. Testes locais durante o desenvolvimento são fortemente recomendados, em parte porque reduzem o risco de erros de codificação que poderiam potencialmente gerar 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 do URL da IU do Emulator Suite. O padrão é localhost:4000 , mas pode estar hospedado em uma porta diferente em sua máquina. Insira esse URL em seu navegador para abrir a IU do Emulator Suite.

  2. Verifique a saída do comando firebase emulators:start para obter 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 na sua máquina local.

  3. Adicione a string de consulta ?text=uppercaseme ao final do URL da função. Deve ser algo como: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Opcionalmente, você pode alterar a mensagem "maiúsculas" para uma mensagem personalizada.

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

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

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Na guia Firestore , você deverá ver um documento contendo sua mensagem original, bem como a versão em maiúscula da sua mensagem (se originalmente era "maiúscula", você verá "MAIÚSCULAS").

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

Depois que suas funções estiverem funcionando conforme desejado no emulador, você poderá implantá-las, testá-las 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 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 CLI do Firebase gera o URL para qualquer endpoint de função HTTP. No seu terminal, você deverá ver uma linha como esta:

    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 é possível autorizar o acesso ao projeto", tente verificar o alias do seu projeto .

  2. Usando a saída de URL addMessage() da 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 é executada e redireciona o navegador para o console do Firebase no local do banco de dados onde a string de texto está armazenada. Este evento de gravação aciona makeUppercase() , que grava uma versão maiúscula da string.

Depois de implantar e executar funções, você poderá visualizar os registros no console do Google Cloud . Se você precisar excluir funções em desenvolvimento ou produção, use a CLI do Firebase.

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

Revise o código de amostra 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 endpoint HTTP que grava um valor no Cloud Firestore e o transforma colocando todos os caracteres na string em letras maiúsculas.

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

// 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 });
  });
index.js

Próximos passos

Nesta documentação, você pode aprender mais sobre como gerenciar funções para Cloud Functions e também como lidar com todos os tipos de eventos compatíveis com Cloud Functions.

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