GSP126

總覽

Natural Language API 是預先訓練的機器學習模型，可分析語法、擷取實體，以及評估文字情緒。您可以透過 Google 文件呼叫 Natural Language API，執行上述所有功能。

本實驗室的重點，是透過 Google 文件呼叫 Natural Language API。您將使用 Natural Language API，辨識 Google 文件中選定文字的情緒，並根據該情緒標示文字。

完成本實驗室後，您將能選取文件中的文字，並使用選單選項標記其情緒，如下所示。

負面情緒的文字標上紅色，正面情緒的文字標上綠色，中性情緒的文字則標上黃色。

課程內容

本實驗室的內容包括：

• 透過 Google 文件呼叫 Natural Language API
• 在 Google 文件新增選單
• 在 Google 文件辨識並處理選取的文字

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

工作 1：啟用 Natural Language API

開始前，請先確認已啟用 Natural Language API。

1. 前往 Google Cloud 控制台，依序點選「導覽選單」>「API 和服務」>「程式庫」。

2. 搜尋 Cloud Natural Language API，然後點按來啟用或確認啟用。

工作 2：取得 API 金鑰

生成 API 使用者金鑰，並在要求網址中傳遞。

1. 如要建立 API 金鑰，請依序點選「導覽選單」>「API 和服務」>「憑證」。

2. 按一下頂端的「建立憑證」，然後選取「API 金鑰」：

3. 將 API 金鑰複製到文字檔或 Google 文件，供後續步驟使用。點選「關閉」。

取得 API 金鑰後，即可前往 Google 文件。

點選「Check my progress」，確認目標已達成。 取得 API 金鑰

工作 3：設定 Google 文件

呼叫 Natural Language API 前，請先編寫 Apps Script 程式，建立選單、將選單連結至標記文字的函式，並從使用者選取的內容中擷取文字。

1. 建立新的 Google 文件。
2. 在新文件中，依序選取選單項目「擴充功能」>「Apps Script」。
3. 刪除指令碼編輯器中的所有程式碼，然後貼上下列程式碼。這段程式碼會建立選單項目、從目前選取的文字擷取內容，並根據情緒進行標示。目前還不會呼叫 Natural Language API。

