將 BigQuery 與 C# 搭配使用

1. 總覽

BigQuery 是 Google 推出的 PB 級全代管低成本數據分析資料倉儲。由於 BigQuery 沒有可管理的基礎架構，更不需要資料庫管理員，因此免除了營運方面的工作，讓您可專心分析資料以找出有意義的結果、使用熟悉的 SQL，以及利用我們的即付即用模型。

在本程式碼研究室中，您將使用 .NET 適用的 Google Cloud 用戶端程式庫，透過 C# 查詢 BigQuery 公開資料集。

課程內容

如何使用 Cloud Shell
如何啟用 BigQuery API
如何驗證 API 要求
如何安裝 C# 適用的 Google Cloud 用戶端程式庫
如何查詢莎士比亞的作品
如何查詢 GitHub 資料集
如何調整快取和顯示統計資料

軟硬體需求

Google Cloud Platform 專案
Chrome 或 Firefox 瀏覽器
熟悉 C# 的使用方式

問卷調查

您會如何使用本教學課程？

僅閱讀

閱讀並完成練習

您對 C# 的體驗評價如何？

新手

中級

熟練

您對使用 Google Cloud Platform 服務的體驗有何評價？

新手

中級

熟練

2. 設定和需求

自修實驗室環境設定

登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
專案 ID 在所有 Google Cloud 專案中都是不重複的，而且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱，看看是否可用。完成這個步驟後就無法變更，且專案期間會維持不變。
請注意，有些 API 會使用第三個值，也就是「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。

接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高，甚至可能完全免費。如要關閉資源，避免在本教學課程結束後繼續產生費用，請刪除您建立的資源或專案。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。

啟動 Cloud Shell

雖然可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

啟用 Cloud Shell

在 Cloud 控制台，點選「啟用 Cloud Shell」圖示。

如果您是首次啟動 Cloud Shell，系統會顯示中繼畫面，說明這個指令列環境。如果出現中繼畫面，請按一下「繼續」。

佈建並連至 Cloud Shell 預計只需要幾分鐘。

這部虛擬機器已載入所有必要的開發工具，並提供永久的 5 GB 主目錄，而且可在 Google Cloud 運作，大幅提升網路效能並強化驗證功能。本程式碼研究室幾乎所有工作都可在瀏覽器上完成。

連至 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

所有 Google Cloud 專案預設都會啟用 BigQuery API。您可以在 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 的網頁版主控台預覽及執行臨時查詢。

如要查看資料的樣貌，請在 BigQuery 網頁版 UI 中開啟 GitHub 資料集：

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

如要快速預覽資料外觀，請使用「預覽」按鈕：

前往 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 姓名標示 2.0 通用授權。