GSP294

概览

API（应用编程接口）是一种软件程序，可让开发者访问计算资源和数据。许多不同领域的公司都提供向公众开放的 API，以便开发者将专用工具、服务或库集成到自己的应用和代码库中。

本实验将回顾 API 的架构和基本功能。此外，您还可以进行实操练习，在 Google Cloud Shell 中配置和运行 Cloud Storage API 方法。通过完成本实验，您可以了解 API 通信、架构和身份验证的关键原则。您还将获得 API 实践经验，这些经验可以应用到未来的实验或项目中。

API - 什么是 API，为什么要使用 API

访问数据和计算资源的能力可以大大提高开发者的效率。使用 API 比从头构建每个程序、方法或数据集要容易得多。API 基于抽象原则构建，您无需了解 API 的内部运行方式或复杂机制，即可在自己的环境中使用它。

API 是为开发者构建的，通常不提供图形界面 (GUI)。不过，此标准也有例外情况。Google 发布了一款名为 APIs Explorer 的新工具，让您能够对各种 Google API 进行交互式探索（如果您有兴趣了解更多信息，请务必在之后查看 APIs Explorer：Qwik Start 实验）。

Cloud API

Google 提供了可应用于许多不同领域和行业的 API。API 通常用于 Web 开发、机器学习、数据科学和系统管理工作流。不过，这也只是众多应用场景中的少数几个。例如，通过探索 AnyAPI，您会发现有很多可用的 API。

在为一项实验预配新的 Google Cloud 项目时，Qwiklabs 会在后台启用大多数 API，以便您能立即处理实验中的任务。如果您在 Qwiklabs 外部创建自己的项目，则必须自行启用某些 API。

随着您对 Google Cloud 的使用越来越熟练，您会在工作流中使用更多 API。经验丰富的用户几乎完全在本地环境中集成和使用 Cloud API，很少使用 Cloud 控制台来运行工具和服务。我们提供了数十个实操实验，让您练习使用不同语言的各种 Google API。

在本实验中，您将探索 API 库，了解有哪些 Google API 可用。

目标

在本实验中，您将学习以下内容：

• Google API
• API 架构
• HTTP 协议和方法
• 端点
• REST（表述性状态转移）和 RESTful API
• JSON（JavaScript 对象表示法）
• API 身份验证服务

前提条件

本实验是入门级实验。我们假定您几乎没有 API 相关知识，也没有使用 Google API 的经验。建议先熟悉一下 shell 环境和命令行界面工具，但不作强制要求。建议您熟悉 Cloud 控制台和 Cloud Storage，因此在尝试本实验之前，请至少完成以下实验：

• Qwiklabs 和 Google Cloud 导览
• Cloud Storage：Qwik Start - Cloud 控制台

准备就绪后，请向下滚动页面，并按下方步骤来设置实验室环境。

设置和要求

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

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 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 产品和服务，请点击导航菜单，或在搜索字段中输入服务或产品的名称。

激活 Cloud Shell

Cloud Shell 是一种装有开发者工具的虚拟机。它提供了一个永久性的 5GB 主目录，并且在 Google Cloud 上运行。Cloud Shell 提供可用于访问您的 Google Cloud 资源的命令行工具。

1. 点击 Google Cloud 控制台顶部的激活 Cloud Shell 。

2. 在弹出的窗口中执行以下操作：

   • 继续完成 Cloud Shell 信息窗口中的设置。
   • 授权 Cloud Shell 使用您的凭据进行 Google Cloud API 调用。

如果您连接成功，即表示您已通过身份验证，且项目 ID 会被设为您的 Project_ID 。输出内容中有一行说明了此会话的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的命令行工具。它已预先安装在 Cloud Shell 上，且支持 Tab 自动补全功能。

3. （可选）您可以通过此命令列出活跃账号名称：

gcloud auth list

4. 点击授权。

输出：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. （可选）您可以通过此命令列出项目 ID：

gcloud config list project

输出：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需查看在 Google Cloud 中使用 gcloud 的完整文档，请参阅 gcloud CLI 概览指南。

为项目设置区域

运行以下命令，为项目设置区域：

gcloud config set compute/region {{{project_0.default_region | Region}}}

API 的工作原理

API 架构

API（应用编程接口）是一组让程序能够相互通信的方法。为了有效通信，程序必须遵循明确的协议，该协议规定了数据的传输和解释方式。互联网是 API 在程序之间传输请求和响应的标准通信渠道。基于 Web 的 API 使用客户端-服务器模型作为底层架构来进行信息交换。客户端是请求某些计算资源或数据的计算设备，而服务器存储着数据和/或计算资源，并且会解释和满足客户端的请求。

