Visão geral

As funções do Cloud Run podem amplificar seus aplicativos e serviços com uma integração aos bancos de dados do Google Cloud, como o Firestore, o Cloud Spanner, o Cloud SQL, o Cloud Bigtable e o Memorystore, o serviço de cache de banco de dados em memória do Google Cloud.

Neste laboratório, você vai criar funções do Cloud Run que se integram ao Firestore, o banco de dados de documentos NoSQL sem servidor do Google Cloud. Você vai usar o framework de funções do Cloud Run e a biblioteca de cliente do Firestore para Node.js ao criar funções e configurar gatilhos para executá-las quando ocorrerem eventos no banco de dados.

O ciclo de vida de uma função do Firestore geralmente envolve estas etapas:

• Esperar por mudanças em um documento específico no banco de dados do Firestore.
• Acionar funções quando um evento ocorrer.
• Executar tarefas usando um objeto de dados que é recebido com um snapshot do documento afetado.

Objetivos

Neste laboratório, você vai aprender a:

• Configurar um banco de dados do Firestore.
• Desenvolver e implantar uma função com base em eventos para registrar informações quando um documento é criado no Firestore.
• Desenvolver e implantar uma função com base em eventos para atualizar o conteúdo do documento.
• Acessar e usar secrets com funções do Cloud Run.
• Usar o console do Google Cloud para acessar os registros gerados pela sua função.

Configuração

Antes de clicar no botão "Começar o laboratório"

Este laboratório prático do Google Skills permite que você realize as atividades em um ambiente real de nuvem, não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

O que é necessário

Veja os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).
• Tempo disponível para concluir as atividades

Ative o Google Cloud Shell

O Google Cloud Shell é uma máquina virtual com ferramentas de desenvolvimento. Ele tem um diretório principal permanente de 5 GB e é executado no Google Cloud.

O Cloud Shell oferece acesso de linha de comando aos recursos do Google Cloud.

1. No console do Cloud, clique no botão "Abrir o Cloud Shell" na barra de ferramentas superior direita.

   

2. Clique em Continuar.

O provisionamento e a conexão do ambiente podem demorar um pouco. Quando você estiver conectado, já estará autenticado, e o projeto estará definido com seu PROJECT_ID. Exemplo:

A gcloud é a ferramenta de linha de comando do Google Cloud. Ela vem pré-instalada no Cloud Shell e aceita preenchimento com tabulação.

• Para listar o nome da conta ativa, use este comando:

Saída:

Exemplo de saída:

• Para listar o ID do projeto, use este comando:

Saída:

Exemplo de saída:

Tarefa 1: Configurar o ambiente

Nesta tarefa, você vai configurar as variáveis de ambiente e ativar as APIs de serviço relevantes para realizar este laboratório.

Defina as variáveis de ambiente

Antes de criar funções do Cloud Run, você define algumas variáveis de ambiente.

1. Faça login no console do Google Cloud com as credenciais do laboratório e abra a janela do terminal do Cloud Shell.

2. Execute o seguinte comando no Cloud Shell para definir as variáveis de ambiente de região e ID do projeto:

   PROJECT_ID=$(gcloud config get-value project) REGION={{{project_0.default_region|set at lab start}}}

3. Crie uma variável de ambiente para o número do projeto:

   PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" \ --format="value(projectNumber)")

4. Defina a região padrão para o Cloud Run functions:

   gcloud config set functions/region {{{project_0.default_region|set at lab start}}}

Ative as APIs

1. Para ativar as APIs de serviço necessárias para este laboratório, execute o seguinte comando:

   gcloud services enable \ artifactregistry.googleapis.com \ cloudfunctions.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ logging.googleapis.com \ storage.googleapis.com \ pubsub.googleapis.com

Tarefa 2: Configurar o Firestore

Para realizar as tarefas deste laboratório, você precisa configurar um banco de dados do Firestore. Esse banco de dados armazena informações em forma de documentos e coleções. Para usar funções do Cloud Run com o Firestore, é necessário configurar o Firestore antes de implantar as funções.

1. No console do Google Cloud, clique na barra de pesquisa na navegação superior e digite Firestore. Selecione Firestore nos resultados da pesquisa.

2. Clique em Criar um banco de dados do Firestore.

3. Selecione Standard Edition.

4. Em Opções de configuração, selecione Firestore no modo nativo.

5. Em "Regras de segurança", escolha Abrir.

6. Em "Tipo de local", clique em Região e selecione a região definida no início do laboratório na lista.

   Observação: se a lista de regiões não for preenchida, atualize o navegador ou tente usar o assistente no menu do console do Cloud.

