探索文件

探索文件適用於大多數 API 的特定版本。每個 API 的探索文件都會說明 API 的介面、 API 存取方式，以及 API 要求和回應的結構。探索文件提供的資訊包括 API 級別屬性，例如 API 說明、資源結構定義、驗證範圍和方法。

方法

探索文件的重點放在 符合 REST 樣式的 API 叫用方法。 discovery.apis.list 方法會傳回 Google API 探索服務支援的所有 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)
      }
    }
  }
}
資源名稱值說明Notes
kindstring這個回應的種類。固定字串 discovery#restDescription。
discoveryVersionstring指出用於產生這份文件的 Discovery API 版本。
idstringAPI 的 Discovery 文件 ID。例如 urlshortener:v1。
namestringAPI 的名稱。例如：urlshortener。
canonicalNamestringAPI 的標準名稱，例如：Url Shortener。
versionstringAPI 版本，例如 v1。
revisionstringAPI 修訂版本。
titlestringAPI 的標題。例如「Google Url Shortener API」。
descriptionstring這個 API 的說明。
iconsobject連結至 API 的 16x16 和 32x32 圖示。
icons.x16string16x16 圖示的網址。
icons.x32string32x32 圖示的網址。
labels[]list這個 API 狀態的標籤。有效值包括 limited_availability 或 deprecated。
protocolstring本文件所說明的通訊協定。例如 REST。
rootUrlstring所有 API 服務都位於的根網址。
endpoints[]list這個 API 的位置型端點物件清單，每個物件都包含端點網址、位置、說明和淘汰狀態。
endpoints[].endpointUrlstring端點目標主機的網址。
endpoints[].locationstring端點的位置。
endpoints[].descriptionstring字串，用來說明網址指定的主機。
endpoints[].deprecatedboolean此端點是否已淘汰。
parametersobject適用於所有 API 的通用參數。
parameters.(key)nested object單一參數的說明。
parameters.(key).idstring這個結構定義的專屬 ID。
parameters.(key).typestring這個結構定義的值類型。相關值清單請參閱 JSON 結構定義中的「類型」一節。
parameters.(key).$refstring其他結構定義的參照。這個屬性的值是其他結構定義的 ID。
parameters.(key).descriptionstring這個物件的說明。
parameters.(key).defaultstring此屬性的預設值 (如果有的話)。
parameters.(key).requiredboolean此為必要參數。
parameters.(key).formatstring可協助限制值的額外規則運算式或鍵。詳情請參閱類型和格式摘要。
parameters.(key).patternstring這個參數必須符合的規則運算式。
parameters.(key).minimumstring這個參數的最小值。
parameters.(key).maximumstring這個參數的最大值。
parameters.(key).enum[]list這個參數可能的值 (如果為列舉)，
parameters.(key).enumDescriptions[]list列舉的說明。每個位置都會對應至列舉陣列中的對應值。
parameters.(key).repeatedboolean這個參數是否可能多次顯示。
parameters.(key).locationstring這個參數是查詢路徑還是 REST 要求的路徑。
parameters.(key).propertiesobject如果這個物件是物件結構定義，請列出這個物件每個屬性的結構定義。
parameters.(key).properties.(key)nested object這個物件的單一屬性。這個值本身是描述這個屬性的 JSON 結構定義物件。
parameters.(key).additionalPropertiesnested object如果物件的結構定義為物件，則這項屬性是任何其他屬性的結構定義，當中包含這個物件動態鍵。
parameters.(key).itemsnested object如果這是陣列的結構定義，這個屬性是陣列中每個元素的結構定義。
parameters.(key).annotationsobject這項資源的其他相關資訊。
parameters.(key).annotations.required[]list列出要求中需要這個屬性的方法清單。
authobject驗證資訊。
auth.oauth2objectOAuth 2.0 驗證資訊。
auth.oauth2.scopesobject可用的 OAuth 2.0 範圍。
auth.oauth2.scopes.(key)object範圍值。
auth.oauth2.scopes.(key).descriptionstring範圍說明。
features[]list這個 API 支援的功能清單。
schemasobject這個 API 的結構定義。
schemas.(key)nested object個別結構定義說明。
schemas.(key).idstring這個結構定義的專屬 ID。範例：URL
schemas.(key).typestring這個結構定義的值類型。如需這些值的清單，請參閱 JSON 結構定義中的「類型」一節。
schemas.(key).$refstring其他結構定義的參照。這個屬性的值是其他結構定義的 ID。
schemas.(key).descriptionstring這個物件的說明。
schemas.(key).defaultstring此屬性的預設值 (如果有的話)。
schemas.(key).requiredboolean此為必要參數。
schemas.(key).deprecatedboolean這個結構定義是否為已淘汰。
schemas.(key).formatstring可協助限制值的額外規則運算式或鍵。請參閱類型和格式摘要。
schemas.(key).patternstring這個參數必須符合的規則運算式。
schemas.(key).minimumstring這個參數的最小值。
schemas.(key).maximumstring這個參數的最大值。
schemas.(key).enum[]list這個參數可能的值 (如果為列舉)，
schemas.(key).enumDescriptions[]list列舉的說明。每個位置都會對應至 enum 陣列中的對應值。
schemas.(key).enumDeprecated[]list列舉的淘汰狀態。每個位置都會對應至 enum 陣列中的對應值。
schemas.(key).repeatedboolean這個參數是否可能多次顯示。
schemas.(key).locationstring這個參數是查詢路徑還是 REST 要求的路徑。
schemas.(key).propertiesobject如果這個物件是物件結構定義，請列出這個物件每個屬性的結構定義。
schemas.(key).properties.(key)nested object這個物件的單一屬性。這個值本身是描述這個屬性的 JSON 結構定義物件。
schemas.(key).additionalPropertiesnested object如果物件的結構定義為物件，則這項屬性是任何其他屬性的結構定義，當中包含這個物件動態鍵。
schemas.(key).itemsnested object如果這是陣列的結構定義，這個屬性是陣列中每個元素的結構定義。
schemas.(key).annotationsobject這項資源的其他相關資訊。
schemas.(key).annotations.required[]list列出要求中需要這個屬性的方法清單。
methodsobject這個 API 的 API 級別方法。
methods.(key)nested object個別方法說明。
methods.(key).idstring這個方法的專屬 ID。這個屬性可用於比對不同版本的探索方法。
methods.(key).descriptionstring這個方法的說明。
methods.(key).deprecatedboolean此方法是否已淘汰。
methods.(key).parametersobject這個方法中所有參數的詳細資料。
methods.(key).parameters.(key)nested object此方法中的單一參數詳細資料。
methods.(key).parameters.(key).idstring這個結構定義的專屬 ID。
methods.(key).parameters.(key).typestring這個結構定義的值類型。如需這些值的清單，請參閱 JSON 結構定義中的「類型」一節。
methods.(key).parameters.(key).$refstring其他結構定義的參照。這個屬性的值是其他結構定義的 ID。
methods.(key).parameters.(key).descriptionstring這個物件的說明。
methods.(key).parameters.(key).defaultstring此屬性的預設值 (如果有的話)。
methods.(key).parameters.(key).requiredboolean此為必要參數。
methods.(key).parameters.(key).deprecatedboolean參數是否已淘汰。
methods.(key).parameters.(key).formatstring可協助限制值的額外規則運算式或鍵。請參閱類型和格式摘要。
methods.(key).parameters.(key).patternstring這個參數必須符合的規則運算式。
methods.(key).parameters.(key).minimumstring這個參數的最小值。
methods.(key).parameters.(key).maximumstring這個參數的最大值。
methods.(key).parameters.(key).enum[]list這個參數可能的值 (如果為列舉)，
methods.(key).parameters.(key).enumDescriptions[]list列舉的說明。每個位置都會對應至 enum 陣列中的對應值。
methods.(key).parameters.(key).enumDeprecated[]list列舉的淘汰狀態。每個位置都會對應至 enum 陣列中的對應值。
methods.(key).parameters.(key).repeatedboolean這個參數是否可能多次顯示。
methods.(key).parameters.(key).locationstring這個參數是查詢路徑還是 REST 要求的路徑。
methods.(key).parameters.(key).propertiesobject如果這個物件是物件結構定義，請列出這個物件每個屬性的結構定義。
methods.(key).parameters.(key).properties.(key)nested object這個物件的單一屬性。這個值本身是描述這個屬性的 JSON 結構定義物件。
methods.(key).parameters.(key).additionalPropertiesnested object如果物件的結構定義為物件，則這項屬性是任何其他屬性的結構定義，當中包含這個物件動態鍵。
methods.(key).parameters.(key).itemsnested object如果這是陣列的結構定義，這個屬性是陣列中每個元素的結構定義。
methods.(key).parameters.(key).annotationsobject這項資源的其他相關資訊。
methods.(key).parameters.(key).annotations.required[]list列出要求時需要這個屬性的方法清單。
methods.(key).parameterOrder[]list必要參數的排序清單。這有助於客戶瞭解如何建構方法簽章。陣列會排序，讓最重要的參數優先顯示。
methods.(key).scopes[]list這個方法適用的 OAuth 2.0 範圍。
methods.(key).supportsMediaDownloadboolean這個方法是否支援下載媒體。
methods.(key).supportsMediaUploadboolean這個方法是否支援媒體上傳。
methods.(key).mediaUploadobject媒體上傳參數。
methods.(key).mediaUpload.accept[]list允許上傳媒體內容至這個方法的 MIME 媒體範圍。
methods.(key).mediaUpload.maxSizestring媒體上傳大小上限，例如「1MB」、「2GB」或「3TB」。
methods.(key).supportsSubscriptionboolean這個方法是否支援訂閱項目。
baseUrlstring[已淘汰] REST 要求的基準網址。
basePathstring[已淘汰] REST 要求的基本路徑。
servicePathstring所有 REST 要求的基本路徑。
batchPathstringREST 批次要求的路徑。
methods.(key).pathstring這個 REST 方法的 URI 路徑。應搭配 API 級別的 servicePath 屬性使用。
methods.(key).httpMethodstring此方法使用的 HTTP 方法。
methods.(key).requestobject要求的結構定義。
methods.(key).request.$refstring要求結構定義的結構定義 ID。
methods.(key).request.parameterNamestring[已淘汰] 基於回溯相容性考量，某些 API 有這個欄位。您可以放心忽略這則訊息。
methods.(key).responseobject回應的結構定義。
methods.(key).response.$refstring回應結構定義的結構定義 ID。
methods.(key).mediaUpload.protocolsobject支援的上傳通訊協定。
methods.(key).mediaUpload.protocols.simpleobject支援上傳單一 HTTP 要求。
methods.(key).mediaUpload.protocols.simple.multipartboolean如果這個端點支援上傳多部分媒體，則為 True。
methods.(key).mediaUpload.protocols.simple.pathstring要上傳的 URI 路徑。應搭配 API 級別中的 rootURL 屬性使用。
methods.(key).mediaUpload.protocols.resumableobject支援支援續傳的媒體上傳通訊協定。
methods.(key).mediaUpload.protocols.resumable.multipartboolean如果這個端點支援上傳多部分媒體，則為 true。
methods.(key).mediaUpload.protocols.resumable.pathstring要上傳的 URI 路徑。應搭配 API 級別的 rootURL 屬性使用。
resourcesobject這個 API 中的資源。
resources.(key)nested object個別資源說明。包含與這項資源相關的方法和子資源。
resources.(key).methodsobject這項資源的方法。
resources.(key).methods.(key)nested object這項資源的任何方法說明。
resources.(key).methods.(key).idstring這個方法的專屬 ID。這個屬性可用於比對不同版本的探索方法。
resources.(key).methods.(key).pathstring這個 REST 方法的 URI 路徑。應搭配 API 級別的 servicePath 屬性使用。
resources.(key).methods.(key).flatPathstring此 REST 方法的 URI 路徑 (RFC 6570) 格式，不含第 2 級功能 ({+var})。與 path 屬性相輔相成。
resources.(key).methods.(key).httpMethodstring此方法使用的 HTTP 方法。
resources.(key).methods.(key).descriptionstring這個方法的說明。
resources.(key).methods.(key).deprecatedboolean此方法是否已淘汰。
resources.(key).methods.(key).parametersobject這個方法中所有參數的詳細資料。
resources.(key).methods.(key).parameters.(key)nested object此方法中的單一參數詳細資料。
resources.(key).methods.(key).parameters.(key).idstring這個結構定義的專屬 ID。
resources.(key).methods.(key).parameters.(key).typestring這個結構定義的值類型。如需這些值的清單，請參閱 JSON 結構定義中的「類型」一節。
resources.(key).methods.(key).parameters.(key).$refstring其他結構定義的參照。這個屬性的值是其他結構定義的「ID」。
resources.(key).methods.(key).parameters.(key).descriptionstring這個物件的說明。
resources.(key).methods.(key).parameters.(key).defaultstring此屬性的預設值 (如果有的話)。
resources.(key).methods.(key).parameters.(key).requiredboolean此為必要參數。
resources.(key).methods.(key).parameters.(key).deprecatedboolean參數是否已淘汰。
resources.(key).methods.(key).parameters.(key).formatstring可協助限制值的額外規則運算式或鍵。請參閱類型和格式摘要。
resources.(key).methods.(key).parameters.(key).patternstring這個參數必須符合的規則運算式。
resources.(key).methods.(key).parameters.(key).minimumstring這個參數的最小值。
resources.(key).methods.(key).parameters.(key).maximumstring這個參數的最大值。
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).repeatedboolean這個參數是否可能多次顯示。
resources.(key).methods.(key).parameters.(key).locationstring這個參數是查詢路徑還是 REST 要求的路徑。
resources.(key).methods.(key).parameters.(key).propertiesobject如果這個物件是物件結構定義，請列出這個物件每個屬性的結構定義。
resources.(key).methods.(key).parameters.(key).properties.(key)nested object這個物件的單一屬性。這個值本身是描述這個屬性的 JSON 結構定義物件。
resources.(key).methods.(key).parameters.(key).additionalPropertiesnested object如果物件的結構定義為物件，則這項屬性是任何其他屬性的結構定義，當中包含這個物件動態鍵。
resources.(key).methods.(key).parameters.(key).itemsnested object如果這是陣列的結構定義，這個屬性是陣列中每個元素的結構定義。
resources.(key).methods.(key).parameters.(key).annotationsobject這項資源的其他相關資訊。
resources.(key).methods.(key).parameters.(key).annotations.required[]list列出要求中需要這個屬性的方法清單。
resources.(key).methods.(key).parameterOrder[]list必要參數的排序清單。這有助於客戶瞭解如何建構方法簽章。陣列會排序，讓最重要的參數優先顯示。
resources.(key).methods.(key).requestobject要求的結構定義。
resources.(key).methods.(key).request.$refstring要求結構定義的結構定義 ID。
resources.(key).methods.(key).responseobject回應的結構定義。
resources.(key).methods.(key).response.$refstring回應結構定義的結構定義 ID。
resources.(key).methods.(key).scopes[]list這個方法適用的 OAuth 2.0 範圍。
resources.(key).methods.(key).supportsMediaDownloadboolean這個方法是否支援下載媒體。
resources.(key).methods.(key).supportsMediaUploadboolean這個方法是否支援媒體上傳。
resources.(key).methods.(key).mediaUploadobject媒體上傳參數。
resources.(key).methods.(key).mediaUpload.accept[]list允許上傳媒體內容至這個方法的 MIME 媒體範圍。
resources.(key).methods.(key).mediaUpload.maxSizestring媒體上傳大小上限，例如「1MB」、「2GB」或「3TB」。
resources.(key).methods.(key).mediaUpload.protocolsobject支援的上傳通訊協定。
resources.(key).methods.(key).mediaUpload.protocols.simpleobject支援上傳單一 HTTP 要求。
resources.(key).methods.(key).mediaUpload.protocols.simple.multipartboolean如果這個端點支援上傳多部分媒體，則為 true。
resources.(key).methods.(key).mediaUpload.protocols.simple.pathstring要上傳的 URI 路徑。應搭配 API 級別的 rootURL 屬性使用。
resources.(key).methods.(key).mediaUpload.protocols.resumableobject支援支援續傳的媒體上傳通訊協定。
resources.(key).methods.(key).mediaUpload.protocols.resumable.multipartboolean如果這個端點支援上傳多部分媒體，則為 true。
resources.(key).methods.(key).mediaUpload.protocols.resumable.pathstring要上傳的 URI 路徑。應搭配 API 級別的 rootURL 屬性使用。
resources.(key).methods.(key).supportsSubscriptionboolean這個方法是否支援訂閱項目。
resources.(key).deprecatedboolean這項資源是否為已淘汰。
resources.(key).resourcesobject這項資源的子資源。
resources.(key).resources.(key)nested object這項資源的任何子資源說明。