本頁面由 Cloud Translation API 翻譯而成。

使用 Discovery API

本文件適用於想要編寫用戶端程式庫、IDE 外掛程式和其他與 Google API 互動的工具的開發人員。透過 Google API 探索服務，您可以透過簡單的 API 公開其他 Google API 的機器可讀中繼資料，執行上述所有操作。本指南將概略介紹 Discovery 文件的各個部分，並提供實用提示，說明如何使用這份文件。

所有對 API 的呼叫都是未經驗證的 REST 要求，使用 SSL 和以 JSON 為基礎，也就是網址開頭為 https。

探索文件格式

本節將概略介紹探索文件。

以下所有範例都使用 Service Usage API 的探索文件。您可以執行這項 GET 要求，為 Service Usage API 載入 Discovery 文件：

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

Discovery 文件的格式包含六大類別的資訊：

API 的基本說明。
API 的驗證資訊。
資源和結構定義詳細資料，說明 API 的資料。
API 方法的詳細資訊。
關於 API 支援的任何自訂功能的資訊。
內嵌說明文件：說明 API 的關鍵元素。

下文將說明每個 Discovery 文件部分。

基本 API 說明

Discovery 文件包含一組 API 專屬屬性。這些屬性不一定會按照這個順序顯示，也不一定會顯示在探索文件的同一節中：

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

這些 API 層級屬性包含特定 API 版本的詳細資料，包括 name、version、title 和 description。protocol 一律會設為固定值 rest，因為 API 探索服務只支援 RESTful 方法來存取 API。

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": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

auth 部分只會定義特定 API 的範圍。如要瞭解這些範圍如何與 API 方法相關聯，請參閱下方的「方法」一節。

資源和結構定義

API 的作業會對名為 resources 的資料物件執行操作。Discovery 文件是以資源概念為基礎而建構，每份 Discovery 文件都有一個頂層 resources 區段，用於將與 API 相關聯的所有資源分組。舉例來說，Service Usage API 在頂層 resources 下有 services 資源和 operations 資源：

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

每個資源專區內都會列出與該資源相關聯的方法。舉例來說，Service Usage API 有六個與 services 資源相關聯的方法：get、enable、disable、batchGet、batchEnable 和 list。

結構定義可讓您瞭解 API 中的資源長什麼樣子。每個 Discovery 文件都有頂層 schemas 區段，其中包含結構定義 ID 與物件的名稱/值組合。每個 API 都有專屬的結構定義 ID，用於在探索文件的 methods 部分中，準確識別結構定義。舉例來說，以下是 Service Usage API Discovery 文件中的幾個結構定義：

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

API 探索服務會使用 JSON 結構定義草稿 03 來呈現結構定義。以下是 EnableServiceResponse 資源的 JSON 結構定義程式碼片段，以及該程式碼參照的 GoogleApiServiceusagev1Service。除了這些結構定義之外，還有部分實際回應，用於啟用 Pub/Sub API 的要求 (pubsub.googleapis.com)。

EnableServiceResponse 資源 JSON 結構定義： 啟用服務的實際回應：

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

以粗體顯示的欄位會顯示 JSON 結構定義與實際回應之間的對應關係。

如本範例所示，結構定義可以包含其他結構定義的參照。如果您正在建構用戶端程式庫，這項功能可協助您在資料模型類別中有效模擬 API 的物件。在上述 EnableServiceResponse 範例中，service 屬性是 ID 為 GoogleApiServiceusageV1Service 的結構定義參照，也就是 Service Usage API Discovery 文件中的另一個結構定義。您可以將 EnableServiceResponse 資源中的 GoogleApiServiceusageV1Service 屬性替換為 GoogleApiServiceusageV1Service 結構定義的值 (請注意，$ref 語法來自 JSON 結構定義規格)。

方法在指示要求和回應體時，也可能會參照結構定義。詳情請參閱「方法」一節。

方法

Discovery 文件的核心是圍繞方法建構。方法是可在 API 上執行的作業。您會在 Discovery 文件的各個區段中找到 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、enable 和 disable：

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

最後，每個方法的部分會詳細說明該方法的各種屬性。以下是 enable 方法的範例：

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

本節包含一般方法詳細資料，例如用於識別方法的唯一 ID、要使用的 httpMethod，以及方法的 path。如要進一步瞭解如何使用 path 屬性來計算完整方法網址，請參閱「編寫要求」一節。除了這些一般方法屬性外，還有幾個屬性可將方法與探索文件中的其他部分連結：

範圍

本文件稍早定義的 auth 部分包含特定 API 支援的所有範圍相關資訊。如果方法支援其中一個範圍，就會有 scopes 陣列。這個陣列中每個項目都代表方法支援的一個範圍。

請注意，選擇應用程式要使用的授權範圍取決於各種因素，例如要呼叫哪些方法，以及要與方法一併傳送哪些參數。因此，開發人員可以決定要使用哪個範圍。僅限探索的文件，其中的範圍是方法的有效範圍。

要求和回應

如果方法含有要求或回應本體，則會分別在 request 或 response 部分記錄這些項目。舉例來說，對於 enable 方法，request 區段的內容表示該方法的要求是由 ID 為 EnableServiceRequest 的 JSON 結構定義。這個結構定義位於頂層結構定義部分。

參數

