从 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，则可能会允许部分用户访问该项目中的资源（如果您在完成后未停用这些用户）。

记下项目名称字段下显示的项目 ID。此 ID 在所有 Google Cloud 项目中都是唯一的名称（上述名称已被占用），稍后在本 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)

注意：Cloud Shell 上已预安装了 gcloud CLI 工具，该工具可帮助您创建和管理 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. 在 Cloud 控制台的主菜单中选择 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 编辑器中或使用 Linux 编辑器（例如 Vim 或 Emacs）为 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 文件输出的详细信息也位于方法：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。