创建用于返回 BigQuery 结果的函数

预览 — Cloud Run functions

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

本教程将向您介绍如何编写将查询提交到 BigQuery 的 HTTP Cloud Run 函数。

准备工作

1. 确保您已按照设置页面中的说明为 Cloud Run 设置了新项目。

2. 启用 Artifact Registry API、Cloud Build API 和 Cloud Run Admin API：

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

3. 如果您通过网域限制组织政策来限制项目的未经身份验证的调用，则您需要按照测试专用服务中的说明访问已部署的服务。

所需的角色

如需获得从源代码部署 Cloud Run 服务所需的权限，请让管理员向您授予以下 IAM 角色：

• Cloud Run 服务的 Cloud Run Source Developer (roles/run.sourceDeveloper) 角色
• Cloud Run 服务的服务使用情况使用方 (roles/serviceusage.serviceUsageConsumer) 角色
• 服务身份的 Service Account User (roles/iam.serviceAccountUser) 角色
• 服务身份的 BigQuery Job User (roles/bigquery.jobUser)

如需查看与 Cloud Run 关联的 IAM 角色和权限的列表，请参阅 Cloud Run IAM 角色和 Cloud Run IAM 权限。如果您的 Cloud Run 服务与Google Cloud API（例如 Cloud 客户端库）进行交互，请参阅服务身份配置指南。如需详细了解如何授予角色，请参阅部署权限和管理访问权限。

服务账号的角色

为了让 Cloud Build 能够构建来源，请运行以下命令，将 Cloud Build Service Account 角色授予给 Compute Engine 默认服务账号：

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

将 PROJECT_NUMBER 替换为您的 Google Cloud项目编号，并将 PROJECT_ID 替换为您的 Google Cloud项目 ID。如需详细了解如何查找项目 ID 和项目编号，请参阅创建和管理项目。

向 Compute Engine 默认服务账号授予 Cloud Build Service Account 角色需要几分钟时间才能传播。

注意：

iam.automaticIamGrantsForDefaultServiceAccounts 组织政策限制条件可以防止将 Editor 角色自动授予默认服务账号。如果您的组织是在 2024 年 5 月 3 日之后创建的，则默认情况下会强制执行此限制条件。

我们强烈建议您实施此限制条件，以停用自动角色授予功能。如果您停用自动角色授予功能，则必须决定向默认服务账号授予哪些角色，然后自行授予这些角色。

如果默认服务账号已具有 Editor 角色，我们建议您将 Editor 角色替换为权限较少的角色。如需安全地修改服务账号的角色，请使用 Policy Simulator 查看更改的影响，然后授予和撤消相应的角色。

准备应用

1. 将示例应用代码库克隆到本地计算机：

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

   或者，下载该示例的 zip 文件并将其解压缩。

2. 转到包含示例代码的目录：

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

3. 查看示例代码。该示例会提交针对指定数据集中至少出现 400 次的字词的查询，并返回结果。

   // 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}`);
     }
   });

部署该函数

如需使用 HTTP 触发器部署函数，请执行以下操作：

1. 在包含示例代码的目录中运行以下命令：

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

   您需要进行如下替换：

   • 将 FUNCTION 替换为您要部署的函数的名称，例如 my-bigquery-function。您可以完全省略此参数，但如果省略它，系统将提示您输入名称。

   • 将 FUNCTION_ENTRYPOINT 替换为源代码中函数的入口点。这是 Cloud Run 在您的函数运行时执行的代码。此标志的值必须是源代码中存在的函数名称或完全限定类名称。您必须为示例函数指定的入口点为 helloBigQuery。

   • 将 BASE_IMAGE 替换为函数的基础映像环境，例如 nodejs22。如需详细了解基础映像以及每个映像中包含的软件包，请参阅运行时基础映像。

   • 将 REGION 替换为您要在其中部署函数的 Google Cloud 区域。例如 us-central1。

   可选：

   • 如果您要创建公开 HTTP 函数（例如 webhook），请指定 --allow-unauthenticated 标志。此标志会将 Cloud Run IAM Invoker 角色分配给特殊标识符 allUser。您可以在创建服务后使用 IAM 修改此设置。

测试函数

1. 当函数完成部署时，复制 uri 属性。

2. 在浏览器中访问此 URI。

   您应该会看到符合查询条件的字词列表，以及每个字词在目标数据集中出现的次数。

清理

虽然 Cloud Run 不会对未在使用中的服务计费，但您可能仍然需要支付将容器映像存储在 Artifact Registry 中而产生的相关费用。为避免产生费用，您可以删除容器映像或删除 Google Cloud 项目。删除您的 Google Cloud 项目后，系统会停止对该项目中使用的所有资源计费。

注意：删除项目会产生以下影响：
• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。
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.