Usar o Spanner com funções do Cloud Run (1.ª geração)

Objetivos

Escrever, implementar e acionar uma função HTTP do Cloud Run que acede ao Spanner.

Custos

Este documento usa funções do Spanner e do Cloud Run, que são componentes faturáveis do Google Cloud.

Antes de começar

  1. Este documento pressupõe que tem uma instância do Spanner com o nome test-instance e uma base de dados com o nome example-db que usa o esquema da aplicação de música. Para obter instruções sobre como criar uma instância e uma base de dados com o esquema da aplicação de música, consulte o guia de início rápido com a consola ou os tutoriais para começar a usar o Go, o Java, o Node.js ou o Python.

  2. Ative as APIs Cloud Run Functions e Cloud Build.

    Ative as APIs

  3. Instale e inicialize a CLI gcloud.

    Se já tiver a CLI gcloud instalada, atualize-a executando o seguinte comando:

    gcloud components update

  4. Prepare o ambiente de programação:

Prepare a candidatura

  1. Clone o repositório da app de exemplo para a sua máquina local:

    Node.js 

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

    Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

    Python 

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

    Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

    Go 

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

    Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

    Java 

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

    Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

  2. Altere para o diretório que contém o código de exemplo das funções do Cloud Run para aceder ao 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. Veja o exemplo de código:

    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());
    }
  }
}

    A função envia uma consulta SQL para obter todos os dados do Albums da sua base de dados. A função é executada quando faz um pedido HTTP ao ponto final da função.

Implemente a função

Para implementar a função com um acionador HTTP, execute o seguinte comando no diretório spanner:

Node.js 

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão suportada do Node.js para executar a sua função.

Python 

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Python suportada para executar a sua função.

Go 

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão do Go suportada para executar a sua função.

Java 

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

Use a flag --runtime para especificar o ID de tempo de execução de uma versão Java suportada para executar a sua função.

A implementação da função pode demorar até dois minutos.

Tenha em atenção o valor url devolvido quando a implementação da função terminar. Vai usá-lo quando acionar a função.

Pode ver as suas funções implementadas na página Funções do Cloud Run na Google Cloud consola. Também pode criar e editar funções nessa página, bem como obter detalhes e diagnósticos para as suas funções.

Acionar a função

Efetue um pedido HTTP à sua função:

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"

em que REGION e PROJECT_ID correspondem aos valores visíveis no seu terminal quando a função termina a implementação. Deverá ver um resultado que mostra os resultados da consulta SQL, partindo do princípio de que seguiu um tutorial de introdução e preencheu a base de dados:

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

Também pode visitar o URL da função no navegador para ver o resultado da sua consulta SQL.

Limpeza

Para evitar incorrer em cobranças adicionais na sua Google Cloud conta pelos recursos das funções do Spanner e do Cloud Run usados neste documento, faça o seguinte:

  1. Elimine a instância:

    gcloud spanner instances delete test-instance

  2. Elimine a função que implementou:

    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

O que se segue?