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