API 呼叫結構

本指南將說明所有 API 呼叫的通用結構。

如果您使用用戶端程式庫與 API 互動，就不需要擔心基礎要求的詳細資料。不過，在測試和偵錯時，如果能進一步瞭解這些函式，就可以派上用場。

Google Ads API 是帶有 REST 繫結的 gRPC API。換句話說，您可以透過兩種方式呼叫 API。

  1. [Preferred] 請建立要求主體做為通訊協定緩衝區，使用 HTTP/2 傳送至伺服器，將回應反序列化為通訊協定緩衝區，並解讀結果。我們的大部分說明文件都介紹如何使用 gRPC。

  2. [選用] 建立要求主體做為 JSON 物件、使用 HTTP 1.1 將要求傳送至伺服器、將回應序列化為 JSON 物件，並解讀結果。如要進一步瞭解如何使用 REST，請參閱 REST 介面指南。

資源名稱

API 中的大部分物件都是以資源名稱字串識別。使用 REST 介面時，這些字串也是網址。請參閱 REST 介面的「資源名稱」瞭解結構。

複合 ID

如果物件的 ID 並非全域不重複的，則該物件的複合 ID 會預先由其父項 ID 和波浪號 (~) 建構。

舉例來說，由於廣告群組廣告 ID 不具有重複性質，因此我們 為了提供專屬複合 ID，在前面加上父項物件 (廣告群組) ID：

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

要求標頭

以下是要求主體中的 HTTP 標頭 (或 grpc 中繼資料)：

授權

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

開發人員權杖

開發人員權杖是由 22 個字元組成的字串，可用來識別 Google Ads API 開發人員。開發人員權杖字串範例為 ABcdeFGH93KL-NOPQ_STUv。開發人員權杖應採用 developer-token : ABcdeFGH93KL-NOPQ_STUv 的形式。

login-customer-id

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

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

設定 login-customer-id 等同於在登入或點選右上方的個人資料相片後，在 Google Ads 使用者介面中選擇帳戶。如果您未提供這個標頭，則預設為作業系統客戶。

連結的客戶 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 trailing-metadata) 會在回應中傳回。建議您記錄這些值以用於偵錯。

request-id

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

上一頁
資源中繼資料