Discovery API 提供 Google API 清單，可用於擷取機器可讀的「探索文件」；各 API 的中繼資料。
本文件的適用對象為想編寫用戶端程式庫、IDE 外掛程式和其他與 Google API 互動的工具。
探索服務背景
概念
Google API 探索服務是以下列兩個基本概念為基礎：
- API 目錄：API 探索服務支援的所有 API 清單。每個目錄項目都會顯示支援 API 的詳細資料，包括其「名稱」、介紹的簡短說明，以及說明文件連結。一個 API 可以有多個目錄項目，每個支援的版本各一個。
- 探索文件：可供機器解讀的特定 API 說明。探索文件會描述特定 API 版本的介面。本文件詳細說明如何透過符合 REST 樣式的 HTTP 呼叫存取每個 API 的各種方法。探索文件包括與 API 相關的資料和說明，以及可用 OAuth 範圍的相關資訊，以及結構定義、方法、參數和可用參數值的說明。
資料模型
資源是具有專屬 ID 的個別資料實體。Google API 探索服務會依據上述概念在兩種類型資源中運作。
API 目錄清單：API 清單
每個目錄項目都包含 API 的名稱/版本組合，其中包含下列資訊：
- 識別資訊與說明：名稱、版本、標題和說明。
- 說明文件資訊：圖示和說明文件連結。
- 狀態資訊，包括狀態標籤以及是否指出這個 API 的偏好版本。
- 探索文件連結：這個 API 的探索文件 URI (以完整網址提供)，例如 https://servicemanagement.googleapis.com/$discovery/rest?version=v1)。
探索文件資源：機器可解讀的特定 API 說明
除了 API 目錄中提供的資訊，探索文件還包括：
- 「結構定義」是 API 資源架構清單，用於說明您可在各個 API 中存取的資料；Google API 探索服務結構定義是以 JSON 架構為基礎。
- 方法，包含 API 方法清單和每個方法可用的參數。
- OAuth 範圍，用於指定這個 API 適用的 OAuth 範圍清單。
- 內嵌說明文件：提供結構定義、方法、參數和可用參數值的簡短說明。
單一目錄集合是單一 API 目錄資源的概念容器，以及每個支援 API 的探索文件資源。
如要進一步瞭解 API 目錄資源和探索文件資源，請參閱使用 API 和參考資料文件。
作業套件
您可以在 Google API 探索服務中針對集合和資源叫用兩種不同的方法，如下表所述。
| 作業 | 說明 | REST HTTP 對應 |
|---|---|---|
| list | 列出所有支援的 API。 | 目錄資源 URI 中的 GET。 |
通話風格
REST
支援的 Google API 探索服務作業會直接對應至 REST HTTP GET 動詞，如作業一節所述。
Google API 探索服務 URI 的具體格式為：
https://discovery.googleapis.com/discovery/v1/apis?parameters
其中 api 是探索文件資源的 ID，version 則是特定 API 版本的 ID，而 _parameters_ 則是要套用至查詢的參數。詳情請參閱參考說明文件中的查詢參數摘要
關於 API 中各項支援作業的完整 URI 組合，請參閱 Google API 探索服務參考資料文件。
以下舉例說明 Google API 探索服務的運作方式。
列出所有 Google API 探索服務支援的 API：
GET https://discovery.googleapis.com/discovery/v1/apis
取得 Google Cloud Service Management API 第 1 版探索文件：
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1