דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

מה תלמדו

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

מה צריך להכין

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

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

לקריאה בלבד

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

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

מתחילים

בינונית

בקיאים

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

הגדרת סביבה בקצב עצמאי

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

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

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

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

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

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

בשלב הבא, אם עדיין לא עשית זאת, יהיה עליך להפעיל את החיוב ב-Developers Console כדי להשתמש במשאבים של Google Cloud ולהפעיל את Cloud Spanner API.

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

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

הגדרת Google Cloud Shell

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

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

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

JjEuRXGg0AYYIY6QZ8d-66gx_Mtc-_jDE9ijmbXLJSAXFvJt-qUpNtsBsYjNpv2W6BQSrDc1D-ARINNQ-1EkwUhz-iUK-FUCZhJ-NtjvIEx9pIkE-246DomWuCfiGHK78DgoeWkHRw

צילום מסך מתאריך 2017-06-14 בשעה 22:13.43.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:

158fNPfwSxsFqz9YbtJVZes8viTS3d1bV4CVhij3XPxuzVFOtTObnwsphlm6lYGmgdMFwBJtc-FaLrZU7XHAg_ZYoCrgombMRR3h-eolLPcvO351c5iBv506B3ZwghZoiRg6cz23Qw

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

לסיום, לחצו על 'יצירה' ותוך שניות יש לכם מכונה של Cloud Spanner.

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

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

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

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

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

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

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

cd java-docs-samples/spanner/leaderboard

כל הקוד הנדרש ל-Codelab הזה נמצא בספרייה הקיימת java-docs-samples/spanner/leaderboard/complete כאפליקציית C# ניתנת להרצה בשם Leaderboard, ומשמשת כחומר עזר עם ההתקדמות ב-Codelab. אנחנו ניצור ספרייה חדשה ונבנה עותק של האפליקציה מסוג Leaderboard בשלבים.

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

mkdir codelab && cd $_

יוצרים אפליקציית Java בסיסית חדשה בשם 'Leaderboard' באמצעות פקודת Maven (mvn) הבאה:

mvn -B archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DgroupId=com.google.codelabs -DartifactId=leaderboard -DarchetypeVersion=1.4

הפקודה הזו יוצרת אפליקציית מסוף פשוטה שמורכבת משני קבצים ראשיים: קובץ התצורה pom.xml של אפליקציית Maven וקובץ Java App.java.

בשלב הבא, עוברים לספריית ה-Leaderboard שנוצרה עכשיו ורושמים את התוכן שלה:

cd leaderboard && ls

הקובץ pom.xml והספרייה src אמורים להופיע:

pom.xml  src

עכשיו נעדכן את אפליקציית המסוף הזו על ידי עריכת App.java כך שישתמש בספריית הלקוח של Java Spanner כדי ליצור לידרבורד שמורכב משתי טבלאות; שחקנים ותוצאות. אפשר לעשות את זה ב-Cloud Shell Editor:

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

פותחים את הקובץ pom.xml מתחת לתיקיית Leaderboard. פותחים את קובץ pom.xml שנמצא בתיקייה java-docs-samples\ spanner\leaderboard\codelab\leaderboard.הקובץ הזה מגדיר את מערכת ה-build של Maven ליצור את האפליקציה בתוך jar, כולל כל יחסי התלות שלנו.

מוסיפים את הקטע החדש הבא של ניהול תלות ישירות אל </properties> הקיימים רכיב:

<dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>google-cloud-bom</artifactId>
        <version>0.83.0-alpha</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

צריך להוסיף גם תלות חדשה אחת בתג <dependencies> הקיים , שיוסיף לאפליקציה את ספריית הלקוח של Cloud Spanner Java.

    <dependency>
      <!-- Version auto-managed by BOM -->
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-spanner</artifactId>
    </dependency>

בשלב הבא צריך להחליף את ה-<build> הקיים של הקובץ pom.xml עם קטע הקוד הבא: <build> :

 <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.5.5</version>
        <configuration>
          <finalName>leaderboard</finalName>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
          <archive>
            <manifest>
              <mainClass>com.google.codelabs.App</mainClass>
            </manifest>
          </archive>
          <appendAssemblyId>false</appendAssemblyId>
          <attach>false</attach>
        </configuration>
        <executions>
          <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>3.0.0-M3</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.0.0-M3</version>
        <configuration>
            <useSystemClassLoader>false</useSystemClassLoader>
        </configuration>
      </plugin>  
    </plugins>
  </build>

