探索文件

探索文件適用於大多數 API 的特定版本。每個 API 的 Discovery 文件都會說明 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 的 Discovery 文件 ID。例如：urlshortener:v1。
name	string	API 名稱。例如：urlshortener。
canonicalName	string	API 的標準名稱。例如 Url Shortener。
version	string	API 版本。例如：v1。
revision	string	API 的修訂版本。
title	string	API 的名稱。例如「Google 網址縮短器 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	這個結構定義的專屬 ID。
parameters.(key).type	string	這個結構定義的值類型。您可以在 JSON 架構的 "type" 部分中找到值清單。
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	這個結構定義的專屬 ID。範例：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	此結構定義的專屬 ID。
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	媒體上傳內容的大小上限，例如「1 MB」、「2 GB」或「3 TB」。
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	這個結構定義的專屬 ID。
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	媒體上傳內容的大小上限，例如「1 MB」、「2 GB」或「3 TB」。
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	此資源的任何子資源說明。