发现文档

发现文档适用于大多数 API 的特定版本。每个 API 的发现文档都介绍了 API 的接口、如何访问 API 以及 API 请求和响应的结构。发现文档提供的信息包括 API 级别属性，例如 API 说明、资源架构、身份验证范围和方法。

方法

发现文档重点介绍调用 API 的 RESTful 方法。discovery.apis.list 方法会返回 Google API Discovery Service 支持的所有 API 的列表，包括用于检索基于 REST 的发现文档的网址。

list

检索此端点中受支持的 API 列表。

资源表示法

{
  "kind": "discovery#restDescription",
  "discoveryVersion": "v1",
  "id": string,
  "name": string,
  "canonicalName": string,
  "version": string,
  "revision": string,
  "title": string,
  "description": string,
  "icons": {
    "x16": string,
    "x32": string
  },
  "documentationLink": string,
  "labels": [
    string
  ],
  "protocol": "rest",
  "baseUrl": string,
  "basePath": string,
  "rootUrl": string,
  "servicePath": string,
  "batchPath": "batch",
  "endpoints": [
    {
      "endpointUrl": string,
      "location": string,
      "deprecated": boolean,
      "description": string
    }
  ],
  "parameters": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "auth": {
    "oauth2": {
      "scopes": {
        (key): {
          "description": string
        }
      }
    }
  },
  "features": [
    string
  ],
  "schemas": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "deprecated": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "enumDeprecated": [
        boolean
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "methods": {
    (key): {
      "id": string,
      "path": string,
      "httpMethod": string,
      "description": string,
      "deprecated": boolean,
      "parameters": {
        (key): {
          "id": string,
          "type": string,
          "$ref": string,
          "description": string,
          "default": string,
          "required": boolean,
          "deprecated": boolean,
          "format": string,
          "pattern": string,
          "minimum": string,
          "maximum": string,
          "enum": [
            string
          ],
          "enumDescriptions": [
            string
          ],
          "enumDeprecated": [
            boolean
          ],
          "repeated": boolean,
          "location": string,
          "properties": {
            (key): (JsonSchema)
          },
          "additionalProperties": (JsonSchema),
          "items": (JsonSchema),
          "annotations": {
            "required": [
              string
            ]
          }
        }
      },
      "parameterOrder": [
        string
      ],
      "request": {
        "$ref": string
      },
      "response": {
        "$ref": string
      },
      "scopes": [
        (value)
      ],
      "supportsMediaDownload": boolean,
      "supportsMediaUpload": boolean,
      "mediaUpload": {
        "accept": [
          string
        ],
        "maxSize": string,
        "protocols": {
          "simple": {
            "multipart": true,
            "path": string
          },
          "resumable": {
            "multipart": true,
            "path": string
          }
        }
      },
      "supportsSubscription": boolean
    }
  },
  "resources": {
    (key): {
      "methods": {
        (key): {
          "id": string,
          "path": string,
          "httpMethod": string,
          "description": string,
          "deprecated": boolean,
          "parameters": {
            (key): {
              "id": string,
              "type": string,
              "$ref": string,
              "description": string,
              "default": string,
              "required": boolean,
              "deprecated": boolean,
              "format": string,
              "pattern": string,
              "minimum": string,
              "maximum": string,
              "enum": [
                string
              ],
              "enumDescriptions": [
                string
              ],
              "enumDeprecated": [
                boolean
              ],
              "repeated": boolean,
              "location": string,
              "properties": {
                (key): (JsonSchema)
              },
              "additionalProperties": (JsonSchema),
              "items": (JsonSchema),
              "annotations": {
                "required": [
                  string
                ]
              }
            }
          },
          "parameterOrder": [
            string
          ],
          "request": {
            "$ref": string
          },
          "response": {
            "$ref": string
          },
          "scopes": [
            (value)
          ],
          "supportsMediaDownload": boolean,
          "supportsMediaUpload": boolean,
          "mediaUpload": {
            "accept": [
              string
            ],
            "maxSize": string,
            "protocols": {
              "simple": {
                "multipart": true,
                "path": string
              },
              "resumable": {
                "multipart": true,
                "path": string
              }
            }
          },
          "supportsSubscription": boolean
        }
      },
      "deprecated": boolean,
      "resources": {
        (key): (RestResource)
      }
    }
  }
}

属性名称	值	说明
kind	string	此响应的种类。固定字符串 discovery#restDescription。
discoveryVersion	string	指明用于生成此文档的 Discovery API 版本。
id	string	API 的发现文档的 ID。例如，urlshortener:v1。
name	string	API 的名称。例如，urlshortener。
canonicalName	string	API 的规范名称。例如，Url Shortener。
version	string	API 的版本。例如，v1。
revision	string	API 的修订版本。
title	string	API 的标题。例如，“Google Url Shortener API”。
description	string	此 API 的说明。
icons	object	指向代表 API 的 16x16 和 32x32 图标的链接。
icons.x16	string	16x16 图标的网址。
icons.x32	string	32x32 图标的网址。
documentationLink	string	直观易懂的 API 文档的链接。
labels[]	list	此 API 状态的标签。有效值包括 limited_availability 或 deprecated。
protocol	string	文档描述的协议。例如，REST。
rootUrl	string	所有 API 服务所在的根网址。
endpoints[]	list	此 API 的基于位置的端点对象列表。每个对象都包含端点网址、位置、说明和弃用状态。
endpoints[].endpointUrl	string	端点目标主机的网址。
endpoints[].location	string	端点的位置。
endpoints[].description	string	描述网址所指定主机的字符串。
endpoints[].deprecated	boolean	此端点是否已弃用。
parameters	object	适用于所有 API 的通用参数。
parameters.(key)	nested object	单个参数的说明。
parameters.(key).id	string	此架构的唯一标识符。
parameters.(key).type	string	此架构的值类型。您可以在 JSON 架构的“类型”部分找到值列表。
parameters.(key).$ref	string	对其他架构的引用。此属性的值是另一个架构的 ID。
parameters.(key).description	string	此对象的说明。
parameters.(key).default	string	此属性的默认值（如果存在）。
parameters.(key).required	boolean	是否为必需参数。
parameters.(key).format	string	有助于约束值的另一个正则表达式或键。 如需了解详情，请参阅类型和格式摘要。
parameters.(key).pattern	string	此参数必须遵循的正则表达式。
parameters.(key).minimum	string	此参数的最小值。
parameters.(key).maximum	string	此参数的最大值。
parameters.(key).enum[]	list	此参数可以采用的值（如果它是枚举）。
parameters.(key).enumDescriptions[]	list	枚举的说明。每个位置都映射到枚举数组中的相应值。
parameters.(key).repeated	boolean	此参数是否可以多次出现。
parameters.(key).location	string	此参数是放在 REST 请求的查询中还是路径中。
parameters.(key).properties	object	如果这是对象的架构，请列出此对象的每个属性的架构。
parameters.(key).properties.(key)	nested object	此对象的单个属性。值本身是描述此属性的 JSON 架构对象。
parameters.(key).additionalProperties	nested object	如果这是对象的架构，则此属性为在此对象上具有动态键的任何其他属性的架构。
parameters.(key).items	nested object	如果这是数组的架构，则此属性是数组中每个元素的架构。
parameters.(key).annotations	object	有关此属性的其他信息。
parameters.(key).annotations.required[]	list	请求中需要有此属性的方法列表。
auth	object	身份验证信息。
auth.oauth2	object	OAuth 2.0 身份验证信息。
auth.oauth2.scopes	object	可用的 OAuth 2.0 范围。
auth.oauth2.scopes.(key)	object	范围值。
auth.oauth2.scopes.(key).description	string	范围说明。
features[]	list	此 API 的受支持功能列表。
schemas	object	此 API 的架构。
schemas.(key)	nested object	单个架构说明。
schemas.(key).id	string	此架构的唯一标识符。示例：URL
schemas.(key).type	string	此架构的值类型。您可以在 JSON 架构的“类型”部分找到值列表。
schemas.(key).$ref	string	对其他架构的引用。此属性的值是另一个架构的 ID。
schemas.(key).description	string	此对象的说明。
schemas.(key).default	string	此属性的默认值（如果存在）。
schemas.(key).required	boolean	是否为必需参数。
schemas.(key).deprecated	boolean	此架构是否已弃用。
schemas.(key).format	string	有助于约束值的另一个正则表达式或键。 如需了解详情，请参阅类型和格式摘要。
schemas.(key).pattern	string	此参数必须遵循的正则表达式。
schemas.(key).minimum	string	此参数的最小值。
schemas.(key).maximum	string	此参数的最大值。
schemas.(key).enum[]	list	此参数可以采用的值（如果它是枚举）。
schemas.(key).enumDescriptions[]	list	枚举的说明。每个位置都映射到 enum 数组中的相应值。
schemas.(key).enumDeprecated[]	list	枚举的弃用状态。每个位置都映射到 enum 数组中的相应值。
schemas.(key).repeated	boolean	此参数是否可以多次出现。
schemas.(key).location	string	此参数是放在 REST 请求的查询中还是路径中。
schemas.(key).properties	object	如果这是对象的架构，请列出此对象的每个属性的架构。
schemas.(key).properties.(key)	nested object	此对象的单个属性。值本身是描述此属性的 JSON 架构对象。
schemas.(key).additionalProperties	nested object	如果这是对象的架构，则此属性为在此对象上具有动态键的任何其他属性的架构。
schemas.(key).items	nested object	如果这是数组的架构，则此属性是数组中每个元素的架构。
schemas.(key).annotations	object	有关此属性的其他信息。
schemas.(key).annotations.required[]	list	请求中需要有此属性的方法列表。
methods	object	此 API 的 API 级别方法。
methods.(key)	nested object	单个方法说明。
methods.(key).id	string	此方法的唯一 ID。此属性可用于在不同版本的发现之间匹配方法。
methods.(key).description	string	此方法的说明。
methods.(key).deprecated	boolean	此方法是否已弃用。
methods.(key).parameters	object	此方法中所有参数的详细信息。
methods.(key).parameters.(key)	nested object	此方法中单个参数的详细信息。
methods.(key).parameters.(key).id	string	此架构的唯一标识符。
methods.(key).parameters.(key).type	string	此架构的值类型。您可以在 JSON 架构的“类型”部分找到值列表。
methods.(key).parameters.(key).$ref	string	对其他架构的引用。此属性的值是另一个架构的 ID。
methods.(key).parameters.(key).description	string	此对象的说明。
methods.(key).parameters.(key).default	string	此属性的默认值（如果存在）。
methods.(key).parameters.(key).required	boolean	是否为必需参数。
methods.(key).parameters.(key).deprecated	boolean	参数是否已弃用。
methods.(key).parameters.(key).format	string	有助于约束值的另一个正则表达式或键。 如需了解详情，请参阅类型和格式摘要。
methods.(key).parameters.(key).pattern	string	此参数必须遵循的正则表达式。
methods.(key).parameters.(key).minimum	string	此参数的最小值。
methods.(key).parameters.(key).maximum	string	此参数的最大值。
methods.(key).parameters.(key).enum[]	list	此参数可以采用的值（如果它是枚举）。
methods.(key).parameters.(key).enumDescriptions[]	list	枚举的说明。每个位置都映射到 enum 数组中的相应值。
methods.(key).parameters.(key).enumDeprecated[]	list	枚举的弃用状态。每个位置都映射到 enum 数组中的相应值。
methods.(key).parameters.(key).repeated	boolean	此参数是否可以多次出现。
methods.(key).parameters.(key).location	string	此参数是放在 REST 请求的查询中还是路径中。
methods.(key).parameters.(key).properties	object	如果这是对象的架构，请列出此对象的每个属性的架构。
methods.(key).parameters.(key).properties.(key)	nested object	此对象的单个属性。值本身是描述此属性的 JSON 架构对象。
methods.(key).parameters.(key).additionalProperties	nested object	如果这是对象的架构，则此属性为在此对象上具有动态键的任何其他属性的架构。
methods.(key).parameters.(key).items	nested object	如果这是数组的架构，则此属性是数组中每个元素的架构。
methods.(key).parameters.(key).annotations	object	有关此属性的其他信息。
methods.(key).parameters.(key).annotations.required[]	list	请求中需要有此属性的方法列表。
methods.(key).parameterOrder[]	list	必需参数的有序列表。这可为客户提供有关如何构建方法签名的提示。对数组进行排序，以使最重要的参数显示在最前面。
methods.(key).scopes[]	list	适用于此方法的 OAuth 2.0 范围。
methods.(key).supportsMediaDownload	boolean	此方法是否支持媒体下载。
methods.(key).supportsMediaUpload	boolean	此方法是否支持上传媒体内容。
methods.(key).mediaUpload	object	媒体上传参数。
methods.(key).mediaUpload.accept[]	list	此方法的可接受媒体上传的 MIME 媒体范围。
methods.(key).mediaUpload.maxSize	string	媒体上传的大小上限，例如“1MB”“2GB”或“3TB”。
methods.(key).supportsSubscription	boolean	此方法是否支持订阅。
baseUrl	string	[已弃用] REST 请求的基础网址。
basePath	string	[已弃用] REST 请求的基础路径。
servicePath	string	所有 REST 请求的基础路径。
batchPath	string	REST 批量请求的路径。
methods.(key).path	string	此 REST 方法的 URI 路径。应在 API 级别与 servicePath 属性结合使用。
methods.(key).httpMethod	string	此方法使用的 HTTP 方法。
methods.(key).request	object	请求的架构。
methods.(key).request.$ref	string	请求架构的 ID。
methods.(key).request.parameterName	string	[已弃用] 出于向后兼容的原因，某些 API 具有此字段。您可以放心地忽略它。
methods.(key).response	object	响应的架构。
methods.(key).response.$ref	string	响应架构的 ID。
methods.(key).mediaUpload.protocols	object	支持的上传协议。
methods.(key).mediaUpload.protocols.simple	object	支持作为单个 HTTP 请求进行上传。
methods.(key).mediaUpload.protocols.simple.multipart	boolean	如果此端点支持上传多部分媒体，则为 true。
methods.(key).mediaUpload.protocols.simple.path	string	用于上传的 URI 路径。应在 API 级别与 rootURL 属性结合使用。
methods.(key).mediaUpload.protocols.resumable	object	支持可断点续传的媒体上传协议。
methods.(key).mediaUpload.protocols.resumable.multipart	boolean	如果此端点支持上传多部分媒体，则为 true。
methods.(key).mediaUpload.protocols.resumable.path	string	用于上传的 URI 路径。应在 API 级别与 rootURL 属性结合使用。
resources	object	此 API 中的资源。
resources.(key)	nested object	单个资源说明。包含与此资源相关的方法和子资源。
resources.(key).methods	object	此资源上的方法。
resources.(key).methods.(key)	nested object	此资源上任何方法的说明。
resources.(key).methods.(key).id	string	此方法的唯一 ID。此属性可用于在不同版本的发现之间匹配方法。
resources.(key).methods.(key).path	string	此 REST 方法的 URI 路径。应在 API 级别与 servicePath 属性结合使用。
resources.(key).methods.(key).flatPath	string	此 REST 方法的 URI 路径，采用 (RFC 6570) 格式，不包含 2 级功能 ({+var})。对 path 属性的补充。
resources.(key).methods.(key).httpMethod	string	此方法使用的 HTTP 方法。
resources.(key).methods.(key).description	string	此方法的说明。
resources.(key).methods.(key).deprecated	boolean	此方法是否已弃用。
resources.(key).methods.(key).parameters	object	此方法中所有参数的详细信息。
resources.(key).methods.(key).parameters.(key)	nested object	此方法中单个参数的详细信息。
resources.(key).methods.(key).parameters.(key).id	string	此架构的唯一标识符。
resources.(key).methods.(key).parameters.(key).type	string	此架构的值类型。您可以在 JSON 架构的“类型”部分找到值列表。
resources.(key).methods.(key).parameters.(key).$ref	string	对其他架构的引用。此属性的值是另一个架构的 ID。
resources.(key).methods.(key).parameters.(key).description	string	此对象的说明。
resources.(key).methods.(key).parameters.(key).default	string	此属性的默认值（如果存在）。
resources.(key).methods.(key).parameters.(key).required	boolean	是否为必需参数。
resources.(key).methods.(key).parameters.(key).deprecated	boolean	参数是否已弃用。
resources.(key).methods.(key).parameters.(key).format	string	有助于约束值的另一个正则表达式或键。 如需了解详情，请参阅类型和格式摘要。
resources.(key).methods.(key).parameters.(key).pattern	string	此参数必须遵循的正则表达式。
resources.(key).methods.(key).parameters.(key).minimum	string	此参数的最小值。
resources.(key).methods.(key).parameters.(key).maximum	string	此参数的最大值。
resources.(key).methods.(key).parameters.(key).enum[]	list	此参数可以采用的值（如果它是枚举）。
resources.(key).methods.(key).parameters.(key).enumDescriptions[]	list	枚举的说明。每个位置都映射到 enum 数组中的相应值。
resources.(key).methods.(key).parameters.(key).enumDeprecated[]	list	枚举的弃用状态。每个位置都映射到 enum 数组中的相应值。
resources.(key).methods.(key).parameters.(key).repeated	boolean	此参数是否可以多次出现。
resources.(key).methods.(key).parameters.(key).location	string	此参数是放在 REST 请求的查询中还是路径中。
resources.(key).methods.(key).parameters.(key).properties	object	如果这是对象的架构，请列出此对象的每个属性的架构。
resources.(key).methods.(key).parameters.(key).properties.(key)	nested object	此对象的单个属性。值本身是描述此属性的 JSON 架构对象。
resources.(key).methods.(key).parameters.(key).additionalProperties	nested object	如果这是对象的架构，则此属性为在此对象上具有动态键的任何其他属性的架构。
resources.(key).methods.(key).parameters.(key).items	nested object	如果这是数组的架构，则此属性是数组中每个元素的架构。
resources.(key).methods.(key).parameters.(key).annotations	object	有关此属性的其他信息。
resources.(key).methods.(key).parameters.(key).annotations.required[]	list	请求中需要有此属性的方法列表。
resources.(key).methods.(key).parameterOrder[]	list	必需参数的有序列表。这可为客户提供有关如何构建方法签名的提示。对数组进行排序，以使最重要的参数显示在最前面。
resources.(key).methods.(key).request	object	请求的架构。
resources.(key).methods.(key).request.$ref	string	请求架构的 ID。
resources.(key).methods.(key).response	object	响应的架构。
resources.(key).methods.(key).response.$ref	string	响应架构的 ID。
resources.(key).methods.(key).scopes[]	list	适用于此方法的 OAuth 2.0 范围。
resources.(key).methods.(key).supportsMediaDownload	boolean	此方法是否支持媒体下载。
resources.(key).methods.(key).supportsMediaUpload	boolean	此方法是否支持上传媒体内容。
resources.(key).methods.(key).mediaUpload	object	媒体上传参数。
resources.(key).methods.(key).mediaUpload.accept[]	list	此方法的可接受媒体上传的 MIME 媒体范围。
resources.(key).methods.(key).mediaUpload.maxSize	string	媒体上传的大小上限，例如“1MB”“2GB”或“3TB”。
resources.(key).methods.(key).mediaUpload.protocols	object	支持的上传协议。
resources.(key).methods.(key).mediaUpload.protocols.simple	object	支持作为单个 HTTP 请求进行上传。
resources.(key).methods.(key).mediaUpload.protocols.simple.multipart	boolean	如果此端点支持上传多部分媒体，则为 true。
resources.(key).methods.(key).mediaUpload.protocols.simple.path	string	用于上传的 URI 路径。应在 API 级别与 rootURL 属性结合使用。
resources.(key).methods.(key).mediaUpload.protocols.resumable	object	支持可断点续传的媒体上传协议。
resources.(key).methods.(key).mediaUpload.protocols.resumable.multipart	boolean	如果此端点支持上传多部分媒体，则为 true。
resources.(key).methods.(key).mediaUpload.protocols.resumable.path	string	用于上传的 URI 路径。应在 API 级别与 rootURL 属性结合使用。
resources.(key).methods.(key).supportsSubscription	boolean	此方法是否支持订阅。
resources.(key).deprecated	boolean	此资源是否已弃用。
resources.(key).resources	object	此资源上的子资源。
resources.(key).resources.(key)	nested object	此资源上的任何子资源的说明。