使用 API

引言

本文件的適用對象為想編寫用戶端程式庫、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 結構定義程式碼片段，以及實際的回應資源：

{
  "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 參數，並以使用者可理解的格式格式化所有方法的回應。以下為常見的參數清單：

功能與特色

在某些情況下，API 支援探索文件其他部分的自訂功能。這會在 features 陣列中收集。特徵陣列包含 API 支援的每個特殊功能的字串標籤。目前僅支援 dataWrapper 的功能，但日後可能會支援其他功能。

"features": dataWrapper

dataWrapper 功能表示所有來自 API 的要求和回應均包裝在 data JSON 物件中。這是舊版 Google API 的功能，但日後即將淘汰。下列 API 支援 dataWrapper 功能：管理員 v1 和 翻譯 v2。

在用戶端程式庫開發人員中，如果 API 支援「dataWrapper」功能，則應執行下列操作：

1. 請求：將要求資源納入 data JSON 物件中。
2. 回應：在 data JSON 物件中尋找資源。

探索文件中的結構定義不含資料包裝函式，因此您必須明確新增及移除相關結構定義。舉例來說，假設有一個 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) 的可讀說明文件，這些欄位就特別實用。

後續步驟

• 建立用戶端程式庫