使用 Discovery API

本文档适用于想要编写客户端库、IDE 插件和其他工具以与 Google API 进行交互的开发者。Google API Discovery Service 通过一个简单的 API 公开有关其他 Google API 的机器可读元数据，让您可以实现上述目标。本指南简要介绍了发现文档的各个部分，以及有关如何使用该文档的实用提示。

对该 API 的所有调用都是未经身份验证的基于 JSON 的 REST 请求，这些请求使用 SSL；换句话说，网址以 https 开头。

发现文档格式

本部分简要介绍了发现文档。

以下所有示例都使用 Service Usage API 中的发现文档。您可以通过执行以下 GET 请求来加载 Service Usage API 的发现文档：

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

发现文档的格式包含 6 大类信息：

API 的基本说明。
API 的身份验证信息。
资源和架构详情，用于描述 API 的数据。
有关 API 方法的详细信息。
有关 API 支持的任何自定义功能的信息。
内嵌文档，用于描述 API 的关键元素。

下文对上述发现文档的各个部分进行了介绍。

基本 API 说明

发现文档包含一组特定于 API 的属性。这些属性不一定按以下顺序显示，也不一定显示在发现文档的同一部分中：

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

这些 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": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

auth 部分仅定义特定 API 的范围。如需了解这些范围如何与 API 方法相关联，请参阅下面的方法部分。

资源和架构

API 的操作作用于名为 resources 的数据对象。发现文档是围绕资源的概念构建的。每个发现文档都有一个顶级 resources 部分，用于对与该 API 关联的所有资源进行分组。例如，Service Usage API 在顶级 resources 下有一个 services 资源和一个 operations 资源：

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

每个资源部分中都包含与该资源关联的方法。例如，Service Usage API 有六个方法与 services 资源相关联：get、enable、disable、batchGet、batchEnable 和 list。

架构可让您了解 API 中的资源是什么样的。每个发现文档都有一个顶级 schemas 部分，其中包含指向对象的架构 ID 的名称/值对。架构 ID 在每个 API 中是唯一的，用于在发现文档的 methods 部分中唯一标识架构。例如，以下是 Service Usage API 发现文档中的一些架构：

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

API Discovery Service 使用 JSON 架构草稿-03 作为其架构表示形式。下面是 EnableServiceResponse 资源的 JSON 架构的代码段，还显示了其引用的 GoogleApiServiceusagev1Service。这些架构旁边是 Pub/Sub API (pubsub.googleapis.com) 启用请求的实际响应的一部分。

EnableServiceResponse 资源 JSON 架构： 关于启用服务的实际响应：

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

粗体字段显示 JSON 架构与实际响应之间的映射。

如该示例中所示，架构可以包含对其他架构的引用。如果您正在构建客户端库，则可以帮助您在数据模型类中有效地对 API 的对象进行建模。在上面的 EnableServiceResponse 示例中，service 属性是对 ID 为 GoogleApiServiceusageV1Service 的架构（即 Service Usage API 发现文档中的另一个架构）的引用。您可以将 EnableServiceResponse 资源中的 GoogleApiServiceusageV1Service 属性替换为 GoogleApiServiceusageV1Service 架构的值（请注意，$ref 语法来自 JSON 架构规范）。

在指示请求和响应正文时，方法也可以引用架构。如需了解详情，请参阅方法部分。

方法

发现文档的核心是围绕方法构建的。方法是指可对 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、enable 和 disable：

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

最后，每个方法的部分都会详细说明有关该方法的各种属性。下面是一个 enable 方法示例：

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

本节包含常规方法详情，例如用于标识方法的唯一 ID、要使用的 httpMethod 以及方法的 path（如需详细了解如何使用path 属性来计算完整的方法网址，请参阅编写请求部分）。除了这些常规方法属性之外，还有一些属性可将该方法与发现文档中的其他部分相关联：

范围

本文档前面定义的 auth 部分包含有关特定 API 支持的所有范围的信息。如果某个方法支持其中一个范围，它将有一个范围数组。对于方法支持的每个范围，此数组中都有一个条目。

请注意，选择要在应用中使用哪个身份验证范围取决于各种因素，例如要调用哪些方法以及随方法一起发送哪些参数。因此，使用哪个范围由开发者决定。发现仅会记录对方法有效的范围。

请求和响应

如果方法具有请求或响应正文，则这些正文分别记录在 request 或 response 部分中。例如，对于 enable 方法，request 部分的内容表示方法的请求由 ID 为 EnableServiceRequest 的 JSON 架构定义。此架构可以在顶级架构部分找到。

参数

如果方法具有应由用户指定的参数，则这些参数会记录在方法级 parameters 部分中。此部分包含参数名称与该参数的更多详细信息的键/值映射。

