۱. مرور کلی
گوگل کلود اسپنر یک سرویس پایگاه داده رابطهای، توزیعشده در سطح جهانی و مقیاسپذیر افقی است که تراکنشهای ACID و مفاهیم SQL را بدون از دست دادن عملکرد و دسترسیپذیری بالا ارائه میدهد.
در این آزمایش، نحوه راهاندازی یک نمونه Cloud Spanner را خواهید آموخت. مراحل ایجاد یک پایگاه داده و طرحوارهای که میتواند برای جدول امتیازات بازی استفاده شود را طی خواهید کرد. با ایجاد یک جدول Players برای ذخیره اطلاعات بازیکنان و یک جدول Scores برای ذخیره امتیازات بازیکنان شروع خواهید کرد.
در مرحله بعد، جداول را با دادههای نمونه پر خواهید کرد. سپس با اجرای چند نمونه کوئری از ده نمونه برتر، این آزمایش را به پایان خواهید رساند و در نهایت نمونه را برای آزادسازی منابع حذف خواهید کرد.
آنچه یاد خواهید گرفت
- نحوه راهاندازی یک نمونه Cloud Spanner.
- نحوه ایجاد پایگاه داده و جداول.
- نحوه استفاده از ستون مهر زمانی کامیت.
- نحوه بارگذاری دادهها در جدول پایگاه داده Cloud Spanner خود با مهرهای زمانی.
- چگونه از پایگاه داده Cloud Spanner خود پرس و جو کنید.
- چگونه نمونه Cloud Spanner خود را حذف کنید.
آنچه نیاز دارید
چگونه از این آموزش استفاده خواهید کرد؟
تجربه خود را با پلتفرم ابری گوگل چگونه ارزیابی میکنید؟
۲. تنظیمات و الزامات
تنظیم محیط خودتنظیم
اگر از قبل حساب گوگل (جیمیل یا برنامههای گوگل) ندارید، باید یکی ایجاد کنید . وارد کنسول پلتفرم ابری گوگل ( console.cloud.google.com ) شوید و یک پروژه جدید ایجاد کنید.
اگر از قبل پروژهای دارید، روی منوی کشویی انتخاب پروژه در سمت چپ بالای کنسول کلیک کنید:
و در پنجرهی باز شده روی دکمهی «پروژهی جدید» کلیک کنید تا یک پروژهی جدید ایجاد شود:
اگر از قبل پروژهای ندارید، باید پنجرهای مانند این را برای ایجاد اولین پروژه خود ببینید:
پنجرهی بعدیِ ایجاد پروژه به شما امکان میدهد جزئیات پروژهی جدید خود را وارد کنید:
شناسه پروژه را به خاطر بسپارید، که یک نام منحصر به فرد در تمام پروژههای Google Cloud است (نام بالا قبلاً گرفته شده و برای شما کار نخواهد کرد، متاسفیم!). بعداً در این آزمایشگاه کد به آن PROJECT_ID گفته خواهد شد.
در مرحله بعد، اگر قبلاً این کار را نکردهاید، برای استفاده از منابع Google Cloud و فعال کردن Cloud Spanner API ، باید صورتحساب را در کنسول توسعهدهندگان فعال کنید .
اجرای این آزمایشگاه کد نباید بیش از چند دلار برای شما هزینه داشته باشد، اما اگر تصمیم به استفاده از منابع بیشتر بگیرید یا اگر آنها را در حال اجرا رها کنید (به بخش «پاکسازی» در انتهای این سند مراجعه کنید)، میتواند بیشتر هم بشود. قیمت Google Cloud Spanner در اینجا مستند شده است.
کاربران جدید پلتفرم ابری گوگل واجد شرایط دریافت یک دوره آزمایشی رایگان ۳۰۰ دلاری هستند که این کدلب را کاملاً رایگان میکند.
راهاندازی پوسته ابری گوگل
اگرچه میتوان از راه دور و از طریق لپتاپ، گوگل کلود و اسپنر را کنترل کرد، اما در این آزمایشگاه کد، از گوگل کلود شل ، یک محیط خط فرمان که در فضای ابری اجرا میشود، استفاده خواهیم کرد.
این ماشین مجازی مبتنی بر دبیان، تمام ابزارهای توسعه مورد نیاز شما را در خود جای داده است. این ماشین مجازی یک دایرکتوری خانگی ۵ گیگابایتی دائمی ارائه میدهد و در فضای ابری گوگل اجرا میشود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود میبخشد. این بدان معناست که تنها چیزی که برای این آزمایشگاه کد نیاز دارید یک مرورگر است (بله، روی کرومبوک هم کار میکند).
- برای فعال کردن Cloud Shell از کنسول Cloud، کافیست روی Activate 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 راهاندازی خواهید کرد.
۳. راهاندازی یک نمونهی Cloud Spanner
در این مرحله، نمونه Cloud Spanner خود را برای این codelab راهاندازی میکنیم. ورودی Spanner را جستجو کنید. 
در منوی همبرگری بالا سمت چپ 
یا با فشردن کلید "/" و تایپ "Spanner" عبارت Spanner را جستجو کنید.
در مرحله بعد، روی کلیک کنید 
و فرم را با وارد کردن نام نمونه cloudspanner-leaderboard برای نمونه خود پر کنید، یک پیکربندی انتخاب کنید (یک نمونه منطقهای را انتخاب کنید) و تعداد گرهها را تنظیم کنید، برای این codelab ما فقط به ۱ گره نیاز داریم. برای نمونههای تولیدی و برای واجد شرایط بودن برای SLA Cloud Spanner، باید ۳ یا بیشتر گره را در نمونه Cloud Spanner خود اجرا کنید.
در آخر، اما نه کماهمیتتر، روی «ایجاد» کلیک کنید و ظرف چند ثانیه یک نمونه Cloud Spanner در اختیار شما قرار میگیرد.
در مرحله بعدی، از کتابخانه کلاینت سیشارپ برای ایجاد یک پایگاه داده و طرحواره در نمونه جدید خود استفاده خواهیم کرد.
۴. ایجاد پایگاه داده و طرحواره
در این مرحله، ما قصد داریم پایگاه داده و طرحواره نمونه خود را ایجاد کنیم.
بیایید از کتابخانه کلاینت سیشارپ برای ایجاد دو جدول استفاده کنیم؛ یک جدول Players برای اطلاعات بازیکنان و یک جدول Scores برای ذخیره امتیازات بازیکنان. برای انجام این کار، مراحل ایجاد یک برنامه کنسول سیشارپ در Cloud Shell را بررسی خواهیم کرد.
ابتدا با تایپ دستور زیر در Cloud Shell، کد نمونه این codelab را از Github کپی کنید:
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
سپس دایرکتوری را به دایرکتوری "applications" تغییر دهید، جایی که برنامه خود را ایجاد خواهید کرد.
cd dotnet-docs-samples/applications/
تمام کدهای مورد نیاز برای این آزمایشگاه کد، در دایرکتوری موجود dotnet-docs-samples/applications/leaderboard به عنوان یک برنامه C# قابل اجرا با نام Leaderboard قرار دارد تا در حین پیشرفت در آزمایشگاه کد، به عنوان مرجع در اختیار شما قرار گیرد. ما یک دایرکتوری جدید ایجاد خواهیم کرد و یک کپی از برنامه Leaderboard را به صورت مرحلهای ایجاد خواهیم کرد.
یک دایرکتوری جدید با نام "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 بهروزرسانی کنیم تا از کتابخانه کلاینت C# Spanner برای ایجاد یک جدول امتیازات شامل دو جدول بازیکنان و امتیازات استفاده کنیم. میتوانید این کار را مستقیماً در ویرایشگر Cloud Shell انجام دهید:
با کلیک روی آیکون مشخص شده در زیر، ویرایشگر Cloud Shell را باز کنید:
سپس، فایل Program.cs را در ویرایشگر Cloud Shell باز کنید و کد موجود در فایل را با کد مورد نیاز برای ایجاد پایگاه داده جدول 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 استفاده کنید و آن را به شکلی مانند کد زیر بهروزرسانی کنید. مطمئن شوید که تمام تغییرات خود را با استفاده از منوی «File» ویرایشگر 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 اضافه میکند که بخشی از مخزن گیتهاب 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، Instance ID و Database ID.
حالا دستور زیر را اجرا کنید. مطمئن شوید که 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 Console، باید پایگاه داده و جداول جدید خود را که در منوی سمت چپ ظاهر میشوند، ببینید.
در مرحله بعدی، برنامه خود را بهروزرسانی خواهیم کرد تا برخی دادهها را در پایگاه داده جدید شما بارگذاری کند.
۵. بارگذاری دادهها
اکنون یک پایگاه داده به نام leaderboard داریم که شامل دو جدول است: Players و Scores . حال بیایید از کتابخانه کلاینت C# برای پر کردن جدول Players با بازیکنان و جدول Scores با نمرات تصادفی برای هر بازیکن استفاده کنیم.
با کلیک روی آیکون مشخص شده در زیر، ویرایشگر Cloud Shell را باز کنید:
در مرحله بعد، فایل Program.cs را در ویرایشگر Cloud Shell ویرایش کنید تا یک دستور insert اضافه شود که میتواند برای درج ۱۰۰ بازیکن در جدول Players استفاده شود یا میتواند برای درج ۴ امتیاز تصادفی در جدول 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 مورد انتظار است که «نوع درج» برای اجرا است. این آرگومان میتواند مقداری از نوع «بازیکنان» یا «نمرات» داشته باشد.
حالا بیایید دستور 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
حالا بیایید از کتابخانه کلاینت سیشارپ برای پر کردن جدول Scores خود با چهار امتیاز تصادفی به همراه مهرهای زمانی برای هر بازیکن در جدول Players استفاده کنیم.
ستون Timestamp جدول Scores از طریق دستور SQL زیر که هنگام اجرای دستور create اجرا شد، به عنوان یک ستون "commit timestamp" تعریف شد:
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 به یک ستون "commit timestamp" تبدیل میکند و امکان پر کردن خودکار آن با مهر زمانی دقیق تراکنش برای عملیات INSERT و UPDATE در یک ردیف جدول مشخص را فراهم میکند.
همچنین میتوانید مقادیر timestamp خودتان را در ستون "commit timestamp" وارد کنید، به شرطی که یک timestamp با مقداری که در گذشته است وارد کنید، که ما برای هدف این codelab همین کار را انجام خواهیم داد.
حالا بیایید دستور insert را با همان مقادیر آرگومانی که هنگام فراخوانی دستور create استفاده کردیم، اجرا کنیم و "scores" را به عنوان آرگومان اضافی "نوع درج" اضافه کنیم. مطمئن شوید که 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 با مهر زمانی که دقیقاً همان زمانی است که تراکنش "Insert" انجام میشود، میتوانید ثابت C# SpannerParameter.CommitTimestamp را مانند قطعه کد زیر وارد کنید:
cmd.Parameters["Timestamp"].Value = SpannerParameter.CommitTimestamp;
حالا که بارگذاری دادهها را تکمیل کردیم، بیایید مقادیری را که در جداول جدیدمان نوشتیم، تأیید کنیم. ابتدا پایگاه داده جدول leaderboard و سپس جدول Players را انتخاب کنید. روی برگه Data کلیک کنید. باید ببینید که در ستونهای PlayerId و PlayerName جدول، داده دارید.
در مرحله بعد، بیایید با کلیک روی جدول Scores و انتخاب تب Data ، بررسی کنیم که آیا جدول Scores نیز داده دارد یا خیر. باید ببینید که در ستونهای PlayerId ، Timestamp و Score جدول، داده دارید.
آفرین! بیایید برنامهمان را بهروزرسانی کنیم تا چند کوئری اجرا کنیم که میتوانیم از آنها برای ایجاد جدول امتیازات بازی استفاده کنیم.
۶. جستجوهای جدول امتیازات را اجرا کنید
حالا که پایگاه داده خود را راهاندازی و اطلاعات را در جداول بارگذاری کردهایم، بیایید با استفاده از این دادهها یک جدول امتیازات ایجاد کنیم. برای انجام این کار باید به چهار سوال زیر پاسخ دهیم:
- کدام بازیکنان جزو "ده بازیکن برتر" تمام دوران هستند؟
- کدام بازیکنان جزو «ده بازیکن برتر» سال هستند؟
- کدام بازیکنان جزو «ده بازیکن برتر» ماه هستند؟
- کدام بازیکنان جزو «ده بازیکن برتر» هفته هستند؟
بیایید برنامه خود را بهروزرسانی کنیم تا کوئریهای SQL را که به این سؤالات پاسخ میدهند، اجرا کند.
ما یک دستور query اضافه خواهیم کرد که روشی برای اجرای پرسوجوها برای پاسخ به سؤالاتی که اطلاعات مورد نیاز برای جدول امتیازات ما را تولید میکنند، فراهم میکند.
فایل Program.cs را در ویرایشگر Cloud Shell ویرایش کنید تا برنامه را برای افزودن یک دستور query بهروزرسانی کنید.
ابتدا یک بلوک فرمان 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 دارد، به این معنی که هیچ رکوردی بر اساس timestamp فیلتر نخواهد شد. بنابراین میتوانیم از دستور query بدون مقدار "timespan" برای دریافت لیستی از "ده بازیکن برتر" خود در تمام دوران استفاده کنیم.
بیایید دستور 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 را با آرگومانهای لازم اجرا کنیم تا با مشخص کردن یک "timespan" برابر با تعداد ساعات در یک سال که ۸۷۶۰ است، "ده بازیکن برتر" سال را جستجو کنیم. مطمئن شوید که 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 را اجرا کنیم تا با مشخص کردن یک "timespan" برابر با تعداد ساعات در یک ماه که ۷۳۰ است، "ده بازیکن برتر" ماه را پیدا کنیم . مطمئن شوید که 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 را اجرا کنیم تا با مشخص کردن یک "timespan" برابر با تعداد ساعات در یک هفته که ۱۶۸ است، "ده بازیکن برتر" هفته را پیدا کنیم. مطمئن شوید که 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 آن، با دقت بیشتری رشد کند.
۷. پاکسازی
بعد از کلی بازی و سرگرمی با Spanner، باید زمین بازیمان را تمیز کنیم و در منابع و پول ارزشمندمان صرفهجویی کنیم. خوشبختانه این مرحله آسان است، فقط کافی است به کنسول توسعهدهندگان بروید و نمونهای را که در مرحله codelab با نام «راهاندازی یک نمونه Cloud Spanner» ایجاد کردیم، حذف کنید.
۸. تبریک میگویم!
آنچه ما پوشش دادهایم:
- نمونههای گوگل کلود اسپنر، پایگاههای داده و طرح جدول برای کسب رتبه برتر
- نحوه ایجاد برنامه کنسول .NET Core C#
- نحوه ایجاد پایگاه داده و جداول Spanner با استفاده از کتابخانه کلاینت C#
- نحوه بارگذاری دادهها در پایگاه داده Spanner با استفاده از کتابخانه کلاینت C#
- چگونه با استفاده از مهرهای زمانی کامیت Spanner و کتابخانه کلاینت C#، نتایج "ده مورد برتر" را از دادههای خود کوئری کنیم؟
مراحل بعدی:
- گزارش رسمی Spanner CAP را بخوانید.
- آشنایی با طراحی Schema و بهترین شیوههای پرسوجو
- درباره مهرهای زمانی کامیت Cloud Spanner بیشتر بدانید
نظرات خود را با ما در میان بگذارید
- لطفا کمی وقت بگذارید و نظرسنجی بسیار کوتاه ما را تکمیل کنید.