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/v12/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-idAuthorization 標頭:指定值的組合,以識別有權存取帳戶 B 的使用者。

回應標頭

系統會透過回應主體傳回下列標頭 (或 grpc 結尾中繼資料)。建議您記錄這些值以用於偵錯。

要求 ID

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