Cloud Spanner: יוצרים לידרבורד של גיימינג באמצעות Go

1. סקירה כללית

‫Google Cloud Spanner הוא שירות מנוהל של מסד נתונים רלציוני, שניתן להרחבה אופקית, מבוזר גלובלית ומספק עסקאות ACID וסמנטיקה של SQL, בלי להתפשר על ביצועים וזמינות גבוהה.

בשיעור ה-Lab הזה תלמדו איך להגדיר מופע של Cloud Spanner. תעברו על השלבים ליצירת מסד נתונים וסכימה שאפשר להשתמש בהם ללידרבורד של משחקים. תתחילו ביצירת טבלת שחקנים לאחסון פרטי השחקנים וטבלת ניקוד לאחסון הניקוד של השחקנים.

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

מה תלמדו

איך מגדירים מופע של Cloud Spanner.
איך יוצרים מסד נתונים וטבלאות.
איך משתמשים בעמודת חותמת זמן של השמירה.
איך טוענים נתונים לטבלת מסד נתונים ב-Cloud Spanner עם חותמות זמן.
איך שולחים שאילתות למסד הנתונים שלכם ב-Cloud Spanner.
איך מוחקים את המכונה של Cloud Spanner.

What you'll need

דפדפן אינטרנט, כמו Chrome או Firefox.

איך תשתמשו במדריך הזה?

רק לקרוא

לקרוא ולבצע את התרגילים

איזה דירוג מגיע לדעתך לחוויית השימוש שלך ב-Google Cloud Platform?

מתחילים

ביניים

מומחים

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

אם עדיין אין לכם חשבון Google (Gmail או Google Apps), אתם צריכים ליצור חשבון. נכנסים אל Google Cloud Platform Console‏ ( console.cloud.google.com) ויוצרים פרויקט חדש.

אם כבר יש לכם פרויקט, לוחצים על התפריט הנפתח לבחירת פרויקט בפינה הימנית העליונה של המסוף:

ולוחצים על הלחצן 'פרויקט חדש' בתיבת הדו-שיח שמופיעה כדי ליצור פרויקט חדש:

אם עדיין אין לכם פרויקט, תופיע תיבת דו-שיח כמו זו שבהמשך כדי ליצור את הפרויקט הראשון:

בתיבת הדו-שיח הבאה ליצירת פרויקט, אפשר להזין את הפרטים של הפרויקט החדש:

חשוב לזכור את מזהה הפרויקט, שהוא שם ייחודי בכל הפרויקטים ב-Google Cloud (השם שלמעלה כבר תפוס ולא יתאים לכם, מצטערים!). בהמשך ה-codelab הזה נתייחס אליו כאל PROJECT_ID.

לאחר מכן, אם עדיין לא עשיתם זאת, תצטרכו להפעיל את החיוב במסוף למפתחים כדי להשתמש במשאבים של Google Cloud ולהפעיל את Cloud Spanner API.

העלות של ה-Codelab הזה לא אמורה להיות גבוהה מכמה דולרים, אבל היא יכולה להיות גבוהה יותר אם תחליטו להשתמש ביותר משאבים או אם תשאירו אותם פועלים (ראו את הקטע 'ניקוי נתונים' בסוף המסמך הזה). מידע על התמחור של Google Cloud Spanner מופיע כאן.

משתמשים חדשים ב-Google Cloud Platform זכאים לתקופת ניסיון בחינם בשווי 300$, כך שסדנת ה-codelab הזו אמורה להיות בחינם לגמרי.

הגדרה של Google Cloud Shell

אפשר להפעיל את Google Cloud ואת Spanner מרחוק מהמחשב הנייד, אבל ב-codelab הזה נשתמש ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

המכונה הווירטואלית הזו מבוססת על Debian, וטעונים בה כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. כלומר, כל מה שצריך כדי לבצע את ההוראות במאמר הזה הוא דפדפן (כן, זה עובד ב-Chromebook).

כדי להפעיל את Cloud Shell ממסוף Cloud, פשוט לוחצים על הפעלת Cloud Shell (הקצאת המשאבים והחיבור לסביבה אמורים להימשך רק כמה רגעים).

Screen Shot 2017-06-14 at 10.13.43 PM.png

אחרי שמתחברים ל-Cloud Shell, אמור להופיע אימות שכבר בוצע, ושהפרויקט כבר הוגדר ל-PROJECT_ID.

gcloud auth list

פלט הפקודה

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)

gcloud config list project

פלט הפקודה

[core]
project = <PROJECT_ID>

אם מסיבה כלשהי הפרויקט לא מוגדר, פשוט מריצים את הפקודה הבאה:

gcloud config set project <PROJECT_ID>

מחפש את PROJECT_ID? כדאי לבדוק באיזה מזהה השתמשתם בשלבי ההגדרה, או לחפש אותו בלוח הבקרה של Cloud Console:

ב-Cloud Shell מוגדרים גם כמה משתני סביבה כברירת מחדל, שיכולים להיות שימושיים כשמריצים פקודות בעתיד.

echo $GOOGLE_CLOUD_PROJECT

פלט הפקודה

<PROJECT_ID>

לבסוף, מגדירים את אזור ברירת המחדל ואת הגדרת הפרויקט.

gcloud config set compute/zone us-central1-f

אפשר לבחור מתוך מגוון אזורים שונים. מידע נוסף זמין במאמר בנושא אזורים ותחומים.

סיכום

בשלב הזה מגדירים את הסביבה.

הבא בתור

בשלב הבא, תגדירו מופע של Cloud Spanner.

3. הגדרת מופע של Cloud Spanner

בשלב הזה נגדיר את מופע Cloud Spanner שלנו בשביל ה-codelab הזה. מחפשים את הערך Spanner בתפריט ההמבורגר בפינה הימנית העליונה או מחפשים את Spanner על ידי הקשה על '/' והקלדת 'Spanner'.

