使用采用 C# 的 BigQuery

使用采用 C# 的 BigQuery

关于此 Codelab

subject上次更新时间:6月 26, 2023
account_circleMete Atamel 编写

1. 概览

BigQuery 是 Google 推出的全托管式低成本分析数据仓库,可支持 PB 级数据规模。BigQuery 无需运维:没有需要管理的基础架构,也无需指派数据库管理员,因此您可以专注于分析数据,使用熟悉的 SQL 发掘有意义的数据洞见,并利用我们的随用随付模式。

在此 Codelab 中,您将使用 .NET 版 Google Cloud 客户端库通过 C# 查询 BigQuery 公共数据集

学习内容

  • 如何使用 Cloud Shell
  • 如何启用 BigQuery API
  • 如何对 API 请求进行身份验证
  • 如何安装适用于 C# 的 Google Cloud 客户端库
  • 如何查询莎士比亚的作品
  • 如何查询 GitHub 数据集
  • 如何调整缓存和显示统计信息

所需条件

  • 一个 Google Cloud Platform 项目
  • 一个浏览器,例如 ChromeFirefox
  • 熟悉 C# 的使用方法

调查问卷

<ph type="x-smartling-placeholder">

您将如何使用本教程?

您如何评价自己使用 C# 的体验?

您如何评价自己在使用 Google Cloud Platform 服务方面的经验水平?

2. 设置和要求

自定进度的环境设置

  1. 登录 Google Cloud 控制台,然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号,则必须创建一个

295004821bab6a87

37d264871000675d

96d86d3d5655cdbe.png

  • 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
  • 项目 ID 在所有 Google Cloud 项目中是唯一的,并且是不可变的(一经设置便无法更改)。Cloud 控制台会自动生成一个唯一字符串;通常情况下,您无需关注该字符串。在大多数 Codelab 中,您都需要引用项目 ID(通常用 PROJECT_ID 标识)。如果您不喜欢生成的 ID,可以再随机生成一个 ID。或者,您也可以尝试自己的项目 ID,看看是否可用。完成此步骤后便无法更改该 ID,并且此 ID 在项目期间会一直保留。
  • 此外,还有第三个值,即部分 API 使用的项目编号,供您参考。如需详细了解所有这三个值,请参阅文档
  1. 接下来,您需要在 Cloud 控制台中启用结算功能,以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用(如果有的话)。若要关闭资源以避免产生超出本教程范围的结算费用,您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作,但在此 Codelab 中,您将使用 Google Cloud Shell,这是一个在云端运行的命令行环境。

激活 Cloud Shell

  1. 在 Cloud Console 中,点击激活 Cloud Shelld1264ca30785e435.png

cb81e7c8e34bc8d.png

如果这是您第一次启动 Cloud Shell,系统会显示一个中间屏幕,说明它是什么。如果您看到中间屏幕,请点击继续

d95252b003979716.png

预配和连接到 Cloud Shell 只需花几分钟时间。

7833d5e1c5d18f54

这个虚拟机装有所需的所有开发工具。它提供了一个持久的 5 GB 主目录,并在 Google Cloud 中运行,大大增强了网络性能和身份验证功能。您在此 Codelab 中的大部分(即使不是全部)工作都可以通过浏览器完成。

在连接到 Cloud Shell 后,您应该会看到自己已通过身份验证,并且相关项目已设为您的项目 ID。

  1. 在 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`
  1. 在 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 的右上角打开代码编辑器:

fd3fc1303e63572.png

找到 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 数据集:

https://console.cloud.google.com/bigquery?p=bigquery-public-data&amp;d=github_repos&amp;t=commits&amp;page=table

使用“预览”按钮快速预览数据:

f706bfe3dfcbd267.png

找到 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 控制台。您应该会看到一个新数据集和一个表。如果您切换到表格的“预览”标签页,就可以看到实际数据:

7d9f7c493acbbf9a.png

9. 恭喜!

您已了解如何通过 C# 使用 BigQuery!

清理

为避免系统因本快速入门中使用的资源向您的 Google Cloud Platform 账号收取费用,请执行以下操作:

  • 前往 Cloud Platform Console
  • 选择要关停的项目,然后点击“删除”顶部:这会安排删除项目。

了解详情

许可

此作品已获得 Creative Commons Attribution 2.0 通用许可授权。