Ir para o console

Primeiros passos: escrever e implantar suas primeiras funções

Para começar a usar o Cloud Functions, siga as etapas deste tutorial, que começa com as tarefas de configuração necessárias e avança para a criação e implantação de duas funções relacionadas:

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

Escolhemos o Realtime Database e as funções JavaScript acionadas por HTTP para esta amostra, mas você pode acionar funções de várias outras formas. Veja os guias de instruções sobre outros gatilhos em segundo plano, como eventos de autenticação e do Analytics. Como opção, se quiser uma alternativa tipificada ao JavaScript, consulte Como gravar funções com o TypeScript.

As seções a seguir detalham as etapas necessárias para criar e implantar a amostra. Se você quiser apenas gerar o código e verificá-lo, acesse Análise completa do código de amostra.

Criar um projeto do Firebase

  1. No Console do Firebase, clique em Adicionar projeto e, em seguida, selecione ou insira o Nome do projeto.

    Se você tiver um projeto do Google Cloud Platform (GCP), poderá selecionar o projeto no menu suspenso para adicionar recursos do Firebase ao projeto em questão.

  2. (Opcional) Se você criou um novo projeto, poderá editar o ID dele.

    O Firebase atribui automaticamente um código exclusivo ao seu projeto. Consulte Noções básicas sobre projetos do Firebase para entender melhor como o Firebase usa o ID do projeto.

  3. Clique em Continuar.

  4. (Opcional) Configure o Google Analytics para o seu projeto, permitindo que você tenha uma ótima experiência ao usar qualquer um dos seguintes produtos do Firebase:

    Quando solicitado, selecione para usar uma Conta do Google Analytics ou criar uma nova conta.
    Se você optar por criar uma nova conta, selecione seu local de relatórios do Google Analytics e aceite as configurações de compartilhamento de dados e os termos do Google Analytics relacionados ao seu projeto.

  5. Clique em Criar projeto (ou Adicionar Firebase, se você estiver usando um projeto do GCP).

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

Configurar o Node.js e a Firebase CLI

Você precisará de um ambiente do Node.js para criar funções e da Firebase CLI, que também requer Node.js e npm (em inglês), para implantar funções no ambiente de execução do Cloud Functions. Entre as versões do Node.js disponíveis para o Cloud Functions, recomendamos o Node.js 8 para começar. Para instalar o Node.js e o npm, recomenda-se o Node Version Manager.

Depois de instalar o Node.js e o NPM, instale a Firebase CLI por meio do NPM:

npm install -g firebase-tools

Essa ação instala o comando do Firebase disponível globalmente. Se o comando falhar, talvez seja necessário alterar as permissões do NPM (em inglês). Para atualizar para a versão mais recente do firebase-tools, execute novamente o mesmo comando.

Inicializar o SDK do Firebase para Cloud Functions

Ao inicializar o SDK do Firebase para Cloud Functions, você cria um projeto vazio que contém dependências e um código de amostra mínimo e escolhe o TypeScript ou JavaScript para compor funções.

Para inicializar seu projeto, siga estas etapas:

  1. Execute o firebase login para fazer login pelo navegador e autenticar a ferramenta do Firebase.
  2. Vá para o diretório do projeto do Firebase.
  3. Execute firebase init functions. A ferramenta oferece uma opção para instalar dependências com NPM. Se você quiser gerenciar as dependências de outra forma, basta recusar.
  4. A ferramenta oferece duas opções de linguagem compatíveis:

    Neste tutorial, selecione JavaScript.

Depois que esses comandos forem concluídos, a estrutura do seu projeto terá a seguinte aparência:

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": "8"}. Isso especifica sua versão de nó para gravar e implementar funções. É possível selecionar outras versões compatíveis, mas o Node.js 8 (efetivamente o padrão) é recomendado para este tutorial.

Importar os módulos necessários e inicializar um aplicativo

Depois de concluir as tarefas de configuração, abra o diretório de origem e comece a adicionar o código conforme descrito nas seções a seguir. Para essa amostra, seu projeto precisa importar os módulos do Cloud Functions e do SDK Admin 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 setup triggers.
const functions = require('firebase-functions');

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

Essas linhas carregam os módulos firebase-functions e firebase-admin e inicializam uma instância de admin do app em que as alterações no Realtime Database podem ser feitas. Os locais compatíveis com o SDK Admin, assim como com o FCM, o Authentication e o Firebase Realtime Database, têm acesso a uma maneira avançada de integrar o Firebase por meio do Cloud Functions.

A Firebase CLI instala automaticamente o Firebase e o SDK do Firebase para os módulos do Node do Cloud Functions quando você inicializa o projeto. Para adicionar bibliotecas de terceiros ao seu projeto, modifique package.json e execute npm install. Para mais informações, consulte Gerenciar dependências.