לאחר מכן, לוחצים על וממלאים את הטופס. מזינים את שם המכונה cloudspanner-leaderboard, בוחרים הגדרה (מכונה אזורית) ומגדירים את מספר הצמתים. בשביל ה-codelab הזה נצטרך רק צומת אחד. כדי שמכונות ייצור יעמדו בדרישות של הסכם רמת השירות (SLA) של Cloud Spanner, צריך להריץ 3 צמתים או יותר במופע Cloud Spanner.

לבסוף, לוחצים על Create (יצירה) ותוך שניות מופעלת לכם אינטס של Cloud Spanner.

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

4. יצירה של מסד נתונים וסכימה

בשלב הזה ניצור את מסד הנתונים ואת הסכימה לדוגמה.

נשתמש בספריית הלקוח של Go כדי ליצור שתי טבלאות: טבלה בשם Players לפרטי השחקנים וטבלה בשם Scores לאחסון ציוני השחקנים. כדי לעשות את זה, נסביר איך ליצור אפליקציית מסוף Go ב-Cloud Shell.

קודם משכפלים את הקוד לדוגמה של ה-codelab הזה מ-GitHub על ידי הקלדת הפקודה הבאה ב-Cloud Shell:

export GO111MODULE=auto
go get -u github.com/GoogleCloudPlatform/golang-samples/spanner/...

לאחר מכן משנים את הספרייה לספרייה leaderboard שבה תיצרו את האפליקציה.

cd gopath/src/github.com/GoogleCloudPlatform/golang-samples/spanner/spanner_leaderboard

כל הקוד שנדרש ל-codelab הזה נמצא בספרייה הקיימת golang-samples/spanner/spanner_leaderboard/ כאפליקציית Go שניתנת להרצה בשם leaderboard, כדי לשמש כהפניה במהלך העבודה על ה-codelab. ניצור ספרייה חדשה ונבנה עותק של אפליקציית טבלת המובילים בשלבים.

יוצרים ספרייה חדשה בשם codelab לאפליקציה ועוברים אליה באמצעות הפקודה הבאה:

mkdir codelab && cd $_

עכשיו ניצור אפליקציית Go בסיסית בשם Leaderboard שמשתמשת בספריית הלקוח של Spanner כדי ליצור לידרבורד שמורכב משתי טבלאות: Players ו-Scores. אפשר לעשות את זה ישירות ב-Cloud Shell Editor:

פותחים את Cloud Shell Editor על ידי לחיצה על סמל Open editor (פתיחת העורך) שמודגש בהמשך:

יוצרים קובץ בשם leaderboard.go בתיקייה ‎~/gopath/src/github.com/GoogleCloudPlatform/golang-samples/spanner/codelab.

קודם מוודאים שהתיקייה codelab נבחרה ברשימת התיקיות של Cloud Shell Editor.
לאחר מכן בוחרים באפשרות 'קובץ חדש' בתפריט 'קובץ' של Cloud Shell Editor.
מזינים את השם leaderboard.go לקובץ החדש.

זהו הקובץ הראשי של האפליקציה שיכיל את קוד האפליקציה והפניות לכל התלות.

כדי ליצור את מסד הנתונים leaderboard ואת הטבלאות Players ו-Scores, מעתיקים (Ctrl + P) ומדביקים (Ctrl + V) את קוד Go הבא לקובץ leaderboard.go:

package main

import (
        "context"
        "flag"
        "fmt"
        "io"
        "log"
        "os"
        "regexp"
        "time"

        "cloud.google.com/go/spanner"
        database "cloud.google.com/go/spanner/admin/database/apiv1"

        adminpb "google.golang.org/genproto/googleapis/spanner/admin/database/v1"
)

type adminCommand func(ctx context.Context, w io.Writer, adminClient *database.DatabaseAdminClient, database string) error


func createDatabase(ctx context.Context, w io.Writer, adminClient *database.DatabaseAdminClient, db string) error {
        matches := regexp.MustCompile("^(.*)/databases/(.*)$").FindStringSubmatch(db)
        if matches == nil || len(matches) != 3 {
                return fmt.Errorf("Invalid database id %s", db)
        }
        op, err := adminClient.CreateDatabase(ctx, &adminpb.CreateDatabaseRequest{
                Parent:          matches[1],
                CreateStatement: "CREATE DATABASE `" + matches[2] + "`",
                ExtraStatements: []string{
                        `CREATE TABLE Players(
                            PlayerId INT64 NOT NULL,
                            PlayerName STRING(2048) NOT NULL
                        ) PRIMARY KEY(PlayerId)`,
                        `CREATE TABLE Scores(
                            PlayerId INT64 NOT NULL,
                            Score INT64 NOT NULL,
                            Timestamp TIMESTAMP NOT NULL
                            OPTIONS(allow_commit_timestamp=true)
                        ) PRIMARY KEY(PlayerId, Timestamp),
                        INTERLEAVE IN PARENT Players ON DELETE NO ACTION`,
                },
        })
        if err != nil {
                return err
        }
        if _, err := op.Wait(ctx); err != nil {
                return err
        }
        fmt.Fprintf(w, "Created database [%s]\n", db)
        return nil
}

func createClients(ctx context.Context, db string) (*database.DatabaseAdminClient, *spanner.Client) {
        adminClient, err := database.NewDatabaseAdminClient(ctx)
        if err != nil {
                log.Fatal(err)
        }

        dataClient, err := spanner.NewClient(ctx, db)
        if err != nil {
                log.Fatal(err)
        }

        return adminClient, dataClient
}

func run(ctx context.Context, adminClient *database.DatabaseAdminClient, dataClient *spanner.Client, w io.Writer,
        cmd string, db string, timespan int) error {
        // createdatabase command
        if cmd == "createdatabase" {
                err := createDatabase(ctx, w, adminClient, db)
                if err != nil {
                        fmt.Fprintf(w, "%s failed with %v", cmd, err)
                }
                return err
        }
        return nil
}

