Discovery API 概览

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

立即在 APIs Explorer 中试用！

获取 Service Usage API 版本 1 的发现文档：

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1