搭配 C# 使用 Natural Language API

1. 總覽

在本程式碼研究室中，您將著重於使用 C# 搭配 Natural Language API。您將瞭解如何執行情緒、實體和語法分析。

Google Cloud Natural Language API 為開發人員提供自然語言理解技術，包括情緒分析、實體分析和語法分析。

課程內容

• 如何使用 Cloud Shell
• 如何啟用 Natural Language API
• 如何驗證 API 要求
• 如何安裝 C# 適用的 Google Cloud 用戶端程式庫
• 如何執行情緒分析
• 如何執行實體分析
• 如何執行語法分析

軟硬體需求

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

問卷調查

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

僅閱讀 閱讀並完成練習

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

新手 中級 熟練

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

新手 中級 熟練

2. 設定和需求

自修實驗室環境設定

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

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

注意：專案 ID 在全域中是唯一的，選定後就無法再供他人使用。您是該 ID 的唯一使用者。即使專案已刪除，ID 也無法再次使用

注意：如果使用 Gmail 帳戶，可以將預設位置設為「沒有機構」。如果你使用 Google Workspace 帳戶，請選擇適合貴機構的位置。

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

啟動 Cloud Shell

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

啟用 Cloud Shell

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

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

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

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

連至 Cloud Shell 後，您應該會看到驗證已完成，專案也已設為獲派的專案 ID。

