1. סקירה כללית
Google Cloud Spanner הוא שירות מנוהל של מסד נתונים רלציוני, שניתן להרחבה אופקית, מבוזר גלובלית ומספק עסקאות ACID וסמנטיקה של SQL, בלי להתפשר על ביצועים וזמינות גבוהה.
בשיעור ה-Lab הזה תלמדו איך להגדיר מופע של Cloud Spanner. תעברו על השלבים ליצירת מסד נתונים וסכימה שאפשר להשתמש בהם ללידרבורד של משחקים. תתחילו ביצירת טבלת שחקנים לאחסון פרטי השחקנים וטבלת ניקוד לאחסון הניקוד של השחקנים.
בשלב הבא מאכלסים את הטבלאות בנתונים לדוגמה. בסיום שיעור ה-Lab, תריצו כמה שאילתות לדוגמה של עשרת המובילים ולבסוף תמחקו את המופע כדי לפנות משאבים.
מה תלמדו
- איך מגדירים מופע של Cloud Spanner.
- איך יוצרים מסד נתונים וטבלאות.
- איך משתמשים בעמודת חותמת זמן של השמירה.
- איך טוענים נתונים לטבלת מסד נתונים ב-Cloud Spanner עם חותמות זמן.
- איך שולחים שאילתות למסד הנתונים שלכם ב-Cloud Spanner.
- איך מוחקים את המכונה של Cloud Spanner.
מה צריך
איך תשתמשו במדריך הזה?
איזה דירוג מגיע לדעתך לחוויית השימוש שלך ב-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
(הקצאת המשאבים והחיבור לסביבה אמורים להימשך רק כמה רגעים).
אחרי שמתחברים ל-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.
בשלב הבא נשתמש בספריית הלקוח C# כדי ליצור מסד נתונים וסכימה במופע החדש שלנו.
4. יצירה של מסד נתונים וסכימה
בשלב הזה ניצור את מסד הנתונים ואת הסכימה לדוגמה.
נשתמש בספריית הלקוח של C# כדי ליצור שתי טבלאות: טבלת Players לפרטי השחקנים וטבלת Scores לאחסון ציוני השחקנים. כדי לעשות את זה, נסביר איך ליצור אפליקציית מסוף C# ב-Cloud Shell.
קודם משכפלים את הקוד לדוגמה של ה-codelab הזה מ-GitHub על ידי הקלדת הפקודה הבאה ב-Cloud Shell:
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
לאחר מכן משנים את הספרייה לספרייה 'applications' שבה תיצור את האפליקציה.
cd dotnet-docs-samples/applications/
כל הקוד שנדרש ל-codelab הזה נמצא בספרייה הקיימת dotnet-docs-samples/applications/leaderboard כאפליקציית C# שאפשר להפעיל בשם Leaderboard, כדי שתשמש כהפניה במהלך ה-codelab. ניצור ספרייה חדשה ונבנה עותק של אפליקציית טבלת המובילים בשלבים.
יוצרים ספרייה חדשה בשם codelab לאפליקציה ועוברים אליה באמצעות הפקודה הבאה:
mkdir codelab && cd $_
יוצרים אפליקציית קונסולה חדשה ב- .NET C# בשם Leaderboard באמצעות הפקודה הבאה:
dotnet new console -n Leaderboard
הפקודה הזו יוצרת אפליקציית קונסולה פשוטה שמורכבת משני קבצים עיקריים: קובץ הפרויקט Leaderboard.csproj וקובץ התוכנית Program.cs.
בוא נריץ אותו. עוברים לספרייה החדשה שנוצרה של Leaderboard, שבה נמצאת האפליקציה:
cd Leaderboard
לאחר מכן מזינים את הפקודה הבאה כדי להפעיל אותו.
dotnet run
הפלט של האפליקציה אמור להיות 'Hello World!'.
עכשיו נעדכן את אפליקציית המסוף שלנו על ידי עריכת Program.cs כדי להשתמש בספריית הלקוח של Spanner ב-C# כדי ליצור לידרבורד שמורכב משתי טבלאות: Players ו-Scores. אפשר לעשות את זה ישירות ב-Cloud Shell Editor:
פותחים את Cloud Shell Editor בלחיצה על הסמל שמודגש למטה:
לאחר מכן, פותחים את הקובץ Program.cs ב-Cloud Shell Editor ומחליפים את הקוד הקיים בקובץ בקוד שנדרש ליצירת מסד הנתונים leaderboard והטבלאות Players ו-Scores. לשם כך, מדביקים את קוד האפליקציה הבא ב-C# בקובץ Program.cs:
using System;
using System.Threading.Tasks;
using Google.Cloud.Spanner.Data;
using CommandLine;
namespace GoogleCloudSamples.Leaderboard
{
[Verb("create", HelpText = "Create a sample Cloud Spanner database "
+ "along with sample 'Players' and 'Scores' tables in your project.")]
class CreateOptions
{
[Value(0, HelpText = "The project ID of the project to use "
+ "when creating Cloud Spanner resources.", Required = true)]
public string projectId { get; set; }
[Value(1, HelpText = "The ID of the instance where the sample database "
+ "will be created.", Required = true)]
public string instanceId { get; set; }
[Value(2, HelpText = "The ID of the sample database to create.",
Required = true)]
public string databaseId { get; set; }
}
public class Program
{
enum ExitCode : int
{
Success = 0,
InvalidParameter = 1,
}
public static object Create(string projectId,
string instanceId, string databaseId)
{
var response =
CreateAsync(projectId, instanceId, databaseId);
Console.WriteLine("Waiting for operation to complete...");
response.Wait();
Console.WriteLine($"Operation status: {response.Status}");
Console.WriteLine($"Created sample database {databaseId} on "
+ $"instance {instanceId}");
return ExitCode.Success;
}
public static async Task CreateAsync(
string projectId, string instanceId, string databaseId)
{
// Initialize request connection string for database creation.
string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}";
using (var connection = new SpannerConnection(connectionString))
{
string createStatement = $"CREATE DATABASE `{databaseId}`";
string[] createTableStatements = new string[] {
// Define create table statement for Players table.
@"CREATE TABLE Players(
PlayerId INT64 NOT NULL,
PlayerName STRING(2048) NOT NULL
) PRIMARY KEY(PlayerId)",
// Define create table statement for Scores table.
@"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" };
// Make the request.
var cmd = connection.CreateDdlCommand(
createStatement, createTableStatements);
try
{
await cmd.ExecuteNonQueryAsync();
}
catch (SpannerException e) when
(e.ErrorCode == ErrorCode.AlreadyExists)
{
// OK.
}
}
}
public static int Main(string[] args)
{
var verbMap = new VerbMap<object>();
verbMap
.Add((CreateOptions opts) => Create(
opts.projectId, opts.instanceId, opts.databaseId))
.NotParsedFunc = (err) => 1;
return (int)verbMap.Run(args);
}
}
}
כדי לספק תמונה ברורה יותר של קוד התוכנית, הנה תרשים של התוכנית עם הרכיבים העיקריים שלה מסומנים:
אפשר להשתמש בקובץ Program.cs בספרייה dotnet-docs-samples/applications/leaderboard/step4 כדי לראות דוגמה לאופן שבו קובץ Program.cs צריך להיראות אחרי שמוסיפים את הקוד להפעלת הפקודה create.
לאחר מכן משתמשים בעורך של Cloud Shell כדי לפתוח ולערוך את קובץ הפרויקט של התוכנית Leaderboard.csproj, ומעדכנים אותו כך שייראה כמו הקוד הבא. חשוב לשמור את כל השינויים באמצעות התפריט 'קובץ' בעורך Cloud Shell.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Google.Cloud.Spanner.Data" Version="3.3.0" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\..\commandlineutil\Lib\CommandLineUtil.csproj" />
</ItemGroup>
</Project>
בשינוי הזה נוספה הפניה לחבילת C# Spanner Nuget Google.Cloud.Spanner.Data שנדרשת כדי ליצור אינטראקציה עם Cloud Spanner API. בנוסף, השינוי הזה מוסיף הפניה לפרויקט CommandLineUtil שהוא חלק ממאגר GitHub של dotnet-doc-samples, ומספק תוסף שימושי של verbmap ל-CommandLineParser קוד פתוח. זהו ספרייה שימושית לטיפול בקלט של שורת פקודה עבור אפליקציות למסוף.
אפשר להשתמש בקובץ Leaderboard.csproj בספרייה dotnet-docs-samples/applications/leaderboard/step4 כדי לראות דוגמה לאופן שבו קובץ Leaderboard.csproj צריך להיראות אחרי שמוסיפים את הקוד להפעלת הפקודה create.
עכשיו אפשר להריץ את הדוגמה המעודכנת. מקלידים את הפקודה הבאה כדי לראות את תגובת ברירת המחדל של האפליקציה המעודכנת:
dotnet run
הפלט אמור להיראות כך:
Leaderboard 1.0.0 Copyright (C) 2018 Leaderboard ERROR(S): No verb selected. create Create a sample Cloud Spanner database along with sample 'Players' and 'Scores' tables in your project. help Display more information on a specific command. version Display version information.
מהתגובה הזו אפשר לראות שזו אפליקציית Leaderboard שאפשר להריץ אותה באמצעות אחת משלוש פקודות אפשריות: create, help ו-version.
ננסה את הפקודה create כדי ליצור מסד נתונים וטבלאות ב-Spanner. מריצים את הפקודה בלי ארגומנטים כדי לראות את הארגומנטים הצפויים של הפקודה.
dotnet run create
אמורה להופיע תגובה כמו זו:
Leaderboard 1.0.0 Copyright (C) 2018 Leaderboard ERROR(S): A required value not bound to option name is missing. --help Display this help screen. --version Display version information. value pos. 0 Required. The project ID of the project to use when creating Cloud Spanner resources. value pos. 1 Required. The ID of the instance where the sample database will be created. value pos. 2 Required. The ID of the sample database to create.
כאן אפשר לראות שהארגומנטים הצפויים של הפקודה create הם מזהה פרויקט, מזהה מופע ומזהה מסד נתונים.
מריצים את הפקודה הבאה. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run create PROJECT_ID cloudspanner-leaderboard leaderboard
אחרי כמה שניות אמורה להופיע תגובה כמו זו:
Waiting for operation to complete... Operation status: RanToCompletion Created sample database leaderboard on instance cloudspanner-leaderboard
בקטע Cloud Spanner במסוף Cloud, אמורים להופיע בתפריט הימני מסד הנתונים והטבלאות החדשים שיצרתם.
בשלב הבא נעדכן את האפליקציה שלנו כדי לטעון נתונים למסד הנתונים החדש.
5. טען נתונים
עכשיו יש לנו מסד נתונים בשם leaderboard שמכיל שתי טבלאות: Players ו-Scores. עכשיו נשתמש בספריית הלקוח של C# כדי לאכלס את הטבלה Players בשחקנים ואת הטבלה Scores בציונים אקראיים לכל שחקן.
פותחים את Cloud Shell Editor בלחיצה על הסמל שמודגש למטה:
בשלב הבא, עורכים את הקובץ Program.cs ב-Cloud Shell Editor כדי להוסיף פקודה insert שאפשר להשתמש בה כדי להוסיף 100 שחקנים לטבלה Players, או כדי להוסיף 4 תוצאות אקראיות לטבלה Scores לכל שחקן בטבלה Players.
קודם מוסיפים בלוק פקודות חדש insert ב-Verbmap בחלק העליון של התוכנית, מתחת לבלוק הפקודות הקיים create:
[Verb("insert", HelpText = "Insert sample 'players' records or 'scores' records "
+ "into the database.")]
class InsertOptions
{
[Value(0, HelpText = "The project ID of the project to use "
+ "when managing Cloud Spanner resources.", Required = true)]
public string projectId { get; set; }
[Value(1, HelpText = "The ID of the instance where the sample database resides.",
Required = true)]
public string instanceId { get; set; }
[Value(2, HelpText = "The ID of the database where the sample database resides.",
Required = true)]
public string databaseId { get; set; }
[Value(3, HelpText = "The type of insert to perform, 'players' or 'scores'.",
Required = true)]
public string insertType { get; set; }
}
לאחר מכן מוסיפים את השיטות הבאות Insert, InsertPlayersAsync ו-InsertScoresAsync מתחת לשיטה הקיימת CreateAsync:
public static object Insert(string projectId,
string instanceId, string databaseId, string insertType)
{
if (insertType.ToLower() == "players")
{
var responseTask =
InsertPlayersAsync(projectId, instanceId, databaseId);
Console.WriteLine("Waiting for insert players operation to complete...");
responseTask.Wait();
Console.WriteLine($"Operation status: {responseTask.Status}");
}
else if (insertType.ToLower() == "scores")
{
var responseTask =
InsertScoresAsync(projectId, instanceId, databaseId);
Console.WriteLine("Waiting for insert scores operation to complete...");
responseTask.Wait();
Console.WriteLine($"Operation status: {responseTask.Status}");
}
else
{
Console.WriteLine("Invalid value for 'type of insert'. "
+ "Specify 'players' or 'scores'.");
return ExitCode.InvalidParameter;
}
Console.WriteLine($"Inserted {insertType} into sample database "
+ $"{databaseId} on instance {instanceId}");
return ExitCode.Success;
}
public static async Task InsertPlayersAsync(string projectId,
string instanceId, string databaseId)
{
string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
long numberOfPlayers = 0;
using (var connection = new SpannerConnection(connectionString))
{
await connection.OpenAsync();
await connection.RunWithRetriableTransactionAsync(async (transaction) =>
{
// Execute a SQL statement to get current number of records
// in the Players table to use as an incrementing value
// for each PlayerName to be inserted.
var cmd = connection.CreateSelectCommand(
@"SELECT Count(PlayerId) as PlayerCount FROM Players");
numberOfPlayers = await cmd.ExecuteScalarAsync<long>();
// Insert 100 player records into the Players table.
SpannerBatchCommand cmdBatch = connection.CreateBatchDmlCommand();
for (int i = 0; i < 100; i++)
{
numberOfPlayers++;
SpannerCommand cmdInsert = connection.CreateDmlCommand(
"INSERT INTO Players "
+ "(PlayerId, PlayerName) "
+ "VALUES (@PlayerId, @PlayerName)",
new SpannerParameterCollection {
{"PlayerId", SpannerDbType.Int64},
{"PlayerName", SpannerDbType.String}});
cmdInsert.Parameters["PlayerId"].Value =
Math.Abs(Guid.NewGuid().GetHashCode());
cmdInsert.Parameters["PlayerName"].Value =
$"Player {numberOfPlayers}";
cmdBatch.Add(cmdInsert);
}
await cmdBatch.ExecuteNonQueryAsync();
});
}
Console.WriteLine("Done inserting player records...");
}
public static async Task InsertScoresAsync(
string projectId, string instanceId, string databaseId)
{
string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Insert 4 score records into the Scores table for each player
// in the Players table.
using (var connection = new SpannerConnection(connectionString))
{
await connection.OpenAsync();
await connection.RunWithRetriableTransactionAsync(async (transaction) =>
{
Random r = new Random();
bool playerRecordsFound = false;
SpannerBatchCommand cmdBatch =
connection.CreateBatchDmlCommand();
var cmdLookup =
connection.CreateSelectCommand("SELECT * FROM Players");
using (var reader = await cmdLookup.ExecuteReaderAsync())
{
while (await reader.ReadAsync())
{
playerRecordsFound = true;
for (int i = 0; i < 4; i++)
{
DateTime randomTimestamp = DateTime.Now
.AddYears(r.Next(-2, 1))
.AddMonths(r.Next(-12, 1))
.AddDays(r.Next(-28, 0))
.AddHours(r.Next(-24, 0))
.AddSeconds(r.Next(-60, 0))
.AddMilliseconds(r.Next(-100000, 0));
SpannerCommand cmdInsert =
connection.CreateDmlCommand(
"INSERT INTO Scores "
+ "(PlayerId, Score, Timestamp) "
+ "VALUES (@PlayerId, @Score, @Timestamp)",
new SpannerParameterCollection {
{"PlayerId", SpannerDbType.Int64},
{"Score", SpannerDbType.Int64},
{"Timestamp",
SpannerDbType.Timestamp}});
cmdInsert.Parameters["PlayerId"].Value =
reader.GetFieldValue<int>("PlayerId");
cmdInsert.Parameters["Score"].Value =
r.Next(1000, 1000001);
cmdInsert.Parameters["Timestamp"].Value =
randomTimestamp.ToString("o");
cmdBatch.Add(cmdInsert);
}
}
if (!playerRecordsFound)
{
Console.WriteLine("Parameter 'scores' is invalid "
+ "since no player records currently exist. First "
+ "insert players then insert scores.");
Environment.Exit((int)ExitCode.InvalidParameter);
}
else
{
await cmdBatch.ExecuteNonQueryAsync();
Console.WriteLine(
"Done inserting score records..."
);
}
}
});
}
}
לאחר מכן, כדי שהפקודה insert תפעל, מוסיפים את הקוד הבא לשיטה Main של התוכנית:
.Add((InsertOptions opts) => Insert(
opts.projectId, opts.instanceId, opts.databaseId, opts.insertType))
אפשר להשתמש בקובץ Program.cs בספרייה dotnet-docs-samples/applications/leaderboard/step5 כדי לראות דוגמה לאופן שבו קובץ Program.cs צריך להיראות אחרי שמוסיפים את הקוד להפעלת הפקודה insert.
עכשיו נריץ את התוכנית כדי לוודא שהפקודה החדשה insert נכללת ברשימת הפקודות האפשריות של התוכנית. מריצים את הפקודה הבאה:
dotnet run
עכשיו הפקודה insert אמורה להיכלל בפלט ברירת המחדל של התוכנית:
Leaderboard 1.0.0 Copyright (C) 2018 Leaderboard ERROR(S): No verb selected. create Create a sample Cloud Spanner database along with sample 'Players' and 'Scores' tables in your project. insert Insert sample 'players' records or 'scores' records into the database. help Display more information on a specific command. version Display version information.
עכשיו נריץ את הפקודה insert כדי לראות את ארגומנטי הקלט שלה. מזינים את הפקודה הבאה.
dotnet run insert
אמורה להתקבל התגובה הבאה:
Leaderboard 1.0.0 Copyright (C) 2018 Leaderboard ERROR(S): A required value not bound to option name is missing. --help Display this help screen. --version Display version information. value pos. 0 Required. The project ID of the project to use when managing Cloud Spanner resources. value pos. 1 Required. The ID of the instance where the sample database resides. value pos. 2 Required. The ID of the database where the sample database resides. value pos. 3 Required. The type of insert to perform, 'players' or 'scores'.
מהתשובה אפשר לראות שבנוסף למזהה הפרויקט, למזהה המופע ולמזהה מסד הנתונים, יש עוד ארגומנט value pos. 3 שצפוי, שהוא 'סוג ההוספה' לביצוע. הארגומנט הזה יכול לקבל את הערך players או scores.
עכשיו נריץ את הפקודה insert עם אותם ערכי ארגומנטים שבהם השתמשנו כשקראנו לפקודה create, ונוסיף את הארגומנט 'players' כארגומנט נוסף של 'סוג ההוספה'. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run insert PROJECT_ID cloudspanner-leaderboard leaderboard players
אחרי כמה שניות אמורה להתקבל תגובה כמו זו:
Waiting for insert players operation to complete... Done inserting player records... Operation status: RanToCompletion Inserted players into sample database leaderboard on instance cloudspanner-leaderboard
עכשיו נשתמש בספריית הלקוח של C# כדי לאכלס את הטבלה 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 הזה.
עכשיו נריץ את הפקודה insert עם אותם ערכי ארגומנטים שבהם השתמשנו כשקראנו לפקודה create, ונוסיף את הארגומנט scores כארגומנט נוסף מסוג insert. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run insert PROJECT_ID cloudspanner-leaderboard leaderboard scores
אחרי כמה שניות אמורה להתקבל תגובה כמו זו:
Waiting for insert players operation to complete... Done inserting player records... Operation status: RanToCompletion Inserted players into sample database leaderboard on instance cloudspanner-leaderboard
הפעלת insert עם 'סוג ההוספה' שצוין כ-scores קוראת לשיטה InsertScoresAsync שמשתמשת בקטעי הקוד הבאים כדי להוסיף חותמת זמן שנוצרה באופן אקראי עם תאריך ושעה שקרו בעבר:
DateTime randomTimestamp = DateTime.Now
.AddYears(r.Next(-2, 1))
.AddMonths(r.Next(-12, 1))
.AddDays(r.Next(-28, 0))
.AddHours(r.Next(-24, 0))
.AddSeconds(r.Next(-60, 0))
.AddMilliseconds(r.Next(-100000, 0));
...
cmdInsert.Parameters["Timestamp"].Value = randomTimestamp.ToString("o");
כדי לאכלס אוטומטית את העמודה Timestamp עם חותמת הזמן של הרגע המדויק שבו מתבצעת העסקה 'הוספה', אפשר במקום זאת להוסיף את הקבוע C# SpannerParameter.CommitTimestamp כמו בקטע הקוד הבא:
cmd.Parameters["Timestamp"].Value = SpannerParameter.CommitTimestamp;
עכשיו, אחרי שסיימנו לטעון את הנתונים, נבדוק את הערכים שכתבנו זה עתה בטבלאות החדשות. קודם בוחרים את מסד הנתונים leaderboard ואז בוחרים את הטבלה Players. לוחצים על הכרטיסייה Data. אפשר לראות שיש נתונים בעמודות PlayerId ו-PlayerName בטבלה.
עכשיו נבדוק אם יש נתונים גם בטבלה Scores. לשם כך, לוחצים על הטבלה Scores ובוחרים בכרטיסייה Data. אפשר לראות שיש נתונים בעמודות PlayerId, Timestamp ו-Score בטבלה.
כל הכבוד! נעדכן את התוכנית כדי להריץ כמה שאילתות שנוכל להשתמש בהן כדי ליצור טבלת מובילים במשחק.
6. הרצת שאילתות של טבלת ההייפ
אחרי שהגדרנו את מסד הנתונים וטעןנו מידע לטבלאות, נשתמש בנתונים האלה כדי ליצור טבלת הישגים. כדי לעשות זאת, צריך לענות על ארבע השאלות הבאות:
- מי השחקנים שנכללים ב-"עשרת הגדולים" בכל הזמנים?
- אילו שחקנים נכללים ב'עשרת המובילים' של השנה?
- מי השחקנים שנכללים ב'עשרת המובילים' של החודש?
- מי השחקנים שנכללים ב-Top Ten של השבוע?
נעדכן את התוכנית כדי להריץ את שאילתות ה-SQL שיענו על השאלות האלה.
נוסיף פקודה query שתאפשר להריץ את השאילתות כדי לענות על השאלות שיובילו למידע שנדרש לטבלת המובילים שלנו.
כדי לעדכן את התוכנית ולהוסיף פקודה query, עורכים את הקובץ Program.cs ב-Cloud Shell Editor.
קודם מוסיפים בלוק פקודות חדש query ב-Verbmap בחלק העליון של התוכנית, מתחת לבלוק הפקודות הקיים insert:
[Verb("query", HelpText = "Query players with 'Top Ten' scores within a specific timespan "
+ "from sample Cloud Spanner database table.")]
class QueryOptions
{
[Value(0, HelpText = "The project ID of the project to use "
+ "when managing Cloud Spanner resources.", Required = true)]
public string projectId { get; set; }
[Value(1, HelpText = "The ID of the instance where the sample data resides.",
Required = true)]
public string instanceId { get; set; }
[Value(2, HelpText = "The ID of the database where the sample data resides.",
Required = true)]
public string databaseId { get; set; }
[Value(3, Default = 0, HelpText = "The timespan in hours that will be used to filter the "
+ "results based on a record's timestamp. The default will return the "
+ "'Top Ten' scores of all time.")]
public int timespan { get; set; }
}
לאחר מכן מוסיפים את השיטות הבאות Query ו-QueryAsync מתחת לשיטה הקיימת InsertScoresAsync:
public static object Query(string projectId,
string instanceId, string databaseId, int timespan)
{
var response = QueryAsync(
projectId, instanceId, databaseId, timespan);
response.Wait();
return ExitCode.Success;
}
public static async Task QueryAsync(
string projectId, string instanceId, string databaseId, int timespan)
{
string connectionString =
$"Data Source=projects/{projectId}/instances/"
+ $"{instanceId}/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
string sqlCommand;
if (timespan == 0)
{
// No timespan specified. Query Top Ten scores of all time.
sqlCommand =
@"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";
}
else
{
// Query Top Ten scores filtered by the timepan specified.
sqlCommand =
$@"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.ToString()} HOUR)
ORDER BY s.Score DESC LIMIT 10";
}
var cmd = connection.CreateSelectCommand(sqlCommand);
using (var reader = await cmd.ExecuteReaderAsync())
{
while (await reader.ReadAsync())
{
Console.WriteLine("PlayerId : "
+ reader.GetFieldValue<string>("PlayerId")
+ " PlayerName : "
+ reader.GetFieldValue<string>("PlayerName")
+ " Score : "
+ string.Format("{0:n0}",
Int64.Parse(reader.GetFieldValue<string>("Score")))
+ " Timestamp : "
+ reader.GetFieldValue<string>("Timestamp").Substring(0, 10));
}
}
}
}
לאחר מכן, כדי שהפקודה query תפעל, מוסיפים את הקוד הבא לשיטה Main של התוכנית:
.Add((QueryOptions opts) => Query(
opts.projectId, opts.instanceId, opts.databaseId, opts.timespan))
אפשר להשתמש בקובץ Program.cs בספרייה dotnet-docs-samples/applications/leaderboard/step6 כדי לראות דוגמה לאופן שבו קובץ Program.cs צריך להיראות אחרי שמוסיפים את הקוד להפעלת הפקודה query.
עכשיו נריץ את התוכנית כדי לוודא שהפקודה החדשה query נכללת ברשימת הפקודות האפשריות של התוכנית. מריצים את הפקודה הבאה:
dotnet run
עכשיו הפקודה query צריכה להופיע בפלט ברירת המחדל של התוכנית כאפשרות פקודה חדשה:
Leaderboard 1.0.0 Copyright (C) 2018 Leaderboard ERROR(S): No verb selected. create Create a sample Cloud Spanner database along with sample 'Players' and 'Scores' tables in your project. insert Insert sample 'players' records or 'scores' records into the database. query Query players with 'Top Ten' scores within a specific timespan from sample Cloud Spanner database table. help Display more information on a specific command. version Display version information.
עכשיו נריץ את הפקודה query כדי לראות את ארגומנטי הקלט שלה. מזינים את הפקודה הבאה:
dotnet run query
תתקבל התשובה הבאה:
Leaderboard 1.0.0 Copyright (C) 2018 Leaderboard ERROR(S): A required value not bound to option name is missing. --help Display this help screen. --version Display version information. value pos. 0 Required. The project ID of the project to use when managing Cloud Spanner resources. value pos. 1 Required. The ID of the instance where the sample data resides. value pos. 2 Required. The ID of the database where the sample data resides. value pos. 3 (Default: 0) The timespan in hours that will be used to filter the results based on a record's timestamp. The default will return the 'Top Ten' scores of all time.
אפשר לראות מהתגובה שבנוסף למזהה הפרויקט, למזהה המופע ולמזהה מסד הנתונים, יש עוד ארגומנט value pos. 3 שצפוי, שמאפשר לנו לציין טווח זמן במספר שעות לשימוש לסינון רשומות על סמך הערך שלהן בעמודה Timestamp בטבלה Scores. ערך ברירת המחדל של הארגומנט הזה הוא 0, כלומר לא יתבצע סינון של רשומות לפי חותמות זמן. לכן, אפשר להשתמש בפקודה query בלי לציין ערך של "טווח זמן" כדי לקבל רשימה של עשרת השחקנים המובילים בכל הזמנים.
נריץ את הפקודה query בלי לציין את הארגומנט timespan, ונשתמש באותם ערכי ארגומנט שבהם השתמשנו כשהרצנו את הפקודה create. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run query PROJECT_ID cloudspanner-leaderboard leaderboard
אתם אמורים לראות תגובה שכוללת את עשרת השחקנים הטובים ביותר בכל הזמנים, כמו בדוגמה הבאה:
PlayerId : 1843159180 PlayerName : Player 87 Score : 998,955 Timestamp : 2016-03-23
PlayerId : 61891198 PlayerName : Player 19 Score : 998,720 Timestamp : 2016-03-26
PlayerId : 340906298 PlayerName : Player 48 Score : 993,302 Timestamp : 2015-08-27
PlayerId : 541473117 PlayerName : Player 22 Score : 991,368 Timestamp : 2018-04-30
PlayerId : 857460496 PlayerName : Player 68 Score : 988,010 Timestamp : 2015-05-25
PlayerId : 1826646419 PlayerName : Player 91 Score : 984,022 Timestamp : 2016-11-26
PlayerId : 1002199735 PlayerName : Player 35 Score : 982,933 Timestamp : 2015-09-26
PlayerId : 2002563755 PlayerName : Player 23 Score : 979,041 Timestamp : 2016-10-25
PlayerId : 1377548191 PlayerName : Player 2 Score : 978,632 Timestamp : 2016-05-02
PlayerId : 1358098565 PlayerName : Player 65 Score : 973,257 Timestamp : 2016-10-30
עכשיו נריץ את הפקודה query עם הארגומנטים הנדרשים כדי לשאול על 10 השחקנים המובילים של השנה. לשם כך נציין את הארגומנט timespan (טווח זמן) ששווה למספר השעות בשנה, כלומר 8760. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run query PROJECT_ID cloudspanner-leaderboard leaderboard 8760
אתם אמורים לראות תגובה שכוללת את עשרת השחקנים המובילים של השנה, כמו בדוגמה הבאה:
PlayerId : 541473117 PlayerName : Player 22 Score : 991,368 Timestamp : 2018-04-30
PlayerId : 228469898 PlayerName : Player 82 Score : 967,177 Timestamp : 2018-01-26
PlayerId : 1131343000 PlayerName : Player 26 Score : 944,725 Timestamp : 2017-05-26
PlayerId : 396780730 PlayerName : Player 41 Score : 929,455 Timestamp : 2017-09-26
PlayerId : 61891198 PlayerName : Player 19 Score : 921,251 Timestamp : 2018-05-01
PlayerId : 634269851 PlayerName : Player 54 Score : 909,379 Timestamp : 2017-07-24
PlayerId : 821111159 PlayerName : Player 55 Score : 908,402 Timestamp : 2017-05-25
PlayerId : 228469898 PlayerName : Player 82 Score : 889,040 Timestamp : 2017-12-26
PlayerId : 1408782275 PlayerName : Player 27 Score : 874,124 Timestamp : 2017-09-24
PlayerId : 1002199735 PlayerName : Player 35 Score : 864,758 Timestamp : 2018-04-24
עכשיו נריץ את הפקודה query כדי לשלוח שאילתה לגבי 10 השחקנים המובילים של החודש. לשם כך, נציין את פרק הזמן (timespan) ששווה למספר השעות בחודש, כלומר 730. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run query PROJECT_ID cloudspanner-leaderboard leaderboard 730
אתם אמורים לראות תגובה שכוללת את עשרת השחקנים המובילים של החודש, כמו בדוגמה הבאה:
PlayerId : 541473117 PlayerName : Player 22 Score : 991,368 Timestamp : 2018-04-30
PlayerId : 61891198 PlayerName : Player 19 Score : 921,251 Timestamp : 2018-05-01
PlayerId : 1002199735 PlayerName : Player 35 Score : 864,758 Timestamp : 2018-04-24
PlayerId : 1228490432 PlayerName : Player 11 Score : 682,033 Timestamp : 2018-04-26
PlayerId : 648239230 PlayerName : Player 92 Score : 653,895 Timestamp : 2018-05-02
PlayerId : 70762849 PlayerName : Player 77 Score : 598,074 Timestamp : 2018-04-22
PlayerId : 1671215342 PlayerName : Player 62 Score : 506,770 Timestamp : 2018-04-28
PlayerId : 1208850523 PlayerName : Player 21 Score : 216,008 Timestamp : 2018-04-30
PlayerId : 1587692674 PlayerName : Player 63 Score : 188,157 Timestamp : 2018-04-25
PlayerId : 992391797 PlayerName : Player 37 Score : 167,175 Timestamp : 2018-04-30
עכשיו נריץ את הפקודה query כדי לשלוף את 10 השחקנים המובילים של השבוע. לשם כך, נציין את פרק הזמן (timespan) ששווה למספר השעות בשבוע, כלומר 168. חשוב להחליף את PROJECT_ID במזהה הפרויקט שיצרתם בתחילת ה-codelab הזה.
dotnet run query PROJECT_ID cloudspanner-leaderboard leaderboard 168
אתם אמורים לראות תגובה שכוללת את עשרת השחקנים המובילים של השבוע, כמו בדוגמה הבאה:
PlayerId : 541473117 PlayerName : Player 22 Score : 991,368 Timestamp : 2018-04-30
PlayerId : 61891198 PlayerName : Player 19 Score : 921,251 Timestamp : 2018-05-01
PlayerId : 228469898 PlayerName : Player 82 Score : 853,602 Timestamp : 2018-04-28
PlayerId : 1131343000 PlayerName : Player 26 Score : 695,318 Timestamp : 2018-04-30
PlayerId : 1228490432 PlayerName : Player 11 Score : 682,033 Timestamp : 2018-04-26
PlayerId : 1408782275 PlayerName : Player 27 Score : 671,827 Timestamp : 2018-04-27
PlayerId : 648239230 PlayerName : Player 92 Score : 653,895 Timestamp : 2018-05-02
PlayerId : 816861444 PlayerName : Player 83 Score : 622,277 Timestamp : 2018-04-27
PlayerId : 162043954 PlayerName : Player 75 Score : 572,634 Timestamp : 2018-05-02
PlayerId : 1671215342 PlayerName : Player 62 Score : 506,770 Timestamp : 2018-04-28
עבודה מצוינת!
מעכשיו, כשתוסיפו רשומות, Spanner ישנה את גודל מסד הנתונים בהתאם לצורך.
לא משנה כמה מסד הנתונים שלכם יגדל, טבלת המובילים של המשחק יכולה להמשיך לגדול בצורה מדויקת בעזרת Spanner וטכנולוגיית Truetime שלו.
7. הסרת המשאבים
אחרי שסיימנו לשחק עם Spanner, צריך לנקות את סביבת הפיתוח כדי לחסוך במשאבים יקרים ובכסף. למזלנו, זה שלב פשוט. פשוט נכנסים למסוף המפתחים ומוחקים את המופע שיצרנו בשלב של ה-codelab שנקרא 'הגדרת מופע של Cloud Spanner'.
8. מעולה!
הנושאים שנדון בהם:
- מופעים, מסדי נתונים וסכמת טבלאות של Google Cloud Spanner לטבלת ניקוד
- איך יוצרים אפליקציית קונסולה ב-C# .NET Core
- איך יוצרים מסד נתונים וטבלאות ב-Spanner באמצעות ספריית הלקוח C#
- איך טוענים נתונים למסד נתונים של Spanner באמצעות ספריית הלקוח C#
- איך ליצור שאילתה של התוצאות 'העשר המובילים' מהנתונים באמצעות חותמות זמן של שמירה ב-Spanner וספריית הלקוח C#
השלבים הבאים:
- לקריאת הסקירה הטכנית בנושא Spanner CAP
- מידע נוסף על תכנון סכימה ועל שיטות מומלצות לשאילתות
- מידע נוסף על חותמות זמן של ביצוע פעולות ב-Cloud Spanner
שליחת משוב
- נשמח אם תקדישו כמה רגעים למילוי הסקר הקצר שלנו.