API 呼叫結構

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

如果您使用用戶端程式庫與 API 互動，就不必擔心底層要求的詳細資料。不過，在測試和偵錯時，瞭解這些概念會很有幫助。

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

  1. [建議] 將要求的內容建立為通訊協定緩衝區，使用 HTTP/2 傳送至伺服器，將回應反序列化為通訊協定緩衝區，並解讀結果。大多數說明文件都會說明如何使用 gRPC。

  2. [選用] 建立要求主體做為 JSON 物件，使用 HTTP 1.1 傳送至伺服器，將回應反序列為 JSON 物件，並解讀結果。如要進一步瞭解如何使用 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/v19/customers/1234567890/campaignBudgets:mutate

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

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 是用於識別這項要求的字串。

上一頁
資源中繼資料