שומרים את השינויים שביצעתם בקובץ pom.xml על ידי בחירה באפשרות 'שמירה' מתחת לקטע 'File' של Cloud Shell Editor. או על ידי לחיצה על ו-S. יחד עם מקשי המקלדת.

אחר כך פותחים את הקובץ App.java ב-Cloud Shell Editor שנמצא בתיקייה src/main/java/com/google/codelabs/. מחליפים את הקוד הקיים של הקובץ בקוד הנדרש ליצירת מסד הנתונים leaderboard ואת הטבלאות Players ו-Scores על ידי הדבקת קוד ה-Java הבא בקובץ App.java:

package com.google.codelabs;

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.spanner.Database;
import com.google.cloud.spanner.DatabaseAdminClient;
import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerException;
import com.google.cloud.spanner.SpannerExceptionFactory;
import com.google.cloud.spanner.SpannerOptions;
import com.google.spanner.admin.database.v1.CreateDatabaseMetadata;
import java.util.Arrays;
import java.util.concurrent.ExecutionException;

/**
 * Example code for using the Cloud Spanner API with the Google Cloud Java client library
 * to create a simple leaderboard.
 * 
 * This example demonstrates:
 *
 * <p>
 *
 * <ul>
 *   <li>Creating a Cloud Spanner database.
 * </ul>
 */
public class App {

  static void create(DatabaseAdminClient dbAdminClient, DatabaseId db) {
    OperationFuture<Database, CreateDatabaseMetadata> op =
        dbAdminClient.createDatabase(
            db.getInstanceId().getInstance(),
            db.getDatabase(),
            Arrays.asList(
                "CREATE TABLE Players(\n"
                    + "  PlayerId INT64 NOT NULL,\n"
                    + "  PlayerName STRING(2048) NOT NULL\n"
                    + ") PRIMARY KEY(PlayerId)",
                "CREATE TABLE Scores(\n"
                    + "  PlayerId INT64 NOT NULL,\n"
                    + "  Score INT64 NOT NULL,\n"
                    + "  Timestamp TIMESTAMP NOT NULL\n"
                    + "  OPTIONS(allow_commit_timestamp=true)\n"
                    + ") PRIMARY KEY(PlayerId, Timestamp),\n"
                    + "INTERLEAVE IN PARENT Players ON DELETE NO ACTION"));
    try {
      // Initiate the request which returns an OperationFuture.
      Database dbOperation = op.get();
      System.out.println("Created database [" + dbOperation.getId() + "]");
    } catch (ExecutionException e) {
      // If the operation failed during execution, expose the cause.
      throw (SpannerException) e.getCause();
    } catch (InterruptedException e) {
      // Throw when a thread is waiting, sleeping, or otherwise occupied,
      // and the thread is interrupted, either before or during the activity.
      throw SpannerExceptionFactory.propagateInterrupt(e);
    }
  }

  static void printUsageAndExit() {
    System.out.println("Leaderboard 1.0.0");
    System.out.println("Usage:");
    System.out.println("  java -jar leaderboard.jar "
        + "<command> <instance_id> <database_id> [command_option]");
    System.out.println("");
    System.out.println("Examples:");
    System.out.println("  java -jar leaderboard.jar create my-instance example-db");
    System.out.println("      - Create a sample Cloud Spanner database along with "
        + "sample tables in your project.\n");
    System.exit(1);
  }

  public static void main(String[] args) throws Exception {
    if (!(args.length == 3 || args.length == 4)) {
      printUsageAndExit();
    }
    SpannerOptions options = SpannerOptions.newBuilder().build();
    Spanner spanner = options.getService();
    try {
      String command = args[0];
      DatabaseId db = DatabaseId.of(options.getProjectId(), args[1], args[2]);
      DatabaseClient dbClient = spanner.getDatabaseClient(db);
      DatabaseAdminClient dbAdminClient = spanner.getDatabaseAdminClient();
      switch (command) {
        case "create":
          create(dbAdminClient, db);
          break;
        default:
          printUsageAndExit();
      }
    } finally {
      spanner.close();
    }
    System.out.println("Closed client");
  }
}

