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,因此我們會在其前方加上父項物件 (廣告群組) ID,藉此成為不重複的複合 ID:

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

要求標頭

以下是要求中與內文一起顯示的 HTTP 標頭 (或 grpc 中繼資料):

授權

您需要加入 OAuth2 存取權杖,格式為 Authorization: Bearer YOUR_ACCESS_TOKEN,以識別代表用戶端的管理員帳戶,或是由廣告主直接管理自己的帳戶。如需擷取存取權杖的操作說明,請參閱 OAuth2 指南。存取權杖在取得後的一小時內有效;如果權杖過期,請重新整理存取權杖以擷取新的權杖。請注意,用戶端程式庫會自動重新整理過期的權杖。

開發人員權杖

開發人員權杖是一組由 22 個字元組成的字串,專門用來識別 Google Ads API 開發人員。範例開發人員權杖字串為 ABcdeFGH93KL-NOPQ_STUv。開發人員權杖應包含在 developer-token : ABcdeFGH93KL-NOPQ_STUv 的形式中。

login-customer-id

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

https://googleads.googleapis.com/v16/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 Trailing-metadata)。建議您記錄這些值以便進行偵錯。

request-id

request-id 是專門用來識別此要求的字串。