1. بررسی اجمالی
Google Cloud Spanner یک سرویس پایگاه داده رابطه‌ای با مقیاس‌پذیر افقی، توزیع‌شده در سطح جهانی و کاملاً مدیریت شده است که تراکنش‌های ACID و معنایی SQL را بدون کاهش عملکرد و در دسترس بودن بالا ارائه می‌کند.
در این آزمایشگاه، نحوه راه اندازی یک نمونه Cloud Spanner را خواهید آموخت. شما مراحل ایجاد یک پایگاه داده و طرحواره ای را طی خواهید کرد که می تواند برای امتیازات بازی استفاده شود. شما با ایجاد یک جدول بازیکنان برای ذخیره اطلاعات بازیکن و یک جدول امتیازات برای ذخیره امتیازات بازیکنان شروع خواهید کرد.
سپس جداول را با داده های نمونه پر می کنید. سپس با اجرای چند پرس و جوی نمونه برتر و در نهایت حذف نمونه برای آزاد کردن منابع، آزمایشگاه را به پایان می رسانید.
چیزی که یاد خواهید گرفت
- نحوه راه اندازی یک نمونه Cloud Spanner.
- نحوه ایجاد پایگاه داده و جداول
- نحوه استفاده از ستون مهر زمان commit
- نحوه بارگیری داده ها در جدول پایگاه داده Cloud Spanner با مُهر زمانی.
- چگونه پایگاه داده Cloud Spanner خود را پرس و جو کنیم.
- چگونه نمونه Cloud Spanner خود را حذف کنیم.
آنچه شما نیاز دارید
چگونه از این آموزش استفاده خواهید کرد؟
تجربه خود را با Google Cloud Platform چگونه ارزیابی می کنید؟
2. راه اندازی و الزامات
تنظیم محیط خود به خود
اگر قبلاً یک حساب Google (Gmail یا Google Apps) ندارید، باید یک حساب ایجاد کنید . به کنسول Google Cloud Platform ( consol.cloud.google.com ) وارد شوید و یک پروژه جدید ایجاد کنید.
اگر قبلاً پروژه ای دارید، روی منوی کشویی انتخاب پروژه در سمت چپ بالای کنسول کلیک کنید:
و روی دکمه "پروژه جدید" در گفتگوی حاصل کلیک کنید تا یک پروژه جدید ایجاد کنید:
اگر قبلاً پروژه ای ندارید، باید یک دیالوگ مانند این را ببینید تا اولین پروژه خود را ایجاد کنید:
گفتگوی بعدی ایجاد پروژه به شما امکان می دهد جزئیات پروژه جدید خود را وارد کنید:
شناسه پروژه را به خاطر بسپارید، که یک نام منحصر به فرد در تمام پروژه های Google Cloud است (نام بالا قبلاً گرفته شده است و برای شما کار نخواهد کرد، متأسفیم!). بعداً در این آزمایشگاه کد به عنوان PROJECT_ID نامیده خواهد شد.
در مرحله بعد، اگر قبلاً این کار را انجام نداده‌اید، برای استفاده از منابع Google Cloud و فعال کردن Cloud Spanner API، باید صورت‌حساب را در Developers Console فعال کنید .
گذراندن این کد نباید بیش از چند دلار هزینه داشته باشد، اما اگر تصمیم به استفاده از منابع بیشتری داشته باشید یا آنها را در حال اجرا رها کنید، ممکن است بیشتر باشد (به بخش "پاکسازی" در انتهای این سند مراجعه کنید). قیمت Google Cloud Spanner در اینجا مستند شده است.
کاربران جدید Google Cloud Platform واجد شرایط استفاده آزمایشی رایگان 300 دلاری هستند که باید این نرم افزار کد را کاملاً رایگان کند.
Google Cloud Shell Setup
در حالی که Google Cloud و Spanner را می‌توان از راه دور از لپ‌تاپ شما کار کرد، در این نرم‌افزار از Google Cloud Shell استفاده می‌کنیم، یک محیط خط فرمان که در Cloud اجرا می‌شود.
این ماشین مجازی مبتنی بر دبیان با تمام ابزارهای توسعه که شما نیاز دارید بارگذاری شده است. این دایرکتوری اصلی 5 گیگابایتی دائمی را ارائه می دهد و در Google Cloud اجرا می شود و عملکرد شبکه و احراز هویت را بسیار افزایش می دهد. این بدان معنی است که تمام چیزی که برای این کد لبه نیاز دارید یک مرورگر است (بله، روی کروم بوک کار می کند).
- برای فعال کردن Cloud Shell از Cloud Console، کافی است روی 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 را تنظیم خواهید کرد.
3. یک نمونه Cloud Spanner راه اندازی کنید
در این مرحله ما نمونه Cloud Spanner خود را برای این Codelab راه اندازی می کنیم. ورودی آچار را جستجو کنید 
در سمت چپ منوی همبرگر بالا 
یا با فشار دادن "/" عبارت "Spanner" را جستجو کنید و "Spanner" را تایپ کنید.
بعد، بر روی کلیک کنید 
و با وارد کردن نام نمونه cloudspanner-leaderboard برای نمونه خود، انتخاب یک پیکربندی (انتخاب یک نمونه منطقه ای) و تنظیم تعداد گره ها، فرم را پر کنید، برای این کد لبه تنها به 1 گره نیاز داریم. برای نمونه های تولید و برای واجد شرایط بودن برای Cloud Spanner SLA، باید 3 یا بیشتر گره را در نمونه Cloud Spanner خود اجرا کنید.
آخرین، اما نه کم اهمیت، روی "ایجاد" کلیک کنید و در عرض چند ثانیه یک نمونه Cloud Spanner در اختیار دارید.
در مرحله بعدی از کتابخانه کلاینت C# برای ایجاد یک پایگاه داده و طرحواره در نمونه جدید خود استفاده می کنیم.
4. یک پایگاه داده و طرحواره ایجاد کنید
در این مرحله می‌خواهیم پایگاه داده و طرحواره خود را بسازیم.
بیایید از کتابخانه مشتری C# برای ایجاد دو جدول استفاده کنیم. یک جدول بازیکنان برای اطلاعات بازیکن و یک جدول امتیازات برای ذخیره امتیازات بازیکنان. برای انجام این کار، مراحل ایجاد یک برنامه کنسول C# را در Cloud Shell طی می کنیم.
ابتدا با تایپ دستور زیر در Cloud Shell، کد نمونه این کد لبه را از Github کلون کنید:
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
سپس دایرکتوری را به دایرکتوری "applications" تغییر دهید که در آن برنامه خود را ایجاد خواهید کرد.
cd dotnet-docs-samples/applications/
تمام کدهای مورد نیاز برای این کد لبه در فهرست راهنمای dotnet-docs-samples/applications/leaderboard موجود به عنوان یک برنامه C# قابل اجرا به نام Leaderboard قرار دارد تا در حین پیشروی شما از طریق Codelab به عنوان مرجع عمل کند. ما یک دایرکتوری جدید ایجاد می کنیم و یک کپی از برنامه Leaderboard در مراحل ایجاد می کنیم.
یک دایرکتوری جدید با نام "codelab" برای برنامه ایجاد کنید و دایرکتوری را با دستور زیر به آن تغییر دهید:
mkdir codelab && cd $_
با استفاده از دستور زیر یک برنامه کنسول دات نت سی شارپ با نام Leaderboard ایجاد کنید:
dotnet new console -n Leaderboard
این دستور یک برنامه کنسول ساده متشکل از دو فایل اصلی، فایل پروژه Leaderboard.csproj و فایل برنامه Program.cs ایجاد می کند.
بیایید آن را اجرا کنیم. دایرکتوری را به دایرکتوری Leaderboard تازه ایجاد شده که برنامه در آن قرار دارد تغییر دهید:
cd Leaderboard
سپس دستور زیر را وارد کنید تا اجرا شود.
dotnet run
شما باید خروجی برنامه "Hello World!" را ببینید.
اکنون بیایید برنامه کنسول خود را با ویرایش Program.cs به روز کنیم تا از کتابخانه کلاینت C# Spanner برای ایجاد تابلوی امتیازات متشکل از دو جدول Players و Scores استفاده کنیم. می توانید این کار را درست در ویرایشگر پوسته ابری انجام دهید:
ویرایشگر پوسته ابری را با کلیک بر روی نماد مشخص شده در زیر باز کنید:
سپس، فایل Program.cs را در ویرایشگر پوسته ابری باز کنید و کد موجود فایل را با کد مورد نیاز برای ایجاد پایگاه داده leaderboard و جداول Players and 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 Editor برای باز کردن و ویرایش فایل پروژه برنامه Leaderboard.csproj استفاده کنید و آن را به شکل کد زیر به روز کنید. مطمئن شوید که تمام تغییرات خود را با استفاده از منوی "File" ویرایشگر پوسته ابری ذخیره کرده اید.
<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 Github است و یک پسوند مفید "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 با شناسه پروژه ای که در ابتدای این آزمایشگاه ایجاد کرده اید جایگزین کرده اید.
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، باید پایگاه داده و جداول جدید خود را در منوی سمت چپ مشاهده کنید.
در مرحله بعدی برنامه خود را برای بارگیری برخی از داده ها در پایگاه داده جدید شما به روز می کنیم.
5. بارگذاری داده ها
ما اکنون یک پایگاه داده به نام leaderboard داریم که شامل دو جدول است. Players و Scores حالا بیایید از کتابخانه مشتری C# استفاده کنیم تا جدول Players خود را با بازیکنان و جدول Scores خود را با امتیازهای تصادفی برای هر بازیکن پر کنیم.
ویرایشگر پوسته ابری را با کلیک بر روی نماد مشخص شده در زیر باز کنید:
در مرحله بعد، فایل Program.cs را در ویرایشگر پوسته ابری ویرایش کنید تا یک دستور 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 مورد انتظار است که "نوع درج" برای اجرا است. این آرگومان می تواند مقدار «بازیکن» یا «امتیاز» داشته باشد.
حالا بیایید دستور insert را با همان مقادیر آرگومان اجرا کنیم که هنگام فراخوانی دستور create استفاده کردیم و "players" را به عنوان آرگومان اضافی "نوع درج" اضافه کنیم. مطمئن شوید که PROJECT_ID با شناسه پروژه ای که در ابتدای این آزمایشگاه ایجاد کرده اید جایگزین کرده اید.
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 timestamp" از طریق عبارت 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 به یک ستون "Commit timestamp" تبدیل می‌کند و آن را قادر می‌سازد تا به طور خودکار با مهر زمانی دقیق تراکنش برای عملیات INSERT و UPDATE در یک ردیف جدول مشخص شود.
همچنین می‌توانید مقادیر مُهر زمانی خود را در ستون «مهر زمانی تعهد» درج کنید تا زمانی که یک مهر زمانی با مقداری که در گذشته است وارد کنید، این همان کاری است که ما برای هدف این آزمایشگاه انجام خواهیم داد.
حالا بیایید دستور insert را با همان مقادیر آرگومان اجرا کنیم که هنگام فراخوانی دستور create و اضافه کردن "scores" به عنوان آرگومان اضافی "نوع درج" استفاده کردیم. مطمئن شوید که PROJECT_ID با شناسه پروژه ای که در ابتدای این آزمایشگاه ایجاد کرده اید جایگزین کرده اید.
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 ، بررسی کنیم که جدول امتیازات نیز دارای داده است. باید ببینید که داده‌هایی در ستون‌های PlayerId ، Timestamp و Score جدول دارید.
آفرین! بیایید برنامه خود را به روز کنیم تا برخی از پرس و جوها را اجرا کنیم که بتوانیم از آنها برای ایجاد تابلوی امتیازات بازی استفاده کنیم.
6. کوئری های تابلوی امتیازات را اجرا کنید
اکنون که پایگاه داده خود را راه اندازی کرده ایم و اطلاعات را در جداول خود بارگذاری کرده ایم، بیایید با استفاده از این داده ها یک تابلوی امتیازات ایجاد کنیم. برای این کار باید به چهار سوال زیر پاسخ دهیم:
- کدام بازیکنان "ده" برتر تمام دوران هستند؟
- کدام بازیکنان "ده" برتر سال هستند؟
- کدام بازیکنان "ده" برتر ماه هستند؟
- کدام بازیکنان "ده" برتر هفته هستند؟
بیایید برنامه خود را برای اجرای پرس و جوهای SQL که به این سؤالات پاسخ می دهند، به روز کنیم.
ما یک دستور query اضافه می کنیم که راهی برای اجرای پرس و جوها برای پاسخ به سوالاتی که اطلاعات مورد نیاز برای تابلوی امتیازات ما را تولید می کند، ارائه می دهد.
فایل Program.cs را در Cloud Shell Editor ویرایش کنید تا برنامه به‌روزرسانی شود تا دستور 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 است که به این معنی است که هیچ رکوردی توسط مهر زمانی فیلتر نخواهد شد. بنابراین می‌توانیم از دستور query بدون مقدار «timespan» برای دریافت لیستی از «ده بازیکن برتر» خود در تمام دوران استفاده کنیم.
بیایید دستور query را بدون تعیین "timespan" اجرا کنیم، با استفاده از همان مقادیر آرگومان که هنگام اجرای دستور create استفاده کردیم. مطمئن شوید که PROJECT_ID با شناسه پروژه ای که در ابتدای این آزمایشگاه ایجاد کرده اید جایگزین کرده اید.
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 را با آرگومان های لازم برای پرس و جو از "ده بازیکن برتر" سال با تعیین "زمان زمانی" برابر با تعداد ساعت های یک سال که 8760 است، اجرا کنیم. مطمئن شوید که PROJECT_ID با ID پروژه خود جایگزین کرده اید. در ابتدای این کد لبه ایجاد شده است.
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 را برای پرس و جو از "ده بازیکن برتر" ماه با تعیین یک "زمان زمانی" برابر با تعداد ساعت های یک ماه که 730 ساعت است، اجرا کنیم. مطمئن شوید که PROJECT_ID را با ID پروژه ای که در ابتدا ایجاد کرده اید جایگزین کرده اید. از این آزمایشگاه کد
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 را برای پرس و جو از "ده بازیکن برتر" هفته با تعیین یک "زمان زمانی" برابر با تعداد ساعات یک هفته که 168 ساعت است، اجرا کنیم. مطمئن شوید که PROJECT_ID با ID پروژه ای که در ابتدا ایجاد کرده اید جایگزین کرده اید. از این آزمایشگاه کد
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، باید زمین بازی خود را تمیز کنیم و منابع و پول گرانبها را ذخیره کنیم. خوشبختانه این یک مرحله آسان است، کافی است به کنسول توسعه دهنده بروید و نمونه ای را که در مرحله کد لبه ایجاد کردیم به نام "Setup a Cloud Spanner Instance" را حذف کنید.
8. تبریک!
آنچه ما پوشش داده ایم:
- نمونه‌های Google Cloud Spanner، پایگاه‌های داده و جدول جدول برای تابلوی امتیازات
- نحوه ایجاد اپلیکیشن کنسول NET Core C#
- نحوه ایجاد یک پایگاه داده و جداول Spanner با استفاده از کتابخانه مشتری C#
- نحوه بارگذاری داده ها در پایگاه داده Spanner با استفاده از کتابخانه مشتری C#
- نحوه پرس و جو کردن نتایج "Top Ten" از داده های خود با استفاده از مهر زمانی Spanner commit و کتابخانه مشتری C#
مراحل بعدی:
- کاغذ سفید Spanner CAP را بخوانید
- درباره بهترین شیوه های طراحی طرحواره و پرس و جو بیاموزید
- درباره مهرهای زمانی commit Cloud Spanner بیشتر بیاموزید
نظرات خود را با ما در میان بگذارید
- لطفا یک لحظه برای تکمیل نظرسنجی بسیار کوتاه ما وقت بگذارید