Discovery API 提供了一系列 Google API，用于为每个 API 检索机器可读的“发现文档”元数据。
本文档适用于想要编写客户端库、IDE 插件以及其他用于与 Google API 交互的工具的开发者。
发现服务背景
概念
Google API 探索服务建立在两个基本概念的基础上：
- API 目录：API 探索服务支持的所有 API 的列表。每个目录条目都会显示有关受支持的 API 的详细信息，包括其名称、用途说明的简短说明，以及文档链接。一个 API 可以有多个目录条目，每个条目对应一个受支持的版本。
- 发现文档：特定 API 的机器可读说明。探索文档介绍了特定 API 版本的 Surface。本文档详细介绍了如何通过 RESTful HTTP 调用访问每个 API 的各种方法。Discovery 文档包括与 API 关联的数据和方法的说明，以及可用 OAuth 范围的信息，以及架构、方法、参数和可用参数值的说明。
数据模型
资源是具有唯一标识符的单个数据实体。Google API Discovery Service 根据上述概念在两种类型的资源上运行。
API 目录列表：API 列表
每个目录条目都包含 API 名称/版本对，其中包含以下信息：
- 标识和说明信息：名称、版本、标题和说明。
- 文档信息：图标和文档链接。
- 状态信息，包括状态标签，以及指明此 API 是否是首选 API 的指示。
- 发现文档链接，即此 API 的发现文档的 URI（以完整网址的形式提供，例如 https://servicemanagement.googleapis.com/$discovery/rest?version=v1）。
发现文档资源：特定 API 的机器可读说明
除了 API 目录中提供的信息之外，发现文档还包含：
- 架构 - 列出了 API 资源架构，用于描述您在每个 API 中可以访问的数据；Google API 探索服务架构基于 JSON 架构。
- 方法，包括 API 方法列表和每个方法的可用参数。
- OAuth 范围，用于标识此 API 可用的 OAuth 范围列表。
- 内嵌文档，其中提供了有关架构、方法、参数和可用参数值的简要说明。
单个目录集是单个 API 目录资源的概念容器，以及每个受支持的 API 的发现文档资源。
如需详细了解 API 目录资源和发现文档资源，请参阅使用 API 和参考文档。
运维
您可以对 Google API Discovery Service 中的集合和资源调用两种不同的方法，如下表所述。
| 操作 | 说明 | REST HTTP 映射 |
|---|---|---|
| list | 列出所有支持的 API。 | 针对目录资源 URI 的 GET 权限。 |
通话风格
REST
受支持的 Google API Discovery Service 操作会直接映射到 REST HTTP GET 动词，如操作中所述。
Google API Discovery Service URI 的具体格式为：
https://discovery.googleapis.com/discovery/v1/apis?parameters
其中 api 是发现文档资源的标识符，version 是特定 API 版本的标识符， 和 _parameters_ 是要应用于查询的任何参数。如需了解详情，请参阅参考文档中的查询参数摘要
如需详细了解用于 API 中各项受支持的操作的全部 URI，请参阅 Google API 探索服务参考文档。
以下几个示例展示了它在 Google API 发现服务中的工作原理。
列出所有 Google API Discovery Service 支持的 API：
GET https://discovery.googleapis.com/discovery/v1/apis
获取 Google Cloud Service Management API 的发现文档（版本 1）：
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1