כדי לשמור את השינויים שביצעת בקובץ App.java, יש ללחוץ על 'שמירה'. מתחת לקטע 'File' של Cloud Shell Editor. תפריט

אפשר להשתמש בקובץ App.java בספרייה java-docs-samples/spanner/leaderboard/step4/src כדי לראות דוגמה לאופן שבו קובץ App.java אמור להיראות אחרי הוספת הקוד כדי להפעיל את הפקודה create.

כדי לבנות את האפליקציה שלך, צריך להריץ חבילת mvn מהספרייה שבה נמצא ה-pom.xml:

mvn package

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

java -jar target/leaderboard.jar

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

Leaderboard 1.0.0
Usage:
  java -jar leaderboard.jar <command> <instance_id> <database_id> [command_option]

Examples:
  java -jar leaderboard.jar create my-instance example-db
      - Create a sample Cloud Spanner database along with sample tables in your project.

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

עכשיו מריצים את הפקודה הבאה.

java -jar target/leaderboard.jar create cloudspanner-leaderboard leaderboard

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

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

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

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

5. טען נתונים

יש לנו עכשיו מסד נתונים בשם leaderboard שמכיל שתי טבלאות; Players וגם Scores עכשיו נשתמש בספריית הלקוח של Java כדי לאכלס את הטבלה Players בשחקנים ואת הטבלה Scores בניקוד אקראי לכל שחקן.

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

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

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

package com.google.codelabs;

import static com.google.cloud.spanner.TransactionRunner.TransactionCallable;

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.spanner.Database;
import com.google.cloud.spanner.DatabaseAdminClient;
import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.Mutation;
import com.google.cloud.spanner.ResultSet;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerException;
import com.google.cloud.spanner.SpannerExceptionFactory;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.Statement;
import com.google.cloud.spanner.TransactionContext;
import com.google.spanner.admin.database.v1.CreateDatabaseMetadata;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Random;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ThreadLocalRandom;

