Crie uma função do Cloud Run que use o BigQuery para enviar uma consulta e devolver resultados.

Este tutorial mostra-lhe como escrever uma função HTTP do Cloud Run que envia uma consulta para o BigQuery.

Objetivos

Neste tutorial, vai:

1. Prepare a aplicação que envia uma consulta para o BigQuery.
2. Implemente a função com um acionador HTTP.
3. Teste a função.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Enable the Artifact Registry, Cloud Run Admin API, and Cloud Build APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

2. Configure o ambiente de programação do Cloud Run no seu Google Cloud projeto.

3. Se estiver ao abrigo de uma política da organização de restrição de domínio que restringe invocações não autenticadas para o seu projeto, tem de aceder ao serviço implementado conforme descrito em Testar serviços privados.

Funções necessárias

Para receber as autorizações de que precisa para implementar serviços do Cloud Run a partir da origem, peça ao administrador para lhe conceder as seguintes funções de IAM:

• Programador de origem do Cloud Run (roles/run.sourceDeveloper) no seu projeto
• Consumidor de utilização do serviço (roles/serviceusage.serviceUsageConsumer) no serviço Cloud Run
• Utilizador da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço
• Utilizador de tarefas do BigQuery (roles/bigquery.jobUser) na identidade do serviço

Para ver uma lista de funções e autorizações de IAM associadas ao Cloud Run, consulte os artigos Funções de IAM do Cloud Run e Autorizações de IAM do Cloud Run. Se o seu serviço do Cloud Run interage com Google Cloud APIs, como as bibliotecas cliente da Google Cloud, consulte o guia de configuração da identidade do serviço. Para mais informações sobre a atribuição de funções, consulte as autorizações de implementação e faça a gestão do acesso.

Funções da conta de serviço do Cloud Build

O utilizador ou o administrador tem de conceder à conta de serviço do Cloud Build a seguinte função do IAM.

Clique para ver as funções necessárias para a conta de serviço do Cloud Build

O Cloud Build usa automaticamente a conta de serviço predefinida do Compute Engine como a conta de serviço predefinida do Cloud Build para compilar o seu código-fonte e o recurso do Cloud Run, a menos que substitua este comportamento. Para que o Cloud Build compile as suas origens, peça ao administrador para conceder a função Cloud Run Builder (roles/run.builder) à conta de serviço predefinida do Compute Engine no seu projeto:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:[e-mail] \
      --role=roles/run.builder
  

Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto e PROJECT_ID pelo seu Google Cloud ID do projeto. Para ver instruções detalhadas sobre como encontrar o ID e o número do projeto, consulte o artigo Criar e gerir projetos.

A concessão da função de criador do Cloud Run à conta de serviço predefinida do Compute Engine demora alguns minutos a propagar.

Nota:

A iam.automaticIamGrantsForDefaultServiceAccounts restrição da política da organização impede que a função de editor seja concedida automaticamente às contas de serviço predefinidas. Se tiver criado a sua organização após 3 de maio de 2024, esta restrição é aplicada por predefinição.

Recomendamos vivamente que aplique esta restrição para desativar a concessão automática de funções. Se desativar a concessão automática de funções, tem de decidir que funções conceder às contas de serviço predefinidas e, em seguida, conceder estas funções manualmente.

Se a conta de serviço predefinida já tiver a função de editor, recomendamos que substitua a função de editor por funções menos permissivas.Para modificar as funções da conta de serviço em segurança, use o Simulador de políticas para ver o impacto da alteração e, em seguida, conceda e revogue as funções adequadas.

Prepare a candidatura

1. Clone o repositório da aplicação de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
   

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd nodejs-docs-samples/functions/v2/helloBigQuery
   

