API 呼叫結構

本指南說明所有 API 呼叫的常見結構。

如果您使用用戶端程式庫與 API 互動，就不需要瞭解基礎要求詳細資料。不過，在測試和偵錯時，瞭解 API 呼叫結構會很有幫助。

Google Ads API 是 gRPC API，具有 REST 繫結。也就是說，您可以透過兩種方式呼叫 API。

建議採用：

  1. 以通訊協定緩衝區的形式建立要求主體。
  2. 使用 HTTP/2 將其傳送至伺服器。
  3. 將回應反序列化為通訊協定緩衝區。
  4. 解讀結果。

我們的大部分說明文件都描述如何使用 gRPC。

選用：

  1. 以 JSON 物件形式建立要求主體。
  2. 使用 HTTP 1.1 將其傳送至伺服器。
  3. 將回應還原序列化為 JSON 物件。
  4. 解讀結果。

如要進一步瞭解如何使用 REST，請參閱 REST 介面指南。

資源 ID

Google Ads API 中的物件會使用結構化資源名稱和複合 ID 定址。

資源名稱

API 中的大多數物件都是透過資源名稱字串識別。使用 REST 介面時，這些字串也會做為網址。如要瞭解結構，請參閱 REST 介面的資源名稱。

複合 ID

如果物件的 ID 不是全域專屬 ID，系統會為該物件建構複合 ID，方法是在物件的 ID 前加上父項 ID 和半形波浪號 (~)。

舉例來說，AdGroupAd 的資源名稱模式為 customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}。由於複合 ID 結合了上層廣告群組 ID (ad_group.id) 和基礎廣告 ID (ad_group_ad.ad.id)，因此我們會在廣告 ID 前加上廣告群組 ID：

  • AdGroupId 則 (建議 123 則以上) + ~ + AdId 則 (建議 45678 則以上) = 複合廣告群組 123~45678 的廣告 ID。

要求標頭

這些是要求中與主體一併傳送的 HTTP 標頭 (或 gRPC 中繼資料)：

授權

您必須以 Authorization: Bearer YOUR_ACCESS_TOKEN 形式加入 OAuth 2.0 存取權杖，用來識別代表客戶執行的管理員帳戶，或是直接管理自己帳戶的廣告主。如需如何擷取存取權杖的操作說明，請參閱 OAuth2 指南。存取權杖的效期為一小時，過期後請重新整理存取權杖，以擷取新的權杖。請注意，我們的用戶端程式庫會自動重新整理過期的權杖。

如果發生授權錯誤，請確認您使用的憑證正確無誤，且具備足夠的權限。USER_PERMISSION_DENIED 錯誤表示經過驗證的使用者可能無法存取要求中指定的客戶帳戶。如果您的 Google Cloud 雲端專案僅獲准存取 Test，且您傳送的請求是以正式版帳戶為目標，則 API 會在第 25 版以上傳回 AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION (或在第 24 版以下傳回 AuthorizationError.ACTION_NOT_PERMITTED)。如要瞭解如何管理權限，請參閱「Google Ads 存取層級」。

login-customer-id

這是授權客戶的客戶 ID，用於要求中，不含連字號 (-)。如果透過管理員帳戶存取客戶帳戶，則必須提供這個標頭，並設為管理員帳戶的客戶 ID。如果您透過管理員帳戶進行驗證時未加入 login-customer-id，就會導致 AuthorizationError.USER_PERMISSION_DENIED 錯誤。如要進一步瞭解這類錯誤，請參閱常見錯誤。如要詳細瞭解如何解決帳戶存取權問題，請參閱「OAuth 存取權模型」指南。

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

設定 login-customer-id 等同於登入後在 Google Ads 使用者介面中選擇帳戶，或點選右上方的預設個人圖片。如未加入這個標題，系統會預設為營運客戶。

linked-customer-id

合作夥伴 (例如第三方應用程式數據分析供應商或資料合作夥伴) 對已連結的 Google Ads 帳戶採取行動時，必須使用這個標頭。這個標頭必須指定具有產品連結的 Google Ads 帳戶客戶 ID。

假設合作夥伴需要根據產品連結，對 Google Ads 帳戶發出 API 呼叫。

  • 廣告主：API 呼叫管理或更新的 Google Ads 帳戶。 要求中指定了廣告主帳戶 ID。在 REST 中，這是 customerId 路徑參數 (例如 customers/1111111111/...)，在 gRPC 中，這是要求中的 customer_id 欄位。
  • 合作夥伴：合作夥伴帳戶 (例如第三方應用程式分析供應商或資料合作夥伴)。
  • 已連結帳戶：與合作夥伴建立產品連結的 Google Ads 帳戶，授予合作夥伴廣告主存取權。

有權存取合作夥伴帳戶的使用者會發出 API 呼叫，對廣告主帳戶中的實體採取行動 (例如上傳轉換或管理使用者名單)。「已連結帳戶」可以是「廣告主」帳戶 本身，也可以是「廣告主」帳戶的管理員帳戶。

要求標頭必須設定如下：

  • Authorization：有權存取合作夥伴的使用者 OAuth 2.0 存取權杖。
  • login-customer-id：合作夥伴帳戶的客戶 ID。通過驗證的使用者必須有這個帳戶的存取權。
  • linked-customer-id：已連結帳戶的客戶 ID。這個標頭表示這項要求的授權依據是連結帳戶與合作夥伴的產品連結。

連結情境有兩種：

  • 如果廣告主帳戶與合作夥伴帳戶有直接產品連結，則已連結帳戶為廣告主，且 linked-customer-id 必須設為廣告主帳戶的客戶 ID。
  • 如果廣告主帳戶是由與合作夥伴帳戶有產品連結的管理員帳戶管理，則已連結帳戶為管理員帳戶，且 linked-customer-id 必須設為管理員的客戶 ID。

範例 1：直接連結

如果廣告主帳戶 1111111111 與合作夥伴帳戶 2222222222 直接連結，且 API 呼叫的目標是 customers/1111111111/...：

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

範例 2：管理員連結

如果廣告主帳戶 1111111111 由管理員帳戶 3333333333 管理，管理員帳戶 3333333333 與合作夥伴帳戶 2222222222 之間有連結，且 API 呼叫的目標是 customers/1111111111/...：

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

回應標頭

下列標頭 (或 gRPC 尾端中繼資料) 會連同回應內文一併傳回。建議您記錄這些值，以利進行偵錯。

要求 ID

request-id 是用於識別這項要求的專屬字串。與支援團隊聯絡時，請提供這個值，協助排解 API 要求失敗或無預期的問題。

上一頁
資源中繼資料