בשלב הבא, מוסיפים את השיטות הבאות מסוג InsertPlayers ו-insertScores מתחת ל-method הקיים של create() ומעל ל-method הקיים של printUsageAndExit():

  static void insert(DatabaseClient dbClient, String insertType) {
    try {
      insertType = insertType.toLowerCase();
    } catch (Exception e) {
      // Invalid input received, set insertType to empty string.
      insertType = "";
    }
    if (insertType.equals("players")) {
      // Insert players.
      insertPlayers(dbClient);
    } else if (insertType.equals("scores")) {
      // Insert scores.
      insertScores(dbClient);
    } else {
      // Invalid input.
      System.out.println("Invalid value for 'type of insert'. "
          + "Specify a valid value: 'players' or 'scores'.");
      System.exit(1);
    }
  }

  static void insertPlayers(DatabaseClient dbClient) {
    dbClient
        .readWriteTransaction()
        .run(
            new TransactionCallable<Void>() {
              @Override
              public Void run(TransactionContext transaction) throws Exception {
                // Get the number of players.
                String sql = "SELECT Count(PlayerId) as PlayerCount FROM Players";
                ResultSet resultSet = transaction.executeQuery(Statement.of(sql));
                long numberOfPlayers = 0;
                if (resultSet.next()) {
                  numberOfPlayers = resultSet.getLong("PlayerCount");
                }
                // Insert 100 player records into the Players table.
                List<Statement> stmts = new ArrayList<Statement>();
                long randomId;
                for (int x = 1; x <= 100; x++) {
                  numberOfPlayers++;
                  randomId = (long) Math.floor(Math.random() * 9_000_000_000L) + 1_000_000_000L;
                  Statement statement =
                      Statement
                        .newBuilder(
                            "INSERT INTO Players (PlayerId, PlayerName) "
                            + "VALUES (@PlayerId, @PlayerName) ")
                        .bind("PlayerId")
                        .to(randomId)
                        .bind("PlayerName")
                        .to("Player " + numberOfPlayers)
                        .build();
                  stmts.add(statement);
                }
                transaction.batchUpdate(stmts);
                return null;
              }
            });
    System.out.println("Done inserting player records...");
  }

  static void insertScores(DatabaseClient dbClient) {
    boolean playerRecordsFound = false;
    ResultSet resultSet =
        dbClient
            .singleUse()
            .executeQuery(Statement.of("SELECT * FROM Players"));
    while (resultSet.next()) {
      playerRecordsFound = true;
      final long playerId = resultSet.getLong("PlayerId");
      dbClient
          .readWriteTransaction()
          .run(
              new TransactionCallable<Void>() {
                @Override
                public Void run(TransactionContext transaction) throws Exception {
                  // Initialize objects for random Score and random Timestamp.
                  LocalDate endDate = LocalDate.now();
                  long end = endDate.toEpochDay();
                  int startYear = endDate.getYear() - 2;
                  int startMonth = endDate.getMonthValue();
                  int startDay = endDate.getDayOfMonth();
                  LocalDate startDate = LocalDate.of(startYear, startMonth, startDay);
                  long start = startDate.toEpochDay();
                  Random r = new Random();
                  List<Statement> stmts = new ArrayList<Statement>();
                  // Insert 4 score records into the Scores table 
                  // for each player in the Players table.
                  for (int x = 1; x <= 4; x++) {
                    // Generate random score between 1,000,000 and 1,000
                    long randomScore = r.nextInt(1000000 - 1000) + 1000;
                    // Get random day within the past two years.
                    long randomDay = ThreadLocalRandom.current().nextLong(start, end);
                    LocalDate randomDayDate = LocalDate.ofEpochDay(randomDay);
                    LocalTime randomTime = LocalTime.of(
                        r.nextInt(23), r.nextInt(59), r.nextInt(59), r.nextInt(9999));
                    LocalDateTime randomDate = LocalDateTime.of(randomDayDate, randomTime);
                    Instant randomInstant = randomDate.toInstant(ZoneOffset.UTC);
                    Statement statement =
                        Statement
                        .newBuilder(
                          "INSERT INTO Scores (PlayerId, Score, Timestamp) "
                          + "VALUES (@PlayerId, @Score, @Timestamp) ")
                        .bind("PlayerId")
                        .to(playerId)
                        .bind("Score")
                        .to(randomScore)
                        .bind("Timestamp")
                        .to(randomInstant.toString())
                        .build();
                    stmts.add(statement);
                  }
                  transaction.batchUpdate(stmts);
                  return null;
                }
              });

    }
    if (!playerRecordsFound) {
      System.out.println("Parameter 'scores' is invalid since "
          + "no player records currently exist. First insert players "
          + "then insert scores.");
      System.exit(1);
    } else {
      System.out.println("Done inserting score records...");
    }
  }

לאחר מכן, כדי שהפקודה insert תפעל, יש להוסיף את הקוד הבא אל ה'ראשי' של האפליקציה בהצהרה switch (command) :

        case "insert":
          String insertType;
          try {
            insertType = args[3];
          } catch (ArrayIndexOutOfBoundsException exception) {
            insertType = "";
          }
          insert(dbClient, insertType);
          break;

בסיום ההצהרה switch (command) אמורה להיראות כך:

      switch (command) {
        case "create":
          create(dbAdminClient, db);
          break;
        case "insert":
          String insertType;
          try {
            insertType = args[3];
          } catch (ArrayIndexOutOfBoundsException exception) {
            insertType = "";
          }
          insert(dbClient, insertType);
          break;
        default:
          printUsageAndExit();
      }

השלב האחרון להשלמת הוספת "insert" הפונקציונליות של האפליקציה היא להוסיף טקסט עזרה עבור ל-method printUsageAndExit(). כדי לכלול טקסט עזרה לפקודת Insert, מוסיפים את שורות הקוד הבאות ל-method: printUsageAndExit():

    System.out.println("  java -jar leaderboard.jar insert my-instance example-db players");
    System.out.println("      - Insert 100 sample Player records into the database.\n");
    System.out.println("  java -jar leaderboard.jar insert my-instance example-db scores");
    System.out.println("      - Insert sample score data into Scores sample Cloud Spanner "
        + "database table.\n");

כדי לשמור את השינויים שביצעת בקובץ App.java, יש ללחוץ על 'שמירה'. מתחת לקטע 'File' של Cloud Shell Editor. תפריט

אפשר להשתמש בקובץ App.java בספרייה java-docs-samples/spanner/leaderboard/step5/src כדי לראות דוגמה לאופן שבו קובץ App.java אמור להיראות אחרי הוספת הקוד כדי להפעיל את הפקודה insert.

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

