引言
本文件的適用對象為想編寫用戶端程式庫、IDE 外掛程式和其他與 Google API 互動的工具。Google API 探索服務可讓您運用簡單的 API，公開機器可讀取的其他 Google API 中繼資料，達成上述目的。本指南將概略介紹探索文件的各個部分，並提供實用的使用提示。
所有對 API 的呼叫都是未經驗證且採用 JSON 的 REST 要求，即使用安全資料傳輸層 (SSL)，即網址開頭為 https。
如果您不熟悉 Google API 探索服務概念，請先閱讀入門指南，再開始撰寫程式碼。
探索文件格式
本節將概略介紹探索文件。
以下示例均使用 Google Cloud Service Management API 的探索文件。只要執行這個 GET 要求，即可載入 Google Cloud Service Management API 的探索文件：
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1探索文件的格式包含以下六大類別的資訊：
- API 的基本說明。
- API 的驗證資訊。
- 說明 API 資料的資源和結構定義詳細資料。
- 進一步瞭解 API's 方法。
- API 支援的任何自訂功能相關資訊。
- 內嵌說明文件：說明 API 的主要元素。
以下將詳細說明這些探索文件部分。如要進一步瞭解各項屬性，請參閱參考資料說明文件。
基本 API 說明
探索文件包含一組 API 專屬屬性：
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
這些 API 級別屬性包含特定 API 版本的詳細資料，包括 name、version、title 和 description。由於 API 探索服務僅支援以 REST 方式存取 API，因此 protocol 的固定值一律是 rest。
servicePath 欄位代表這個特定 API 版本的路徑前置字串。
驗證
「auth」部分包含 API 的 OAuth 2.0 驗證範圍詳細資料。如要進一步瞭解如何在 OAuth 2.0 中使用範圍，請參閱使用 OAuth 2.0 存取 Google API。
auth 區段包含巢狀的 oauth2 和 scopes 區段。scopes 區段是範圍/鍵的對應範圍值，提供更多關於範圍的詳細資料：
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
auth 區段只會定義特定 API 的範圍。如要瞭解這些範圍與 API 方法之間的關聯，請參閱下方的方法一節。
資源和結構定義
API 的作業稱為 resources 資料物件。探索文件是以資源概念為基礎，每個探索文件都有頂層 resources 區段，會將所有與 API 相關的資源分組。舉例來說，Google Cloud Service Management API 擁有 services 資源，以及頂層 resources 下的 operations 資源。services 資源有三項子資源：configs、rollouts 和 consumers：
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
每個資源部分內都是與資源相關聯的方法。舉例來說，Google Cloud Service Management API 提供三種與 services.rollouts 資源相關聯的方法：get、list 和 create。
結構定義可讓您瞭解 API 中的資源。每個探索文件都有頂層 schemas 區段，其中包含各物件的結構定義 ID 名稱/值配對。每個 API 的架構 ID 均不重複，可用來在探索文件的 methods 部分明確識別結構定義：
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
API 探索服務會使用 JSON 結構定義草稿-03 做為結構定義表示法。以下是網址資源的 JSON 結構定義程式碼片段，以及實際的回應資源：
| 推出資源 JSON 結構定義： | 實際推出資源回應： |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
粗體的欄位代表 JSON 結構定義與實際回應之間的對應關係。
架構也可能包含其他結構定義的參照。如果您打算建構用戶端程式庫，這可協助您在資料模型類別中有效建立 API 物件模型。在上述的 Rollout 範例中，trafficPercentStrategy 屬性實際上是 ID 為 TrafficPercentStrategy 的結構定義的參照。如果您查看 schemas 部分，就會看到 TrafficPercentStrategy 結構定義。此結構定義的值可替換成 Rollout 資源中的 trafficPercentStrategy 屬性 (請注意，$ref 語法來自 JSON 結構定義規格)。
方法也可能在表示要求和回應主體時參照結構定義。詳情請參閱「方法」一節。
方法
探索文件的核心是以建立方法為基礎。方法可透過 API 執行的作業，您可以在探索文件的各個部分中找到 methods 部分，包括頂層 (我們稱為 API 層級方法) 或 resources 層級。
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
雖然 API 「可以」使用 API 層級方法，但資源「必須」具有 methods 區段。
每個 methods 區段都是鍵/值對應，當中包含方法名稱以及該方法的其他詳細資料。以下範例記錄了三個方法：get、list 和 create：
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
最後，每個方法的章節會詳細說明該方法的各種屬性。以下是 get 方法的範例：
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
本節包含一般方法詳細資料，例如專屬的 ID 來識別方法、要使用的 httpMethod 和該方法的 path (如要進一步瞭解如何使用 path 屬性計算完整方法網址，請參閱「傳送要求」一節)。除了這些一般方法屬性外，還有幾種屬性可將探索方法連結至探索文件中的其他部分：
範圍
本說明文件先前設定的 auth 部分包含特定 API 支援的所有範圍資訊。如果方法支援其中一個範圍，則會有範圍陣列。在這個陣列中，每個支援的範圍都有一個項目。舉例來說，Google Cloud Service Management API get 方法的 scopes 區段如下所示：
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
請注意，選擇要在應用程式中使用的驗證範圍，取決於許多因素，例如要呼叫的方法，以及要在方法中傳送的參數。因此，開發人員選擇要使用哪個範圍。探索功能只會追蹤範圍受方法影響的文件。
要求與回應
如果此方法提供要求或回應主體，系統會分別記錄在 request 或 response 區段中。在上述 get 範例中，此方法有 response 主體：
"response": {
"$ref": "Rollout"
}
上述語法表示回應主體是由 ID 為 Rollout 的 JSON 結構定義定義。這個結構定義位於頂層結構定義部分。要求和回應主體都使用 $ref 語法來參照結構定義。
參數
如果方法包含應由使用者指定的參數，則這些參數會記錄在方法層級的 parameters 區段中。本節包含參數名稱的鍵/值對應，以及該參數的詳細資訊：
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
在上述範例中，get 方法有兩個參數：serviceName 和 rolloutId。參數可輸入在 path 或網址 query 中；location 屬性會指出用戶端程式庫應在何處放置參數。
還有許多屬性相關說明，包括參數資料 type (適用於嚴格輸入的語言)、參數是否為 required，以及參數是否為列舉。如要進一步瞭解屬性，請參閱參考指南。
參數順序
在用戶端程式庫中，您可以透過多種方式建構介面。其中一種方法就是在方法簽章中使用每個 API 參數的方法。但是，由於 JSON 是未排序的格式，因此很難透過程式輔助方式知道如何排序方法簽章中的參數。parameterOrder 陣列提供傳送要求的固定參數順序。這個陣列會按照重要性列出每個參數的名稱；其中可包含路徑或查詢參數，但陣列中的每個參數都是必要項目。在上述範例中，Java 方法簽章看起來會像這樣：
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);parameterOrder 陣列中的第一個值 serviceName 也是方法簽章中的第一個元素。如果 parameterOrder 陣列中有其他參數，這些參數會放在 serviceName 參數之後。由於 parameterOrder 陣列只包含必要參數，因此建議使用者一併指定選用參數。以上範例使用 optionalParameters 地圖進行了這項操作。
媒體上傳
如果方法支援上傳媒體 (例如圖片、音訊或影片)，則 mediaUpload 區段中會說明上傳媒體時支援的位置和通訊協定。本節詳細介紹支援的上傳通訊協定，以及可上傳哪些類型的媒體資訊：
"supportsMediaUpload": true,
"mediaUpload": {
"accept": [
"image/*"
],
"maxSize": "10MB",
"protocols": {
"simple": {
"multipart": true,
"path": "/upload/storage/v1beta1/b/{bucket}/o"
},
"resumable": {
"multipart": true,
"path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
}
}
}
在上述範例中，supportsMediaUpload 屬性是布林值，用於判斷這個方法是否支援上傳媒體。如果值為 true，mediaUpload 區段會記錄可上傳的媒體類型。
accept 屬性是媒體範圍的清單，用於決定要上傳哪些 MIME 類型。上述範例中顯示的端點可接受任何圖片格式。
maxSize 屬性的上傳大小上限。這個值是以 MB、GB 或 TB 為單位的字串。在上述範例中，上傳內容的大小上限為 10 MB。請注意，這個值不會反映個別使用者的 API 剩餘儲存空間配額，因此即使上傳次數少於 maxSize，用戶端程式庫仍可準備處理因空間不足而失敗的上傳作業。
protocols 區段會列出方法支援的上傳通訊協定。simple 通訊協定只是將媒體張貼到單一 HTTP 要求中的指定端點。resumable 通訊協定暗示 path URI 中指定的端點支援可恢復的上傳通訊協定。如果 multipart 屬性為 true，則端點接受多個部分的上傳作業。也就是說，JSON 要求和媒體可以包裝在多個 / 相關主體中，並一起傳送。請注意，simple 和 resumable 通訊協定都支援多部分上傳作業。
path 屬性是 URI 範本，其展開方式與方法的 path 屬性相同，如「編寫要求」一節所述。
媒體下載
如果方法支援下載圖片 (例如圖片、音訊或影片)，supportsMediaDownload 參數會指定：
"supportsMediaDownload": true,
下載媒體時，您必須在要求網址中將 alt 查詢參數設為 media。
如果 API 方法的 useMediaDownloadService 屬性為 true，請在 servicePath 之前插入 /download 以避免重新導向。舉例來說，如果 servicePath 和 path 的串連為 /youtube/v3/captions/{id}，下載路徑就會是 /download/youtube/v3/captions/{id}。即使 useMediaDownloadService 為 False，我們仍建議您使用 /download 建構媒體下載網址。
常見參數
頂層探索文件包含 parameters 屬性。這個部分與每個方法的參數部分類似，但這些參數可以套用至 API 中的任何方法。
舉例來說，Google Cloud Service Management API 的 get、insert 或 list 方法可以在要求參數中加入 prettyPrint 參數，並以使用者可理解的格式格式化所有方法的回應。以下為常見的參數清單：
| 參數 | 意義 | 附註 | 適用性 |
|---|---|---|---|
access_token |
目前使用者的 OAuth 2.0 憑證。 |
|
|
alt |
回應的資料格式。 |
|
|
callback |
回呼函式。 |
| |
fields |
選擇工具，用於指定要包含在回應中的欄位子集。 |
|
|
key |
API 金鑰 (必要*) | ||
prettyPrint |
傳回包含分項與斷行的回覆。 |
|
|
quotaUser |
userIp 的替代選項。 |
|
|
userIp |
進行 API 呼叫時，受呼叫的使用者 IP 位址。 |
|
功能與特色
在某些情況下，API 支援探索文件其他部分的自訂功能。這會在 features 陣列中收集。特徵陣列包含 API 支援的每個特殊功能的字串標籤。目前僅支援 dataWrapper 的功能，但日後可能會支援其他功能。
"features": dataWrapper
dataWrapper 功能表示所有來自 API 的要求和回應均包裝在 data JSON 物件中。這是舊版 Google API 的功能，但日後即將淘汰。下列 API 支援 dataWrapper 功能：管理員 v1 和 翻譯 v2。
在用戶端程式庫開發人員中，如果 API 支援「dataWrapper」功能，則應執行下列操作：
- 請求：將要求資源納入
dataJSON 物件中。 - 回應：在
dataJSON 物件中尋找資源。
探索文件中的結構定義不含資料包裝函式，因此您必須明確新增及移除相關結構定義。舉例來說，假設有一個 API 含有名為「Foo」的資源：
{
"id": 1,
"foo": "bar"
}
使用 API 插入這項資源之前，您必須先將其包裝在資料元素中：
{
"data": {
"id": 1,
"foo": "bar"
}
}
反過來，當您從 API 取得回應時，其中也會包含資料包裝函式：
{
"data": {
"id": 1,
"foo": "bar"
}
}
如要取得由結構定義定義的資源，您必須移除資料包裝函式：
{
"id": 1,
"foo": "bar"
}
內嵌說明文件
每個探索文件都會加註多個 description 欄位，為 API 提供內嵌文件。下列 API 元素皆可使用 description 欄位：
- API 本身
- OAuth 範圍
- 資源結構定義
- API 方法
- 方法參數
- 特定參數可接受的值
如果您想使用 Google API 探索服務來產生用戶端程式庫 (例如 JavaDoc) 的可讀說明文件，這些欄位就特別實用。