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

目標

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

費用

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

事前準備

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

  2. 啟用 Cloud Run functions 和 Cloud Build API。

    啟用 API

  3. 安裝並初始化 gcloud CLI。

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

    gcloud components update

  4. 準備您的開發環境：

準備應用程式

  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 nodejs20 --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 functions」頁面中，查看已部署的函式。您也可在該頁面上建立及編輯函式，並取得函式的詳細資料與診斷資訊。

觸發函式

對您的函式提出 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. 刪除您部署的函式： <0

    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

後續步驟