探索文档

发现文档适用于大多数 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",
  "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,
      "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
        ]
      }
    }
  },
  "methods": {
    (key): {
      "id": string,
      "path": string,
      "httpMethod": string,
      "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
            ]
          }
        }
      },
      "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,
          "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
                ]
              }
            }
          },
          "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): (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 图标的网址。
labels[] list 此 API 的状态标签。有效值包括 limited_availabilitydeprecated
protocol string 文档描述的协议。例如 REST。
rootUrl string 所有 API 服务都位于的根网址。
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).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).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).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).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).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 采用第 2 层级功能 ({+var}) 的 REST 方法的 URI 路径 (RFC 6570)。作为 path 媒体资源的补充。
resources.(key).methods.(key).httpMethod string 此方法使用的 HTTP 方法。
resources.(key).methods.(key).description string 此方法的说明。
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).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).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).resources object 此资源的子资源。
resources.(key).resources.(key) nested object 对此资源上所有子资源的说明。