GSP126

概览

Natural Language API 是一种预训练的机器学习模型，可用于分析语法、提取实体并评估文本情感。您可以从 Google 文档中调用 Natural Language API 来执行这些功能。

本实验重点介绍如何从 Google 文档调用 Natural Language API。您将使用 Natural Language API 识别 Google 文档中所选文本的情感，并根据该情感突出显示文本。

完成本实验后，您将能够选择文档中的文本，并通过菜单选项标记其情感，如下所示。

文本以红色突出显示表示负面情感，绿色表示正面情感，黄色表示中性情感。

学习内容

在本实验中，您将学习如何完成以下操作：

• 从 Google 文档调用 Natural Language API
• 在 Google 文档中添加菜单
• 识别并处理 Google 文档中的选定文本

设置和要求

点击“开始实验”按钮前的注意事项

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 Google Cloud 资源可供您使用多长时间。

此实操实验可让您在真实的云环境中开展实验活动，免受模拟或演示环境的局限。为此，我们会向您提供新的临时凭据，您可以在该实验的规定时间内通过此凭据登录和访问 Google Cloud。

为完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。

注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

• 完成实验的时间 - 请注意，实验开始后无法暂停。

注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

如何开始实验并登录 Google Cloud 控制台

1. 点击开始实验按钮。如果该实验需要付费，系统会打开一个对话框供您选择支付方式。右侧是实验设置和访问权限面板，其中包含以下内容：

   • 打开 Google Cloud 控制台按钮
   • 您在本实验中必须使用的临时凭证（用户名和密码）
   • 帮助您逐步完成该实验所需的其他信息（如果需要）

   请注意，实验计时器位于页面顶部附近，将显示剩余时间。

2. 点击打开 Google Cloud 控制台（如果您使用的是 Chrome 浏览器，请右键点击并选择在无痕式窗口中打开链接）。

   该实验会启动资源并打开另一个标签页，显示“登录”页面。

   提示：可以将这些标签页分别放在不同的窗口中，并排显示。

   注意：如果您看见选择账号对话框，请点击使用其他账号。

3. 如有必要，请复制下方的用户名，然后将其粘贴到登录对话框中。

   {{{user_0.username | "<用户名>"}}}

   您也可以在实验设置和访问权限面板中找到“用户名”。

4. 点击下一步。

