搭配使用 Spanner 與 Cloud Run 函式 (第 1 代)

目標

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

費用

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

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

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

事前準備

1. 本文假設您擁有一個名為 test-instance 的 Spanner 執行個體，以及一個名為 example-db 且使用音樂應用程式架構的資料庫。如需使用音樂應用程式架構建立執行個體與資料庫的操作說明，請參閱使用主控台的快速入門導覽課程，或 Go、Java、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 設定指南

   Go

   前往 Go 設定指南

   Java

   前往 Java 設定指南

準備應用程式

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 格式的範例檔案，然後將檔案解壓縮。

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

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

   Java

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

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

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

   Node.js

   cd nodejs-docs-samples/functions/spanner/

   Python

   cd python-docs-samples/functions/spanner/

   Go

   cd golang-samples/functions/spanner/

   Java

   cd java-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)
   
   

   Go

   
   // Package spanner contains an example of using Spanner from a Cloud Function.
   package spanner
   
   import (
   	"context"
   	"fmt"
   	"log"
   	"net/http"
   	"sync"
   
   	"cloud.google.com/go/spanner"
   	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
   	"google.golang.org/api/iterator"
   )
   
   // client is a global Spanner client, to avoid initializing a new client for
   // every request.
   var client *spanner.Client
   var clientOnce sync.Once
   
   // db is the name of the database to query.
   var db = "projects/my-project/instances/my-instance/databases/example-db"
   
   func init() {
   	functions.HTTP("HelloSpanner", HelloSpanner)
   }
   
   // HelloSpanner is an example of querying Spanner from a Cloud Function.
   func HelloSpanner(w http.ResponseWriter, r *http.Request) {
   	clientOnce.Do(func() {
   		// Declare a separate err variable to avoid shadowing client.
   		var err error
   		client, err = spanner.NewClient(context.Background(), db)
   		if err != nil {
   			http.Error(w, "Error initializing database", http.StatusInternalServerError)
   			log.Printf("spanner.NewClient: %v", err)
   			return
   		}
   	})
   
   	fmt.Fprintln(w, "Albums:")
   	stmt := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
   	iter := client.Single().Query(r.Context(), stmt)
   	defer iter.Stop()
   	for {
   		row, err := iter.Next()
   		if err == iterator.Done {
   			return
   		}
   		if err != nil {
   			http.Error(w, "Error querying database", http.StatusInternalServerError)
   			log.Printf("iter.Next: %v", err)
   			return
   		}
   		var singerID, albumID int64
   		var albumTitle string
   		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
   			http.Error(w, "Error parsing database response", http.StatusInternalServerError)
   			log.Printf("row.Columns: %v", err)
   			return
   		}
   		fmt.Fprintf(w, "%d %d %s\n", singerID, albumID, albumTitle)
   	}
   }
   

   Java

   import com.google.api.client.http.HttpStatusCodes;
   import com.google.cloud.functions.HttpFunction;
   import com.google.cloud.functions.HttpRequest;
   import com.google.cloud.functions.HttpResponse;
   import com.google.cloud.spanner.DatabaseClient;
   import com.google.cloud.spanner.DatabaseId;
   import com.google.cloud.spanner.LazySpannerInitializer;
   import com.google.cloud.spanner.ResultSet;
   import com.google.cloud.spanner.SpannerException;
   import com.google.cloud.spanner.SpannerOptions;
   import com.google.cloud.spanner.Statement;
   import com.google.common.annotations.VisibleForTesting;
   import com.google.common.base.MoreObjects;
   import java.io.PrintWriter;
   import java.util.logging.Level;
   import java.util.logging.Logger;
   
   // HelloSpanner is an example of querying Spanner from a Cloud Function.
   public class HelloSpanner implements HttpFunction {
     private static final Logger logger = Logger.getLogger(HelloSpanner.class.getName());
   
     // TODO<developer>: Set these environment variables.
     private static final String SPANNER_INSTANCE_ID =
         MoreObjects.firstNonNull(System.getenv("SPANNER_INSTANCE"), "my-instance");
     private static final String SPANNER_DATABASE_ID =
         MoreObjects.firstNonNull(System.getenv("SPANNER_DATABASE"), "example-db");
   
     private static final DatabaseId databaseId =
         DatabaseId.of(
             SpannerOptions.getDefaultProjectId(),
             SPANNER_INSTANCE_ID,
             SPANNER_DATABASE_ID);
   
     // The LazySpannerInitializer instance is shared across all instances of the HelloSpanner class.
     // It will create a Spanner instance the first time one is requested, and continue to return that
     // instance for all subsequent requests.
     private static final LazySpannerInitializer SPANNER_INITIALIZER = new LazySpannerInitializer();
   
     @VisibleForTesting
     DatabaseClient getClient() throws Throwable {
       return SPANNER_INITIALIZER.get().getDatabaseClient(databaseId);
     }
   
     @Override
     public void service(HttpRequest request, HttpResponse response) throws Exception {
       var writer = new PrintWriter(response.getWriter());
       try {
         DatabaseClient client = getClient();
         try (ResultSet rs =
             client
                 .singleUse()
                 .executeQuery(Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"))) {
           writer.printf("Albums:%n");
           while (rs.next()) {
             writer.printf(
                 "%d %d %s%n",
                 rs.getLong("SingerId"), rs.getLong("AlbumId"), rs.getString("AlbumTitle"));
           }
         } catch (SpannerException e) {
           writer.printf("Error querying database: %s%n", e.getMessage());
           response.setStatusCode(HttpStatusCodes.STATUS_CODE_SERVER_ERROR, e.getMessage());
         }
       } catch (Throwable t) {
         logger.log(Level.SEVERE, "Spanner example failed", t);
         writer.printf("Error setting up Spanner: %s%n", t.getMessage());
         response.setStatusCode(HttpStatusCodes.STATUS_CODE_SERVER_ERROR, t.getMessage());
       }
     }
   }

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

部署函式

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

Node.js

gcloud functions deploy get \
--runtime nodejs22 --trigger-http

使用 --runtime 旗標指定支援的 Node.js 版本執行階段 ID，執行函式。

Python

gcloud functions deploy spanner_read_data \
--runtime python312 --trigger-http

使用 --runtime 旗標指定支援的 Python 版本執行階段 ID，執行函式。

Go

gcloud functions deploy HelloSpanner \
--runtime go121 --trigger-http

使用 --runtime 旗標指定支援的 Go 版本執行階段 ID，執行函式。

Java

gcloud functions deploy java-spanner-function \
--entry-point functions.HelloSpanner \
--runtime java17 \
--memory 512MB --trigger-http

使用 --runtime 旗標指定支援的 Java 版本執行階段 ID，執行函式。

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

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

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

觸發函式

對您的函式提出 HTTP 要求：

Node.js

curl "https://REGION-PROJECT_ID.cloudfunctions.net/get" 

Python

curl "https://REGION-PROJECT_ID.cloudfunctions.net/spanner_read_data" 

Go

curl "https://REGION-PROJECT_ID.cloudfunctions.net/HelloSpanner" 

Java

curl "https://REGION-PROJECT_ID.cloudfunctions.net/java-spanner-function" 

其中 REGION 與 PROJECT_ID 應與函式部署完成後，在終端機中顯示的值相符。假設您已完成入門指南教學課程並填好資料庫，您應該會看到顯示 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 查詢的結果。

清除所用資源

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

1. 刪除執行個體：

   gcloud spanner instances delete test-instance
   

2. 刪除您部署的函式：

   Node.js

   gcloud functions delete get 

   Python

   gcloud functions delete spanner_read_data 

   Go

   gcloud functions delete HelloSpanner 

   Java

   gcloud functions delete java-spanner-function 

後續步驟

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