3. Veja o exemplo de código. O exemplo envia uma consulta de palavras que ocorrem, pelo menos, 400 vezes no conjunto de dados especificado e devolve o resultado.

   // Import the Google Cloud client library
   const {BigQuery} = require('@google-cloud/bigquery');
   const bigquery = new BigQuery();
   
   const functions = require('@google-cloud/functions-framework');
   
   /**
    * HTTP Cloud Function that returns BigQuery query results
    *
    * @param {Object} req Cloud Function request context.
    * @param {Object} res Cloud Function response context.
    */
   functions.http('helloBigQuery', async (req, res) => {
     // Define the SQL query
     // Queries the public Shakespeare dataset using named query parameter
     const sqlQuery = `
         SELECT word, word_count
               FROM \`bigquery-public-data.samples.shakespeare\`
               WHERE corpus = @corpus
               AND word_count >= @min_word_count
               ORDER BY word_count DESC`;
   
     const options = {
       query: sqlQuery,
       // Location must match that of the dataset(s) referenced in the query.
       location: 'US',
       params: {corpus: 'romeoandjuliet', min_word_count: 400},
     };
   
     // Execute the query
     try {
       const [rows] = await bigquery.query(options);
       // Send the results
       res.status(200).send(rows);
     } catch (err) {
       console.error(err);
       res.status(500).send(`Error querying BigQuery: ${err}`);
     }
   });

Implemente a função

Para implementar a função com um acionador HTTP:

1. Execute o seguinte comando no diretório que contém o código de exemplo:

   gcloud run deploy FUNCTION \
      --source . \
      --function FUNCTION_ENTRYPOINT \
      --base-image BASE_IMAGE \
      --region REGION \
      --allow-unauthenticated

   Substituição:

   • FUNCTION com o nome da função que está a implementar, por exemplo, my-bigquery-function. Pode omitir este parâmetro por completo, mas é-lhe pedido o nome se o omitir.

   • FUNCTION_ENTRYPOINT com o ponto de entrada da sua função no código-fonte. Este é o código que o Cloud Run executa quando a sua função é executada. O valor desta flag tem de ser um nome de função ou um nome de classe totalmente qualificado que exista no seu código-fonte. O ponto de entrada que tem de especificar para a função de exemplo é helloBigQuery.

   • BASE_IMAGE com o ambiente de imagem base para a sua função, por exemplo, nodejs22. Para ver detalhes sobre as imagens base e os pacotes incluídos em cada imagem, consulte o artigo Imagens base de tempos de execução.

   • REGION com a Google Cloud região onde quer implementar a sua função. Por exemplo, europe-west1.

   Opcional:

   • Se estiver a criar uma função HTTP pública, por exemplo, um webhook, especifique a flag --allow-unauthenticated. Esta flag atribui a função de invocador da IAM do Cloud Run ao identificador especial allUser. Pode usar o IAM para editar esta definição mais tarde, depois de criar o serviço.

Teste a função

1. Quando a implementação da função terminar, copie a propriedade uri.

2. Visite este URI no seu navegador.

   Deve ver uma lista das palavras que correspondem aos critérios da consulta e quantas vezes cada palavra aparece no conjunto de dados de destino.

Êxito: criou uma função HTTP do Cloud Run que envia uma consulta ao BigQuery.

Limpar

Para evitar custos adicionais na sua conta do Google Cloud , elimine todos os recursos que implementou com este tutorial.

Elimine o projeto

Se criou um novo projeto para este tutorial, elimine-o. Se usou um projeto existente e precisa de o manter sem as alterações que adicionou neste tutorial, elimine os recursos que criou para o tutorial.

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimine recursos de tutoriais

1. Elimine o serviço do Cloud Run que implementou neste tutorial. Os serviços do Cloud Run não incorrem em custos até receberem pedidos.

   Para eliminar o seu serviço do Cloud Run, execute o seguinte comando:

   gcloud run services delete SERVICE-NAME

   Substitua SERVICE-NAME pelo nome do seu serviço.

   Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.

2. Remova a configuração da região predefinida gcloud que adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project