关于此 Codelab
1. 概览
BigQuery 是 Google 推出的全托管式低成本分析数据仓库,可支持 PB 级数据规模。BigQuery 无需运维:没有需要管理的基础架构,也无需指派数据库管理员,因此您可以专注于分析数据,使用熟悉的 SQL 发掘有意义的数据洞见,并利用我们的随用随付模式。
在此 Codelab 中,您将使用 .NET 版 Google Cloud 客户端库通过 C# 查询 BigQuery 公共数据集。
学习内容
- 如何使用 Cloud Shell
- 如何启用 BigQuery API
- 如何对 API 请求进行身份验证
- 如何安装适用于 C# 的 Google Cloud 客户端库
- 如何查询莎士比亚的作品
- 如何查询 GitHub 数据集
- 如何调整缓存和显示统计信息
所需条件
调查问卷
您将如何使用本教程?
您如何评价自己使用 C# 的体验?
您如何评价自己在使用 Google Cloud Platform 服务方面的经验水平?
2. 设置和要求
自定进度的环境设置
- 登录 Google Cloud 控制台,然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号,则必须创建一个。
- 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
- 项目 ID 在所有 Google Cloud 项目中是唯一的,并且是不可变的(一经设置便无法更改)。Cloud 控制台会自动生成一个唯一字符串;通常情况下,您无需关注该字符串。在大多数 Codelab 中,您都需要引用项目 ID(通常用
PROJECT_ID
标识)。如果您不喜欢生成的 ID,可以再随机生成一个 ID。或者,您也可以尝试自己的项目 ID,看看是否可用。完成此步骤后便无法更改该 ID,并且此 ID 在项目期间会一直保留。 - 此外,还有第三个值,即部分 API 使用的项目编号,供您参考。如需详细了解所有这三个值,请参阅文档。
- 接下来,您需要在 Cloud 控制台中启用结算功能,以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用(如果有的话)。若要关闭资源以避免产生超出本教程范围的结算费用,您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。
启动 Cloud Shell
虽然可以通过笔记本电脑对 Google Cloud 进行远程操作,但在此 Codelab 中,您将使用 Google Cloud Shell,这是一个在云端运行的命令行环境。
激活 Cloud Shell
- 在 Cloud Console 中,点击激活 Cloud Shell
。
如果这是您第一次启动 Cloud Shell,系统会显示一个中间屏幕,说明它是什么。如果您看到中间屏幕,请点击继续。
预配和连接到 Cloud Shell 只需花几分钟时间。
这个虚拟机装有所需的所有开发工具。它提供了一个持久的 5 GB 主目录,并在 Google Cloud 中运行,大大增强了网络性能和身份验证功能。您在此 Codelab 中的大部分(即使不是全部)工作都可以通过浏览器完成。
在连接到 Cloud Shell 后,您应该会看到自己已通过身份验证,并且相关项目已设为您的项目 ID。
- 在 Cloud Shell 中运行以下命令以确认您已通过身份验证:
gcloud auth list
命令输出
Credentialed Accounts ACTIVE ACCOUNT * <my_account>@<my_domain.com> To set the active account, run: $ gcloud config set account `ACCOUNT`
- 在 Cloud Shell 中运行以下命令,以确认 gcloud 命令了解您的项目:
gcloud config list project
命令输出
[core] project = <PROJECT_ID>
如果不是上述结果,您可以使用以下命令进行设置:
gcloud config set project <PROJECT_ID>
命令输出
Updated property [core/project].
3. 启用 BigQuery API
默认情况下,BigQuery API 应在所有 Google Cloud 项目中启用。您可以在 Cloud Shell 中使用以下命令检查是否属实:BigQuery 应该会列出:
gcloud services list
您应该会看到 BigQuery 列出:
NAME TITLE
bigquery-json.googleapis.com BigQuery API
...
如果 BigQuery API 未启用,您可以在 Cloud Shell 中使用以下命令启用它:
gcloud services enable bigquery-json.googleapis.com
4. 安装适用于 C# 的 BigQuery 客户端库
首先,创建一个简单的 C# 控制台应用,用于运行 BigQuery API 示例。
dotnet new console -n BigQueryDemo
您应该会看到该应用已创建且依赖项已解析:
The template "Console Application" was created successfully.
Processing post-creation actions...
...
Restore succeeded.
接下来,前往 BigQueryDemo
文件夹:
cd BigQueryDemo
并将 Google.Cloud.BigQuery.V2
NuGet 软件包添加到项目中:
dotnet add package Google.Cloud.BigQuery.V2
info : Adding PackageReference for package 'Google.Cloud.BigQuery.V2' into project '/home/atameldev/BigQueryDemo/BigQueryDemo.csproj'.
log : Restoring packages for /home/atameldev/BigQueryDemo/BigQueryDemo.csproj...
...
info : PackageReference for package 'Google.Cloud.BigQuery.V2' version '1.2.0' added to file '/home/atameldev/BigQueryDemo/BigQueryDemo.csproj'.
现在,您可以使用 BigQuery API 了!
5. 查询莎士比亚的作品
公共数据集是存储在 BigQuery 中且可供公众使用的任何数据集。还有许多其他公共数据集可供查询,其中一些也由 Google 托管,但更多则是由第三方托管。您可以在公共数据集页面上了解详情。
除公共数据集外,BigQuery 还提供了有限数量的示例表供您查询。这些表包含在 bigquery-public-data:samples dataset
中。其中一个表名为 shakespeare.
,它包含莎士比亚作品的字词索引,提供每个字词在每个语料库中出现的次数。
在此步骤中,您将查询 Shakespeare 表。
首先,从 Cloud Shell 的右上角打开代码编辑器:
找到 BigQueryDemo
文件夹内的 Program.cs
文件,并将代码替换为以下代码。请务必将 projectId
替换为您的实际项目 ID:
using System;
using Google.Cloud.BigQuery.V2;
namespace BigQueryDemo
{
class Program
{
static void Main(string[] args)
{
var client = BigQueryClient.Create("projectId");
var table = client.GetTable("bigquery-public-data", "samples", "shakespeare");
var sql = $"SELECT corpus AS title, COUNT(word) AS unique_words FROM {table} GROUP BY title ORDER BY unique_words DESC LIMIT 10";
var results = client.ExecuteQuery(sql, parameters: null);
foreach (var row in results)
{
Console.WriteLine($"{row["title"]}: {row["unique_words"]}");
}
}
}
}
花一两分钟时间研究一下代码,看看如何查询该表。
返回 Cloud Shell,运行应用:
dotnet run
您应该会看到一个字词列表及其出现次数:
hamlet: 5318
kinghenryv: 5104
cymbeline: 4875
troilusandcressida: 4795
kinglear: 4784
kingrichardiii: 4713
2kinghenryvi: 4683
...
6. 查询 GitHub 数据集
为了进一步熟悉 BigQuery,您现在需要针对 GitHub 公共数据集发出查询。您可以在 GitHub 上找到最常见的提交消息。您还将使用 BigQuery 的 Web 控制台来预览和运行临时查询。
如需查看数据,请在 BigQuery 网页界面中打开 GitHub 数据集:
使用“预览”按钮快速预览数据:
找到 BigQueryDemo
文件夹内的 Program.cs
文件,并将代码替换为以下代码。请务必将 projectId
替换为您的实际项目 ID:
using System;
using Google.Cloud.BigQuery.V2;
namespace BigQueryDemo
{
class Program
{
static void Main(string[] args)
{
var client = BigQueryClient.Create("projectId");
var table = client.GetTable("bigquery-public-data", "github_repos", "commits");
var sql = $"SELECT subject AS subject, COUNT(*) AS num_duplicates FROM {table} GROUP BY subject ORDER BY num_duplicates DESC LIMIT 10";
var results = client.ExecuteQuery(sql, parameters: null);
foreach (var row in results)
{
Console.WriteLine($"{row["subject"]}: {row["num_duplicates"]}");
}
}
}
}
花一两分钟时间研究一下代码,看看如何查询表中最常见的提交消息。
返回 Cloud Shell,运行应用:
dotnet run
您应该会看到提交消息及其发生实例的列表:
Update README.md: 2509242
: 1971725
Initial commit: 1942149
Mirroring from Micro.blog.: 838586
update: 575188
Update data.json: 548651
Update data.js: 548339
Add files via upload: 379941
*** empty log message ***: 358528
Can't you see I'm updating the time?: 286863
7. 缓存和统计信息
初始查询完成后,BigQuery 会缓存结果。因此,后续查询所花的时间要少得多。您可以使用查询选项停用缓存。BigQuery 还会跟踪一些有关查询的统计信息,例如创建时间、结束时间、处理的总字节数。
在此步骤中,您将停用缓存,并显示有关查询的一些统计信息。
找到 BigQueryDemo
文件夹内的 Program.cs
文件,并将代码替换为以下代码。请务必将 projectId
替换为您的实际项目 ID:
using System;
using Google.Cloud.BigQuery.V2;
namespace BigQueryDemo
{
class Program
{
static void Main(string[] args)
{
var client = BigQueryClient.Create("projectId");
var table = client.GetTable("bigquery-public-data", "github_repos", "commits");
var sql = $"SELECT subject AS subject, COUNT(*) AS num_duplicates FROM {table} GROUP BY subject ORDER BY num_duplicates DESC LIMIT 10";
var queryOptions = new QueryOptions {
UseQueryCache = false
};
var results = client.ExecuteQuery(sql, parameters: null, queryOptions: queryOptions);
foreach (var row in results)
{
Console.WriteLine($"{row["subject"]}: {row["num_duplicates"]}");
}
var job = client.GetJob(results.JobReference);
var stats = job.Statistics;
Console.WriteLine("----------");
Console.WriteLine($"Creation time: {stats.CreationTime}");
Console.WriteLine($"End time: {stats.EndTime}");
Console.WriteLine($"Total bytes processed: {stats.TotalBytesProcessed}");
}
}
}
关于代码的几点注意事项。首先,通过引入查询选项并将 UseQueryCache
设置为 false 来停用缓存。其次,您从作业对象访问了有关查询的统计信息。
返回 Cloud Shell,运行应用:
dotnet run
与之前一样,您应该会看到提交消息及其发生实例的列表。此外,在末尾处应该会显示有关该查询的一些统计信息,
Update README.md: 2509242
: 1971725
Initial commit: 1942149
Mirroring from Micro.blog.: 838586
update: 575188
Update data.json: 548651
Update data.js: 548339
Add files via upload: 379941
*** empty log message ***: 358528
Can't you see I'm updating the time?: 286863
----------
Creation time: 1533052057398
End time: 1533052066961
Total bytes processed: 9944197093
8. 将数据加载到 BigQuery 中
如果您想查询自己的数据,需要先将数据加载到 BigQuery 中。BigQuery 支持从多种来源加载数据,例如 Google Cloud Storage、其他 Google 服务、可读来源。您甚至可以使用流式插入功能流式传输数据。如需了解详情,请参阅将数据加载到 BigQuery 中页面。
在此步骤中,您需要将存储在 Google Cloud Storage 中的 JSON 文件加载到 BigQuery 表中。JSON 文件位于 gs://cloud-samples-data/bigquery/us-states/us-states.json
如果您想了解 JSON 文件的内容,可以使用 gsutil
命令行工具在 Cloud Shell 中下载该文件:
gsutil cp gs://cloud-samples-data/bigquery/us-states/us-states.json .
Copying gs://cloud-samples-data/bigquery/us-states/us-states.json...
/ [1 files][ 2.0 KiB/ 2.0 KiB]
Operation completed over 1 objects/2.0 KiB.
您可以看到,该文件包含美国各州的列表,每个州都是一个 JSON 文档,并单独占一行:
less us-states.json
{"name": "Alabama", "post_abbr": "AL"}
{"name": "Alaska", "post_abbr": "AK"}
...
如需将此 JSON 文件加载到 BigQuery 中,请找到 BigQueryDemo
文件夹内的 Program.cs
文件,并将代码替换为以下代码。请务必将 projectId
替换为您的实际项目 ID:
using System;
using Google.Cloud.BigQuery.V2;
namespace BigQueryDemo
{
class Program
{
static void Main(string[] args)
{
var gcsUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
var client = BigQueryClient.Create("projectId");
var dataset = client.GetOrCreateDataset("us_states_dataset");
var schema = new TableSchemaBuilder
{
{ "name", BigQueryDbType.String },
{ "post_abbr", BigQueryDbType.String }
}.Build();
var jobOptions = new CreateLoadJobOptions
{
SourceFormat = FileFormat.NewlineDelimitedJson
};
var table = dataset.GetTableReference("us_states_table");
var loadJob = client.CreateLoadJob(gcsUri, table, schema, jobOptions);
loadJob.PollUntilCompleted();
loadJob.ThrowOnAnyError();
Console.WriteLine("Json file loaded to BigQuery");
}
}
}
花两分钟时间研究一下代码如何加载 JSON 文件以及如何在数据集下创建具有架构的表。
返回 Cloud Shell,运行应用:
dotnet run
在 BigQuery 中创建数据集和表
Json file loaded to BigQuery
如需验证数据集是否确实已创建,您可以转到 BigQuery 控制台。您应该会看到一个新数据集和一个表。如果您切换到表格的“预览”标签页,就可以看到实际数据:
9. 恭喜!
您已了解如何通过 C# 使用 BigQuery!
清理
为避免系统因本快速入门中使用的资源向您的 Google Cloud Platform 账号收取费用,请执行以下操作:
- 前往 Cloud Platform Console。
- 选择要关停的项目,然后点击“删除”顶部:这会安排删除项目。
了解详情
- Google BigQuery:https://cloud.google.com/bigquery/docs/
- Google Cloud Platform 上的 C#/.NET:https://cloud.google.com/dotnet/
- Google Cloud .NET 客户端:https://googlecloudplatform.github.io/google-cloud-dotnet/
许可
此作品已获得 Creative Commons Attribution 2.0 通用许可授权。