例如，enable 方法有一个参数：name。参数可以位于 path 或网址 query 中；location 属性指示客户端库应将参数放入何处。

还有许多其他属性会描述该参数，包括参数数据 type（适用于强类型语言）、参数是否为 required 以及参数是否为枚举。如需详细了解这些属性，请参阅此 API 的参考文档。

参数顺序

客户端库可以通过多种方式构建其接口。一种方式是在方法签名中使用具有每个 API 参数的方法。但是，由于 JSON 是一种无序格式，因此很难以程序化方式了解如何对方法签名中的参数进行排序。parameterOrder 数组提供用于发出请求的固定参数排序。该数组按重要性列出每个参数的名称；它可以包含路径或查询参数，但数组中的每个参数都是必需的。

媒体上传

如果某个方法支持上传图片、音频或视频等媒体，则 mediaUpload 部分中会记录支持上传该媒体的位置和协议。本部分详细介绍了受支持的上传协议，以及可上传的媒体类型的相关信息。

enable 方法不包含 mediaUpload 部分。但是，典型的 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 属性是一个 media-range 列表，用于确定可以上传哪些 MIME 类型。上述示例中显示的端点将接受任何图片格式。

maxSize 属性具有上传的大小上限。该值是一个字符串，以 MB、GB 或 TB 为单位。在上面的示例中，上传的大小上限为 10 MB。请注意，此值并不反映该 API 的个别用户剩余存储空间配额，因此即使上传小于 maxSize，客户端库仍应准备好处理因空间不足而失败的上传。

protocols 部分列出了某种方法支持的上传协议。simple 协议只是在单个 HTTP 请求中将媒体 POST 到给定端点。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}。建议您构造包含 /download 的媒体下载网址，即使 useMediaDownloadService 为 false 也是如此。

注意：一种 API 方法可以同时支持媒体下载和上传。媒体上传和下载的请求网址构造逻辑独立工作，不会相互干扰。因此，此类 API 方法会有一个用于媒体下载的 /download/... 网址，以及一个用于媒体上传的 /upload/... 网址。不过，您无法在单个请求中进行媒体上传和下载。

常用参数

顶级发现文档包含 parameters 属性。本部分类似于每个方法的参数部分，但这些参数可以应用于 API 中的任何方法。

例如，Service Usage API 的 get 和 list 方法可以在请求参数中包含 prettyPrint 参数，用于将所有这些方法的响应设置为人类可读的格式。下面列出了常见参数：

参数	含义	备注	适用性
`access_token`	当前用户的 OAuth 2.0 令牌。	提供 OAuth 2.0 令牌的一种可行方式。
`alt`	响应的数据格式。	有效值：`json`、`atom`、`csv`。默认值：因 API 而异。并非所有值都适用于每个 API。	适用于所有资源的所有操作。
`callback`	回调函数。	用于处理响应的 JavaScript 回调函数的名称。用于 JavaScript JSON-P 请求。
`fields`	指定响应中所含字段子集的选择器。	用于提升性能。
`key`	API 密钥。（必需）	必需参数（除非您提供 OAuth 2.0 令牌）。您的 API 密钥用于标识您的项目，并为您提供 API 访问权限、配额和报告。从 API 控制台获取项目的 API 密钥。
`prettyPrint`	返回带有缩进和换行符的响应。	如果该参数的值为 `true`，则系统会以人类可读的格式返回响应。默认值：因 API 而异。如果该参数的值为 `false`，则可缩减响应的载荷大小（在某些环境中或许可提升性能）。
`quotaUser`	`userIp` 的替代参数。	可以让您即使在用户 IP 地址不明的情况下，也能通过服务器端的应用实施每个用户的配额限制。例如，当应用代表用户在 App Engine 上运行 cron 作业时，会发生此类情况。您可以选择使用任意字符串作为用户的唯一标识符，但字符数不能超过 40 个。如果同时提供这两个参数，则该参数会覆盖 `userIp`。详细了解上限的用法。
`userIp`	最终用户的 IP 地址，表示此 API 是为哪个用户调用的。	可以让您在通过服务器端应用调用 API 时，实施每个用户的配额限制。详细了解上限的用法。

内嵌文档

每个发现文档都使用多个 description 字段进行注解，这些字段会为 API 提供内嵌文档。您可以在以下 API 元素中找到 description 字段：

API 本身
OAuth 范围
资源架构
API 方法
方法参数
某些参数的可接受值

如果您希望使用 Google API Discovery Service 为客户端库生成人类可读的文档（例如 JavaDoc），则这些字段特别有用。

使用 Discovery API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

发现文档格式

基本 API 说明

身份验证

资源和架构

方法

范围

请求和响应

参数

媒体上传

媒体下载

常用参数

内嵌文档

使用 Discovery API