2. 在 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`

注意：gcloud 指令列工具是 Google Cloud 中功能強大的整合式指令列工具，並已預先安裝於 Cloud Shell。你會發現它支援 Tab 鍵自動完成功能。第一次執行指令時，系統可能會提示您進行驗證。詳情請參閱 gcloud 指令列工具總覽。

3. 在 Cloud Shell 中執行下列指令，確認 gcloud 指令知道您的專案：

gcloud config list project

指令輸出

[core]
project = <PROJECT_ID>

如未設定，請輸入下列指令手動設定專案：

gcloud config set project <PROJECT_ID>

指令輸出

Updated property [core/project].

注意：如果您在 Cloud Shell 以外的環境完成本教學課程，請按照「設定應用程式預設憑證」一文的說明操作。

3. 啟用 Natural Language API

您必須先啟用 API，才能開始使用 Natural Language API。您可以使用 Cloud Shell 執行下列指令來啟用 API：

gcloud services enable language.googleapis.com

注意：如果這項指令發生錯誤，請確認目前的專案 ID 與程式碼研究室專案 ID 相符。

使用下列指令找出 Cloud Shell 目前使用的專案 ID：

gcloud info | grep "project"

如果專案 ID 不正確，請使用下列指令來使用正確的專案 ID：

gcloud config set project <PROJECT_ID>

將 <PROJECT_ID> 替換為正確的專案 ID。

4. 安裝 C# 適用的 Google Cloud Natural Language API 用戶端程式庫

首先，請建立簡單的 C# 控制台應用程式，用來執行 Natural Language API 範例：

dotnet new console -n NaturalLanguageApiDemo

您應該會看到建立的應用程式和已解決的依附元件：

The template "Console Application" was created successfully.
Processing post-creation actions...
...
Restore succeeded.

接著前往 NaturalLanguageApiDemo 資料夾：

cd NaturalLanguageApiDemo/

並將 Google.Cloud.Language.V1 NuGet 套件新增至專案：

dotnet add package Google.Cloud.Language.V1

info : Adding PackageReference for package 'Google.Cloud.Language.V1' into project '/home/atameldev/NaturalLanguageApiDemo/NaturalLanguageApiDemo.csproj'.
log  : Restoring packages for /home/atameldev/NaturalLanguageApiDemo/NaturalLanguageApiDemo.csproj...
...
info : PackageReference for package 'Google.Cloud.Language.V1' version '1.1.0' added to file '/home/atameldev/NaturalLanguageApiDemo/NaturalLanguageApiDemo.csproj'.

您現在可以使用 Natural Language API 了！

5. 情緒分析

在本節中，您將使用 Natural Language API 對字串執行情緒分析，並找出分數和強度。

情緒的「分數」範圍介於 -1.0 (負面) 和 1.0 (正面) 之間，可反映指定資訊的整體情緒。

情緒的強度範圍介於 0.0 到 +無限大之間，表示指定資訊的整體情緒強度。提供的資訊越多，量值就越高。

從 Cloud Shell 右上方開啟程式碼編輯器：

前往 NaturalLanguageApiDemo 資料夾中的 Program.cs 檔案，並將程式碼替換成以下程式碼：

using System;
using Google.Cloud.Language.V1;

namespace NaturalLanguageApiDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var text = "Yukihiro Matsumoto is great!";
            var client = LanguageServiceClient.Create();
            var response = client.AnalyzeSentiment(Document.FromPlainText(text));
            var sentiment = response.DocumentSentiment;
            Console.WriteLine($"Score: {sentiment.Score}");
            Console.WriteLine($"Magnitude: {sentiment.Magnitude}");
        }
    }
}

請花一兩分鐘研究程式碼，瞭解如何使用程式碼片段對字串「Yukihiro Matsumoto is great!」執行情緒分析。

回到 Cloud Shell，執行應用程式：

dotnet run

您應該會看到以下的輸出內容：

Score: 0.9
Magnitude: 0.9

注意：如果這個 C# 程式碼無法運作，請檢查您在「驗證 API 要求」步驟中執行的操作說明。

使用下列指令驗證 GOOGLE_APPLICATION_CREDENTIALS 環境變數的值：

echo GOOGLE_APPLICATION_CREDENTIALS

應該會輸出值 "~/key.json".

如果有的話，請使用下列指令，確認服務帳戶已建立並位於 "~/key.json"：

cat "~/key.json"

您應該會看到類似下列內容：

{

"type": "service_account",

"project_id": "PROJECT_ID",

"private_key_id": "ff31939192529e07f42e4535fb20bb029def1276",

"Private_key":...

如果沒有，請返回「驗證 API 要求」步驟。

摘要

在本步驟中，您已對文字字串執行情緒分析，並列印分數和幅度。進一步瞭解情緒分析。

6. 實體分析

實體分析會搜尋專有名詞 (例如公眾人物、地標等)，檢查指定資訊中的實體，並傳回這些實體的相關資訊。

如要執行實體分析，請前往 NaturalLanguageApiDemo 資料夾中的 Program.cs 檔案，然後將程式碼替換為下列程式碼：

using System;
using Google.Cloud.Language.V1;

namespace NaturalLanguageApiDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var text = "Yukihiro Matsumoto is great!";
            var client = LanguageServiceClient.Create();
            var response = client.AnalyzeEntitySentiment(Document.FromPlainText(text));

            foreach (var entity in response.Entities)
            {
                Console.WriteLine($"Entity: \"{entity.Name}\" ({entity.Type})");
                if (entity.Metadata.ContainsKey("wikipedia_url"))
                {
                    Console.WriteLine($"URL: {entity.Metadata["wikipedia_url"]}");
                }
            }
        }
    }
}

請花一兩分鐘研究程式碼，瞭解如何使用程式碼片段對「Yukihiro Matsumoto is great!」字串執行實體分析。

回到 Cloud Shell，執行應用程式：

dotnet run

您應該會看到以下的輸出內容：

Entity: "Yukihiro Matsumoto" (Person)
URL: https://en.wikipedia.org/wiki/Yukihiro_Matsumoto

摘要

在這個步驟中，您對一串文字執行了實體分析，並列印出實體。進一步瞭解實體分析。

7. 語法分析

語法分析會擷取語言資訊，將指定的文字內容拆解為各段語句與符記 (通稱斷詞) 並提供有關這些符記的進一步分析。

這個範例會輸出句子和符記的數量，並提供每個符記的詞性。

如要執行語法分析，請前往 NaturalLanguageApiDemo 資料夾中的 Program.cs 檔案，並將程式碼替換成以下程式碼：

using System;
using Google.Cloud.Language.V1;
using static Google.Cloud.Language.V1.AnnotateTextRequest.Types;

namespace NaturalLanguageApiDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var text = "Yukihiro Matsumoto is great!";
            var client = LanguageServiceClient.Create();
            var response = client.AnnotateText(Document.FromPlainText(text), 
                new Features { ExtractSyntax = true });

            var sentences = response.Sentences;
            var tokens = response.Tokens;

            Console.WriteLine($"Sentences: {sentences.Count}");
            Console.WriteLine($"Tokens: {tokens.Count}");

            foreach (var token in tokens)
            {
                Console.WriteLine($"{token.PartOfSpeech.Tag} {token.Text.Content}");
            }
        }
    }
}

請花一兩分鐘研究程式碼，瞭解如何使用程式碼片段對字串「Yukihiro Matsumoto is great!」執行語法分析。

回到 Cloud Shell，執行應用程式：

dotnet run

您應該會看到以下的輸出內容：

Sentences: 1
Tokens: 5
Noun Yukihiro
Noun Matsumoto
Verb is
Adj great
Punct !

下方顯示視覺解讀結果。

注意：您可以使用 Natural Language 示範 (網址：https://cloud.google.com/natural-language/) 自行建立剖析樹狀結構。

摘要

在本步驟中，您已對簡單的文字字串執行語法分析，並印出句子數、符記數，以及每個符記的語言資訊。進一步瞭解語法分析。

8. 恭喜！

您已學會如何使用 C# 語言的 Natural Language API，對資訊執行各種分析！

清除所用資源

如何避免系統向您的 Google Cloud Platform 帳戶收取您在本快速入門導覽課程中所用資源的相關費用：

• 前往 Cloud Platform Console。
• 選取要關閉的專案，然後按一下頂端的「刪除」，系統就會排定刪除專案的時間。

瞭解詳情

• Google Cloud Natural Language API：https://cloud.google.com/natural-language/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 通用授權。