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 介面指南。

資源名稱

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

複合 ID

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

舉例來說，由於廣告群組廣告 ID 並非全域不重複，我們會將其父項物件 (廣告群組) ID 加到廣告群組廣告 ID 前面，藉此建立不重複的複合 ID：

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

要求標頭

這些是要求中隨附於主體的 HTTP 標頭 (或 grpc 中繼資料)：

授權

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

developer-token

開發人員權杖是 22 個字元的字串，用於專屬識別 Google Ads API 開發人員。開發人員權杖字串範例如下：ABcdeFGH93KL-NOPQ_STUv。開發人員權杖應以 developer-token : ABcdeFGH93KL-NOPQ_STUv 形式加入。

login-customer-id

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

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

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

linked-customer-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-id 和 Authorization 標頭：用來識別有權存取帳戶 B 的使用者。

回應標頭

下列標頭 (或 grpc 尾隨中繼資料) 會隨回應內文傳回。建議您記錄這些值，以利偵錯。

request-id

request-id 是用於識別這項要求的專屬字串。

上一頁
資源中繼資料