API 呼叫結構

本指南將說明所有 API 呼叫的一般結構。

如果您使用用戶端程式庫與 API 互動，就不需要瞭解底層要求的詳細資料。不過，在測試和偵錯時，您可能會需要一些 API 呼叫結構的相關知識。

Google Ads API 是採用 REST 繫結的 gRPC API。也就是說，您可以透過兩種方式呼叫 API。

建議採用：

  1. 將要求主體建立為通訊協定緩衝區。

  2. 使用 HTTP/2 傳送至伺服器。

  3. 將回應反序列化為通訊協定緩衝區。

  4. 解讀結果。

大部分的說明文件都會說明如何使用 gRPC。

選用：

  1. 將要求的內文建立為 JSON 物件。

  2. 使用 HTTP 1.1 將其傳送至伺服器。

  3. 將回應反序列為 JSON 物件。

  4. 解讀結果。

如要進一步瞭解如何使用 REST，請參閱 REST 介面指南。

資源名稱

API 中的大多數物件會透過資源名稱字串進行識別。使用 REST 介面時，這些字串也會做為網址使用。如要瞭解其結構，請參閱 REST 介面的資源名稱。

複合 ID

如果物件的 ID 並非全域不重複，則會在前面加上父項 ID 和 tilde (~)，藉此建構該物件的複合 ID。

舉例來說，廣告群組廣告 ID 並非全域唯一，因此我們會在前面加上其父項物件 (廣告群組) ID，以產生不重複的複合 ID：

  • 123 的 AdGroupId + ~ + 45678 的 AdGroupAdId = 123~45678 的複合廣告群組廣告 ID。

要求標頭

以下是要求中內文隨附的 HTTP 標頭 (或 grpc 中繼資料)：

授權

您必須在 Authorization: Bearer YOUR_ACCESS_TOKEN 表單中加入 OAuth2 存取權權杖，以便識別代表客戶行事的管理員帳戶，或是直接管理自身帳戶的廣告主。如要瞭解如何擷取存取權杖，請參閱 OAuth2 指南。存取權杖的效期為取得後的一小時，過期後請重新整理存取權杖，以便擷取新的存取權杖。請注意，我們的用戶端程式庫會自動重新整理過期權杖。

developer-token

開發人員權杖是 22 個字元的字串，用於識別 Google Ads API 開發人員。開發人員權杖字串的範例為 ABcdeFGH93KL-NOPQ_STUv。開發人員權杖應以 developer-token : ABcdeFGH93KL-NOPQ_STUv 的形式提供。

login-customer-id

這是授權客戶的客戶 ID，可用於要求中，不含連字號 (-)。如果您是透過管理員帳戶存取客戶帳戶，則此標頭為必要，且必須設為管理員帳戶的客戶 ID。

https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate

設定 login-customer-id 的做法，等同於登入 Google Ads 使用者介面後，在該介面中選擇帳戶或按一下右上方的個人資料相片。如果未納入這個標頭，系統會預設為運作客戶。

linked-customer-id

這個標頭僅供 [第三方應用程式數據分析供應商]使用，用於將轉換資料上傳至已連結的 Google Ads 帳戶。

請考慮以下情境：帳戶 A 的使用者透過 ThirdPartyAppAnalyticsLink 為帳戶 B 提供實體的讀取和編輯存取權。連結完成後，帳戶 B 的使用者就能根據連結提供的權限，對帳戶 A 發出 API 呼叫。在這種情況下，帳戶 A 的 API 呼叫權限是由帳戶 B 的第三方連結決定，而非其他 API 呼叫中使用的管理員-帳戶關係。

第三方應用程式分析供應商會發出以下 API 呼叫：

  • linked-customer-id：上傳資料的第三方應用程式數據分析帳戶 (帳戶 B)。
  • customer-id：資料上傳的 Google Ads 帳戶 (帳戶 A)。
  • login-customer-id 和 Authorization 標頭：值組合，用於識別有���存取���戶 B 的使用者。

回應標頭

系統會隨回應內文傳回下列標頭 (或 grpc trailing-metadata)。建議您記錄這些值，以利偵錯。

request-id

request-id 是用於識別這項要求的字串。

上一頁
資源中繼資料