func main() {
        flag.Usage = func() {
                fmt.Fprintf(os.Stderr, `Usage: leaderboard <command> <database_name> [command_option]

        Command can be one of: createdatabase

Examples:
        leaderboard createdatabase projects/my-project/instances/my-instance/databases/example-db
                - Create a sample Cloud Spanner database along with sample tables in your project.
`)
        }

        flag.Parse()
        flagCount := len(flag.Args())
        if flagCount != 2 {
                flag.Usage()
                os.Exit(2)
        }

        cmd, db := flag.Arg(0), flag.Arg(1)
        // Set timespan to zero, as it's not currently being used
        var timespan int = 0

        ctx, cancel := context.WithTimeout(context.Background(), 1*time.Minute)
        defer cancel()
        adminClient, dataClient := createClients(ctx, db)
        if err := run(ctx, adminClient, dataClient, os.Stdout, cmd, db, timespan); err != nil {
                os.Exit(1)
        }
}

שומרים את השינויים שביצעתם בקובץ leaderboard.go על ידי בחירה באפשרות 'שמירה' בתפריט 'קובץ' של Cloud Shell Editor.

אפשר להשתמש בקובץ leaderboard.go בספרייה golang-samples/spanner/spanner_leaderboard כדי לראות דוגמה לאופן שבו קובץ leaderboard.go צריך להיראות אחרי שמוסיפים את הקוד להפעלת הפקודה createdatabase.

כדי לבנות את האפליקציה ב-Cloud Shell, מריצים את הפקודה go build מהספרייה codelab שבה נמצא הקובץ leaderboard.go:

go build leaderboard.go

אחרי שהאפליקציה נוצרת בהצלחה, מריצים אותה ב-Cloud Shell באמצעות הפקודה הבאה:

./leaderboard

הפלט אמור להיראות כך:

Usage: leaderboard <command> <database_name> [command_option]

        Command can be one of: createdatabase

Examples:
        leaderboard createdatabase projects/my-project/instances/my-instance/databases/example-db
                - Create a sample Cloud Spanner database along with sample tables in your project.

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

מריצים את הפקודה הבאה. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard createdatabase projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard

אחרי כמה שניות אמורה להתקבל תגובה כמו זו:

Created database [projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard]

בקטע Cloud Spanner databases overview במסוף Cloud, אמורים להופיע בתפריט בצד ימין מסד הנתונים והטבלאות החדשים שיצרתם.

בשלב הבא נעדכן את האפליקציה שלנו כדי לטעון נתונים למסד הנתונים החדש.

5. טען נתונים

עכשיו יש לנו מסד נתונים בשם leaderboard שמכיל שתי טבלאות: Players ו-Scores. עכשיו נשתמש בספריית הלקוח של Go כדי לאכלס את הטבלה Players בשחקנים ואת הטבלה Scores בציונים אקראיים לכל שחקן.

אם הוא לא פתוח, פותחים את Cloud Shell Editor בלחיצה על הסמל שמודגש למטה:

לאחר מכן, עורכים את הקובץ leaderboard.go ב-Cloud Shell Editor כדי להוסיף פקודה insertplayers שאפשר להשתמש בה כדי להוסיף 100 שחקנים לטבלה Players. בנוסף, נוסיף פקודה insertscores שאפשר להשתמש בה כדי להוסיף 4 ציונים אקראיים לטבלה Scores לכל שחקן בטבלה Players.

קודם מעדכנים את הקטע imports בחלק העליון של הקובץ leaderboard.go, ומחליפים את מה שמופיע שם כרגע. בסיום, הקטע צריך להיראות כך:

import (
        "context"
        "flag"
        "fmt"
        "io"
        "log"
        "math/rand"
        "os"
        "regexp"
        "time"

        "cloud.google.com/go/spanner"
        database "cloud.google.com/go/spanner/admin/database/apiv1"

        "google.golang.org/api/iterator"
        adminpb "google.golang.org/genproto/googleapis/spanner/admin/database/v1"
)

לאחר מכן מוסיפים סוג פקודה חדש יחד עם רשימת פקודות בחלק העליון של הקובץ, ממש מתחת לשורה שמתחילה ב-type adminCommand ..., כך שבסיום הפעולה הקובץ ייראה כך:

type adminCommand func(ctx context.Context, w io.Writer, adminClient *database.DatabaseAdminClient, database string) error

type command func(ctx context.Context, w io.Writer, client *spanner.Client) error
var (
        commands = map[string]command{
                "insertplayers": insertPlayers,
                "insertscores":  insertScores,
        }
)

לאחר מכן מוסיפים את הפונקציות insertPlayers ו-insertScores מתחת לפונקציה createdatabase() הקיימת:

func insertPlayers(ctx context.Context, w io.Writer, client *spanner.Client) error {
        // Get number of players to use as an incrementing value for each PlayerName to be inserted
        stmt := spanner.Statement{
                SQL: `SELECT Count(PlayerId) as PlayerCount FROM Players`,
        }
        iter := client.Single().Query(ctx, stmt)
        defer iter.Stop()
        row, err := iter.Next()
        if err != nil {
                return err
        }
        var numberOfPlayers int64 = 0
        if err := row.Columns(&numberOfPlayers); err != nil {
                return err
        }
        // Initialize values for random PlayerId
        rand.Seed(time.Now().UnixNano())
        min := 1000000000
        max := 9000000000
        // Insert 100 player records into the Players table
        _, err = client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
                stmts := []spanner.Statement{}
                for i := 1; i <= 100; i++ {
                        numberOfPlayers++
                        playerID := rand.Intn(max-min) + min
                        playerName := fmt.Sprintf("Player %d", numberOfPlayers)
                        stmts = append(stmts, spanner.Statement{
                                SQL: `INSERT INTO Players
                                                (PlayerId, PlayerName)
                                                VALUES (@playerID, @playerName)`,
                                Params: map[string]interface{}{
                                        "playerID":   playerID,
                                        "playerName": playerName,
                                },
                        })
                }
                _, err := txn.BatchUpdate(ctx, stmts)
                if err != nil {
                        return err
                }
                return nil
        })
        fmt.Fprintf(w, "Inserted players \n")
        return nil
}