Adicionar 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 the
// Realtime Database under the path /messages/:pushId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into the Realtime Database using the Firebase Admin SDK.
  const snapshot = await admin.database().ref('/messages').push({original: original});
  // Redirect with 303 SEE OTHER to the URL of the pushed object in the Firebase console.
  res.redirect(303, snapshot.ref.toString());
});

A função addMessage() é um ponto de extremidade de HTTP. Qualquer solicitação para o ponto de extremidade resulta em objetos de solicitação e resposta (ambos em inglês) do estilo ExpressJS transmitidos para o retorno de chamada onRequest().

Como as funções HTTP são síncronas (semelhantes às funções chamáveis), é necessário enviar uma resposta o mais rápido possível e adiar o trabalho usando o Realtime Database. A função HTTP addMessage() transmite um valor de texto para o ponto de extremidade HTTP e o insere no Realtime Database no caminho /messages/:pushId/original usando o app admin previamente inicializado.

Implantar e executar addMessage()

Para implantar e executar a função addMessage(), siga estas etapas:

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

    $ firebase deploy --only functions
    

    Depois de executar o comando, a Firebase CLI produz o URL para quaisquer pontos de extremidade da função HTTP. No seu terminal, aparecerá uma linha como esta:

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

    O URL contém o código do seu projeto, bem como uma região para a função HTTP. Embora não seja necessário se preocupar com isso agora, algumas funções HTTP de produção precisam especificar um local para minimizar a latência da rede.

  2. Adicione um parâmetro de consulta de texto ao URL addMessage() e abra-o em um navegador:

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

    A função executa e redireciona o navegador para o Console do Firebase no local do banco de dados em que a string de texto está armazenada. Seu valor de texto aparecerá no console.

Após a implantação e execução das funções, você pode ver os registros no Console do Firebase.

Adicionar a função makeUppercase()

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

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snapshot, context) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = snapshot.val();
      console.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return snapshot.ref.parent.child('uppercase').set(uppercase);
    });

A função makeUppercase() é executada após a gravação no Realtime Database. A função ref(path) define a parte do banco de dados a ser detectada. Para melhorar o desempenho, você deve ser o mais específico possível.

As chaves, por exemplo, {pushId}, envolvem "parâmetros", caracteres curinga que expõem os dados correspondidos no retorno de chamada.

O Realtime Database aciona o retorno de chamada onWrite() sempre que os dados são gravados ou atualizados no caminho determinado.

As funções baseadas em eventos, como os eventos do Realtime Database, são assíncronas. A função de retorno de chamada precisa retornar um valor null, um objeto ou uma Promise. Se não retornar nada, a função expira, sinaliza um erro e é repetida. Veja Sincronização, dessincronização e promessas.

Implantar e executar makeUppercase()

Para completar o tutorial, implante suas funções novamente e, em seguida, execute addMessage() para acionar makeUppercase().

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

    $ firebase deploy --only functions
    

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

  2. Use o resultado do URL addMessage() da CLI para adicionar 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 Console do Firebase no local do banco de dados em que a string de texto está armazenada. Este evento de gravação aciona makeUppercase(), que grava uma versão da string em letra maiúscula.

Após a implantação e execução das funções, você pode ver os registros no Console do Firebase para o Cloud Functions. Se você precisar excluir funções em desenvolvimento ou produção, use a Firebase CLI.

Análise completa do código de amostra

Veja a seguir o valor functions/index.js completo contendo as funções addMessage() e makeUppercase(). Essas funções permitem que você envie um parâmetro para um ponto de extremidade HTTP, que grava um valor no Realtime Database. Depois, elas mudam todos os caracteres da string para letras maiúsculas.

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

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

// Take the text parameter passed to this HTTP endpoint and insert it into the
// Realtime Database under the path /messages/:pushId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into the Realtime Database using the Firebase Admin SDK.
  const snapshot = await admin.database().ref('/messages').push({original: original});
  // Redirect with 303 SEE OTHER to the URL of the pushed object in the Firebase console.
  res.redirect(303, snapshot.ref.toString());
});

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snapshot, context) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = snapshot.val();
      console.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return snapshot.ref.parent.child('uppercase').set(uppercase);
    });

Próximas etapas

Veja mais informações nesta documentação sobre os conceitos gerais do Cloud Functions. Consulte, bem como guias sobre como escrever funções para saber como processar os tipos de evento compatíveis com o Cloud Functions.

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

Tutorial em vídeo

Para saber mais sobre o Cloud Functions, assista a tutoriais em vídeo. Neste vídeo, você verá instruções detalhadas sobre como usar o Cloud Functions, incluindo a configuração do Node.js e da CLI.