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.

Aqui está o código de exemplo completo contendo as funções:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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 saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Sobre este tutorial

Escolhemos o Cloud Firestore e as funções 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 chamáveis ​​Realtime Database, Cloud Storage, PubSub, Auth e HTTP. Outros tipos de acionadores em segundo plano, como os acionadores do Configuração remota e do TestLab, 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.

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:

   Crashlytics do Firebase Mensagens na nuvem do Firebase

   Mensagens no aplicativo do Firebase Configuração remota do Firebase

   Personalização da Configuração remota Teste A/B 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 seu ambiente e a CLI do Firebase

Inicialize seu projeto

Ao inicializar o SDK do Firebase para Cloud Functions, você cria um projeto vazio contendo dependências e alguns exemplos mínimos de código. Se estiver usando Node.js, você pode escolher 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 inicialização 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 estas opções para suporte ao idioma:

   • JavaScript
   • Texto datilografado
   • Pitão

   Para este tutorial, selecione JavaScript ou Python . Para criação em TypeScript, consulte Escrever funções com TypeScript .

6. A CLI oferece a opção de instalar dependências. É seguro recusar se você quiser gerenciar dependências de outra maneira.

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

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
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

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. Adicione linhas como as seguintes ao seu arquivo de origem:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

Essas linhas carregam os módulos necessários 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 Admin SDK e Firebase SDK for Cloud Functions quando você inicializa seu projeto. Para obter mais informações sobre como adicionar bibliotecas de terceiros ao seu projeto, consulte Lidar com dependências .

Adicione a função "adicionar mensagem"

Para a função "adicionar mensagem", adicione estas linhas ao seu arquivo de origem:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

A função "adicionar mensagem" é um terminal HTTP. Qualquer solicitação para o endpoint resulta em objetos de solicitação e resposta passados ​​para o manipulador de solicitações da sua plataforma ( onRequest() ou on_request ).

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 "adicionar mensagem" 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 "fazer maiúsculas"

Para a função "fazer maiúsculas", adicione estas linhas ao seu arquivo de origem:

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

A função "fazer maiúsculas" é executada quando o Cloud Firestore é gravado, definindo 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 sempre que novas mensagens são adicionadas.

No Node.js, 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. 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 guia Logs , você verá novos logs indicando que suas funções HTTP foram executadas com sucesso:

      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. Tenha em mente que para implantar em produção, 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-as.

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 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 a função "fazer maiúsculas", que grava uma versão em 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.

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:

• Leia sobre os casos de uso do Cloud Functions .
• Experimente o codelab do Cloud Functions .
• Revise e execute exemplos de código no GitHub