func insertScores(ctx context.Context, w io.Writer, client *spanner.Client) error {
        playerRecordsFound := false
        // Create slice for insert statements
        stmts := []spanner.Statement{}
        // Select all player records
        stmt := spanner.Statement{SQL: `SELECT PlayerId FROM Players`}
        iter := client.Single().Query(ctx, stmt)
        defer iter.Stop()
        // Insert 4 score records into the Scores table for each player in the Players table
        for {
                row, err := iter.Next()
                if err == iterator.Done {
                        break
                }
                if err != nil {
                        return err
                }
                playerRecordsFound = true
                var playerID int64
                if err := row.ColumnByName("PlayerId", &playerID); err != nil {
                        return err
                }
                // Initialize values for random score and date
                rand.Seed(time.Now().UnixNano())
                min := 1000
                max := 1000000
                for i := 0; i < 4; i++ {
                        // Generate random score between 1,000 and 1,000,000
                        score := rand.Intn(max-min) + min
                        // Generate random day within the past two years
                        now := time.Now()
                        endDate := now.Unix()
                        past := now.AddDate(0, -24, 0)
                        startDate := past.Unix()
                        randomDateInSeconds := rand.Int63n(endDate-startDate) + startDate
                        randomDate := time.Unix(randomDateInSeconds, 0)
                        // Add insert statement to stmts slice
                        stmts = append(stmts, spanner.Statement{
                                SQL: `INSERT INTO Scores
                                                (PlayerId, Score, Timestamp)
                                                VALUES (@playerID, @score, @timestamp)`,
                                Params: map[string]interface{}{
                                        "playerID":  playerID,
                                        "score":     score,
                                        "timestamp": randomDate,
                                },
                        })
                }

        }
        if !playerRecordsFound {
                fmt.Fprintln(w, "No player records currently exist. First insert players then insert scores.")
        } else {
                _, err := client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
                        // Commit insert statements for all scores to be inserted as a single transaction
                        _, err := txn.BatchUpdate(ctx, stmts)
                        return err
                })
                if err != nil {
                        return err
                }
                fmt.Fprintln(w, "Inserted scores")
        }
        return nil
}

לאחר מכן, כדי שהפקודה insert תפעל, מוסיפים את הקוד הבא לפונקציה run של האפליקציה, מתחת להצהרת הטיפול createdatabase, ומחליפים את ההצהרה return nil :

        // insert and query commands
        cmdFn := commands[cmd]
        if cmdFn == nil {
                flag.Usage()
                os.Exit(2)
        }
        err := cmdFn(ctx, w, dataClient)
        if err != nil {
                fmt.Fprintf(w, "%s failed with %v", cmd, err)
        }
        return err

בסיום התהליך, הפונקציה run אמורה להיראות כך:

func run(ctx context.Context, adminClient *database.DatabaseAdminClient, dataClient *spanner.Client, w io.Writer,
        cmd string, db string, timespan int) error {
        // createdatabase command
        if cmd == "createdatabase" {
                err := createDatabase(ctx, w, adminClient, db)
                if err != nil {
                        fmt.Fprintf(w, "%s failed with %v", cmd, err)
                }
                return err
        }

        // insert and query commands
        cmdFn := commands[cmd]
        if cmdFn == nil {
                flag.Usage()
                os.Exit(2)
        }
        err := cmdFn(ctx, w, dataClient)
        if err != nil {
                fmt.Fprintf(w, "%s failed with %v", cmd, err)
        }
        return err
}

השלב האחרון להוספת הפונקציונליות 'הוספה' לאפליקציה הוא הוספת טקסט עזרה לפקודות 'insertplayers' ו-'insertscores' לפונקציה flag.Usage(). מוסיפים את טקסט העזרה הבא לפונקציה flag.Usage() כדי לכלול טקסט עזרה לפקודות ההוספה:

מוסיפים את שתי הפקודות לרשימת הפקודות האפשריות:

Command can be one of: createdatabase, insertplayers, insertscores

מוסיפים את הטקסט הנוסף הזה מתחת לטקסט העזרה של הפקודה createdatabase.

        leaderboard insertplayers projects/my-project/instances/my-instance/databases/example-db
                - Insert 100 sample Player records into the database.
        leaderboard insertscores projects/my-project/instances/my-instance/databases/example-db
                - Insert sample score data into Scores sample Cloud Spanner database table.

שומרים את השינויים שביצעתם בקובץ leaderboard.go על ידי בחירה באפשרות 'שמירה' בתפריט 'קובץ' של Cloud Shell Editor.

עכשיו נבנה ונריץ את האפליקציה כדי לוודא שהפקודות החדשות insertplayers ו-insertscores כלולות ברשימת הפקודות האפשריות של האפליקציה. מריצים את הפקודה הבאה כדי ליצור את האפליקציה:

go build leaderboard.go

מריצים את האפליקציה שנוצרה ב-Cloud Shell על ידי הזנת הפקודה הבאה:

./leaderboard

עכשיו הפקודות insertplayers ו-insertscores אמורות להיכלל בפלט ברירת המחדל של האפליקציה:

Usage: leaderboard <command> <database_name> [command_option]

        Command can be one of: createdatabase, insertplayers, insertscores

Examples:
        leaderboard createdatabase projects/my-project/instances/my-instance/databases/example-db
                - Create a sample Cloud Spanner database along with sample tables in your project.
        leaderboard insertplayers projects/my-project/instances/my-instance/databases/example-db
                - Insert 100 sample Player records into the database.
        leaderboard insertscores projects/my-project/instances/my-instance/databases/example-db
                - Insert sample score data into Scores sample Cloud Spanner database table.

