简介
本文档适用于想要编写客户端库、IDE 插件和其他工具以便与 Google API 进行交互的开发者。借助 Google API Discovery Service，您可以通过简单的 API 公开其他 Google API 的机器可读元数据，从而实现上述所有目的。本指南简要介绍了发现文档的各个部分，并提供了实用的文档使用提示。
对此 API 的所有调用都是未经身份验证且基于 SSL 的 REST 请求，这些请求使用 SSL，例如，网址以 https 开头。
如果您不熟悉 Google API Discovery Service 的概念，请在开始编写代码之前阅读使用入门。
探索文档格式
本部分简要介绍了发现文档。
以下所有示例均使用 Google Cloud Service Management API 中的 Discovery 文档。您可以执行以下 GET 请求，加载 Google Cloud Service Management API 的发现文档：
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1发现文档的格式包括六大类：
下面逐一介绍了这些发现文档的各个部分。如需详细了解每个属性，请参阅参考文档。
基本 API 说明
探索文档包含一组 API 专用属性：
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
这些 API 级别属性包含有关 API 特定版本的详细信息，包括 name、version、title 和 description。protocol 始终具有固定的 rest 值，因为 API Discovery Service 仅支持通过 RESTful 方法访问 API。
servicePath 字段用于指明此特定 API 版本的路径前缀。
身份验证
auth 部分包含有关 API 的 OAuth 2.0 身份验证范围的详细信息。要详细了解如何在 OAuth 2.0 中使用范围，请参阅使用 OAuth 2.0 访问 Google API。
auth 部分包含嵌套的 oauth2 和 scopes 部分。scopes 部分是一个从范围值到范围的更多详细信息的键值对：
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
auth 部分仅定义特定 API 的范围。如需了解这些作用域如何与 API 方法相关联，请参阅下文中的方法部分。
资源和架构
API 的操作会对名为 resources 的数据对象执行操作。“发现”文档是围绕资源的概念构建的。每个发现文档都有一个顶级 resources 部分，用于对与此 API 关联的所有资源进行分组。例如，Google Cloud Service Management API 在顶级 resources 下设置了 services 资源和 operations 资源，而 services 资源包含三个子资源 configs、rollouts 和 consumers：
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
每个资源部分内都有与该资源相关联的方法。例如，Google Cloud Service Management API 有三个与 services.rollouts 资源关联的方法：get、list 和 create。
架构可以告知您 API 中的资源是什么样的。每个发现文档都有一个顶级 schemas 部分，其中包含指向对象的架构 ID 的名称/值对。架构 ID 对于每个 API 都是唯一的，用于对发现文档的 methods 部分中的架构进行唯一标识：
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
API 探索服务使用 JSON 架构草稿-03 作为其架构表示法。以下是 Url 资源的 JSON 架构代码段，以及实际响应资源：
| 发布资源 JSON 架构： | 实际发布资源响应： |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
以粗体显示的字段显示了 JSON 架构与实际响应之间的映射。
架构也可能包含对其他架构的引用。如果您正在构建客户端库，这有助于您有效地在数据模型类中为 API 的对象建模。在上面的 Rollout 示例中，trafficPercentStrategy 属性实际上是对 ID 为 TrafficPercentStrategy 的架构的引用。如果您查看 schemas 部分，就会发现 TrafficPercentStrategy 架构。此架构的值可以替换为 Rollout 资源中的 trafficPercentStrategy 属性（请注意，$ref 语法来自 JSON 架构规范）。
在指示架构的请求和响应正文时，方法还可以引用架构。如需了解详情，请参阅方法部分。
方法
Discovery 文档的核心是围绕各种方法构建的。方法是指可以对 API 执行的操作。methods 部分位于发现文档的各个方面，包括顶级（我们称之为 API 级别方法）或 resources 级别。
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
虽然 API 可以有 API 级方法，但资源必须包含 methods 部分。
每个 methods 部分都是从方法名称到该方法的其他详细信息的键值对。以下示例记录了三个方法：get、list 和 create：
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
最后，每个方法的部分中都详细说明了该方法的各种属性。下面是一个 get 方法示例：
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
本部分包含常规方法详细信息，例如标识方法的唯一 ID、要使用的 httpMethod 以及方法的 path（如需详细了解如何使用 path 属性计算完整方法网址，请参阅编写请求部分）。除了这些常规方法属性外，还有一些属性用于将方法与发现文档中的其他部分相关联：
权限范围
本文档前面定义的 auth 部分包含有关特定 API 支持的所有范围的信息。如果某个方法支持其中某个范围，则该方法将拥有范围数组。对于该方法支持的每个范围，此数组中都有一个条目。例如，Google Cloud Service Management API get 方法的 scopes 部分如下所示：
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
请注意，选择要在应用中使用的身份验证范围取决于多种因素，例如要调用哪些方法，以及随方法一起发送哪些参数。因此，具体使用哪种作用域由开发者决定。只能用于发现范围对某个方法有效的文档。
请求和响应
如果该方法具有请求或响应正文，请分别参阅 request 或 response 部分。在上面的 get 示例中，该方法具有 response 正文：
"response": {
"$ref": "Rollout"
}
上面的语法表明响应正文由 ID 为 Rollout 的 JSON 架构定义。此架构可在顶级架构部分找到。请求正文和响应正文都使用 $ref 语法来引用架构。
参数
如果某个方法有应由用户指定的参数，则这些参数会记录在方法级 parameters 部分中。本部分包含将参数名称映射到相应参数的键值对的更多详细信息：
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
在上面的示例中，get 方法有两个参数：serviceName 和 rolloutId。参数可以位于 path 或网址 query 中；location 属性用于指明客户端库应该将该参数放在什么位置。
还有很多其他描述参数的属性，包括参数数据 type（对强类型语言很有用）、参数是否为 required 以及参数是否为枚举。如需详细了解这些属性，请参阅参考指南。
参数顺序
客户端库可通过多种方式构建其接口。一种方法是在方法签名中有一个包含每个 API 参数的方法。但是，由于 JSON 是一种无序格式，因此以编程方式难以知道如何对方法签名中的参数进行排序。parameterOrder 数组为发出请求提供固定的参数顺序。该数组会按有效性顺序列出每个参数的名称；它可以包含路径参数或查询参数，但数组中的每个参数都是必需参数。在上面的示例中，Java 方法签名可能如下所示：
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);parameterOrder 数组中的第一个值 serviceName 也是方法签名中的第一个元素。如果 parameterOrder 数组中还有其他形参，这些形参则位于 serviceName 形参后面。由于 parameterOrder 数组仅包含必需参数，因此最好也提供一种供用户指定可选参数的方法。上面的示例使用 optionalParameters 地图执行此操作。
媒体上传
如果某个方法支持上传媒体（例如图片、音频或视频），则 mediaUpload 部分会记录支持上传该媒体的位置和协议。本部分详细介绍了哪些上传协议受支持，以及可以上传哪些类型的媒体：
"supportsMediaUpload": true,
"mediaUpload": {
"accept": [
"image/*"
],
"maxSize": "10MB",
"protocols": {
"simple": {
"multipart": true,
"path": "/upload/storage/v1beta1/b/{bucket}/o"
},
"resumable": {
"multipart": true,
"path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
}
}
}
在上面的示例中，supportsMediaUpload 属性是一个布尔值，用于确定该方法是否支持上传媒体。如果值为 true，则 mediaUpload 部分会记录可以上传的媒体种类。
accept 属性是一系列媒体范围，用于确定可接受的上传 MIME 类型。上述示例中显示的端点将接受任何图片格式。
maxSize 属性的上传大小上限。该值是一个以 MB、GB 或 TB 为单位的字符串。在上面的示例中，上传文件的大小上限为 10 MB。请注意，此值不会反映单个用户的 API 剩余存储空间配额，因此即使上传量低于 maxSize，客户端库也应准备好处理由于空间不足而上传的失败情况。
protocols 部分列出了某个方法支持的上传协议。simple 协议只是在单个 HTTP 请求中将媒体发布到给定端点。resumable 协议意味着 path URI 中提供的端点支持可续传上传协议。如果 multipart 属性为 true，则端点接受多部分上传，这意味着 JSON 请求和媒体可以封装在互斥/相关正文中并一起发送。请注意，simple 和 resumable 协议可能均支持多部分上传。
path 属性是一个 URI 模板，应像方法的 path 属性一样进行扩展，如编写请求部分中所述。
媒体下载
如果某个方法支持下载媒体（例如图片、音频或视频），则通过 supportsMediaDownload 参数指明：
"supportsMediaDownload": true,
下载媒体时，您必须在请求网址中将 alt 查询参数设为 media。
如果 API 方法的 useMediaDownloadService 属性为 true，请在 servicePath 前插入 /download 以避免重定向。例如，如果 servicePath 和 path 的串联为 /youtube/v3/captions/{id}，下载路径为 /download/youtube/v3/captions/{id}。即使 useMediaDownloadService 为 false，仍建议您使用 /download 构建媒体下载网址。
常见参数
顶级发现文档包含一个 parameters 属性。本部分与每种方法的参数部分类似，但这些参数可应用于 API 中的任何方法。
例如，Google Cloud Service Management API 的 get、insert 或 list 方法的请求参数中可以有 prettyPrint 参数，该参数采用人类可读懂的格式设置所有方法的响应。下面列出了常见参数：
| 参数 | 含义 | 备注 | 适用性 |
|---|---|---|---|
access_token |
当前用户的 OAuth 2.0 令牌。 |
|
|
alt |
响应的数据格式。 |
|
|
callback |
回调函数。 |
| |
fields |
指定响应中所含字段子集的选择器。 |
|
|
key |
API 密钥。（必需*） | ||
prettyPrint |
返回带有标识符和换行符的响应。 |
|
|
quotaUser |
userIp 的替代参数。 |
|
|
userIp |
最终用户的 IP 地址，表示此 API 是为哪个用户调用的。 |
|
特性
在某些情况下，API 支持探索文档其余范围之外的自定义功能。这些数据收集在 features 数组中。功能数组包含 API 支持的各个特殊功能的字符串标签。目前，dataWrapper 是唯一受支持的功能，但将来可能会支持其他功能。
"features": dataWrapper
dataWrapper 功能表示对 API 的所有请求和来自 API 的响应均封装在 data JSON 对象中。这是旧版 Google API 的一项功能，但今后我们将弃用。以下 API 支持 dataWrapper 功能：汇问 v1 和 翻译 v2。
作为客户端库开发者，如果 API 支持“dataWrapper”功能，您应执行以下操作：
- 针对请求：将请求资源封装在
dataJSON 对象中。 - 在响应时：在
dataJSON 对象内找到相应资源。
Discovery 文档中的架构不包含数据封装容器，因此您必须明确添加和移除这些封装容器。例如，假设有一个名为“Foo”的 API，其资源如下所示：
{
"id": 1,
"foo": "bar"
}
在使用 API 插入此资源之前，您需要先将其封装在数据元素中：
{
"data": {
"id": 1,
"foo": "bar"
}
}
另一方面，当您从 API 获得响应时，它还包含数据封装容器：
{
"data": {
"id": 1,
"foo": "bar"
}
}
如需获取架构定义的资源，您需要移除数据封装容器：
{
"id": 1,
"foo": "bar"
}
内嵌文档
每个发现文档都带有许多 description 字段，这些字段提供 API 内嵌文档。您可以为以下 API 元素找到 description 字段：
- API 本身
- OAuth 范围
- 资源架构
- API 方法
- 方法参数
- 某些参数的可接受值
如果您希望使用 Google API Discovery Service 为客户端库（例如 JavaDoc）生成简单易懂的文档，这些字段将特别有用。