建立 Cloud Run functions，使用 BigQuery 提交查詢並傳回結果。

本教學課程說明如何編寫 HTTP Cloud Run 函式，向 BigQuery 提交查詢。

目標

在這個教學課程中，您將執行下列操作：

  1. 準備向 BigQuery 提交查詢的應用程式。
  2. 使用 HTTP 觸發條件部署函式。
  3. 測試函式。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用資格。

事前準備

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

  2. 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.

    Go to project selector

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

  4. 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.

    Go to project selector

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

  6. 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

  7. 在 Google Cloud 專案中設定 Cloud Run 開發環境。

  8. 如果專案受到網域限制組織政策限制，無法進行未經驗證的呼叫，您必須按照「測試私人服務」一節的說明存取已部署的服務。

    9. 必要的角色

    如要取得從來源部署 Cloud Run 服務所需的權限，請要求管理員授予下列 IAM 角色：

    如需與 Cloud Run 相關聯的 IAM 角色和權限清單，請參閱 Cloud Run IAM 角色和 Cloud Run IAM 權限。如果 Cloud Run 服務與Google Cloud API (例如 Cloud 用戶端程式庫) 介接，請參閱服務身分設定指南。 如要進一步瞭解如何授予角色，請參閱部署權限和管理存取權。

    Cloud Build 服務帳戶的角色

    您或管理員必須將下列 IAM 角色授予 Cloud Build 服務帳戶。

    按一下即可查看 Cloud Build 服務帳戶的必要角色

    除非您覆寫這項行為，否則 Cloud Build 會自動使用 Compute Engine 預設服務帳戶做為預設的 Cloud Build 服務帳戶，建構您的原始碼和 Cloud Run 資源。如要讓 Cloud Build 建構來源，請要求管理員將Cloud Run 建構工具 (roles/run.builder) 授予專案中的 Compute Engine 預設服務帳戶：

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

    請將 PROJECT_NUMBER 替換為專案編號，並將 PROJECT_ID 替換為專案 ID。 Google CloudGoogle Cloud如需如何找出專案 ID 和專案編號的詳細操作說明，請參閱「建立及管理專案」。

    將 Cloud Run 建構者角色授予 Compute Engine 預設服務帳戶後，需要幾分鐘才能傳播。

準備應用程式

  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 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是您要部署函式的地區。例如：europe-west1。

    選用：

    • 如要建立公開 HTTP 函式 (例如 Webhook)，請指定 --allow-unauthenticated 旗標。這個標記會將 Cloud Run IAM 叫用者角色指派給特殊 ID allUser。您可以在建立服務之後使用 IAM 編輯這項設定。

測試函式

  1. 函式部署完成後，請複製 uri 屬性。

  2. 在瀏覽器中前往這個 URI。

    您應該會看到符合查詢條件的字詞清單，以及每個字詞在目標資料集中出現的次數。

清除所用資源

為避免系統向您的 Google Cloud 帳戶收取額外費用，請刪除您在本教學課程中部署的所有資源。

刪除專案

如果您是為了這個教學課程建立新專案，請刪除該專案。如果您使用現有專案，且需要保留專案，但不想保留您在本教學課程中新增的變更，請刪除您為本教學課程建立的資源。

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。

如要刪除專案：

  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.

刪除教學課程資源

  1. 刪除您在本教學課程中部署的 Cloud Run 服務。 Cloud Run 服務收到要求後才會開始計費。

    如要刪除 Cloud Run 服務，請執行下列指令：

    gcloud run services delete SERVICE-NAME

    將 SERVICE-NAME 改為您的服務名稱。

    您也可以從Google Cloud 控制台刪除 Cloud Run 服務。

  2. 移除您在教學課程設定期間新增的gcloud預設區域設定：

     gcloud config unset run/region

  3. 移除專案設定：

     gcloud config unset project