עכשיו נריץ את הפקודה insertplayers עם אותם ערכי ארגומנטים שבהם השתמשנו כשקראנו לפקודה createdatabase. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard insertplayers projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard

אחרי כמה שניות אמורה להתקבל תגובה כמו זו:

Inserted players

עכשיו נשתמש בספריית הלקוח של Go כדי לאכלס את הטבלה Scores בארבעה ציונים אקראיים, יחד עם חותמות זמן לכל שחקן בטבלה Players.

העמודה Timestamp בטבלה Scores הוגדרה כעמודה של חותמת זמן של ביצוע (commit) באמצעות הצהרת ה-SQL הבאה שהופעלה כשקודם הרצנו את הפקודה create:

CREATE TABLE Scores(
  PlayerId INT64 NOT NULL,
  Score INT64 NOT NULL,
  Timestamp TIMESTAMP NOT NULL OPTIONS(allow_commit_timestamp=true)
) PRIMARY KEY(PlayerId, Timestamp),
    INTERLEAVE IN PARENT Players ON DELETE NO ACTION

שימו לב למאפיין OPTIONS(allow_commit_timestamp=true). כך העמודה Timestamp הופכת לעמודה של חותמת זמן של ביצוע, והמערכת יכולה למלא אותה באופן אוטומטי בחותמת הזמן המדויקת של העסקה עבור פעולות INSERT ו-UPDATE בשורה נתונה בטבלה.

אפשר גם להוסיף ערכים של חותמות זמן משלכם לעמודה commit timestamp (חותמת זמן של ביצוע), כל עוד מוסיפים חותמת זמן עם ערך מהעבר. זה מה שנעשה לצורך ה-codelab הזה.

עכשיו נריץ את הפקודה insertscores עם אותם ערכי ארגומנטים שבהם השתמשנו כשקראנו לפקודה insertplayers. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard insertscores projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard

אחרי כמה שניות אמורה להתקבל תגובה כמו זו:

Inserted scores

הפעלת הפונקציה insertScores משתמשת בקטע הקוד הבא כדי להוסיף חותמת זמן שנוצרה באופן אקראי עם תאריך ושעה שקרו בעבר:

now := time.Now()
endDate := now.Unix()
past := now.AddDate(0, -24, 0)
startDate := past.Unix()
randomDateInSeconds := rand.Int63n(endDate-startDate) + startDate
randomDate := time.Unix(randomDateInSeconds, 0)
stmts = append(stmts, spanner.Statement{
        SQL: `INSERT INTO Scores
              (PlayerId, Score, Timestamp)
                 VALUES (@playerID, @score, @timestamp)`,
        Params: map[string]interface{}{
                "playerID":  playerID,
                "score":     score,
                "timestamp": randomDate,
        },
})

כדי לאכלס אוטומטית את העמודה Timestamp עם חותמת הזמן של הרגע המדויק שבו מתבצעת העסקה 'הוספה', אפשר במקום זאת להוסיף את הקבוע Go‏ spanner.CommitTimestamp כמו בקטע הקוד הבא:

...
stmts = append(stmts, spanner.Statement{
        SQL: `INSERT INTO Scores
              (PlayerId, Score, Timestamp)
                 VALUES (@playerID, @score, @timestamp)`,
        Params: map[string]interface{}{
                "playerID":  playerID,
                "score":     score,
                "timestamp": spanner.CommitTimestamp,
        },
})

עכשיו, אחרי שסיימנו לטעון את הנתונים, נבדוק את הערכים שכתבנו זה עתה לטבלאות החדשות בקטע Cloud Spanner במסוף Cloud. קודם בוחרים את מסד הנתונים leaderboard ואז בוחרים את הטבלה Players. לוחצים על הכרטיסייה Data. אפשר לראות שיש נתונים בעמודות PlayerId ו-PlayerName בטבלה.

עכשיו נבדוק אם יש נתונים גם בטבלה Scores. לשם כך, לוחצים על הטבלה Scores ובוחרים בכרטיסייה Data. אפשר לראות שיש נתונים בעמודות PlayerId, Timestamp ו-Score בטבלה.

כל הכבוד! נניח שאנחנו רוצים לעדכן את האפליקציה שלנו כדי להריץ כמה שאילתות שבעזרתן נוכל ליצור טבלת הישגים במשחק.

6. הרצת שאילתות של טבלת ההייפ

אחרי שהגדרנו את מסד הנתונים וטעןנו מידע לטבלאות, נשתמש בנתונים האלה כדי ליצור טבלת הישגים. כדי לעשות זאת, צריך לענות על ארבע השאלות הבאות:

מי השחקנים שנכללים ב-"עשרת הגדולים" בכל הזמנים?
אילו שחקנים נכללים ב'עשרת המובילים' של השנה?
מי השחקנים שנכללים ב'עשרת המובילים' של החודש?
מי השחקנים שנכללים ב-Top Ten של השבוע?

נעדכן את האפליקציה כדי להריץ את שאילתות ה-SQL שיענו על השאלות האלה.

נוסיף פקודה query ופקודה queryWithTimespan שיאפשרו להריץ את השאילתות כדי לענות על השאלות שיובילו למידע שנדרש לטבלת המובילים שלנו.

עורכים את הקובץ leaderboard.go ב-Cloud Shell Editor כדי לעדכן את האפליקציה ולהוסיף את הפקודה query ואת הפקודה queryWithTimespan. נוסיף גם פונקציית עזר formatWithCommas לעיצוב הניקוד שלנו עם פסיקים.

import (
        "bytes"
        "context"
        "flag"
        "fmt"
        "io"
        "log"
        "math/rand"
        "os"
        "regexp"
        "strconv"
        "time"

        "cloud.google.com/go/spanner"
        database "cloud.google.com/go/spanner/admin/database/apiv1"

        "google.golang.org/api/iterator"
        adminpb "google.golang.org/genproto/googleapis/spanner/admin/database/v1"
)