כדי ליצור את האפליקציה, צריך להריץ את mvn package מהספרייה שבה נמצא קובץ ה-pom.xml:

mvn package

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

java -jar target/leaderboard.jar

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

Leaderboard 1.0.0
Usage:
  java -jar leaderboard.jar <command> <instance_id> <database_id> [command_option]

Examples:
  java -jar leaderboard.jar create my-instance example-db
      - Create a sample Cloud Spanner database along with sample tables in your project.

  java -jar leaderboard.jar insert my-instance example-db players
      - Insert 100 sample Player records into the database.

  java -jar leaderboard.jar insert my-instance example-db scores
      - Insert sample score data into Scores sample Cloud Spanner database table.

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

עכשיו נריץ את הפקודה insert עם אותם ערכי ארגומנטים שבהם השתמשנו כשקראנו לפקודה create, והוספת "נגנים" בתור "סוג ההזנה" הנוסף ארגומנט.

java -jar target/leaderboard.jar insert cloudspanner-leaderboard leaderboard players

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

Done inserting player records...

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

העמודה Timestamp בטבלה Scores הוגדרה בתור 'חותמת זמן של התחייבות' באמצעות הצהרת ה-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 בשורה נתונה בטבלה.

אתם יכולים גם להוסיף ערכים של חותמת זמן משלכם ל'חותמת זמן של ההתחייבות'. כל עוד מזינים חותמת זמן עם ערך שכבר עבר. זה מה שנעשה במסגרת ה-Codelab הזה.

עכשיו נריץ את הפקודה insert עם אותם ערכי ארגומנטים שבהם השתמשנו כשקראנו לפקודה create הוספת 'ציון' בתור "סוג ההזנה" הנוסף ארגומנט.

java -jar target/leaderboard.jar insert cloudspanner-leaderboard leaderboard scores

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

Done inserting score records...

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

          LocalDate endDate = LocalDate.now();
          long end = endDate.toEpochDay();
          int startYear = endDate.getYear() - 2;
          int startMonth = endDate.getMonthValue();
          int startDay = endDate.getDayOfMonth();
          LocalDate startDate = LocalDate.of(startYear, startMonth, startDay);
          long start = startDate.toEpochDay();
...
            long randomDay = ThreadLocalRandom.current().nextLong(start, end);
            LocalDate randomDayDate = LocalDate.ofEpochDay(randomDay);
            LocalTime randomTime = LocalTime.of(
                        r.nextInt(23), r.nextInt(59), r.nextInt(59), r.nextInt(9999));
            LocalDateTime randomDate = LocalDateTime.of(randomDayDate, randomTime);
            Instant randomInstant = randomDate.toInstant(ZoneOffset.UTC);

...
               .bind("Timestamp")
               .to(randomInstant.toString())

כדי לאכלס באופן אוטומטי את העמודה Timestamp בחותמת הזמן של המועד המדויק שבו 'Insert' העסקה מתבצעת, אפשר במקום זאת להוסיף את קבוע Java Value.COMMIT_TIMESTAMP כמו בקטע הקוד הבא:

               .bind("Timestamp")
               .to(Value.COMMIT_TIMESTAMP)

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

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

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

6. הפעלת שאילתות בלוח הישגי השחקנים המובילים

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

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

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

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

כדי לעדכן את האפליקציה ולהוסיף לה פקודת query, צריך לערוך את הקובץ App.java ב-Cloud Shell Editor. הפקודה query מורכבת משתי methods של query, אחת שדורשת רק ארגומנט DatabaseClient והשנייה משתמשת בארגומנט timespan נוסף כדי לאפשר סינון של התוצאות לפי טווח הזמן שמצוין בשעות.