HTTP 协议和方法

由于 API 使用 Web 作为通信渠道，因此许多 API 都遵循 HTTP 协议，该协议规定了客户端和服务器之间通过互联网交换数据的规则和方法。使用 HTTP 协议的 API 使用 HTTP 请求方法（也称为“HTTP 动词”）将客户端请求传输到服务器。最常用的 HTTP 请求方法是 GET、POST、PUT 和 DELETE。GET 由客户端用于从服务器提取数据，PUT 用于替换现有数据或创建数据（如果数据不存在），POST 主要用于创建新资源，而 DELETE 用于从服务器上移除客户端指定的数据或资源。

端点

API 使用 HTTP 方法与服务器上托管的数据或计算服务进行交互。如果无法以一致的方式访问具体资源，这些方法就毫无用处。API 利用称为端点的通信渠道，使客户端能够轻松、顺畅地访问所需的资源。端点是用来访问服务器上托管的数据或计算资源的接入点，以 HTTP URI 的形式存在。端点会添加到 API 的基础网址中，以创建指向特定资源或资源容器的路径。此外，还可以向端点添加查询字符串，以传入完成 API 请求可能需要的变量。

REST 和 RESTful API

利用 HTTP 协议、请求方法和端点的 API 称为 RESTful API。RESTful API 位于服务器上，充当客户端请求的实现者。此模型定义了一个端点（作用类似名词）框架，这些端点是 HTTP 方法（作用类似动词）的操作对象，而 API 使用此框架来满足请求。总而言之，RESTful API 使用客户端-服务器模型，遵循 HTTP 协议，使用 HTTP 请求方法，并使用端点来访问特定资源。

检验您的掌握情况

请回答以下选择题，以强化您对我们到目前为止所讲解的各个概念的理解。

任务 1. 使用 API 库

在本部分中，您将探索 API 库并启用一个 API。API 库是所有 Google API 的集中位置。您可以使用 API 库在各个项目中启用、停用和管理 API。

1. 打开导航菜单并依次选择 API 和服务 > 库。

API 库可让您快速访问 200 多种 Google API，并提供相关文档和配置选项。尽管 API 库位于控制台中，但请注意，您可以通过该库访问所有 Google API，而不仅仅是那些围绕 Google Cloud 打造的 API。这凸显了一个重要主题：API 是所有 Google 服务的基础，而 Cloud API 并非都属于 Google Cloud 类别。

现在，我们来动手练习一下，启用 API 库中的一个 API。假设您是某健身网站的移动应用开发者，想要使用 Google Fitness API 构建应用。

2. 在搜索 API 和服务 (Search for APIs and Service) 搜索栏中，输入 Fitness API 并按 Enter 键。
3. 在结果列表中点击 Fitness API。然后，点击启用。

Fitness API 页面随即打开，API 状态为已启用。

API 库提供了指向教程和文档、服务条款，以及 API Explorer 支持的互动方法的链接。如需查看指标和使用情况信息，请使用 API 和服务信息中心。在此页面中，您可以查看和请求配额、控制对资源和数据的访问权限，以及查看指标。

4. 如需查看其中某项功能的实际效果，请选择配额和系统限制标签页。

5. 这会显示此 API 每天和每分钟允许的查询次数。

您现在已预配了一个非 Cloud API。在接下来的部分中，您将了解 API 的架构和基本功能。然后，您将练习使用 Cloud Storage API。

检验您的掌握情况

请回答以下选择题，以强化您对我们到目前为止所讲解的各个概念的理解。

任务 2. 在 Cloud 控制台中创建 JSON 文件

为了运用所学知识，请在 Cloud Shell 中调用 Cloud Storage REST/JSON API 来创建存储桶并上传内容。

1. 在新标签页中打开 Google Cloud Storage JSON API，确保已启用 Cloud Storage API。请注意，此 API 已启用。

2. 在 Cloud Shell 中，运行以下命令来创建并编辑名为 values.json 的文件：

nano values.json

3. 在 nano 文本编辑器中，复制并粘贴以下内容。由于存储桶必须具有唯一的存储桶名称，因此在存储桶名称中使用了项目 ID：

{ "name": "{{{project_0.project_id | Project_ID}}}-bucket", "location": "us", "storageClass": "multi_regional" } 注意：由于项目 ID 是全局唯一的，因此您可以使用项目 ID 作为存储桶名称。

4. 完成后，依次按 CTRL+X、Y 和 ENTER 键退出 nano 文本编辑器。

