1. 概览
Google Cloud Spanner 是一种全代管式可横向扩容的关系型数据库服务，可提供 ACID 事务和 SQL 语义，而不会提升性能和高可用性。
在本实验中，您将学习如何设置 Cloud Spanner 实例。您将逐步完成创建可用于游戏排行榜的数据库和架构的步骤。首先，创建一个用于存储玩家信息的 Players 表和一个用于存储玩家得分的 Scores 表。
接下来，您将使用示例数据填充表。然后，您将通过运行前十名示例查询并最终删除实例以释放资源来结束本实验。
您将学习的内容
- 如何设置 Cloud Spanner 实例。
- 如何创建数据库和表。
- 如何使用提交时间戳列。
- 如何使用时间戳将数据加载到您的 Cloud Spanner 数据库表中。
- 如何查询您的 Cloud Spanner 数据库。
- 如何删除 Cloud Spanner 实例。
所需 条件
您打算如何使用本教程？
您如何评价自己使用 Google Cloud Platform 的体验？
<ph type="x-smartling-placeholder">2. 设置和要求
自定进度的环境设置
如果您还没有 Google 账号（Gmail 或 Google Apps），则必须创建一个。登录 Google Cloud Platform Console (console.cloud.google.com) 并创建一个新项目。
如果您已经有一个项目，请点击控制台左上方的项目选择下拉菜单：
然后在出现的对话框中点击“新建项目”按钮以创建一个新项目：
如果您还没有项目，则应该看到一个类似这样的对话框来创建您的第一个项目：
随后的项目创建对话框可让您输入新项目的详细信息：
请记住项目 ID，它是所有 Google Cloud 项目中的唯一名称（很抱歉，上述名称已被占用，您无法使用！）。它稍后将在此 Codelab 中被称为 PROJECT_ID。
接下来，如果尚未执行此操作，则需要在 Developers Console 中启用结算功能，以便使用 Google Cloud 资源并启用 Cloud Spanner API。
在此 Codelab 中运行不会花费您超过几美元，但是如果您决定使用更多的资源或让它们运行（请参阅本文档末尾的“清理”部分），则可能会花费更多。如需了解 Google Cloud Spanner 价格，请参阅此处。
Google Cloud Platform 的新用户均有资格获享 $300 赠金，免费试用此 Codelab。
Google Cloud Shell 设置
虽然 Google Cloud 和 Spanner 可以从笔记本电脑远程操作，但在此 Codelab 中，我们将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。
基于 Debian 的这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5GB 主目录，并且在 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 Console 信息中心查找该 ID：
默认情况下，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，我们仅需要一个节点。对于生产实例并符合 Cloud Spanner SLA 的资格，您将需要在 Cloud Spanner 实例中运行 3 个或更多节点。
最后但并非最不重要的一点是，点击“创建”，然后在几秒钟内就可以使用 Cloud Spanner 实例。
在下一步中，我们将使用 C# 客户端库在新实例中创建数据库和架构。
4. 创建数据库和架构
在此步骤中，我们将创建示例数据库和架构。
我们使用 C# 客户端库创建两个表；用于存储玩家信息的 Players 表和用于存储玩家得分的 Scores 表。为此，我们将逐步介绍如何在 Cloud Shell 中创建 C# 控制台应用。
首先，通过在 Cloud Shell 中键入以下命令，从 GitHub 克隆此 Codelab 的示例代码：
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
然后将目录更改为创建应用的“应用”目录。
cd dotnet-docs-samples/applications/
此 Codelab 所需的所有代码都作为一个可运行的 C# 应用位于现有 dotnet-docs-samples/applications/leaderboard 目录中，该应用命名为 Leaderboard 在您逐步通过 Codelab 时可作为参考。我们将创建一个新目录，并分阶段构建排行榜应用的副本。
为应用创建一个名为“Codelab”的新目录，并使用以下命令将目录切换到该目录：
mkdir codelab && cd $_
新建一个名为“Leaderboard”的 .NET C# 控制台应用创建 Deployment
dotnet new console -n Leaderboard
此命令会创建一个简单的控制台应用，该应用由两个主要文件（项目文件 Leaderboard.csproj 和程序文件 Program.cs）组成。
我们来运行一下。将目录更改为应用所在的新创建的排行榜目录：
cd Leaderboard
然后输入以下命令来运行它。
dotnet run
您应该会看到应用输出“Hello World!”。
现在，我们来更新控制台应用，方法是修改 Program.cs，以使用 C# Spanner 客户端库创建由两个表“Players”和“Scores”组成的排行榜。您可以直接在 Cloud Shell Editor 中执行此操作：
通过点击下面突出显示的图标，打开 Cloud Shell Editor：
接下来，在 Cloud Shell Editor 中打开 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 Editor 打开和修改程序的项目文件 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 的引用。这项更改还添加了对 CommandLineUtil 项目的引用，该项目是 dotnet-doc-samples GitHub 代码库的一部分，并提供了一个实用的“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.
从此响应中，我们可以看到这是 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 命令的预期参数为项目 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. 加载数据
现在，我们有一个名为 leaderboard 的数据库，包含两个表：Players 和 Scores。现在，我们使用 C# 客户端库使用玩家填充 Players 表，并使用每个玩家的随机得分填充 Scores 表。
通过点击下面突出显示的图标，打开 Cloud Shell Editor：
接下来，修改Program.cs向 Cloud Shell 编辑器中添加一个insert命令，用于将 100 名玩家插入Players您可以使用 表格插入 4 个随机得分，Scores表格中的每个播放器Players表。
首先，在“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 命令时使用的相同参数值运行 insert 命令，并在命令中添加“players”作为一种额外的“插入类型”参数。确保将 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# 客户端库在 Scores 表中填充四个随机得分以及 Players 表中每个玩家的时间戳。
通过以下 SQL 语句，将 Scores 表的 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 成为“提交时间戳”列，并且会在指定表行中自动填充 INSERT 和 UPDATE 操作的确切事务时间戳。
您还可以将自己的时间戳值插入“提交时间戳”列中，只要您插入带有过去值的时间戳即可，这是本 Codelab 将要做的。
现在，使用我们在调用 create 命令（添加“scores”）时使用的相同参数值运行 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
使用“insert type of insert”运行 insert会调用 InsertScoresAsync 方法，该方法使用以下代码段来插入随机生成的时间戳，且时间戳为过去的日期：scores
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 标签页，验证“得分”表中是否也包含数据。您应该看到表的 PlayerId、Timestamp 和 Score 列中都有数据。
太棒了！我们来更新程序，以便运行一些用于创建游戏排行榜的查询。
6. 运行排行榜查询
现在我们已经建立了数据库并将信息加载到表中，让我们使用此数据创建一个排行榜。为此，我们需要回答以下四个问题：
- 哪些球员排名“前十”？
- 今年哪些国家/地区的“十大”玩家？
- 哪些球员排名“前十”该怎么办？
- 本周哪些玩家达到“十大”？
让我们更新程序来运行能够回答这些问题的 SQL 查询。
我们将添加 query 命令，为您提供运行查询的方法，以回答问题，从而生成排行榜所需的信息。
在 Cloud Shell Editor 中修改 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，表示不会按时间戳过滤任何记录。因此，我们可以使用不带“timespan”的 query 命令值来获取“十大热门”最佳球员
我们使用在运行 create 命令时使用的相同参数值运行 query 命令，而不指定“timespan”。确保将 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 命令，通过指定等于一年中小时数的“时间范围”（即 8760）来查询年度“十大”玩家。确保将 PROJECT_ID 替换为在此 Codelab 开始时创建的项目 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 替换为在此 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
现在，我们运行 query 命令来查询每周的“十大”玩家，方法是指定“时间范围”等于一周中的小时（共 168 个）。确保将 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 的各种乐趣之后，我们需要清理操场，从而节省宝贵的资源和资金。幸运的是，此步骤很简单，只需进入 Developer Console 并删除我们在 Codelab 步骤“设置 Cloud Spanner 实例”中创建的实例即可。
8. 恭喜！
所学内容：
- 排行榜的 Google Cloud Spanner 实例、数据库和表架构
- 如何创建 .NET Core C# 控制台应用
- 如何使用 C# 客户端库创建 Spanner 数据库和表
- 如何使用 C# 客户端库将数据加载到 Spanner 数据库
- 如何查询“十大热门”使用 Spanner 提交时间戳和 C# 客户端库从数据中提取结果
后续步骤：
- 阅读 Spanner CAP 白皮书
- 了解架构设计和查询最佳实践
- 详细了解 Cloud Spanner 提交时间戳
向我们提供反馈
- 请抽空完成我们简短的调查问卷