探索文档

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

方法

Discovery 文档重点介绍了调用 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 的 Discovery 文档的 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 指向 16x16 和 32x32 图标(代表 API)的链接。
icons.x16 string 16x16 图标的网址。
icons.x32 string 32x32 图标的网址。
labels[] list 此 API 状态的标签。有效值包括 limited_availabilitydeprecated
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 架构中的“type”部分找到值列表。
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。此属性可用于匹配不同版本的 Discovery 之间的方法。
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 架构中的“type”部分中找到。
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。此属性可用于匹配不同版本的 Discovery 之间的方法。
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 架构中的“type”部分中找到。
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 对此资源上的所有子资源的说明。