您刚刚创建了一个 JSON 文件，其中包含一个具有三个键值对的对象：name、location 和 storageClass。这些值正是您使用 gsutil 命令行工具或在控制台中创建存储桶时所需要的值。

在使用 Cloud Storage REST/JSON API 创建存储桶之前，您需要设置适当的身份验证和授权政策。

任务 3. 对 Cloud Storage JSON/REST API 进行身份验证和授权

身份验证和授权

身份验证和授权这两个词经常被混用，但它们并不相同。

• 身份验证过程用于确定客户端的身份。
• 授权是确定经过身份验证的客户端对一组资源具有哪些权限的过程。

身份验证识别您的身份，而授权决定您可以执行的操作。

Google API 使用三种类型的身份验证/授权服务。它们分别是“API 密钥”“服务账号”和“OAuth”。API 会根据其请求的资源以及调用 API 的位置使用其中一种身份验证服务。

API 密钥

API 密钥是通常以加密字符串形式出现的密钥令牌。API 密钥可以快速生成和使用。通常，使用公开数据或方法并希望开发者快速上手的 API 会使用 API 密钥来快速验证用户身份。

对于 Google Cloud 而言，API 密钥用于标识正在调用 API 的调用方项目。通过标识调用方项目，API 密钥让系统能够将使用情况信息与该项目相关联，并可拒绝尚未获得访问权限或尚未启用 API 的项目发出的调用请求。

OAuth

OAuth 令牌在格式上与 API 密钥类似，但更加安全，并且可以与用户账号或身份相关联。这些令牌主要用于 API 允许开发者访问用户数据的场景中。

API 密钥让开发者可以访问 API 的所有功能，而 OAuth 客户端 ID 则完全基于范围；不同的身份会被授予不同的权限。

服务账号

服务账号是一种特殊的 Google 账号，它属于您的应用或虚拟机，不属于个人最终用户。您的应用会使用服务账号的身份调用 Google API，这样用户就不必直接参与。

您可以通过以下两种方式使用服务账号：向应用提供服务账号的私钥；或者使用内置服务账号（在 Google Cloud Functions、Google App Engine、Google Compute Engine 或 Google Kubernetes Engine 上运行时可用）。

如需关于服务账号和角色的专题实验，请参阅：服务账号和角色：基础知识。

由于 Cloud Storage 是一个托管用户数据和提供用户数据访问服务的平台，因此您需要先生成 OAuth 令牌，然后才能使用其服务。

1. 在新标签页中打开 OAuth 2.0 Playground。这是一项可让您轻松生成 OAuth 令牌的服务。

2. 向下滚动并选择 Cloud Storage API V1。

3. 然后选择 https://www.googleapis.com/auth/devstorage.full_control 范围。

4. 点击显示授权 API (Authorize APIs) 字样的蓝框。系统会打开 Google 登录页面。

5. 选择您的用户名，然后在系统提示您授予权限时点击允许。

OAuth 2.0 Playground 随即打开。请注意，第 2 步中已生成授权代码。

6. 点击将授权代码转换为令牌 (Exchange authorization code for tokens)。如果您被转到第 3 步，请点击第 2 步面板。

7. 复制访问令牌，以便在下一步中使用。

任务 4. 使用 Cloud Storage JSON/REST API 创建存储桶

1. 返回到 Cloud Shell 会话。在 CLI 提示符处，输入 ls 并按 Enter 键。您应该会看到之前创建的 values.json 文件和一个 README-cloudshell.txt 文件：

输出：

README-cloudshell.txt values.json

2. 运行以下命令，并将 <YOUR_TOKEN> 替换为您生成的访问令牌，以便将您的 OAuth2 令牌设置为环境变量：

export OAUTH2_TOKEN=<YOUR_TOKEN>

3. 运行以下命令，将项目 ID 设置为环境变量：

export PROJECT_ID=$(gcloud config get-value project)

4. 现在运行以下命令来创建 Cloud Storage 存储桶：

curl -X POST --data-binary @values.json \ -H "Authorization: Bearer $OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://www.googleapis.com/storage/v1/b?project=$PROJECT_ID"

5. 您应该会看到大致如下的输出结果：

{ "kind": "storage#bucket", "selfLink": "https://www.googleapis.com/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7", "id": "qwiklabs-gcp-02-5d551758b5a7", "name": "qwiklabs-gcp-02-5d551758b5a7", "projectNumber": "670840659006", "metageneration": "1", "location": "US", "storageClass": "MULTI_REGIONAL", "etag": "CAE=", "timeCreated": "2020-11-11T06:41:40.901Z", "updated": "2020-11-11T06:41:40.901Z", "iamConfiguration": { "bucketPolicyOnly": { "enabled": false }, "uniformBucketLevelAccess": { "enabled": false } }, "locationType": "multi-region" } 注意：如果您收到“此存储桶名称受到使用限制”或“抱歉，该名称不可用”之类的错误消息，则表示该名称与通用存储桶命名惯例冲突。修改 values.json 文件并替换存储桶名称。