7. Deixe as outras configurações com os valores padrão e clique em Criar banco de dados.

Clique em Verificar meu progresso para conferir o objetivo. Configurar o Firestore.

Tarefa 3: Desenvolver uma função com base em eventos para novos documentos do Firestore

Depois de criar o banco de dados do Firestore, você pode desenvolver o código da sua função. Nessa tarefa, você vai escrever o código-fonte da função que responde à criação de novos documentos no banco de dados. A função registra informações sobre os dados recebidos na invocação dela.

Configure seu diretório de trabalho

As funções do Firestore são invocadas com uma estrutura de dados cloudevents que pode ser decodificada usando buffers de protocolo com o módulo NPM protobuf.js. Para mais informações, consulte os links fornecidos no final do laboratório.

1. Para copiar .proto e os arquivos de dependência necessários do Cloud Storage e extrair o conteúdo do arquivo, execute o seguinte comando:

   gcloud storage cp gs://cloud-training/CBL493/firestore_functions.zip . && unzip firestore_functions && rm firestore_functions.zip

2. Mude para o diretório firestore_functions:

   cd firestore_functions

   O diretório firestore_functions também contém os arquivos node.js e package.json vazios, que você vai atualizar na próxima subtarefa.

Escreva o código da função

1. Na barra de ferramentas do Cloud Shell, clique em Abrir editor.

   Você pode alternar o Cloud Shell e o editor de código usando Abrir editor e Abrir terminal ou clicando em Abrir em uma nova janela para deixar o editor aberto em uma guia separada.

2. No editor, adicione o código a seguir ao arquivo firestore_functions/index.js:

   /** * Cloud Event Function triggered by a change to a Firestore document. */ const functions = require('@google-cloud/functions-framework'); const protobuf = require('protobufjs'); functions.cloudEvent('newCustomer', async cloudEvent => { console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType('google.events.cloud.firestore.v1.DocumentEventData'); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); console.log('\nNew document:'); console.log(JSON.stringify(firestoreReceived.value, null, 2)); const documentData = firestoreReceived.value.fields; console.log('Document data:', documentData); }); O código usa a biblioteca do framework de funções do Node.js para criar uma função que processa dados entregues usando a especificação do cloudEvent.

3. No editor, adicione o seguinte ao arquivo firestore_functions/package.json:

   { "name": "firestore_functions", "version": "0.0.1", "main": "index.js", "dependencies": { "@google-cloud/functions-framework": "^3.1.3", "protobufjs": "^7.2.2", "@google-cloud/firestore": "^6.0.0" } }

Atualize as permissões da conta de serviço

Conceda algumas permissões ao agente de serviço do Cloud Run Functions antes de implantar a função. Execute os comandos a seguir no Cloud Shell.

1. Clique em Abrir terminal.

2. Defina uma variável de ambiente para a conta do agente de serviço do Cloud Run Functions:

   SERVICE_ACCOUNT=service-$PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com

3. Para acessar e receber artefatos do Artifact Registry, conceda o papel de artifactregistry.reader à conta de serviço do Cloud Run Functions:

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader Observação: se aparecer um erro na etapa anterior indicando que a conta de serviço não existe ou que a solicitação tem credenciais de autenticação inválidas, siga estas etapas:

4. Desative a API Cloud Functions:

   gcloud services disable cloudfunctions.googleapis.com

5. Ative a API Cloud Functions de novo:

   gcloud services enable cloudfunctions.googleapis.com

6. Aguarde alguns segundos e execute o comando novamente para conceder o papel de artifactregistry.reader à conta de serviço do Cloud Run Functions:

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader

Implante a função

• Para implantar a função, execute o seguinte comando no Cloud Shell:

  gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' O Firestore oferece suporte aos eventos created, updated, deleted e written que você especifica como a opção trigger-event-filter no comando de implantação. O padrão de caminho informa que todos os documentos na coleção customers precisam ser monitorados.

  Depois que o comando é executado, ele gera o URL do endpoint da função, como mostrado nesta amostra de resposta parcial ao comando:

  ... state: ACTIVE updateTime: '2024-03-19T21:38:04.917134057Z' url: https://{{{project_0.default_region|set at lab start}}}-{{{project_0.default_region}}}.cloudfunctions.net/newCustomer Se aparecer um erro quando você implantar a função, aguarde alguns minutos antes de tentar usar novamente o comando de implantação. As permissões da conta de serviço para o Eventarc podem levar algum tempo para serem propagadas.

Teste a função

1. Acesse o Firestore Studio no console do Cloud.