לאחר מכן מוסיפים את שתי הפונקציות הבאות ואת פונקציית העזר שמתחת לשיטה הקיימת insertScores:

func query(ctx context.Context, w io.Writer, client *spanner.Client) error {
        stmt := spanner.Statement{
                SQL: `SELECT p.PlayerId, p.PlayerName, s.Score, s.Timestamp
                        FROM Players p
                        JOIN Scores s ON p.PlayerId = s.PlayerId
                        ORDER BY s.Score DESC LIMIT 10`}
        iter := client.Single().Query(ctx, stmt)
        defer iter.Stop()
        for {
                row, err := iter.Next()
                if err == iterator.Done {
                        return nil
                }
                if err != nil {
                        return err
                }
                var playerID, score int64
                var playerName string
                var timestamp time.Time
                if err := row.Columns(&playerID, &playerName, &score, &timestamp); err != nil {
                        return err
                }
                fmt.Fprintf(w, "PlayerId: %d  PlayerName: %s  Score: %s  Timestamp: %s\n",
                        playerID, playerName, formatWithCommas(score), timestamp.String()[0:10])
        }
}

func queryWithTimespan(ctx context.Context, w io.Writer, client *spanner.Client, timespan int) error {
        stmt := spanner.Statement{
                SQL: `SELECT p.PlayerId, p.PlayerName, s.Score, s.Timestamp
                                FROM Players p
                                JOIN Scores s ON p.PlayerId = s.PlayerId 
                                WHERE s.Timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @Timespan HOUR)
                                ORDER BY s.Score DESC LIMIT 10`,
                Params: map[string]interface{}{"Timespan": timespan},
        }
        iter := client.Single().Query(ctx, stmt)
        defer iter.Stop()
        for {
                row, err := iter.Next()
                if err == iterator.Done {
                        return nil
                }
                if err != nil {
                        return err
                }
                var playerID, score int64
                var playerName string
                var timestamp time.Time
                if err := row.Columns(&playerID, &playerName, &score, &timestamp); err != nil {
                        return err
                }
                fmt.Fprintf(w, "PlayerId: %d  PlayerName: %s  Score: %s  Timestamp: %s\n",
                        playerID, playerName, formatWithCommas(score), timestamp.String()[0:10])
        }
}

func formatWithCommas(n int64) string {
        numberAsString := strconv.FormatInt(n, 10)
        numberLength := len(numberAsString)
        if numberLength < 4 {
                return numberAsString
        }
        var buffer bytes.Buffer
        comma := []rune(",")
        bufferPosition := numberLength % 3
        if (bufferPosition) > 0 {
                bufferPosition = 3 - bufferPosition
        }
        for i := 0; i < numberLength; i++ {
                if bufferPosition == 3 {
                        buffer.WriteRune(comma[0])
                        bufferPosition = 0
                }
                bufferPosition++
                buffer.WriteByte(numberAsString[i])
        }
        return buffer.String()
}

בקטע הבא בחלק העליון של קובץ leaderboard.go, מוסיפים את האפשרות query (שאילתה) כאחת מאפשרויות הפקודה במשתנה commands, ממש מתחת לאפשרות insertscores": insertScores, כך שהמשתנה commands ייראה כך:

var (
        commands = map[string]command{
                "insertplayers": insertPlayers,
                "insertscores":  insertScores,
                "query":         query,
        }
)

לאחר מכן מוסיפים את queryWithTimespan כאפשרות פקודה בפונקציה run, מתחת לקטע הפקודה createdatabase ומעל לקטע הפקודות insert and query:

        // querywithtimespan command
        if cmd == "querywithtimespan" {
                err := queryWithTimespan(ctx, w, dataClient, timespan)
                if err != nil {
                        fmt.Fprintf(w, "%s failed with %v", cmd, err)
                }
                return err
        }

בסיום התהליך, הפונקציה run אמורה להיראות כך:

func run(ctx context.Context, adminClient *database.DatabaseAdminClient, dataClient *spanner.Client, w io.Writer,
        cmd string, db string, timespan int) error {
        // createdatabase command
        if cmd == "createdatabase" {
                err := createDatabase(ctx, w, adminClient, db)
                if err != nil {
                        fmt.Fprintf(w, "%s failed with %v", cmd, err)
                }
                return err
        }

        // querywithtimespan command
        if cmd == "querywithtimespan" {
                if timespan == 0 {
                        flag.Usage()
                        os.Exit(2)
                }
                err := queryWithTimespan(ctx, w, dataClient, timespan)
                if err != nil {
                        fmt.Fprintf(w, "%s failed with %v", cmd, err)
                }
                return err
        }

        // insert and query commands
        cmdFn := commands[cmd]
        if cmdFn == nil {
                flag.Usage()
                os.Exit(2)
        }
        err := cmdFn(ctx, w, dataClient)
        if err != nil {
                fmt.Fprintf(w, "%s failed with %v", cmd, err)
        }
        return err
}

לאחר מכן, כדי שהפקודה queryWithTimespan תפעל, מעדכנים את בלוק הקוד flag.Parse()‎ בשיטה 'main' של האפליקציה כך שייראה כמו הדוגמה הבאה:

        flag.Parse()
        flagCount := len(flag.Args())
        if flagCount < 2 || flagCount > 3 {
                flag.Usage()
                os.Exit(2)
        }

        cmd, db := flag.Arg(0), flag.Arg(1)
        // If query timespan flag is specified, parse to int
        var timespan int = 0
        if flagCount == 3 {
                parsedTimespan, err := strconv.Atoi(flag.Arg(2))
                if err != nil {
                        fmt.Println(err)
                        os.Exit(2)
                }
                timespan = parsedTimespan
        }

        ctx, cancel := context.WithTimeout(context.Background(), 1*time.Minute)
        defer cancel()
        adminClient, dataClient := createClients(ctx, db)
        if err := run(ctx, adminClient, dataClient, os.Stdout, cmd, db, timespan); err != nil {
                os.Exit(1)
        }

