探索文件

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

方法

探索文件著重於叫用 API 的 REST 方法。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",
  "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 這個結構定義的專屬 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).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。這項屬性可用於比對不同探索版本之間的方法。
methods.(key).description string 此方法的說明。
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).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。這項屬性可用於比對不同探索版本之間的方法。
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).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).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 這項資源的所有子資源說明。