2. Crie uma nova coleção de documentos clicando em Iniciar coleção.

3. Para ID da coleção, digite customers.

4. Se quiser gerar um ID para um documento nessa coleção, clique em ID do documento.

5. Para esse documento, adicione um campo com os seguintes valores:

   Nome do campo	Tipo de campo	Valor do campo
   firstname	string	Lucas

6. Clique em Salvar.

7. Para verificar se a função do Cloud Run foi invocada, no menu de navegação (), clique em Cloud Run.

8. Clique no nome da função newCustomer.

9. Clique em Registros.

10. Verifique se as entradas de registro geradas pelo código da função estão presentes e se elas mostram os dados do documento de banco de dados que você criou.

    Talvez seja necessário clicar em Atualizar para ver as entradas de registro mais recentes.

Clique em Verificar meu progresso para conferir o objetivo. Desenvolver uma função com base em eventos para novos documentos do Firestore.

Tarefa 4: Desenvolver uma função com base em eventos para o Firestore atualizar um documento

Nessa tarefa, você vai desenvolver uma função que é acionada quando um documento é atualizado no banco de dados do Firestore. Sua função adiciona um novo campo ao documento com um valor derivado dos valores de alguns dos outros campos do documento.

Escreva o código da função

1. No editor, adicione o código abaixo ao arquivo firestore_functions/index.js:

   const Firestore = require('@google-cloud/firestore'); const firestore = new Firestore({ projectId: process.env.GOOGLE_CLOUD_PROJECT, }); functions.cloudEvent('updateCustomer', async cloudEvent => { console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType( 'google.events.cloud.firestore.v1.DocumentEventData' ); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); const resource = firestoreReceived.value.name; const affectedDoc = firestore.doc(resource.split('/documents/')[1]); // O nome completo já existe, portanto, não atualize novamente para evitar um loop infinito. if (firestoreReceived.value.fields.hasOwnProperty('fullname')) { console.log('O nome completo já está presente no documento.'); return; } if (firestoreReceived.value.fields.hasOwnProperty('lastname')) { const lname = firestoreReceived.value.fields.lastname.stringValue; const fname = firestoreReceived.value.fields.firstname.stringValue; const fullname = `${fname} ${lname}` console.log(`Adding fullname --> ${fullname}`); await affectedDoc.update({ fullname: fullname }); } }); É possível definir várias funções com pontos de entrada próprios no mesmo arquivo main do projeto e implantá-las separadamente no Cloud Run.

   Com essa abordagem, todas as funções podem compartilhar o mesmo conjunto de dependências, mesmo que algumas funções não exijam o uso delas.

   Para minimizar o número de dependências necessárias para uma função específica e reduzir os requisitos de memória, é recomendável manter o código-fonte de cada função no próprio diretório na raiz do sistema com os respectivos arquivos de configuração do projeto.

Implante a função

1. Para implantar a nova função, execute o seguinte comando no Cloud Shell:

   gcloud functions deploy updateCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=updateCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.updated \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}'

2. Verifique a resposta ao comando indicando que a função foi implantada e o estado é Active.

Teste a função

1. No console do Cloud, no Firestore Studio, selecione os documentos na coleção customers com o valor do campo firstname Lucas.

2. Para esse documento, clique em Adicionar campo.

3. Adicione um campo com os seguintes valores:

   Nome do campo	Tipo de campo	Valor do campo
   lastname	string	Sherman

4. Clique em Salvar.

5. Aguarde alguns segundos e verifique se o novo campo fullname foi adicionado ao documento.

   Isso indica que a função updateCustomer foi invocada quando o documento foi atualizado.

6. Para verificar se a função do Cloud Run foi invocada, no menu de navegação (), clique em Cloud Run.

7. Clique no nome da função updateCustomer.

8. Clique em Registros.

9. Verifique se as entradas de registro geradas pelo código da função estão presentes e indicam que o campo fullname foi adicionado ao documento.

   Talvez seja necessário clicar em Atualizar para ver as entradas de registro mais recentes.

Clique em Verificar meu progresso para conferir o objetivo. Desenvolver uma função com base em eventos para o Firestore atualizar um documento.

Tarefa 5: Usar secrets com funções do Cloud Run

O Secret Manager é um serviço do Google Cloud que armazena com segurança dados como chaves de API, senhas, certificados, credenciais e outras informações sensíveis. Depois, é possível acessar esses secrets a partir de funções do Cloud Run ou outros serviços para uso na lógica da função ou na implementação do serviço.

Nessa tarefa, você vai criar e armazenar uma credencial como um secret no Secret Manager. Você desenvolve uma função para acessar a chave na lógica da sua função.