השלב האחרון בהוספת הפונקציונליות של 'שאילתה' לאפליקציה הוא הוספת טקסט עזרה לפקודות 'שאילתה' ו'שאילתה עם טווח זמן' לפונקציה flag.Usage(). מוסיפים את שורות הקוד הבאות לפונקציה flag.Usage() כדי לכלול טקסט עזרה לפקודות השאילתה:

מוסיפים את שתי הפקודות query לרשימת הפקודות האפשריות:

Command can be one of: createdatabase, insertplayers, insertscores, query, querywithtimespan

מוסיפים את הטקסט הנוסף הזה מתחת לטקסט העזרה של הפקודה insertscores.

        leaderboard query projects/my-project/instances/my-instance/databases/example-db
                - Query players with top ten scores of all time.
        leaderboard querywithtimespan projects/my-project/instances/my-instance/databases/example-db 168
                - Query players with top ten scores within a timespan specified in hours.

שומרים את השינויים שביצעתם בקובץ leaderboard.go על ידי בחירה באפשרות 'שמירה' בתפריט 'קובץ' של Cloud Shell Editor.

עכשיו נבנה ונריץ את האפליקציה כדי לוודא שהפקודות החדשות query ו-querywithtimespan כלולות ברשימת הפקודות האפשריות של האפליקציה.

מריצים את הפקודה הבאה ב-Cloud Shell כדי ליצור את האפליקציה:

go build leaderboard.go

מריצים את האפליקציה שנוצרה ב-Cloud Shell על ידי הזנת הפקודה הבאה:

./leaderboard

עכשיו הפקודות query ו- querywithtimespan צריכות להופיע בפלט ברירת המחדל של האפליקציה כאפשרות חדשה:

Usage: leaderboard <command> <database_name> [command_option]

        Command can be one of: createdatabase, insertplayers, insertscores, query, querywithtimespan

Examples:
        leaderboard createdatabase projects/my-project/instances/my-instance/databases/example-db
                - Create a sample Cloud Spanner database along with sample tables in your project.
        leaderboard insertplayers projects/my-project/instances/my-instance/databases/example-db
                - Insert 100 sample Player records into the database.
        leaderboard insertscores projects/my-project/instances/my-instance/databases/example-db
                - Insert sample score data into Scores sample Cloud Spanner database table.
        leaderboard query projects/my-project/instances/my-instance/databases/example-db
                - Query players with top ten scores of all time.
        leaderboard querywithtimespan projects/my-project/instances/my-instance/databases/example-db 168
                - Query players with top ten scores within a timespan specified in hours.

אפשר לראות מהתשובה שאפשר להשתמש בפקודה query כדי לקבל רשימה של עשרת השחקנים המובילים בכל הזמנים. אפשר גם לראות שהפקודה querywithtimespan מאפשרת לנו לציין טווח זמן במספר שעות לשימוש לסינון רשומות על סמך הערך שלהן בעמודה Timestamp בטבלה Scores.

נריץ את הפקודה query באמצעות אותם ערכי ארגומנטים שבהם השתמשנו כשהרצנו את הפקודה create. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard query  projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard

אתם אמורים לראות תגובה שכוללת את עשרת השחקנים הטובים ביותר בכל הזמנים, כמו בדוגמה הבאה:

PlayerId: 4018687297  PlayerName: Player 83  Score: 999,618  Timestamp: 2017-07-01
PlayerId: 4018687297  PlayerName: Player 83  Score: 998,956  Timestamp: 2017-09-02
PlayerId: 4285713246  PlayerName: Player 51  Score: 998,648  Timestamp: 2017-12-01
PlayerId: 5267931774  PlayerName: Player 49  Score: 997,733  Timestamp: 2017-11-09
PlayerId: 1981654448  PlayerName: Player 35  Score: 997,480  Timestamp: 2018-12-06
PlayerId: 4953940705  PlayerName: Player 87  Score: 995,184  Timestamp: 2018-09-14
PlayerId: 2456736905  PlayerName: Player 84  Score: 992,881  Timestamp: 2017-04-14
PlayerId: 8234617611  PlayerName: Player 19  Score: 992,399  Timestamp: 2017-12-27
PlayerId: 1788051688  PlayerName: Player 76  Score: 992,265  Timestamp: 2018-11-22
PlayerId: 7127686505  PlayerName: Player 97  Score: 992,038  Timestamp: 2017-12-02

עכשיו נריץ את הפקודה querywithtimespan עם הארגומנטים הנדרשים כדי לשאול על 10 השחקנים המובילים של השנה. לשם כך נציין את הארגומנט timespan (טווח זמן) ששווה למספר השעות בשנה, כלומר 8760. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard querywithtimespan projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard 8760

אתם אמורים לראות תגובה שכוללת את עשרת השחקנים המובילים של השנה, כמו בדוגמה הבאה:

PlayerId: 1981654448  PlayerName: Player 35  Score: 997,480  Timestamp: 2018-12-06
PlayerId: 4953940705  PlayerName: Player 87  Score: 995,184  Timestamp: 2018-09-14
PlayerId: 1788051688  PlayerName: Player 76  Score: 992,265  Timestamp: 2018-11-22
PlayerId: 6862349579  PlayerName: Player 30  Score: 990,877  Timestamp: 2018-09-14
PlayerId: 5529627211  PlayerName: Player 16  Score: 989,142  Timestamp: 2018-03-30
PlayerId: 9743904155  PlayerName: Player 1  Score: 988,765  Timestamp: 2018-05-30
PlayerId: 6809119884  PlayerName: Player 7  Score: 986,673  Timestamp: 2018-05-16
PlayerId: 2132710638  PlayerName: Player 54  Score: 983,108  Timestamp: 2018-09-11
PlayerId: 2320093590  PlayerName: Player 79  Score: 981,373  Timestamp: 2018-05-07
PlayerId: 9554181430  PlayerName: Player 80  Score: 981,087  Timestamp: 2018-06-21