5. 复制下面的密码，然后将其粘贴到欢迎对话框中。

   {{{user_0.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，然后点击该 API 以启用它，或确认该 API 已启用。

任务 2. 获取 API 密钥

生成 API 用户密钥，并将其包含在请求网址中。

1. 要创建 API 密钥，请依次点击导航菜单 > API 和服务 > 凭据。

2. 在页面顶部点击创建凭据，然后选择 API 密钥：

3. 将生成的 API 密钥复制到文本文件或 Google 文档中，以便在后续步骤中使用。点击关闭。

获得 API 密钥后，您就可以开始使用 Google 文档了。

点击“检查我的进度”，以验证是否完成了以下目标： 获取 API 密钥

任务 3. 设置 Google 文档

在调用 Natural Language API 之前，请编写一个 Apps 脚本程序，用于创建菜单，将其链接到标记文本的函数，并从用户选择中提取文本。

1. 创建新的 Google 文档。
2. 在新文档中，依次选择扩展程序 > Apps 脚本菜单项。
3. 删除脚本编辑器中的所有代码，然后粘贴以下代码。这段代码会创建一个菜单项，从当前选定文本中提取文本，并根据文本的情感突出显示文本。它尚未调用 Natural Language API。

/** * @OnlyCurrentDoc * * 上述注释指示 Apps 脚本将此附加组件的文件访问范围 * 限制为当前文档。它指定该附加组件只会 * 尝试读取或修改使用该附加组件的文档， * 而不会访问用户的所有文件。向用户显示的授权请求消息 * 将反映这一受限范围。 */ /** * 在打开文档时，在 Google Docs 界面中创建一个 * 菜单项。 * */ function onOpen() { var ui = DocumentApp.getUi(); ui.createMenu('Natural Language Tools') .addItem('Mark Sentiment', 'markSentiment') .addToUi(); } /** * 获取用户选定的文本，并根据情感进行突出显示 * 绿色表示正面情感，红色表示负面情感，黄色表示 * 中性情感。 * */ function markSentiment() { var POSITIVE_COLOR = '#00ff00'; // 情感颜色定义 var NEGATIVE_COLOR = '#ff0000'; var NEUTRAL_COLOR = '#ffff00'; var NEGATIVE_CUTOFF = -0.2; // 情感阈值 var POSITIVE_CUTOFF = 0.2; var selection = DocumentApp.getActiveDocument().getSelection(); if (selection) { var string = getSelectedText(); var sentiment = retrieveSentiment(string); // 选择合适的颜色 var color = NEUTRAL_COLOR; if (sentiment <= NEGATIVE_CUTOFF) { color = NEGATIVE_COLOR; } if (sentiment >= POSITIVE_CUTOFF) { color = POSITIVE_COLOR; } // 突出显示所选文本 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 脚本，请参阅 Google Apps 脚本参考文档。

4. 在菜单栏上，点击将项目保存到云端硬盘 ()。（脚本名称会在多个位置向最终用户显示，包括授权对话框。）
5. 返回文档。向文档中添加文本。您可以使用来自 Project Gutenberg 网站的《爱丽丝梦游仙境》示例文本（将纯文本 UTF-8 版本复制并粘贴到文档中），也可以使用任意文本。
6. 重新加载文档后，您会在 Google 文档工具栏中看到创建的新菜单 Natural Language Tools（自然语言工具）。
7. 选择文本，然后从“自然语言工具”菜单中选择标记情感选项。首次选择该选项时，系统会提示您授权脚本运行。点击确定，然后确认您的账号。
8. 允许“自然语言工具”查看和管理已安装此应用的文档。
9. 脚本获得授权后，所选文本会以黄色突出显示，因为情感分析的桩始终返回 0.0，即中性。

点击“检查我的进度”，以验证是否完成了以下目标： 设置 Google 文档

任务 4. 调用 Natural Language API

当您的程序能够从所选内容中提取文本并突出显示后，就可以调用 Natural Language API 了。所有这些操作都在 retrieveSentiment 函数的正文中完成。

注意：如需详细了解 Natural Language API，请参阅 Cloud Natural Language API 参考文档。

1. 返回 Google 文档，前往扩展程序 > Apps 脚本。
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 格式返回。解析该响应并提取 score 字段（如果存在）。返回该字段的值或 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"; // Replace with your actual API key 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 进行实体和情感分析。或者选择完全不同的课程，例如租用虚拟机来处理地震数据。
• 开始学习课程。一个课程就是一系列相关的实验，学习时按部就班地完成这些实验即可。完成课程即可赢得一枚数字徽章，以表彰您取得的成就。您可以公开展示徽章，还可以在您的在线简历或社交媒体账号中加入指向徽章的链接。请参阅 Google Skills 目录，查看所有可学习的课程。

Google Cloud 培训和认证

…可帮助您充分利用 Google Cloud 技术。我们的课程会讲解各项技能与最佳实践，可帮助您迅速上手使用并继续学习更深入的知识。我们提供从基础到高级的全方位培训，并有点播、直播和虚拟三种方式选择，让您可以按照自己的日程安排学习时间。各项认证可以帮助您核实并证明您在 Google Cloud 技术方面的技能与专业知识。

上次更新手册的时间：2025 年 3 月 21 日

上次测试实验的时间：2025 年 3 月 21 日

版权所有 2026 Google LLC 保留所有权利。Google 和 Google 徽标是 Google LLC 的商标。其他所有公司名和产品名可能是其各自相关公司的商标。