Criar uma função que retorna resultados do BigQuery

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

Antes de começar

  1. Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.

  2. Ative as APIs Artifact Registry, Cloud Build e Cloud Run Admin:

     gcloud services enable artifactregistry.googleapis.com \
     cloudbuild.googleapis.com \
     run.googleapis.com

  3. 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:

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 interagir com APIsGoogle Cloud , 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 Cloud Run Builder (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@developer.gserviceaccount.com \
      --role=roles/run.builder

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

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

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 como um arquivo zip e extraia-a.

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

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

  3. Confira o código de amostra. 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}`);
  }
});

Implante 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: 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 exemplo é helloBigQuery.

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

    • REGION pela região do Google Cloudem que você quer implantar a função. Por exemplo, us-central1.

    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.

Limpar

Ainda que o Cloud Run não gere custos quando o serviço não estiver em uso, é possível que receba cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. É possível excluir sua imagem de contêiner ou excluir seu projeto do Google Cloud para evitar cobranças. A exclusão do projeto do Google Cloud interrompe o faturamento de todos os recursos usados no projeto.

  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.