עכשיו נריץ את הפקודה querywithtimespan כדי לשלוח שאילתה לגבי 10 השחקנים המובילים של החודש. לשם כך, נציין את פרק הזמן (timespan) ששווה למספר השעות בחודש, כלומר 730. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard querywithtimespan projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard 730

אתם אמורים לראות תגובה שכוללת את עשרת השחקנים המובילים של החודש, כמו בדוגמה הבאה:

PlayerId: 3869829195  PlayerName: Player 69  Score: 949,686  Timestamp: 2019-02-19
PlayerId: 7448359883  PlayerName: Player 20  Score: 938,998  Timestamp: 2019-02-07
PlayerId: 1981654448  PlayerName: Player 35  Score: 929,003  Timestamp: 2019-02-22
PlayerId: 9336678658  PlayerName: Player 44  Score: 914,106  Timestamp: 2019-01-27
PlayerId: 6968576389  PlayerName: Player 40  Score: 898,041  Timestamp: 2019-02-21
PlayerId: 5529627211  PlayerName: Player 16  Score: 896,433  Timestamp: 2019-01-29
PlayerId: 9395039625  PlayerName: Player 59  Score: 879,495  Timestamp: 2019-02-09
PlayerId: 2094604854  PlayerName: Player 39  Score: 860,434  Timestamp: 2019-02-01
PlayerId: 9395039625  PlayerName: Player 59  Score: 849,955  Timestamp: 2019-02-21
PlayerId: 4285713246  PlayerName: Player 51  Score: 805,654  Timestamp: 2019-02-02

עכשיו נריץ את הפקודה querywithtimespan כדי לשלוף את 10 השחקנים המובילים של השבוע. לשם כך, נציין את פרק הזמן (timespan) ששווה למספר השעות בשבוע, כלומר 168. חשוב להחליף את my-project במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.

./leaderboard querywithtimespan  projects/my-project/instances/cloudspanner-leaderboard/databases/leaderboard 168

אתם אמורים לראות תגובה שכוללת את עשרת השחקנים המובילים של השבוע, כמו בדוגמה הבאה:

PlayerId: 3869829195  PlayerName: Player 69  Score: 949,686  Timestamp: 2019-02-19
PlayerId: 1981654448  PlayerName: Player 35  Score: 929,003  Timestamp: 2019-02-22
PlayerId: 6968576389  PlayerName: Player 40  Score: 898,041  Timestamp: 2019-02-21
PlayerId: 9395039625  PlayerName: Player 59  Score: 849,955  Timestamp: 2019-02-21
PlayerId: 5954045812  PlayerName: Player 8  Score: 795,639  Timestamp: 2019-02-22
PlayerId: 3889939638  PlayerName: Player 71  Score: 775,252  Timestamp: 2019-02-21
PlayerId: 5529627211  PlayerName: Player 16  Score: 604,695  Timestamp: 2019-02-19
PlayerId: 9006728426  PlayerName: Player 3  Score: 457,208  Timestamp: 2019-02-22
PlayerId: 8289497066  PlayerName: Player 58  Score: 227,697  Timestamp: 2019-02-20
PlayerId: 8065482904  PlayerName: Player 99  Score: 198,429  Timestamp: 2019-02-24

עבודה מצוינת!

מעכשיו, כשתוסיפו רשומות, Cloud Spanner ישנה את גודל מסד הנתונים לפי הצורך. לא משנה כמה מסד הנתונים שלכם יגדל, תוכלו להמשיך להרחיב את הלידרבורד של המשחק שלכם בצורה מדויקת באמצעות Cloud Spanner והטכנולוגיה Truetime שלו.

7. הסרת המשאבים

אחרי שסיימנו לשחק עם Spanner, צריך לנקות את סביבת הפיתוח כדי לחסוך במשאבים יקרים ובכסף. למזלנו, זה שלב פשוט. פשוט נכנסים אל הקטע Cloud Spanner ב-Cloud Console ומוחקים את המופע שיצרנו בשלב של ה-codelab שנקרא 'הגדרת מופע Cloud Spanner'.

8. מעולה!

הנושאים שנדון בהם:

מופעים, מסדי נתונים וסכמת טבלאות של Google Cloud Spanner לטבלת ניקוד
איך יוצרים אפליקציית מסוף ב-Go
איך יוצרים מסד נתונים וטבלאות ב-Spanner באמצעות ספריית הלקוח של Go
איך טוענים נתונים למסד נתונים של Spanner באמצעות ספריית הלקוח של Go
איך שולחים שאילתות לגבי התוצאות של 'העשרה הראשונות' מהנתונים באמצעות חותמות זמן של שמירה ב-Spanner וספריית הלקוח של Go

השלבים הבאים:

לקריאת הסקירה הטכנית בנושא Spanner CAP
מידע נוסף על תכנון סכימה ועל שיטות מומלצות לשאילתות
מידע נוסף על חותמות זמן של ביצוע פעולות ב-Cloud Spanner

שליחת משוב

נשמח אם תקדישו כמה רגעים למילוי הסקר הקצר שלנו.

Cloud Spanner: יוצרים לידרבורד של גיימינג באמצעות Go

1. סקירה כללית

מה תלמדו

W****hat you'll need

איך תשתמשו במדריך הזה?

איזה דירוג מגיע לדעתך לחוויית השימוש שלך ב-Google Cloud Platform?

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

הגדרה של Google Cloud Shell

פלט הפקודה

פלט הפקודה

פלט הפקודה

סיכום

הבא בתור

3. הגדרת מופע של Cloud Spanner

4. יצירה של מסד נתונים וסכימה

5. טען נתונים

6. הרצת שאילתות של טבלת ההייפ

7. הסרת המשאבים

8. מעולה!

הנושאים שנדון בהם:

השלבים הבאים:

שליחת משוב

What you'll need