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 和 tilde (~)，藉此建構該物件的複合 ID。

舉例來說，廣告群組廣告 ID 並非全域唯一，因此會在前面加上父項物件 (廣告群組) ID，產生專屬的複合 ID。

範例：123 的 AdGroupId + 45678 的 ~ + AdGroupAdId = 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 標頭是用於識別要求的專屬字串。