如果方法含有使用者應指定的參數，這些參數會記錄在方法層級的 parameters 區段中。本節包含參數名稱的鍵/值對應，以及該參數的詳細資料。

舉例來說，enable 方法有一個參數：name。參數可放入 path 或網址 query；location 屬性會指出用戶端程式庫應放置參數的位置。

還有許多其他屬性可用來描述參數，包括參數資料 type (適用於強型別語言)、參數是否為 required，以及參數是否為枚舉。如要進一步瞭解這些屬性，請參閱此 API 的參考說明文件。

參數順序

用戶端程式庫可以透過多種方式建構介面。方法簽章中包含每個 API 參數。不過，由於 JSON 是無序格式，因此很難透過程式設計瞭解如何在方法簽章中排序參數。parameterOrder 陣列會提供固定的參數排序，用於提出要求。陣列會依重要性順序列出每個參數的名稱，可包含路徑或查詢參數，但陣列中的每個參數都是必要的。

上傳媒體

如果方法支援上傳媒體 (例如圖片、音訊或影片)，則上傳該媒體時支援的位置和通訊協定會記載在 mediaUpload 部分。本節將詳細說明支援哪些上傳通訊協定，以及可上傳哪些類型的媒體。

enable 方法不含 mediaUpload 部分。不過，一般 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 屬性是 media-ranges 清單，可決定可上傳的 mime 類型。上方範例中的端點會接受任何圖片格式。

maxSize 資源有上傳大小上限。這個值是 MB、GB 或 TB 單位的字串。在上例中，上傳檔案大小上限為 10 MB。請注意，這個值不會反映個別使用者針對該 API 的剩餘儲存空間配額，因此即使上傳量小於 maxSize，用戶端程式庫仍應準備好處理因空間不足而上傳失敗的情況。

protocols 部分會列出方法支援的上傳通訊協定。simple 通訊協定只會在單一 HTTP 要求中，將媒體 POST 至指定端點。resumable 通訊協定暗示 path URI 中提供的端點支援續傳上傳通訊協定。如果 multipart 屬性為 true，則端點會接受多部分上傳，也就是說 JSON 要求和媒體可以一起包裝在 mutlipart/related 主體中，並一起傳送。請注意，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 建構媒體下載網址。

注意：一個 API 方法可同時支援媒體下載和上傳。媒體上傳和下載的網址要求建構邏輯會獨立運作，不會互相干擾。因此，這類 API 方法會提供一個用於媒體下載的 /download/... 網址，以及一個用於媒體上傳的 /upload/... 網址。不過，無法在單一要求中上傳及下載媒體。

常見參數

頂層探索文件包含 parameters 資源。這個部分類似於各個方法的參數部分，但這些參數可套用至 API 中的任何方法。

舉例來說，Service Usage API 的 get 和 list 方法可在要求參數中包含 prettyPrint 參數，以便以人類可讀的格式，為所有這些方法格式化回應。以下列出常見的參數：

參數	意義	附註	適用性
`access_token`	目前使用者的 OAuth 2.0 憑證。	提供 OAuth 2.0 憑證的一種可能方式。
`alt`	回應資料格式。	有效值：`json`、`atom`、`csv`。預設值：視 API 而定。並非所有 API 都支援所有值。	適用於所有資源的所有作業。
`callback`	回呼函式。	負責處理回應的 JavaScript 回呼函式名稱。用於 JavaScript JSON-P 要求。
`fields`	選擇工具，用於指定要包含在回應中的欄位子集。	用於提升效能。
`key`	API 金鑰。(必要)	除非您提供 OAuth 2.0 憑證，否則此為必要參數。您的 API 金鑰可識別專案並為您提供 API 存取權、配額和報表。您可以透過 API 控制台取得專案的 API 金鑰。
`prettyPrint`	傳回包含縮排和分行符號的回應。	如果為 `true`，則以使用者能夠理解的格式傳送回應。預設值：視 API 而定。當這個值是 `false` 時，可以縮減回應的酬載大小，在某些環境中或許可提升效能。
`quotaUser`	`userIp` 的替代方案。	讓您在使用者 IP 位址不明的情況下，也能透過伺服器端的應用程式強制執行每個使用者的配額限制。舉例來說，如果是代表使用者在 App Engine 上執行 cron 工作的應用程式，就可能發生這種情形。您可以選擇用來識別使用者的任意字串，但上限為 40 個字元。如果兩者都提供就會覆寫 `userIp`。進一步瞭解如何限制用量。
`userIp`	進行 API 呼叫時，受呼叫的使用者 IP 位址。	讓您在透過伺服器端應用程式呼叫 API 時，強制執行每個使用者的配額限制。進一步瞭解如何限制用量。

內嵌說明文件

每份 Discovery 文件都會附註多個 description 欄位，提供 API 內嵌說明文件。下列 API 元素可找到 description 欄位：

API 本身
個 OAuth 範圍
資源結構定義
API 方法
方法參數
特定參數的可接受值

如果您想使用 Google API 探索服務為用戶端程式庫產生人類可讀的說明文件 (例如 JavaDoc)，這些欄位就特別實用。

使用 Discovery API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

探索文件格式

基本 API 說明

驗證

資源和結構定義

方法

範圍

要求和回應

參數

上傳媒體

媒體下載

常見參數

內嵌說明文件

使用 Discovery API