API 呼叫結構

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

若您使用用戶端程式庫與 API 互動,就不需要擔心基礎要求的詳細資料。不過,如果對測試和偵錯很有助益,這項功能就可派上用場。

Google Ads API 是一種具備 REST 繫結的 gRPC API。這表示呼叫 API 的方法有兩種。

  1. [建議做法] 建立要求主體做為通訊協定緩衝區,使用 HTTP/2 將要求傳送至伺服器、將回應序列化為通訊協定緩衝區,並解讀結果。大部分的說明文件都描述瞭如何使用 gRPC。

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

資源名稱

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

複合 ID

如果物件的 ID 並非全域唯一的物件,該物件的複合 ID 就會由其上層 ID 和波浪號 (~) 的組成而建構。

舉例來說,由於廣告群組廣告 ID 沒有全域通用,因此我們在它前面加上其上層物件 (廣告群組) ID 以建立不重複的複合 ID:

  • 123」的AdGroupId + ~ + AdGroupAdId45678 = 綜合廣告群組廣告 ID:123~45678

要求標頭

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

授權

您必須加入 Authorization: Bearer YOUR_ACCESS_TOKEN 形式的 OAuth2 存取憑證,以便識別代表客戶行事的管理員帳戶,或是直接管理自己的帳戶的廣告客戶。如需擷取存取憑證的操作說明,請參閱 OAuth2 指南。存取憑證在取得後的一小時內有效;憑證到期後,請重新整理存取憑證以擷取新的憑證。請注意,我們的用戶端程式庫會自動更新過期的符記。

開發人員權杖

開發人員權杖是由 22 個字元組成的字串,可識別 Google Ads API 開發人員。開發人員權杖字串是 ABcdeFGH93KL-NOPQ_STUv。開發人員權杖應包含 developer-token : ABcdeFGH93KL-NOPQ_STUv 的形式。

登入客戶 ID

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

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

設定 login-customer-id 等同於在登入或點選右上角的個人資料相片時,在 Google Ads 使用者介面中選擇帳戶。如果您沒有包含此標頭,則根據預設,這個欄位會預設為「營運客戶」

連結的客戶編號

只有在您將轉換資料上傳至已連結的 Google Ads 帳戶時,第三方應用程式分析供應商才會用到這個標頭

請考慮帳戶 A 中的使用者透過 ThirdPartyAppAnalyticsLink 授予帳戶 B 的讀取及編輯權限。建立連結後,帳戶 B 的使用者即可根據帳戶提供的權限,針對帳戶 A 進行 API 呼叫。在本案例中,帳戶 A 的 API 呼叫權限取決於帳戶 B 的第三方連結,而不是其他 API 呼叫中使用的管理員帳戶關係。

第三方應用程式分析供應商發出 API 呼叫,如下所示:

  • linked-customer-id:上傳資料的第三方應用程式分析帳戶 (帳戶 B)。
  • customer-id:上傳資料的目標 Google Ads 帳戶 (帳戶 A)。
  • login-customer-idAuthorization 標頭:一組值,用來識別擁有帳戶 B 存取權的使用者。

回應標頭

下列標頭 (或 grpc Trailing-metadata) 會以回應內文傳回。建議您記錄這些值以進行偵錯。

要求 ID

request-id 是可辨識此要求的字串。