简介

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

立即在 API Explorer 中试用!

获取 Google Cloud Service Management API 的发现文档(版本 1):

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