שימוש ב-Spanner עם פונקציות Cloud Run (דור ראשון)

מטרות

כתיבה, פריסה והפעלה של פונקציית HTTP Cloud Run עם גישה ל-Spanner.

עלויות

במסמך הזה נעשה שימוש בפונקציות של Spanner ו-Cloud Run, שהן רכיבים של Google Cloudשחלים עליהם חיובים.

• מידע על העלות של שימוש ב-Spanner מופיע במאמר בנושא תמחור Spanner.

• למידע על העלות של שימוש בפונקציות Cloud Run, כולל הפעלות בחינם, ראו תמחור של פונקציות Cloud Run.

לפני שמתחילים

1. במסמך הזה אנחנו מניחים שיש לכם מופע Spanner בשם test-instance ומסד נתונים בשם example-db שמשתמש בסכימה של אפליקציית המוזיקה. הוראות ליצירת מופע ומסד נתונים עם סכימת אפליקציית המוזיקה מופיעות במאמר הפעלה מהירה באמצעות המסוף או במדריכים לתחילת העבודה ב-Go,‏ Java,‏ Node.js או Python.

   הערה: אחרי השלב הזה, אמורות להיות לכם שתי טבלאות, Singers ו-Albums, במסד הנתונים עם נתוני הדוגמה שצוינו בסכימה של אפליקציית המוזיקה.

2. מפעילים את פונקציות Cloud Run ואת Cloud Build API.

   הפעלת ממשקי ה-API

3. מתקינים ומפעילים את ה-CLI של gcloud.

   אם כבר התקנתם את ה-CLI של gcloud, תוכלו לעדכן אותו באמצעות הפקודה הבאה:

   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 נתמכת להרצת הפונקציה.

Python

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

משתמשים בדגל --runtime כדי לציין את מזהה זמן הריצה של גרסת Python נתמכת להרצת הפונקציה.

Go

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

כדי לציין את מזהה זמן הריצה של גרסת Go נתמכת להרצת הפונקציה, משתמשים בדגל --runtime.

Java

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

משתמשים בדגל --runtime כדי לציין את מזהה זמן הריצה של גרסת Java נתמכת להרצת הפונקציה.

פריסת הפונקציה עשויה להימשך עד שתי דקות.

שימו לב לערך url שמוחזר כשהפריסה של הפונקציה מסתיימת. תשתמשו בו כשמפעילים את הפונקציה.

אפשר לראות את פונקציות Cloud Run שפרסתם בדף Cloud Run functions במסוףGoogle Cloud . בדף הזה אפשר גם ליצור ולערוך פונקציות, ולקבל פרטים וניתוח של הפונקציות.

הפעלת הפונקציה

שליחת בקשת 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

אפשר גם להיכנס לכתובת ה-URL של הפונקציה בדפדפן כדי לראות את התוצאה של שאילתת ה-SQL.

הסרת המשאבים

כדי להימנע מחיובים נוספים בחשבון על המשאבים של פונקציות Spanner ו-Cloud Run שבהם נעשה שימוש במסמך הזה, צריך לבצע את הפעולות הבאות: 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 

המאמרים הבאים

• מידע נוסף על כתיבת פונקציות Cloud Run
• מידע נוסף על פריסת פונקציות Cloud Run
• מידע נוסף על הפעלת פונקציות Cloud Run
• מידע נוסף על מעקב אחר פונקציות Cloud Run