此请求综合运用了您此前所学的全部知识。您使用了 curl CLI 工具来发出 HTTP POST 方法请求。您将 values.json 文件传入请求正文中。您将 OAuth 令牌和 JSON 规范作为请求标头传递。此请求被路由到 Cloud Storage 端点，其中包含一个设置为您的项目 ID 的查询字符串参数。

查看新创建的 Cloud Storage 存储桶

• 如需查看新创建的存储桶，请在导航菜单中依次选择 Cloud Storage > 存储桶。

验证您已完成的任务

点击检查我的进度可验证您已完成的任务。如果您已使用 Cloud Storage JSON/REST API 成功创建存储桶，评估分数将会更新。

使用 Cloud Storage JSON/REST API 创建存储桶

任务 5. 使用 Cloud Storage JSON/REST API 上传文件

您可以使用 Cloud Storage JSON/REST API 将文件上传到存储桶。

1. 将以下图片保存到您的计算机，并将其命名为 demo-image.png：

2. 在 Cloud Shell 会话中，点击右上角的三点状菜单图标。依次点击上传 > 选择文件。选择并上传 demo-image.png 文件。这会将该图片添加到您的目录中。

3. 运行以下命令以获取图片文件的路径：

realpath demo-image.png

您应该会看到大致如下的输出结果：

/home/gcpstaging25084_student/demo-image.png

4. 运行以下命令，并将 <DEMO_IMAGE_PATH> 替换为上一条命令的输出，以便将文件路径设置为环境变量：

export OBJECT=<DEMO_IMAGE_PATH>

5. 运行以下命令，将存储桶名称设置为环境变量：

export BUCKET_NAME={{{project_0.project_id | Project_ID}}}-bucket

6. 现在运行以下命令，将演示图片上传到您的 Cloud Storage 存储桶：

curl -X POST --data-binary @$OBJECT \ -H "Authorization: Bearer $OAUTH2_TOKEN" \ -H "Content-Type: image/png" \ "https://www.googleapis.com/upload/storage/v1/b/$BUCKET_NAME/o?uploadType=media&name=demo-image"

您应该会看到大致如下的输出结果：

{ "kind": "storage#object", "id": "qwiklabs-gcp-02-5d551758b5a7/demo-image/1605077118178936", "selfLink": "https://www.googleapis.com/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7/o/demo-image", "mediaLink": "https://www.googleapis.com/download/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7/o/demo-image?generation=1605077118178936&alt=media", "name": "demo-image", "bucket": "qwiklabs-gcp-02-5d551758b5a7", "generation": "1605077118178936", "metageneration": "1", "contentType": "image/png", "storageClass": "MULTI_REGIONAL", "size": "401951", "md5Hash": "LbpHpwhnApQKQx9IEXjTsQ==", "crc32c": "j5oPrg==", "etag": "CPis3Zvy+ewCEAE=", "timeCreated": "2020-11-11T06:45:18.178Z", "updated": "2020-11-11T06:45:18.178Z", "timeStorageClassUpdated": "2020-11-11T06:45:18.178Z" }

7. 如需查看已添加到存储桶中的图片，请打开导航菜单并依次选择 Cloud Storage > 存储桶。

8. 点击存储桶的名称，确认 demo-image 已添加：

9. 点击图片名称，打开对象详情页面。

验证您已完成的任务

点击检查我的进度可验证您已完成的任务。如果您已使用 Cloud Storage JSON/REST API 成功上传文件，评估分数将会更新

使用 Cloud Storage JSON/REST API 上传文件

恭喜！

在本实验中，您加深了对 API 的理解，并亲手进行了 Cloud Storage JSON/REST API 相关操作。您了解了 Cloud API、API 架构、HTTP 协议和方法、端点、RESTful API、JSON 和 API 身份验证实践。现在，有了这些知识储备，您可以在 Qwiklabs 中完成更多 API 实验了。

后续步骤/了解详情

强烈建议您通过以下实验进行更多针对 API 的练习：

• APIs Explorer：Qwik Start
• Cloud Natural Language API：Qwik Start

Google Cloud 培训和认证

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

本手册的最后更新时间：2024 年 2 月 26 日

上次测试实验的时间：2024 年 2 月 26 日

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