搭配使用 Cloud Spanner 与 Cloud Functions

Cloud Spanner

目标

编写、部署和触发可访问 Spanner 的 HTTP Cloud Functions 函数

费用

本主题使用了 Spanner 和 Cloud Functions,它们是 Google Cloud 的收费组件。

准备工作

  1. 本主题假设您有一个名为 test-instance 的 Spanner 实例和一个使用音乐应用架构的名为 example-db 的数据库。如需了解如何创建实例以及使用音乐应用架构的数据库,请参阅《快速入门:使用控制台》或者 GoJavaNode.jsPython 版使用入门教程。

  2. 启用 Cloud Functions API。

    启用该 API

  3. 安装并初始化 Cloud SDK

  4. 更新 gcloud 组件:

    gcloud components update
    
  5. 准备开发环境:

准备应用

  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. 切换到包含用于访问 Spanner 的 Cloud Functions 函数示例代码的目录:

    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');
    
    // 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.
     */
    exports.get = 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

    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)
    
    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"
    	"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"
    
    // 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.ResultSet;
    import com.google.cloud.spanner.Spanner;
    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());
    
      @VisibleForTesting
      static Spanner createSpanner() {
        return SpannerOptions.newBuilder().build().getService();
      }
    
      // SpannerHolder is a holder class for a Spanner instance that is initialized lazily.
      private static final class SpannerHolder {
        private final Object lock = new Object();
        private volatile boolean initialized;
        private volatile DatabaseClient client;
        private volatile Throwable error;
    
        private SpannerHolder() {}
    
        // Initialize the {@link Spanner} instance in a method and not as a static variable, as it
        // might throw an error, and we want to catch and log that specific error. An administrator must
        // take action to mitigate the reason for the initialization failure, for example ensuring that
        // the service account being used to access Cloud Spanner has permission to do so.
        DatabaseClient get() throws Throwable {
          if (!initialized) {
            synchronized (lock) {
              if (!initialized) {
                try {
                  DatabaseId db =
                      DatabaseId.of(
                          SpannerOptions.getDefaultProjectId(),
                          SPANNER_INSTANCE_ID,
                          SPANNER_DATABASE_ID);
                  client = createSpanner().getDatabaseClient(db);
                } catch (Throwable t) {
                  error = t;
                }
                initialized = true;
              }
            }
          }
          if (error != null) {
            throw error;
          }
          return client;
        }
      }
    
      // The SpannerHolder instance is shared across all instances of the HelloSpanner class.
      private static final SpannerHolder SPANNER_HOLDER = new SpannerHolder();
    
      @VisibleForTesting
      DatabaseClient getClient() throws Throwable {
        return SPANNER_HOLDER.get();
      }
    
      // 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");
    
      @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 nodejs10 --trigger-http
您可以使用 --runtime 标志的以下值来指定偏好的 Node.js 版本:
  • nodejs10
  • nodejs12

Python

gcloud functions deploy spanner_read_data \
--runtime python37 --trigger-http
您可以使用 --runtime 标志的以下值来指定偏好的 Python 版本:
  • python37
  • python38

Go

gcloud functions deploy HelloSpanner \
--runtime go111 --trigger-http
您可以使用 --runtime 标志的以下值来指定偏好的 Go 版本:
  • go111
  • go113

Java

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

函数部署最多可能需要 2 分钟。

当您的函数完成部署时,请记下系统返回的 url 值。您将会在触发该函数时用到该值。

您可以在 Google Cloud Console 中的 Cloud 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" 

其中,REGIONPROJECT_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 查询结果。

清理

为避免系统因本主题中使用的 Spanner 和 Cloud Functions 资源向您的 Google Cloud 帐号收取额外费用,请执行以下操作:

  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 

后续步骤