从 Google Cloud 项目调用 API

1. 准备工作

此 Codelab 介绍了如何创建 Google Cloud 项目，然后从该项目调用 Google Cloud API。

前提条件

• 能够浏览 Google Cloud 控制台。

学习内容

• 如何创建 Google Cloud 项目。
• 如何设置结算账号。
• 如何设置 Cloud Shell。
• 如何启用 API。
• 如何使用 API 密钥为 API 授权。
• 如何使用服务账号授权 API。

所需条件

• 拥有一个 Google 账号，例如 Gmail 账号或 Google Workspace 账号。
• 拥有 Cloud Billing 账号或信用卡的访问权限，以用于注册免费试用计划。

2. 进行设置

本部分介绍如何创建 Google Cloud 项目、设置结算账号以及设置 Cloud Shell。

创建 Google Cloud 项目并设置结算账号

注意：如果您还没有 Gmail 账号或 Google Workspace 账号，则需要先创建一个账号。

1. 登录 Cloud 控制台，然后选择或创建项目。

警告：如果您重复使用某个项目并完成此 Codelab，但完成此 Codelab 后，如果您未关闭相关资源，则可能会允许部分用户访问该项目中的资源。

记下项目 ID，它显示在项目名称字段下。此 ID 是所有 Google Cloud 项目中的唯一名称（以上名称已被占用），此 Codelab 稍后会在此 Codelab 中将其称为 PROJECT_ID。

注意：如果您使用的是 Gmail 账号，可以将默认位置设置为无组织。如果您使用的是 Google Workspace 账号，请选择对贵组织来说合理的位置。

2. 接下来，在 Cloud 控制台中启用结算功能，以便使用 Google Cloud 资源。

虽然此 Codelab 应该不会产生太多费用，但如果有任何费用，请按照清理部分中的说明关停资源，并避免此 Codelab 以外的费用。请注意，Google Cloud 的新用户有资格获享$300 的免费试用。

设置 Cloud Shell

在此 Codelab 中，您将使用 Cloud Shell，它是在 Google Cloud 中运行的命令行环境。Cloud Shell 是一个基于 Debian 的虚拟机，其中预装了您需要的所有开发工具。它提供了一个永久性的 5GB 主目录，可极大地增强网络性能和身份验证功能。这意味着在本 Codelab 中，您只需要一个浏览器。

如需从 Cloud 控制台激活 Cloud Shell，请执行以下操作：

1. 点击 激活 Cloud Shell。

配置和连接到环境可能需要一些时间。

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

2. 生成具有凭据的账号列表：

gcloud auth list

您应该会看到以下输出：

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

注意：gcloud CLI 工具已预安装在 Cloud Shell 中，可帮助您创建和管理 Google Cloud 资源。如需了解详情，请参阅 gcloud 工具概览。

3. 如需查看项目列表，请输入以下命令。

gcloud config list project

您应该会看到以下输出：

[core]
project = <PROJECT_ID>

如果出于某种原因未设置项目，请运行此命令来设置项目。

gcloud config set project <PROJECT_ID>

PROJECT_ID 是您在设置步骤中使用的 ID。您还可以在 Cloud 控制台信息中心内找到该 ID：

默认情况下，Cloud Shell 还会设置一些环境变量，这对您日后运行命令可能会很有用。

4. 如需查看您的项目 ID，请输入以下命令。

echo $GOOGLE_CLOUD_PROJECT

您应该会看到以下输出内容：

<PROJECT_ID>

5. 最后，设置默认可用区和项目配置。

gcloud config set compute/zone us-central1-f

您可以选择各种不同的可用区。如需了解详情，请参阅区域和地区。

注意：在机器上运行 gcloud CLI 工具时，配置设置在不同会话之间保持不变。不过，在 Cloud Shell 中，您需要为每个新会话或在重新连接时配置这些设置。

3. 从项目中调用 API

此 Codelab 介绍了如何使用示例 API (Natural Language API) 查找文本中的实体（例如人物、地点和事件），以及如何大致估算该文本的情感（好感度级别）。你将学习如何

• 启用 Google Cloud API。
• 使用 API 密钥和服务账号获取 API 授权。
• 使用 curl 和客户端库调用 API。

启用 API

1. 选择 API 和服务。

2. 从屏幕顶部选择 + 启用 API 和服务。

3. 此时，您可以过滤和浏览 API，也可以通过搜索框直接转到某个 API。搜索 Natural Language，然后选择 Cloud Natural Language API。

4. 点击试用此 API。

如果未显示尝试此 API 按钮，请点击列出的任一方法以尝试该方法。

创建 API 密钥

由于您使用 curl 向 Natural Language API 发送请求，因此必须生成 API 密钥以传入请求网址。

1. 在 Cloud 控制台中，选择导航菜单 >API 和服务 >凭据。

2. 点击创建凭据，然后选择 API 密钥：

3. 复制生成的 API 密钥，然后点击关闭。

使用 API 密钥调用 API

1. 在 Cloud Shell 命令行中，导出您的 API 密钥。

export API_KEY=<YOUR_API_KEY>

将 <YOUR_API_KEY> 替换为您之前生成的密钥。

2. 在 Cloud Shell Editor 或使用 Vim 或 Emacs 等 Linux 编辑器创建 API 请求。您可以在方法：documents.analyzeEntities 中找到参数的详细信息。将输出保存在名为 request.json 的文件中：

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. 使用请求信息调用 API。

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. 重新运行该命令并将输出重定向到文件并检查结果。JSON 文件输出的详细信息也可在 Method: documents.analyzeEntities 中查看。
5. 如需更改 request.json 文件中要分析的文本，请将 content 值替换为您选择的文本。

4. 使用服务账号进行授权

服务账号通常优先于 API 密钥，因为它们可以提供身份验证和授权。您可以将服务账号视为应用的电子邮件地址。

1. 返回 API 和服务菜单。
2. 选择创建凭据，但这次选择服务账号。

3. 提供可描述其用途的服务账号名称，如“Natural Language Service Account”。系统会推荐一个 ID。您还可以添加说明。随着对服务账号的详细了解，您需要为服务账号提供项目访问权限，并授予用户访问服务账号的权限，但目前，您只需点击完成即可创建服务账号。
4. 如需创建密钥对以供服务账号使用，请点击 修改服务账号。

系统会显示您的服务账号的详细信息。

5. 复制服务账号的电子邮件地址，然后返回到 Cloud Shell。
6. 在 Cloud Shell 中，为您的服务账号创建一个密钥对，并设置一个指向该服务账号的环境变量：

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

Google Cloud 使用此环境变量查找凭据，因此无需将凭据包含在 API 调用中。

7. 现在，您可以使用以下命令调用该 API：

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

结果应该与之前相同。

许多 API 都有大量客户端库供您提取这些详细信息。如需详细了解客户端库，请参阅 Cloud 客户端库。您还可以阅读所用 API 的文档，了解其适用的客户端库。

5. 清理

对项目使用不受限制的 API 密钥是一种不良做法。如果有人可以访问该密钥，则此人可以直接使用它，而无需进一步进行身份验证。

如需删除此 API 密钥，请执行以下操作：

1. 点击 导航菜单 >API 和服务 >凭据。
2. 在 API 密钥下，选择要删除的密钥，然后点击 删除。
3. 同样，您无需担心服务账号私钥不受保护，可以在服务账号下选择要删除的服务账号，然后点击删除。

6. 恭喜

恭喜！您学习了如何创建 Google Cloud 项目以及如何在项目中调用 API。