Crie um secret

1. Para criar e usar secrets, execute o seguinte comando no Cloud Shell e ative a API Secret Manager:

   gcloud services enable secretmanager.googleapis.com

2. Crie e armazene um secret chamado api-cred com o valor secret_api_key no Secret Manager:

   echo -n "secret_api_key" | gcloud secrets create api-cred --replication-policy="automatic" --data-file=- A configuração replication-policy determina quais regiões são usadas para armazenar secrets e as versões deles. Para especificar uma ou mais regiões em que um secret pode ser replicado, defina replication-policy como user-managed.

Conceda acesso

Para acessar um secret, a conta de serviço do ambiente de execução da função precisa ter acesso ao secret.

• Por padrão, o Cloud Run Functions usa a conta de serviço padrão do Compute Engine como a conta de serviço do ambiente de execução de uma função.

  Para fazer a autenticação com o Secret Manager, conceda o papel de acessador de secrets do Secret Manager à conta de serviço padrão do Compute Engine:

  gcloud secrets add-iam-policy-binding api-cred --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com --project=$PROJECT_ID --role='roles/secretmanager.secretAccessor' Observação: para uso em produção, configure a função para autenticar com a própria conta de serviço gerenciada pelo usuário, que recebe o conjunto menos permissivo de papéis exigidos para as tarefas da função.

Acesse o secret da sua função

Nesta subtarefa, você vai modificar a função newCustomer desenvolvida anteriormente para acessar o secret.

• No editor, adicione o código a seguir à função newCustomer no arquivo index.js. Adicione o código ao final do corpo da função, depois da última instrução console.log:

  // BEGIN access a secret const fs = require('fs/promises'); try { const secret = await fs.readFile('/etc/secrets/api_cred/latest', { encoding: 'utf8' }); // use the secret. For lab testing purposes, we log the secret. console.log('secret: ', secret); } catch (err) { console.log(err); } // End access a secret O código da função lê o valor do secret de um arquivo montado em um volume acessível à função. Você vai configurar esse método de acesso ao secret na próxima etapa, quando implantar a função.

Implante a função

1. No Cloud Shell, implante novamente a função newCustomer com o secret:

   gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' \ --set-secrets '/etc/secrets/api_cred/latest=api-cred:latest' A opção de comando de implantação set-secrets especifica o caminho de montagem: /etc/secrets/api_cred e o caminho do secret: /latest.

   Ao referir-se a um secret como um volume, sua função acessa o valor mais recente do secret no Secret Manager sempre que o arquivo é lido no disco.

   A função também pode acessar uma versão específica do valor do secret como uma variável de ambiente. Consulte a documentação sobre como usar secrets com funções do Cloud Run para mais informações.

2. Depois que a função for implantada, verifique se ela tem acesso ao secret:

   gcloud functions describe newCustomer

   A resposta ao comando describe inclui informações sobre o secret. Confira uma resposta parcial ao comando:

   ... secretVolumes: - mountPath: /etc/secrets/api_cred projectId: '{{{project_0.project_id|Project_ID}}}' secret: api-cred versions: - path: /latest version: latest ...

Teste a função

1. Para testar a função, repita o teste da tarefa anterior para adicionar um novo documento de um cliente no Firestore Studio no console do Cloud.

2. Para acessar os registros da função no console do Cloud, no menu de navegação (), clique em Cloud Run.

3. Clique no nome da função newCustomer.

4. Para ver a atividade da função, clique em Registros.

   Verifique se a entrada para registrar o valor do secret está presente:

   secret: secret_api_key Observação: embora não seja uma prática geral registrar o valor dos secrets, essa etapa é usada para confirmar que a função tem acesso ao valor e pode utilizar o secret no código.

Clique em Verificar meu progresso para conferir o objetivo. Usar secrets com funções do Cloud Run.

Parabéns!

Neste laboratório, você configurou um banco de dados do Firestore e desenvolveu uma função do Cloud baseada em eventos que é acionada quando um novo documento é criado no banco de dados. Você também desenvolveu uma função para adicionar um novo campo a um documento quando ele é atualizado. Além disso, você criou e acessou um secret usando uma função do Cloud Run e usou registros para verificar o valor do secret.

Próximas etapas / Saiba mais

Para saber mais sobre funções do Cloud Run para Firestore e outros tópicos, consulte a documentação:

• Gatilhos do Firestore
• Buffers de protocolo
• Cloud Functions para Firebase

Copyright 2026 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de empresas e produtos podem ser marcas registradas das empresas a que estão associados.