建立可傳回 Spanner 結果的 Cloud Run 函式

本教學課程說明如何編寫 HTTP Cloud Run 函式，以傳回 Spanner 結果。

目標

編寫、部署及觸發可存取 Spanner 的 HTTP 函式。

費用

本文使用 Spanner 和 Cloud Run，這兩者都是 Google Cloud的計費元件。

• 如要瞭解 Spanner 的使用費用，請參閱 Spanner 定價。

• 如要瞭解 Cloud Run 的使用費用，包括免費叫用，請參閱 Cloud Run 定價。

事前準備

1. 本文假設您擁有一個名為 test-instance 的 Spanner 執行個體，以及一個名為 example-db 且使用音樂應用程式架構的資料庫。如需使用音樂應用程式結構定義建立執行個體與資料庫的操作說明，請參閱使用主控台的快速入門導覽課程，或 Node.js 或 Python 中的入門指南教學課程。

   注意： 完成此步驟後，資料庫中應該會有兩個資料表：Singers 和 Albums，其中包含音樂應用程式架構中指定的範例資料。

2. 啟用 Cloud Run 和 Cloud Build API。

   啟用 API

3. 安裝並初始化 gcloud CLI。

   如果您已安裝 gcloud CLI，請執行下列指令來更新：

   gcloud components update
   

4. 準備您的開發環境：

   Node.js

   請參閱 Node.js 設定指南。

   Python

   請參閱 Python 設定指南。

必要的角色

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

• Cloud Run 原始碼開發者 (roles/run.sourceDeveloper) 專案
• 服務用量消費者 (roles/serviceusage.serviceUsageConsumer) 在 Cloud Run 服務上
• 服務帳戶使用者 (roles/iam.serviceAccountUser) 服務身分
• Spanner 管理員 (roles/spanner.admin) 在 Spanner 執行個體上

如需與 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 Builder (roles/run.builder) 授予專案的 Compute Engine 預設服務帳戶：

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

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

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

注意：

iam.automaticIamGrantsForDefaultServiceAccounts 組織政策限制可防止系統自動將編輯者角色授予預設服務帳戶。如果組織是在 2024 年 5 月 3 日後建立，系統預設會強制執行這項限制。

強烈建議您強制執行這項限制，停用自動角色授予功能。停用此功能後，您必須決定要將哪些角色授予預設服務帳戶，然後自行授予這些角色。

如果預設服務帳戶已具備「編輯者」角色，建議您將「編輯者」角色替換為權限較少的角色。如要安全修改服務帳戶的角色，請使用 Policy Simulator 查看變更會造成的影響，然後授予及撤銷適當的角色。

服務身分角色

您必須將下列 IAM 角色授予 Cloud Run 服務使用的服務身分。

• Spanner 資料庫讀取者 (roles/spanner.databaseReader)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

準備應用程式

1. 將應用程式存放區範例複製到本機電腦中：

   Node.js

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

   您也可以下載 zip 格式的範例，然後解壓縮該檔案。

   Python

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

   您也可以下載 zip 格式的範例，然後解壓縮該檔案。

2. 變更到包含 Cloud Run 函式程式碼範例的目錄，以存取 Spanner：

   Node.js

   cd nodejs-docs-samples/functions/spanner

   Python

   cd python-docs-samples/functions/spanner

3. 查看程式碼範例：

   Node.js

   // Imports the Google Cloud client library
   const {Spanner} = require('@google-cloud/spanner');
   
   // Imports the functions framework to register your HTTP function
   const functions = require('@google-cloud/functions-framework');
   
   // Instantiates a client
   const spanner = new Spanner();
   
   // Your Cloud Spanner instance ID
   const instanceId = 'test-instance';
   
   // Your Cloud Spanner database ID
   const databaseId = 'example-db';
   
   /**
    * HTTP Cloud Function.
    *
    * @param {Object} req Cloud Function request context.
    * @param {Object} res Cloud Function response context.
    */
   functions.http('spannerQuickstart', async (req, res) => {
     // Gets a reference to a Cloud Spanner instance and database
     const instance = spanner.instance(instanceId);
     const database = instance.database(databaseId);
   
     // The query to execute
     const query = {
       sql: 'SELECT * FROM Albums',
     };
   
     // Execute the query
     try {
       const results = await database.run(query);
       const rows = results[0].map(row => row.toJSON());
       rows.forEach(row => {
         res.write(
           `SingerId: ${row.SingerId}, ` +
             `AlbumId: ${row.AlbumId}, ` +
             `AlbumTitle: ${row.AlbumTitle}\n`
         );
       });
       res.status(200).end();
     } catch (err) {
       res.status(500).send(`Error querying Spanner: ${err}`);
     }
   });

   Python

   import functions_framework
   from google.cloud import spanner
   
   instance_id = "test-instance"
   database_id = "example-db"
   
   client = spanner.Client()
   instance = client.instance(instance_id)
   database = instance.database(database_id)
   
   
   @functions_framework.http
   def spanner_read_data(request):
       query = "SELECT * FROM Albums"
   
       outputs = []
       with database.snapshot() as snapshot:
           results = snapshot.execute_sql(query)
   
           for row in results:
               output = "SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row)
               outputs.append(output)
   
       return "\n".join(outputs)
   
   

   函式會傳送 SQL 查詢，從您的資料庫擷取所有 Albums 資料。函式會在您對函式的端點提出 HTTP 要求時執行。

部署函式

如要使用 HTTP 觸發條件部署函式，請在 spanner 目錄中執行下列指令：

Node.js

gcloud run deploy nodejs-spanner-function \
    --source . \
    --region REGION \
    --function spannerQuickstart \
    --base-image RUNTIME_ID \
    --log-http

Python

gcloud run deploy python-spanner-function \
    --source . \
    --region REGION \
    --function spanner_read_data \
    --base-image RUNTIME_ID \
    --log-http

取代：

• REGION：要部署函式的 Google Cloud 區域名稱 (例如 us-west1)。

• RUNTIME_ID，並使用適當的執行階段 ID (例如 nodejs22)。請參閱「支援的語言執行階段和基礎映像檔」。

部署函式可能需要兩分鐘的時間。

請注意函式完成部署時傳回的 url 值，您將在觸發函式時使用它。

您可以在Google Cloud 控制台的「Cloud Run」頁面中，查看已部署的函式。您也可在該頁面上建立及編輯函式，並取得函式的詳細資料與診斷資訊。

觸發函式

對您的函式提出 HTTP 要求：

curl URL

將 URL 替換為函式完成部署時傳回的網址值。

假設您已完成入門指南教學課程並填好資料庫，您應該會看到顯示 SQL 查詢結果的輸出內容：

SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk

您也可以透過瀏覽器造訪函式的網址，查看 SQL 查詢的結果。

成功： 您已建立 HTTP Cloud Run 函式，可傳回 Spanner 結果。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本文件所用 Spanner 和 Cloud Run 函式資源的額外費用，請執行下列操作：

1. 刪除執行個體：

   gcloud CLI instances delete test-instance
   

2. 刪除您在本教學課程中部署的 Cloud Run 服務：

   Node.js

   gcloud run services delete nodejs-spanner-function

   Python

   gcloud run services delete python-spanner-function

後續步驟

• 進一步瞭解如何編寫 Cloud Run 函式
• 進一步瞭解呼叫 Cloud Run 函式
• 進一步瞭解如何觸發 Cloud Run 函式。