Discovery API 提供了一系列 Google API，用于检索每个 API 的机器可读的“发现文档”元数据。
本文档适用于想要编写客户端库、IDE 插件和其他工具以与 Google API 进行交互的开发者。
Discovery Service 背景
概念
Google API Discovery Service 基于两个基本概念构建：
- API 目录：API Discovery Service 支持的所有 API 的列表。每个目录条目都会显示有关受支持的 API 的详细信息，包括其名称、其功能的简要说明以及文档链接。一个 API 可以有多个目录条目，每个条目对应它的受支持版本之一。
- 发现文档：特定 API 的机器可读说明。 发现文档描述特定 API 版本的接口。本文档详细介绍了如何通过 RESTful HTTP 调用访问每个 API 的各种方法。发现文档包含与 API 关联的数据和方法的说明、可用的 OAuth 范围的相关信息，以及架构、方法、参数和可用参数值的说明。
数据模型
资源是指具有唯一标识符的单个数据实体。根据上述概念，Google API Discovery Service 基于两种类型的资源运行。
API 目录列表：API 列表
每个目录条目都包含一个 API 名称/版本对，其中包含以下信息：
- 身份和说明信息：名称、版本、标题和说明。
- 文档信息：图标和文档链接。
- 状态信息，包括状态标签以及有关这是否是 API 首选版本的指示。
-
发现文档链接：此 API 的发现文档的 URI（以完整网址的形式提供，例如
https://serviceusage.googleapis.com/$discovery/rest?version=v1）。
发现文档资源：特定 API 的机器可读说明
除了 API 目录中提供的信息之外，发现文档还包含以下内容：
- 架构，它是 API 资源架构的列表，用于描述您在每个 API 中有权访问的数据；Google API Discovery Service 架构基于 JSON 架构。
- 方法，包括 API 方法以及每个方法的可用参数的列表。
- OAuth 范围，标识此 API 可用的 OAuth 范围列表。
- 内嵌文档：简要介绍架构、方法、参数和可用参数值。
单一目录集合是单个 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://API/$discovery/rest?version=VERSION
其中 API 是发现文档资源的标识符，VERSION 是特定 API 版本的标识符。
下面几个示例说明了其在 Google API Discovery Service 中的工作原理。
列出 Google API Discovery Service 支持的所有 API：
GET https://discovery.googleapis.com/discovery/v1/apis
获取 Service Usage API 版本 1 的发现文档：
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1