/** * @OnlyCurrentDoc * *上述註解會指示 Apps Script 限制這個外掛程式的 *檔案存取範圍，並指出這個外掛程式只會 *嘗試讀取或修改外掛程式所在檔案的內容， *而非使用者的所有檔案。向使用者顯示的授權要求訊息 *會反映這個有限的範圍。 */ /** *在文件開啟時，於 Google 文件 UI *建立選單項目。 * */ function onOpen() { var ui = DocumentApp.getUi(); ui.createMenu('Natural Language Tools') .addItem('Mark Sentiment', 'markSentiment') .addToUi(); } /** *取得使用者選取的文字，並根據情緒標示： *正面情緒標為綠色、負面情緒為紅色、 *中性情緒為黃色。 * */ function markSentiment() { var POSITIVE_COLOR = '#00ff00'; // Colors for sentiments var NEGATIVE_COLOR = '#ff0000'; var NEUTRAL_COLOR = '#ffff00'; var NEGATIVE_CUTOFF = -0.2; // Thresholds for sentiments var POSITIVE_CUTOFF = 0.2; var selection = DocumentApp.getActiveDocument().getSelection(); if (selection) { var string = getSelectedText(); var sentiment = retrieveSentiment(string); // Select the appropriate color var color = NEUTRAL_COLOR; if (sentiment <= NEGATIVE_CUTOFF) { color = NEGATIVE_COLOR; } if (sentiment >= POSITIVE_CUTOFF) { color = POSITIVE_COLOR; } // Highlight the text var elements = selection.getSelectedElements(); for (var i = 0; i < elements.length; i++) { if (elements[i].isPartial()) { var element = elements[i].getElement().editAsText(); var startIndex = elements[i].getStartOffset(); var endIndex = elements[i].getEndOffsetInclusive(); element.setBackgroundColor(startIndex, endIndex, color); } else { var element = elements[i].getElement().editAsText(); foundText = elements[i].getElement().editAsText(); foundText.setBackgroundColor(color); } } } } /** *傳回字串包含所選文字內容。 *如未選取任何文字，則傳回空白字串。 */ function getSelectedText() { var selection = DocumentApp.getActiveDocument().getSelection(); var string = ""; if (selection) { var elements = selection.getSelectedElements(); for (var i = 0; i < elements.length; i++) { if (elements[i].isPartial()) { var element = elements[i].getElement().asText(); var startIndex = elements[i].getStartOffset(); var endIndex = elements[i].getEndOffsetInclusive() + 1; var text = element.getText().substring(startIndex, endIndex); string = string + text; } else { var element = elements[i].getElement(); //只翻譯可做為文字編輯的元素； //跳過圖片和其他非文字元素。if (element.editAsText) { string = string + element.asText().getText(); } } } } return string; } /**傳入字串後，將呼叫 Natural Language API 並擷取 *該字串的情緒。情緒是介於 * -1 到 1 之間的實數，其中 -1 代表極度負面的情緒， *1 代表極度正面的情緒。 */ function retrieveSentiment (line) { // TODO: Call the Natural Language API with the line given // and return the sentiment value. return 0.0; } 注意：如要進一步瞭解 Apps Script，請參閱 Google Apps Script 參考資料。

4. 在選單列，按一下「將專案儲存至雲端硬碟」圖示 (指令碼名稱會在授權對話方塊等位置向使用者顯示。)
5. 返回您的文件，並在此新增文字。您可以使用古騰堡計劃網站上的《愛麗絲夢遊仙境》範例 (將 Plain Text UTF-8 版本複製並貼到文件中)，或任何您想要的文字。
6. 重新載入文件，即可在 Google 文件工具列中，看到您建立的新選單「Natural Language Tools」。
7. 選取文字，然後從「Natural Language Tools」選單中，選取「Mark Sentiment」。首次選取這個選項時，系統會提示您授權執行指令碼。點選「確定」，然後確認帳戶。
8. 允許 Natural Language Tools 查看及管理已安裝這個應用程式的文件。
9. 授權指令碼後，選取的文字會標為黃色，因為情緒分析的虛設常式一律會傳回 0.0 (中性)。

點選「Check my progress」，確認目標已達成。 設定 Google 文件

工作 4：呼叫 Natural Language API

程式能從選取範圍擷取文字並標記後，就可以呼叫 Natural Language API 了。所有作業都會在 retrieveSentiment 函式主體中完成。

注意：如要進一步瞭解 Natural Language API，請參閱 Cloud Natural Language API 參考資料。

1. 返回 Google 文件的「擴充功能」>「Apps Script」。
2. 在 retrieveSentiment 函式中，將「your key here」替換成 Google Cloud 控制台的實際 API 金鑰。

var apiKey = "your key here"; // 替換為您的實際 API 金鑰

3. 建立變數來儲存 Natural Language API 的網址，並在網址後方附加 API 金鑰 (請勿修改這一行)：

var apiEndpoint = "https://language.googleapis.com/v1/documents:analyzeSentiment?key=" + apiKey;

4. 從傳入函式的行建立結構，其中包含該行的文字、類型和語言 (目前僅支援英文)。

var docDetails = { language: 'en-us', type: 'PLAIN_TEXT', content: line };

5. 加入編碼類型，根據文件詳細資料建構整個資料酬載：

var nlData = { document: docDetails, encodingType: 'UTF8' };

6. 建立的結構須包含酬載和必要標頭資訊：

var nlOptions = { method : 'post', contentType: 'application/json', payload : JSON.stringify(nlData) };

7. 呼叫並儲存回應：

var response = UrlFetchApp.fetch(apiEndpoint, nlOptions);

8. 回應會以 JSON 格式傳回，請剖析並擷取分數欄位 (如有)。如果成功擷取到，就傳回該欄位的值，否則就傳回 0.0。

var data = JSON.parse(response); var sentiment = 0.0; // 確保所有部分都包含在傳回的值中 if (data && data.documentSentiment && data.documentSentiment.score){ sentiment = data.documentSentiment.score; } return sentiment;

擷取情緒的完整程式碼如下：

function retrieveSentiment (line) { var apiKey = "your key here"; // 替換為您的實際 API 金鑰 var apiEndpoint = "https://language.googleapis.com/v1/documents:analyzeSentiment?key=" + apiKey; // 建立結構，須包含文字、語言、類型 // 和編碼 var docDetails = { language: 'en-us', type: 'PLAIN_TEXT', content: line }; var nlData = { document: docDetails, encodingType: 'UTF8' }; // 將所有選項和資料包裝起來以供呼叫 var nlOptions = { method : 'post', contentType: 'application/json', payload : JSON.stringify(nlData) }; // 呼叫 var response = UrlFetchApp.fetch(apiEndpoint, nlOptions); var data = JSON.parse(response); var sentiment = 0.0; // 確保所有部分都包含在傳回的值中 if (data && data.documentSentiment && data.documentSentiment.score){ sentiment = data.documentSentiment.score; } return sentiment; }

9. 儲存指令碼、重新載入文件，然後測試完整程式。您可能需要重新授權憑證，才能啟用新功能。選取文件的不同部分，查看各部分的情緒可能有哪些差異。

10. (選用) 輸入自訂文字並分析。例如您可以輸入並分析「I'm mad」以及「I'm happy」。實驗看看 Natural Language API 如何解讀不同詞組，例如分析「I'm happy. I'm happy. I'm sad.」，如果再加入一個「I'm sad.」，會發生什麼事？

恭喜！

恭喜！您建立了 Google 文件，並呼叫了 Natural Language API 來分析文件中選定部分的情緒。

後續步驟/瞭解詳情

歡迎繼續學習 Google Cloud 相關知識，以下是給您的建議：

• 參加更多實驗室。如要進一步瞭解 Natural Language API，請完成「使用 Natural Language API 進行實體和情緒分析」等實驗室，或是參加完全不同的課程，例如「租借 VM 來處理地震資料」。
• 參加任務。「任務」是指一系列相關的實驗室課程，這些課程構成完整的學習路徑。完成任務後即可獲得數位徽章，以表彰您的成就。徽章可公開展示，也能連結至自己的線上履歷或社群媒體帳戶。請參閱 Google Cloud 技能重點加強目錄查看所有可參加的任務。

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2025 年 3 月 21 日

實驗室上次測試日期：2025 年 3 月 21 日

Copyright 2025 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。