1. 概要
Google Cloud Spanner はフルマネージドで水平スケール可能なグローバルに分散されたリレーショナル データベース サービスで、パフォーマンスと高可用性を損なうことなく ACID トランザクションと SQL セマンティクスを提供します。
このラボでは、Cloud Spanner インスタンスの設定方法について学びます。ゲーム リーダーボードに使用できるデータベースとスキーマを作成する手順について説明します。まず、プレーヤー情報を格納する Players テーブルと、プレーヤーのスコアを格納する Scores テーブルを作成します。
次に、テーブルにサンプルデータを入力します。その後、ラボの最後に、上位 10 個のサンプルクエリを実行し、最後にインスタンスを削除してリソースを解放します。
ラボの内容
- Cloud Spanner インスタンスを設定する方法。
- データベースとテーブルの作成方法。
- commit タイムスタンプ列の使用方法
- タイムスタンプを使用して Cloud Spanner データベース テーブルにデータを読み込む方法。
- Cloud Spanner データベースに対してクエリを実行する方法。
- Cloud Spanner インスタンスを削除する方法。
必要なもの
このチュートリアルの利用方法をお選びください。
Google Cloud Platform の使用経験をどのように評価されますか。
<ph type="x-smartling-placeholder">2. 設定と要件
セルフペース型の環境設定
Google アカウント（Gmail または Google Apps）をお持ちでない場合は、1 つ作成する必要があります。Google Cloud Platform のコンソール（console.cloud.google.com）にログインし、新しいプロジェクトを作成します。
すでにプロジェクトが存在する場合は、コンソールの左上にあるプロジェクト選択プルダウン メニューをクリックします。
[新しいプロジェクト] をクリックします。] ボタンをクリックし、新しいプロジェクトを作成します。
まだプロジェクトが存在しない場合は、次のような最初のプロジェクトを作成するためのダイアログが表示されます。
続いて表示されるプロジェクト作成ダイアログでは、新しいプロジェクトの詳細を入力できます。
プロジェクト ID を忘れないようにしてください。プロジェクト ID は、すべての Google Cloud プロジェクトを通じて一意の名前にする必要があります（上記の名前はすでに使用されているため使用できません）。以降、この Codelab では PROJECT_ID と表します。
次に、Google Cloud リソースを使用し、Cloud Spanner API を有効にするために、Developers Console で課金を有効にする必要があります。
この Codelab をすべて実行しても費用はかかりませんが、より多くのリソースを使用する場合や実行したままにする場合は、コストが高くなる可能性があります（このドキュメントの最後にある「クリーンアップ」セクションをご覧ください）。Google Cloud Spanner の料金については、こちらをご覧ください。
Google Cloud Platform の新規ユーザーの皆さんには、$300 の無料トライアルをご利用いただけます。その場合は、この Codelab を完全に無料でご利用いただけます。
Google Cloud Shell のセットアップ
Google Cloud と Spanner はノートパソコンからリモートで操作でき、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。
この Debian ベースの仮想マシンには、必要な開発ツールがすべて揃っています。永続的なホーム ディレクトリが 5 GB 用意されており、Google Cloud で稼働するため、ネットワークのパフォーマンスと認証が大幅に向上しています。つまり、この Codelab に必要なのはブラウザだけです（はい、Chromebook で動作します）。
- Cloud Console から Cloud Shell を有効にするには、[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 が見つからない場合は、設定手順で使用した ID を確認するか、Cloud コンソール ダッシュボードで調べます。
Cloud Shell では、デフォルトで環境変数もいくつか設定されます。これらの変数は、以降のコマンドを実行する際に有用なものです。
echo $GOOGLE_CLOUD_PROJECT
コマンド出力
<PROJECT_ID>
- 最後に、デフォルトのゾーンとプロジェクト構成を設定します。
gcloud config set compute/zone us-central1-f
さまざまなゾーンを選択できます。詳しくは、リージョンとゾーン。
概要
この手順では、環境の設定を行います。
次の設定
次に、Cloud Spanner インスタンスを設定します。
3. Cloud Spanner インスタンスを設定する
この手順では、この Codelab 用に Cloud Spanner インスタンスを設定します。左上のハンバーガー メニュー 
で Spanner の項目 
を探すか、「/」を押して「Spanner」と入力し Spanner を検索します。
次に、
をクリックしてインスタンスのインスタンス名 cloudspanner-leaderboard を入力し、構成を選択（リージョン インスタンスを選択）してノード数を設定しフォームに入力します。この Codelab で必要となるノードは 1 つのみです。本番環境インスタンスの場合に Cloud Spanner SLA の対象となるには、Cloud Spanner インスタンスで 3 つ以上のノードを実行する必要があります。
最後に、重要な [作成] をクリックすると、数秒で指定した Cloud Spanner インスタンスが作成されます。
次のステップでは、C# クライアント ライブラリを使用して、新しいインスタンスにデータベースとスキーマを作成します。
4. データベースとスキーマを作成する
この手順では、サンプルのデータベースとスキーマを作成します。
C# クライアント ライブラリを使用して、2 つのテーブルを作成しましょう。プレーヤー情報を格納する Players テーブルと、プレーヤーのスコアを格納する Scores テーブルがあります。そのために、Cloud Shell で C# コンソール アプリケーションを作成する手順を説明します。
まず、Cloud Shell で次のコマンドを入力して、GitHub にあるこの Codelab 用のサンプルコードのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
次に、アプリケーションを作成する「applications」ディレクトリに移動します。
cd dotnet-docs-samples/applications/
この Codelab に必要なすべてのコードは、既存の dotnet-docs-samples/applications/leaderboard ディレクトリ（Leaderboard という実行可能な C# アプリケーション）に格納されており、この Codelab を進める際の参考になります。新しいディレクトリを作成し、リーダーボード アプリケーションのコピーを段階的にビルドします。
アプリケーション用に「codelab」という新しいディレクトリを作成し、次のコマンドを使用して作成したディレクトリに移動します。
mkdir codelab && cd $_
「Leaderboard」という名前の新しい .NET C# コンソール アプリケーションを作成する次のコマンドを使用します。
dotnet new console -n Leaderboard
このコマンドにより、プロジェクト ファイル Leaderboard.csproj とプログラム ファイル Program.cs の 2 つのプライマリ ファイルで構成されるシンプルなコンソール アプリケーションが作成されます。
実行してみましょう。アプリケーションが存在する、新しく作成したリーダーボード ディレクトリに移動します。
cd Leaderboard
次に、以下のコマンドを入力して実行します。
dotnet run
アプリケーションの出力「Hello World!」が表示されます。
次に、Program.cs を編集してコンソール アプリを更新し、C# Spanner クライアント ライブラリを使用して、Players と Scores の 2 つのテーブルで構成されるリーダーボードを作成しましょう。この操作は、Cloud Shell エディタで行えます。
下のハイライト表示されたアイコンをクリックして、Cloud Shell エディタを開きます。
次に、Cloud Shell エディタで Program.cs ファイルを開き、次の C# アプリケーション コードを Program.cs ファイルに貼り付けて、ファイルの既存のコードを leaderboard データベースと Players テーブルと Scores テーブルの作成に必要なコードに置き換えます。
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);
}
}
}
プログラムのコードを明確に把握できるように、以下にプログラムの図を示します。主なコンポーネントにはラベルが付けられています。
dotnet-docs-samples/applications/leaderboard/step4 ディレクトリの Program.cs ファイルを使用して、create コマンドを有効にするコードを追加した後の Program.cs ファイルの表示例を確認できます。
次に、Cloud Shell エディタを使用してプログラムのプロジェクト ファイル Leaderboard.csproj を開き、次のコードのように更新します。[ファイル] タブを使用して、すべての変更内容を保存してください。メニューを選択します。
<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>
この変更により、Cloud Spanner API を操作する必要がある C# Spanner Nuget パッケージ Google.Cloud.Spanner.Data への参照が追加されました。この変更により、dotnet-doc-samples GitHub リポジトリの一部である CommandLineUtil プロジェクトへの参照も追加され、有用な「verbmap」が提供されます。オープンソースの CommandLineParser に対する拡張機能です。コンソール アプリケーションのコマンドライン入力を処理するための便利なライブラリです。
dotnet-docs-samples/applications/leaderboard/step4 ディレクトリの Leaderboard.csproj ファイルを使用して、create コマンドを有効にするコードを追加した後の Leaderboard.csproj ファイルの表示例を確認できます。
これで、更新されたサンプルを実行する準備が整いました。次のコマンドを入力すると、更新したアプリケーションのデフォルトのレスポンスが表示されます。
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.
このレスポンスから、これは create、help、version の 3 つのコマンドのいずれかで実行できる Leaderboard アプリケーションであることがわかります。
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 コマンドに想定される引数がプロジェクト ID、インスタンス ID、データベース ID であることがわかります。
そこで、次のコマンドを実行します。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト 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 Console の [Cloud Spanner] セクションで、左側のメニューに新しいデータベースとテーブルが表示されます。
次の手順では、新しいデータベースにデータが読み込まれるようにアプリケーションを更新します。
5. データの読み込み
これで、Players と Scores の 2 つのテーブルを含む leaderboard という名前のデータベースが作成されました。次に、C# クライアント ライブラリを使用して、Players テーブルにプレーヤーを入力し、Scores テーブルに各プレーヤーのランダムスコアを入力します。
下のハイライト表示されたアイコンをクリックして、Cloud Shell エディタを開きます。
次に、Cloud Shell エディタで Program.cs ファイルを編集して、insert コマンドを追加します。このコマンドを使用すると、100 人のプレーヤーを Players テーブルに挿入する、または Players テーブルの各プレーヤーの Scores テーブルに 4 つのランダムなスコアを挿入することができます。
まず、「Verbmap」に新しい insert コマンド ブロックを追加します。既存の 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; }
}
次に、既存の CreateAsync メソッドの下に、以下の Insert、InsertPlayersAsync、InsertScoresAsync の各メソッドを追加します。
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))
dotnet-docs-samples/applications/leaderboard/step5 ディレクトリの Program.cs ファイルを使用して、insert コマンドを有効にするコードを追加した後の Program.cs ファイルの表示例を確認できます。
プログラムを実行して、プログラムで使用可能なコマンドのリストに新しい 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'.
レスポンスから、プロジェクト ID、インスタンス ID、データベース ID に加えて、「挿入のタイプ」である別の引数 value pos. 3 が予期されていることがわかります。必要があります。この引数には「players」という値を指定できます。「scores」を使用します。
次に、create コマンドを呼び出したときに使用したのと同じ引数値で「players」を追加して insert コマンドを実行します。追加の「挿入のタイプ」として渡します。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト 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# クライアント ライブラリを使用して、Players テーブル内の各プレーヤーのタイムスタンプと 4 つのランダムスコアを Scores テーブルに入力します。
Scores テーブルの Timestamp 列は、前に create コマンドを実行したときに実行された次の SQL ステートメントを使用して「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 オペレーションの正確なトランザクション タイムスタンプが自動的に入力されます。
また、独自のタイムスタンプ値を「commit timestamp」列に挿入することもでき、この Codelab でもそれを扱います。この場合は、過去の値を持つタイムスタンプを挿入する必要があります。
次に、「scores」を追加して create コマンドを呼び出したときに使用したのと同じ引数値で、insert コマンドを実行します。追加の「挿入のタイプ」として渡します。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト 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
scores として指定された「挿入の種類」を指定して insert を実行すると、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] テーブルをクリックして [Data] タブを選択し、Scores テーブルにもデータが存在することを確認しましょう。テーブルの PlayerId、Timestamp、Score の各列にデータが存在することを確認できます。
頑張りましたね。プログラムを更新して、ゲームのリーダーボードを作成するために使用できるクエリを実行してみましょう。
6. リーダーボード クエリを実行する
データベースを設定して情報をテーブルに読み込んだところで、このデータを使用してリーダーボードを作成してみましょう。そのためには、次の 4 つの質問に答える必要があります。
- 常時「トップ 10」入りしているのは、どのプレーヤーですか？
- どのプレーヤーが今年の「トップ 10」のプレーヤーですか？
- どのプレーヤーが今月のトップ 10 のプレーヤーですか？
- どのプレーヤーが今週の「トップ 10」のプレーヤーですか？
プログラムを更新して、これらの質問に答える SQL クエリを実行してみましょう。
次に、query コマンドを追加します。このコマンドには、リーダーボードに必要な情報を生成するための質問に回答するクエリを実行する方法が用意されていますす。
Cloud Shell エディタで Program.cs ファイルを編集し、プログラムを更新して query コマンドを追加します。
まず、「Verbmap」に新しい query コマンド ブロックを追加します。既存の 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; }
}
次に、既存の InsertScoresAsync メソッドの下に、次の Query メソッドと QueryAsync メソッドを追加します。
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))
dotnet-docs-samples/applications/leaderboard/step6 ディレクトリの Program.cs ファイルを使用して、query コマンドを有効にするコードを追加した後の Program.cs ファイルの表示例を確認できます。
プログラムを実行して、プログラムで使用可能なコマンドのリストに新しい 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.
このレスポンスから、プロジェクト ID、インスタンス ID、データベース ID に加えて、別の引数 value pos. 3 が想定されていることがわかります。これにより、Scores テーブルの Timestamp 列の値に基づいてレコードをフィルタリングする期間を時間で指定できます。この引数のデフォルト値は 0 です。つまり、タイムスタンプでフィルタされるレコードはありません。したがって、「期間」値を指定せずに query コマンドを使用して、常時「トップ 10」のプレーヤーの一覧を取得できます。
「timespan」を指定せずに query コマンドを実行しましょう。create コマンドを実行したときに使用したのと同じ引数値を使用します。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト 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 コマンドに必要な引数を指定して実行し、年間の「トップテン」プレーヤーをクエリします。この場合、「timespan」には、1 年に相当する 8,760 時間を指定します。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト ID に置き換えてください。
dotnet run query PROJECT_ID cloudspanner-leaderboard leaderboard 8760
次のような年間の「トップ 10」プレーヤーを含むレスポンスが表示されます。
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
次に、1 か月に相当する 730 時間を「timespan」に指定して、query コマンドを実行し、月間の「トップテン」プレーヤーをクエリしてみましょう。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト 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
次に、1 週間に相当する 168 時間を「timespan」に指定して、query コマンドを実行し、週間の「トップテン」プレーヤーをクエリしてみましょう。必ず、PROJECT_ID は、この Codelab の最初に作成したプロジェクト 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 の操作を楽しんだ後は、使用した環境をクリーンアップして貴重なリソースと予算を節約する必要があります。これは簡単なステップです。デベロッパー コンソールに移動し、「Cloud Spanner インスタンスを設定する」という Codelab のステップで作成したインスタンスを削除するだけです。
8. 完了
学習した内容
- リーダーボードの Google Cloud Spanner インスタンス、データベース、テーブル スキーマ
- .NET Core C# コンソール アプリケーションの作成方法
- C# クライアント ライブラリを使用して Spanner データベースとテーブルを作成する方法
- C# クライアント ライブラリを使用して Spanner データベースにデータを読み込む方法
- 「トップ 10」をクエリする方法Spanner commit タイムスタンプと C# クライアント ライブラリを使用してデータから結果を
次のステップ:
- Spanner CAP ホワイトペーパーを確認する
- スキーマ設計とクエリのベスト プラクティスについて確認する
- Cloud Spanner の commit タイムスタンプの詳細を確認する
フィードバックをお寄せください
- 簡単なアンケートにご協力ください