Search Ads 360 Reporting API 呼叫結構

呼叫 Search Ads 360 Reporting API 時，通常會透過用戶端程式庫進行。詳情請參閱用戶端程式庫說明。不過，在測試和偵錯時，瞭解基礎要求詳細資料的結構會很實用。

Search Ads 360 Reporting API 是帶有 REST 繫結的 gRPC API。換句話說，您可以透過下列兩種方式呼叫 API：

首選方式
使用用戶端程式庫：
  • 建立要求的主體做為通訊協定緩衝區。
  • 使用 HTTP/2 將要求傳送至伺服器。
  • 將通訊協定緩衝區的回應反序列化。
  • 解讀結果。
選用替代方法
使用 REST：
  • 以 JSON 物件的形式建立要求主體。
  • 使用 HTTP 1.1 將要求傳送至伺服器。
  • 將回應反序列化為 JSON 物件。
  • 解讀結果。

詳情請參閱「Google Cloud API」。

以下各節適用於 gRPC 和 REST 通訊協定。

資源名稱

API 中的大多數物件都是以資源名稱字串識別。使用 REST 介面時，這些字串也會做為網址使用。

如要進一步瞭解支援的資源及其路徑表示法，請參閱參考資料 > REST。其他服務也使用相同的格式。

複合 ID

如果物件的 ID 不是「全域唯一」，則在建構該物件的複合 ID 時，系統會在其父項 ID 和波浪號 (~) 前面加上該 ID。

舉例來說，由於廣告群組廣告 ID 沒有全域唯一性，因此系統會在前面加入父項物件 (廣告群組) ID 以產生不重複的複合 ID。

範例：AdGroupId123 + ~ + AdGroupAdId/45678 = 123~45678 的複合廣告群組廣告 ID。

要求標頭

要求內文應包含下列部分的 HTTP 標頭 (或 gRPC 中繼資料)。

授權

您必須按照下列格式加入 OAuth2 存取權杖：

Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

該憑證應識別代表客戶行事的管理員帳戶，或直接管理其副管理員或客戶帳戶的廣告客戶。詳情請參閱「關於 Search Ads 360 管理員帳戶」和「驗證」這兩篇文章。

登入客戶 ID 標頭

使用管理員帳戶存取副管理員或客戶帳戶時，必須使用 login-customer-id 標頭。如果直接存取副管理員或客戶帳戶，則不需要用到這些資料。雖然這不是硬性規定，但建議您一律為可存取多個帳戶且經過驗證的使用者指定 login-customer-id。這樣可以避免混淆，並避免不小心將情境設為錯誤的帳戶。

要求應包含授權使用者的客戶 ID，不含連字號 (-)，例如：

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets

設定 login-customer-id 等同於在登入或點選右上角的個人資料圖片後，在 Search Ads 360 UI 中選擇帳戶。

回應標頭

下列標頭 (或 gRPC 結尾中繼資料) 會與回應主體一併傳回。建議您記錄這些值，以便進行偵錯。

要求 ID

request-id 標頭是專門識別要求的字串。