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 會在前面加上父項 ID 和波浪號 (~)。

舉例來說，由於廣告群組廣告 ID 並非全域唯一，因此我們會在其上層物件前加上其父物件 (廣告群組) ID，藉此建立專屬的複合編號：

  • 123 中的 AdGroupId + ~ + AdGroupAdId (共 45678) = 合併廣告群組廣告 ID：123~45678。

要求標頭

這些要求包含要求主體中的 HTTP 標頭 (或 grpc 中繼資料)：

授權

您必須以 Authorization: Bearer YOUR_ACCESS_TOKEN 的形式加入 OAuth2 存取憑證，以識別代表用戶端執行動作的管理員帳戶，或是直接管理自己的帳戶的廣告客戶。您可以在 OAuth2 指南中找到擷取存取憑證的操作說明。存取憑證在取得後的一小時內有效；當存取權杖過期時，請重新整理存取權杖以擷取新的權杖。請注意，我們的用戶端程式庫會自動重新整理過期的權杖。

開發人員權杖

開發人員權杖是一組由 22 個字元組成的字串，可用來識別 Google Ads API 開發人員。開發人員權杖字串為 ABcdeFGH93KL-NOPQ_STUv。開發人員權杖應以 developer-token : ABcdeFGH93KL-NOPQ_STUv 的形式加入。

login-customer-id

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

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

設定 login-customer-id 等同於在登入或點選右上角的個人資料圖片後，在 Google Ads UI 中選擇帳戶。如未加入這個標頭，則預設為「營運客戶」。

連結的客戶 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 結尾中繼資料)。建議您記錄這些值以用於偵錯。

要求 ID

request-id 是唯一可識別這個要求的字串。

上一頁
資源中繼資料