Discovery API 提供 Google API 清單，可擷取每個 API 的機器可讀「探索文件」中繼資料。
本文件適用於想要編寫用戶端程式庫、IDE 外掛程式和其他與 Google API 互動的工具的開發人員。
探索服務背景
概念
Google API Discovery 服務建立在兩個基本概念上：
- API 目錄：API 探索服務支援的所有 API 清單。每個目錄項目都會顯示所支援 API 的詳細資料，包括其名稱、簡短的說明，以及說明文件連結。API 可包含多個目錄項目，每個項目代表一個支援的版本。
- 探索文件：特定 API 的機器可解讀說明。Discovery 文件說明特定 API 版本的介面。這份文件詳細說明如何透過 RESTful HTTP 呼叫存取各個 API 的各種方法。Discovery 文件包含與 API 相關聯的資料和方法說明，以及可用的 OAuth 範圍資訊，以及結構定義、方法、參數和可用的參數值說明。
資料模型
資源是具有專屬 ID 的個別資料實體。Google API Discovery 服務會根據上述概念，對兩種資源進行操作。
API 目錄清單：API 清單
每個目錄項目都包含 API 名稱/版本組合，其中包含以下資訊：
- 識別和說明資訊：名稱、版本、標題和說明。
- 說明文件資訊：圖示和說明文件連結。
- 狀態資訊，包括狀態標籤，以及指出這是否為 API 的偏好版本。
-
探索文件連結：這個 API 探索文件的 URI (以完整網址的形式提供，例如
https://serviceusage.googleapis.com/$discovery/rest?version=v1)。
探索文件資源：特定 API 的機器可讀說明
除了 API 目錄中提供的資訊外，Discovery 文件還包含下列資訊：
- 結構定義：這是 API 資源結構定義清單，可說明您在每個 API 中可存取的資料；Google API Discovery Service 結構定義是根據 JSON 結構定義建立。
- 方法：包括 API 方法清單，以及每個方法的可用參數。
- OAuth 範圍：指出可用於此 API 的 OAuth 範圍清單。
- 內嵌說明文件：提供簡短的結構定義、方法、參數和可用參數值說明。
單一目錄集合是單一 API 目錄資源的概念容器，以及每個支援 API 的 Discovery 文件資源。
作業
您可以在 Google API Discovery Service 中對集合和資源叫用兩種不同的方法，如下表所述。
| 作業 | 說明 | REST HTTP 對應 |
|---|---|---|
| list | 列出所有支援的 API。 | 在目錄資源 URI 中使用 GET。 |
調用風格
REST
如「作業」一節所述，支援的 Google API Discovery Service 作業會直接對應至 REST HTTP GET 動詞。
Google API 探索服務 URI 的具體格式如下：
https://API/$discovery/rest?version=VERSION
其中 API 是探索文件資源的 ID，VERSION 則是特定 API 版本的 ID。
以下列舉幾個例子，說明這項功能在 Google API Discovery Service 中的運作方式。
列出 Google API Discovery Service 支援的所有 API：
GET https://discovery.googleapis.com/discovery/v1/apis
取得 Service Usage API 1.0 版的探索文件：
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1