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

Neste tutorial, mostramos como criar uma função HTTP do Cloud Run que envia uma consulta para o BigQuery.

Objetivos

Com este tutorial, você vai:

1. Preparar o aplicativo que envia uma consulta para o BigQuery.
2. Implantar a função com um acionador HTTP.
3. Testar a função.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run

Para gerar uma estimativa de custo baseada na projeção de uso, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Antes de começar

1. 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 role (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

2. Verify that billing is enabled for your Google Cloud project.

3. Ative o Artifact Registry, a API Cloud Run Admin e as APIs Cloud Build.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

4. Configure o ambiente de desenvolvimento do Cloud Run no seu Google Cloud projeto do.

5. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

Funções exigidas

Para receber as permissões necessárias para implantar os serviços do Cloud Run a partir da origem, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper) no seu projeto
• Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) no serviço do Cloud Run
• Usuário da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço
• Usuário de jobs do BigQuery (roles/bigquery.jobUser) na identidade do serviço

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o serviço do Cloud Run interage com Google Cloud APIs, como as bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Papéis da conta de serviço do Cloud Build

Você ou seu administrador precisa conceder à conta de serviço do Cloud Build o seguinte papel do IAM.

Clique para conferir os papéis necessários para a conta de serviço do Cloud Build

O Cloud Build usa automaticamente a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar o código-fonte e o recurso do Cloud Run, a menos que você substitua esse comportamento. Para que o Cloud Build crie suas origens, peça ao administrador para conceder o criador do Cloud Run (roles/run.builder) à conta de serviço padrão do Compute Engine no seu projeto:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@ \
      --role=roles/run.builder
  

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

A concessão do papel de criador do Cloud Run à conta de serviço padrão do Compute Engine leva alguns minutos para se propagar.

Observação:

O restrição de política da organização iam.automaticIamGrantsForDefaultServiceAccounts impede que o papel de editor seja concedido automaticamente a contas de serviço padrão. Se você criou a organização após 3 de maio de 2024, essa restrição será aplicada por padrão.

É altamente recomendável aplicar essa restrição para desativar a concessão automática de papéis. Se você desativar a concessão automática de papéis, precisará decidir quais papéis conceder às contas de serviço padrão e, em seguida, conceder esses papéis por conta própria.

Se a conta de serviço padrão já tiver o papel de editor, recomendamos que você o substitua por papéis menos permissivos.Para modificar com segurança os papéis da conta de serviço, use o Simulador de política para ver o impacto da mudança e, em seguida, conceda e revogue os papéis apropriados.

Preparar o aplicativo

1. Clone o repositório de aplicativos de exemplo na máquina local:

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

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

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

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

3. Confira o exemplo de código. A amostra envia uma consulta para palavras que ocorrem pelo menos 400 vezes no conjunto de dados especificado e retorna 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}`);
     }
   });

Implantar a função

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

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

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

   Substitua:

   • FUNCTION pelo nome da função que você está implantando, por exemplo, my-bigquery-function. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome, se você omiti-lo.

   • FUNCTION_ENTRYPOINT com o ponto de entrada da função no código-fonte. Esse é o código que o Cloud Run executa quando é executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte. O ponto de entrada que você precisa especificar para a função de amostra é helloBigQuery.

   • BASE_IMAGE com o ambiente de imagem base da sua função, por exemplo, nodejs24. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Imagens de base dos ambientes de execução.

   • REGION com a Google Cloud região em que você quer implantar a função. Por exemplo, europe-west1.

   Opcional:

   • Se você estiver criando uma função HTTP pública, por exemplo, um webhook, especifique a flag --allow-unauthenticated. Essa flag atribui o papel de invocador do IAM do Cloud Run ao identificador especial allUser. É possível usar o IAM para editar essa configuração depois de criar o serviço.

Testar a função

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

2. Acesse o URI no seu navegador.

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

Sucesso: você criou uma função HTTP do Cloud Run que envia uma consulta para o BigQuery.

Limpar

Para evitar cobranças extras na sua Google Cloud conta do, exclua todos os recursos implantados com este tutorial.

Excluir o projeto

Se você criou um novo projeto para este tutorial, exclua-o. Se você usou um projeto atual e precisa mantê-lo sem as mudanças adicionadas neste tutorial, exclua os recursos criados para o tutorial.

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No Google Cloud console, acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
3. Na caixa de diálogo, digite o ID do projeto e clique em Desligar para excluir o projeto.

Excluir recursos do tutorial

1. Exclua o serviço do Cloud Run que você implantou neste tutorial. Os serviços do Cloud Run não geram custos até receberem solicitações.

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

   gcloud run services delete SERVICE-NAME

   Substitua SERVICE-NAME pelo nome do serviço.

   Também é possível excluir os serviços do Cloud Run no Google Cloud console.

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

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project