מוסיפים את שתי ה-methods הבאות של query מתחת ל-method הקיים של insertScores() ומעל ל-method הקיים של printUsageAndExit():

  static void query(DatabaseClient dbClient) {
    String scoreDate;
    String score;
    ResultSet resultSet =
        dbClient
            .singleUse()
            .executeQuery(
                Statement.of(
                    "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"));
    while (resultSet.next()) {
      scoreDate = String.valueOf(resultSet.getTimestamp("Timestamp"));
      score = String.format("%,d", resultSet.getLong("Score"));
      System.out.printf(
          "PlayerId: %d  PlayerName: %s  Score: %s  Timestamp: %s\n",
          resultSet.getLong("PlayerId"), resultSet.getString("PlayerName"), score,
          scoreDate.substring(0,10));
    }
  }

  static void query(DatabaseClient dbClient, int timespan) {
    String scoreDate;
    String score;
    Statement statement =
        Statement
            .newBuilder(
              "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")
            .bind("Timespan")
            .to(timespan)
            .build();
    ResultSet resultSet =
        dbClient
            .singleUse()
            .executeQuery(statement);
    while (resultSet.next()) {
      scoreDate = String.valueOf(resultSet.getTimestamp("Timestamp"));
      score = String.format("%,d", resultSet.getLong("Score"));
      System.out.printf(
          "PlayerId: %d  PlayerName: %s  Score: %s  Timestamp: %s\n",
          resultSet.getLong("PlayerId"), resultSet.getString("PlayerName"), score,
          scoreDate.substring(0,10));
    }
  }

לאחר מכן, כדי שהפקודה query תפעל, צריך להוסיף את הקוד הבא להצהרה switch(command) בקטע 'הראשי' של האפליקציה method:

        case "query":
          if (args.length == 4) {
            int timespan = 0;
            try {
              timespan = Integer.parseInt(args[3]);
            } catch (NumberFormatException e) {
              System.err.println("query command's 'timespan' parameter must be a valid integer.");
              System.exit(1);
            }
            query(dbClient, timespan);
          } else {
            query(dbClient);
          }
          break;

השלב האחרון בתהליך הוספת "query" היא להוסיף טקסט עזרה לאפליקציה ל-method printUsageAndExit(). צריך להוסיף את שורות הקוד הבאות ל-method printUsageAndExit() כדי לכלול טקסט עזרה עבור 'query' הפקודה:

    System.out.println("  java -jar leaderboard.jar query my-instance example-db");
    System.out.println("      - Query players with top ten scores of all time.\n");
    System.out.println("  java -jar leaderboard.jar query my-instance example-db 168");
    System.out.println("      - Query players with top ten scores within a timespan "
        + "specified in hours.\n");

כדי לשמור את השינויים שביצעת בקובץ App.java, יש ללחוץ על 'שמירה'. מתחת לקטע 'File' של Cloud Shell Editor. תפריט

אפשר להשתמש בקובץ App.java בספרייה dotnet-docs-samples/applications/leaderboard/step6/src כדי לראות דוגמה לאופן שבו קובץ App.java אמור להיראות אחרי הוספת הקוד כדי להפעיל את הפקודה query.

כדי ליצור את האפליקציה, צריך להריץ את mvn package מהספרייה שבה נמצא קובץ ה-pom.xml:

mvn package

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

java -jar target/leaderboard.jar

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

Leaderboard 1.0.0
Usage:
  java -jar leaderboard.jar <command> <instance_id> <database_id> [command_option]

Examples:
  java -jar leaderboard.jar create my-instance example-db
      - Create a sample Cloud Spanner database along with sample tables in your project.

  java -jar leaderboard.jar insert my-instance example-db players
      - Insert 100 sample Player records into the database.

  java -jar leaderboard.jar insert my-instance example-db scores
      - Insert sample score data into Scores sample Cloud Spanner database table.

  java -jar leaderboard.jar query my-instance example-db
      - Query players with top ten scores of all time.

  java -jar leaderboard.jar query my-instance example-db 168
      - Query players with top ten scores within a timespan specified in hours.

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

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

java -jar target/leaderboard.jar query cloudspanner-leaderboard 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

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

java -jar target/leaderboard.jar query cloudspanner-leaderboard 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

עכשיו נריץ את הפקודה query כדי להריץ שאילתה על 'עשרת המובילים' השחקנים של החודש על ידי ציון 'טווח זמן' שווה למספר השעות בחודש, שהוא 730.

java -jar target/leaderboard.jar query cloudspanner-leaderboard 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

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

java -jar target/leaderboard.jar query cloudspanner-leaderboard 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 ומוחקים את המכונה שיצרנו בשלב ה-Codelab בשם 'Setup a Cloud Spanner Instance'.

8. מעולה!

נושאים שטיפלנו בנושא:

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

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

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

נשמח לקבל ממך משוב

כדאי למלא את הסקר הקצר מאוד שלנו