對象、方法和服務
AdWords API 主要供 AdWords 的高級用戶使用。如果您是 AdWords 新手，或需要復習 AdWords 基本概念，請查看 AdWords 基礎知識頁面。
對象層級結構和范圍
可以將每個 AdWords 帳號視為由多個對象組成的層級結構。
每個帳號下都有一個或多個 Campaigns，表示您正在投放的廣告系列。
每個廣告系列有多個 AdGroups，用來按邏輯將您的廣告加以組合。
每個 AdGroup 中有多個 AdGroupAds 和 AdGroupCriteria。AdGroupAd 表示您正在投放的廣告。AdGroupCriterion 代表用於定義廣告觸發方式的條件，即關鍵字。
您可以指定廣告系列條件，以定義整個廣告系列廣告觸發方式的規則。您還可以指定整個廣告系列的預算和日期。
最后，在廣告系列一級可以使用廣告附加信息，可讓您在廣告中提供額外信息，例如電話號碼、街道地址等。
AdWords 中的每個對象都由自己的 ID 標識。其中某些 ID 在所有 AdWords 帳號中具有全局唯一性，而其他 ID 僅在限定范圍內是唯一的。
AdWords 中每個對象 ID 的唯一性如下表所示。
| 對象 ID | 唯一性的范圍 | 是否在全局級別具有唯一性？ |
|---|---|---|
| 預算 ID | 全局 | 是 |
| 廣告系列 ID | 全局 | 是 |
| AdGroup ID | 全局 | 是 |
| 廣告 ID | 廣告組 | 否。(AdGroupId, AdId) 對在全局級別具有唯一性。 |
| AdGroupCriterion ID | 廣告組 | 否。(AdGroupId, CriterionId) 對在全局級別具有唯一性。 |
| CampaignCriterion ID | 廣告系列 | 否。(CampaignId, CriterionId) 對在全局級別具有唯一性。 |
| 廣告附加信息 | 廣告系列 | 否。(CampaignId, AdExtensionId) 對在全局級別具有唯一性。 |
| Feed ID | 全局 | 是 |
| Feed Item ID | 全局 | 是 |
| Feed Attribute ID | Feed | 否 |
| Feed Mapping ID | 全局 | 是 |
| 標簽 ID | 全局 | 是 |
在設計本地數據庫以存儲 AdWords 對象時，這些 ID 規則很有用。
如果某個對象是從其他對象衍生出來的，那么該對象還會有一個 Type 字段。
例如，TextAd 有一個表示它是衍生自 Ad 對象的 Type 字段。
如果您使用動態語言，可以使用此字段來檢查對象的類型，例如，查看 Ad 對象是否為 TextAd 類型。
方法和操作
AdWords API 提供管理 AdWords 對象的服務。
例如，CampaignService 用於管理 Campaign，而 AdGroupService 用於管理 AdGroup，依此類推。
query() 方法
query() 方法是 get() 的替代方法，它使用類似於 SQL 語言的 AdWords 查詢語言 (AWQL)，不使用選擇器。在 AWQL 中對相同的請求進行編碼通常更有效率。大多數常見服務都支持 query() 方法。請注意，AWQL 不支持對數據進行轉變。
mutate() 方法
mutate() 方法用於轉變（創建、更新或移除）AdWords 對象。
要轉變對象，您必須構建相應的 Operation 對象。例如，要轉變 Campaign，您必須創建 CampaignOperation。
並發轉變
如果您有多個用戶使用您的應用更新同一個對象，或者您使用多個線程並行轉變 AdWords 對象以獲得更高的吞吐量，那么請務必了解 AdWords 如何處理針對同一對象的並發 mutate 請求。
不能同時由多個來源並行修改 AdWords 對象。這包括從同一應用的多個線程或通過其他應用（例如，您的應用和一個同時進行的 AdWords 編輯器會話）更新對象。API 不提供在更新之前鎖定對象的方法：如果兩個源試圖同時轉變對象，則 API 會引發 CONCURRENT_MODIFICATION_ERROR 錯誤。
您可以在這篇博文中了解有關 AdWords API 並發管理的詳情。
異步轉變與同步轉變
AdWords API mutate() 方法是同步的：只有在對象發生轉變后，API 調用才會返回響應，因此需要等待對每個請求的響應。雖然這種方法在代碼編寫方面相對簡單，但它可能會對負載平衡造成負面影響，在機器等待調用完成時會造成資源浪費。
另一種方法是使用 BatchJobService 異步轉變對象，這種方法無需等待操作完成，即可對多個服務執行批處理操作。提交批處理作業后，AdWords API 服務器會異步執行操作，釋放計算機的資源，以便執行其他操作，並定期檢查作業狀態是否為已完成。
有關異步處理的更多信息，請參見批處理指南。
轉變驗證
validateOnly SOAP 標頭允許測試 API 調用，而不對真實數據實際執行調用：您可以測試缺少的參數和不正確的字段值，而不實際執行操作。
要使用此功能，請在 RequestHeader 中將 validateOnly 字段設置為 true。默認情況下，客戶端庫會將此字段設置為 false。
系統會對您的請求進行充分驗證，就像即將執行該請求一樣，但會跳過最終的執行步驟。
如果沒有找到錯誤，則返回空響應。
如果驗證失敗，錯誤消息會指明失敗點。
使用此會話進行的所有 API 調用都將 validateOnly 標頭設置為 true。
validateOnly 標頭在測試廣告是否存在常見違規情形時特別有用。
如果廣告違反了使用特定字詞、標點符號、大小寫或長度等相關政策，則系統會自動拒絕廣告。
如果您嘗試批量上傳廣告，那么一個不良廣告就可能導致您的整個批量上傳操作失敗。
使用 validateOnly 測試新廣告可讓您輕松查看哪些廣告會被拒絕。
請參閱處理違規錯誤的代碼示例以查看實際操作情況。
如果不使用客戶端庫，則只需設置正確的 SOAP 標頭，您仍可以驗證您的 mutate() 請求。
AdWords API 服務
本節介紹了 AdWords API 提供的服務，並提供了指向各項服務其他詳細信息所在參考頁的鏈接。
AdWords API 服務可組合為四個功能類別：
廣告系列數據管理
使用廣告系列數據管理服務來處理 AdWords 廣告系列及其相關聯的實體。每個廣告系列數據管理服務都對應於廣告系列數據層級結構中的實體
| 服務 | 說明 |
|---|---|
| CampaignService | 創建、更新和移除廣告系列。廣告系列由一個或多個廣告組組成，並且有自己的預算、出價策略、投放日期范圍和定位設置。 |
| AdGroupService | 創建、更新和移除廣告組。廣告組由一組廣告和條件組成，並為其條件提供默認出價。 |
| AdGroupAdService | 創建、更新和移除廣告。 |
| CampaignExtensionSettingService | 創建、更新和移除廣告附加信息。廣告系列的廣告附加信息通過向廣告系列中的所有廣告添加地址信息、附加鏈接或電話號碼來豐富標准文字廣告。 |
| CampaignCriterionService AdGroupCriterionService |
創建、更新和移除條件。條件決定廣告是否應該展示。 |
| ConversionTrackerService OfflineConversionFeedService |
了解用戶點擊您的廣告后會發生什么，以衡量廣告和關鍵字的效果。OfflineConversionFeedService 處理離線轉化數據的導入。 |
| DataService | 根據指定的條件獲取廣告系列管理數據。 |
| FeedService FeedItemService FeedMappingService AdGroupFeedService CampaignFeedService |
創建自定義數據 Feed 以管理網站、電話和應用附加鏈接信息。 |
| AdwordsUserListService | 創建、更新和移除用戶列表。用戶列表和用戶列表條件會向之前在您的網站上觸發了轉化事件的用戶展示廣告。 |
| BudgetService | 創建、更新和移除預算。用於管理可在廣告系列之間共享的預算。 |
優化
使用優化服務獲取效果統計信息並查找新條件的參考提示。
| 服務 | 說明 |
|---|---|
| ReportDefinitionService | 創建和下載各種效果報告。 |
| TargetingIdeaService | 根據您指定的參數生成新的關鍵字和展示位置參考提示。 |
| TrafficEstimatorService | 獲取所提議的廣告系列、廣告組和關鍵字的流量估算值。 |
| DraftService 和 TrialService | 制作新的草稿和試用版，用於測試您的廣告系列設置。有關詳情，請參閱此指南。 |
帳號管理
使用帳號管理服務來跟蹤您的帳號活動。
| 服務 | 說明 |
|---|---|
| CustomerService | 獲取有關客戶帳號的基本詳細信息。 |
| CustomerSyncService | 獲取指定日期范圍內廣告系列數據的更改記錄。 |
| ManagedCustomerService | 管理客戶帳號以及經理帳號和客戶帳號之間的關聯。 |
實用工具
使用這些實用工具服務通過 AdWords API 執行各種實用任務。
| 服務 | 說明 |
|---|---|
| BatchJobService | 異步處理大批量的廣告系列數據操作。與對標准網絡服務的同步調用相比，完成批處理作業所需的時間更長，不過具有其他優勢（如批處理指南中所述）。 |
| MediaService | 上傳和獲取您在基於媒體的廣告（例如圖片廣告或視頻廣告）中使用的媒體的 ID。 |
| ConstantDataService | 獲取 API 使用的常量值。 |
| LocationCriterionService | 獲取地理位置條件的 ID。 |
廣告系列數據
處理廣告系列數據是使用 AdWords API 執行的基本任務之一。下表說明了各個廣告系列數據實體及各實體與其他廣告系列數據的關系。
| 實體
子實體
（數量）
|
數據類型 | 說明 |
|---|---|---|
| 廣告系列
廣告組
(1+)
廣告系列定位列表
(7)
廣告系列廣告附加信息
(0+)
廣告系列條件
(0+)
|
Campaign |
廣告系列由一個或多個廣告組組成，並且有自己的預算、出價策略和投放日期范圍。 |
| 廣告組
廣告
(1+)
條件
(1+)
|
AdGroup |
廣告組由一組廣告和條件組成，並為其條件提供默認出價。 |
| 廣告
廣告附加信息覆蓋
(0+)
|
AdGroupAd |
可用廣告類型在 API 參考中記錄為抽象 Ad 類型的子類。 |
| 條件
無
|
AdGroupCriterion，CampaignCriterion |
條件決定廣告是應該得到展示（可出價條件）還是不應得到展示（排除條件）。廣告組條件會影響父級廣告組中的廣告。廣告系列條件（始終是排除條件）定義了阻止廣告系列的廣告進行展示的條件。 |
| 廣告附加信息
無
|
CampaignExtensionSetting |
廣告系列的廣告附加信息通過向廣告系列中的所有廣告添加地址信息、附加鏈接或電話號碼來豐富標准文字廣告。 |
| Feed
無
|
Feed |
Feed 可用作廣告附加信息（附加鏈接、電話、應用）的數據渠道。 |
| 用戶列表
無
|
UserList |
用戶列表跟蹤曾對您的網站感興趣的用戶。通過創建用戶列表條件並將其關聯到現有用戶列表，可以將廣告定位到這組用戶。 |
| 預算
無
|
Budget |
預算用於管理在廣告系列上花費的金額。可以在不同的廣告系列之間共享預算，系統將確定最佳分配方式。 |
API 調用結構
OAuth2 身份驗證
所有 AdWords API 調用都必須通過 OAuth2 授權。
OAuth2 可讓您的 AdWords API 客戶端應用訪問用戶的 AdWords 帳號，而無需處理或存儲用戶的登錄信息。
生成 OAuth2 憑據
要生成 OAuth2 憑據，請按以下步驟操作：
確定您的應用類型
首先，為要構建的應用確定適當的應用類型。AdWords API 有兩種應用類型選項：
- 已安裝應用（推薦）
- 網絡應用
請查看下表，了解哪種類型最適合您要構建的應用：
| 選擇此應用類型 | 如果... |
|---|---|
| 已安裝應用（推薦） |
|
| 網絡應用 |
|
有關詳情，請參閱有關已安裝應用和網絡應用的 Google 身份平台 OAuth 文檔。
創建客戶端 ID 和客戶端密鑰
確定應用類型后，請點擊下面的相應標簽，然后按照說明生成 OAuth2 客戶端 ID 和客戶端密鑰：
OAuth2 Playground
生成 OAuth2 憑據的另一種選擇是使用 OAuth2 Playground。OAuth2 Playground 與 Google API 控制台配合使用，可讓您手動創建 OAuth2 令牌。
OAuth2 Playground 適用於只需訪問單個經理帳號或 AdWords 用戶帳號的用戶。
如果您需要提示多個用戶提供憑據，則可能最好使用上述基於客戶端庫的方法
OAuth2 服務帳號
本節討論如何使用服務帳號訪問 AdWords API。
服務帳號是屬於您的應用而不是個別最終用戶的帳號。服務帳號允許網絡應用和 Google 服務之間進行服務器到服務器的互動。您的應用會代表服務帳號調用 Google API，因此用戶不會直接參與。
AdWords API 允許通過 G Suite 網域訪問服務帳號。
服務帳號使用 OAuth2 流程，無需人工授權，但需要使用只有您的應用可以訪問的密鑰文件。
使用服務帳號主要有以下兩個優勢：
- 對應用授予 Google API 訪問權限的操作是作為配置步驟進行的，可以避免使用其他 OAuth2 流程所帶來的復雜問題；用戶不需要進行干預，應用也不必為避免將來需要用戶干預而緩存令牌。
- OAuth2 斷言流程允許您的應用在必要時模擬其他用戶。
注意：我們強烈建議您使用已安裝應用或網絡流程，除非您需要使用網域所特有的功能（例如模擬），否則不建議您使用服務帳號。如果獲得了對帳號的訪問權限，OAuth2 已安裝應用和網絡流程只需要一次用戶互動。
服務帳號的替代方法
開發者通常會考慮使用服務帳號，因為他們需要在不進行用戶干預的情況下，使用 OAuth2 以編程方式訪問 API。
考慮到為 AdWords API 設置服務帳號訪問權限的復雜性，我們建議使用一個更簡單的替代方案來實現相同的目標，即使用 OAuth2 已安裝應用流程，並持久保留刷新令牌。這樣，如有必要，您的應用始終能夠請求新的訪問令牌。
此過程需要您根據上述已安裝應用過程配置您的客戶端庫，從而對您的應用進行授權。
前提條件
- 您擁有的 G Suite 網域（如 mydomain.com 或 mybusiness.com）。
- AdWords API 開發者令牌以及（可選）測試帳號。
- 您使用的語言的客戶端庫。
安全考慮
考慮到 G Suite 的網域級控制，因此一定要保護允許服務帳號訪問其獲授權的 Google 服務的密鑰文件。因為該服務帳號能夠模擬網域中的任何用戶，所以尤其需要強調這一點。
另一個好的做法是每個服務帳號只允許訪問一個 Google API（使用下一節中描述的范圍字段）。這是一種先發制人的措施，即使服務帳號的密鑰文件被泄露，仍能限制攻擊者可以訪問的數據量。
授權進行模擬
執行以下步驟，將模擬能力授予服務帳號：
- 轉到
https://admin.google.com/YOUR_DOMAIN/ManageOauthClients，將已獲授權的新 API 客戶端添加到您的 G Suite 網域中。 注意：請確保將YOUR_DOMAIN替換為您的實際域名（例如 mydomain.com）。 - 使用您在上述步驟中為全網域委派啟用服務帳號時生成的 JSON 文件中的客戶端 ID，將已獲授權的新 API 客戶端添加為客戶端名稱。
-
輸入以下內容作為 API 范圍：
https://www.googleapis.com/auth/adwords -
對要向其授予模擬權的所有其他服務帳號重復此過程。
您現在即可使用服務帳號通過 OAuth2 斷言流程訪問您的 AdWords 帳號。
優化 OAuth2 請求
如果您的應用不能在服務器、進程和線程之間共享憑據，就可能會向 Google 發送過多的請求。這可能導致我們的服務器對您的應用強制執行速率限制，造成性能下降。
本節介紹如何優化 OAuth2 憑據管理，以便您的應用可以與 AdWords API 進行高效互動。
憑據共享策略
跨 API 請求共享憑據可提高性能，並避免可能引發速率限制錯誤的過多開銷。
您的憑據共享策略取決於您的應用設計：
在多線程應用中，應該為每個線程的會話提供相同的憑據。
在多進程或分布式應用中，要跨進程共享憑據，必須實現一些基礎架構。您還應該確保線程不會被阻止，並且自己的實現中不存在爭用的情況。
如果應用的每次處理中同時具有多進程/分布式和多線程，則應該同時使用這兩種策略。
下面介紹了對單個 AdWords 帳號（例如層級結構中的頂級經理帳號）進行身份驗證的這些策略。
然后描述了如何改變這些策略，以便對多個 AdWords 帳號進行身份驗證
多線程應用
多線程應用應在線程之間共享憑據。應同步執行對憑據的刷新，以避免出現爭用情況。
該圖顯示了一個運行時，其中帶有提取自會話（或用戶）池的線程，可向 AdWords API 發出請求。請注意，每個會話應使用相同的憑據對象。在每個 API 請求中，由線程獲得會話（或用戶）。如果憑據需要訪問令牌刷新，則必須同步執行，即憑據對象對線程必須是安全的，以避免出現爭用情況。
客戶端庫可直接跨線程共享憑據。每個客戶端庫都有一個會話（或用戶）對象，並帶有可在其生命周期中重用的憑據。要跨線程共享憑據，只需使用相同的憑據構建每個會話即可。在所有客戶端庫中，憑據是當訪問令牌期滿時會對自身進行同步刷新的對線程安全的對象。
例如，在 Java 客戶端庫中，您可以將 Credential 創建為單實例模式，並在所有會話間共享。
多進程或分布式應用
要在多進程或分布式應用中共享憑據，需要實現對憑據的持久保留。為了確保多個進程或服務器不會同時嘗試刷新憑據（從而導致刷新請求過多），我們建議在某中央位置主動刷新憑據，並在進程/服務器之間共享憑據。
例如，可以由獨立的作業或服務負責周期性地刷新憑據，並且主動將其推送到數據存儲，以供服務器池使用。
該圖顯示了定期運行的憑據刷新作業，並將憑據的屬性寫入數據存儲。然后，每個服務器在向 API 發出請求之前都要獲取憑據。
刷新作業
刷新作業會定期刷新憑據並將其存儲在數據存儲中。作業不應等到當前憑據到期才啟動刷新，否則可能導致應用因缺少有效憑據而停止運行，開一個“天窗”。
較好的替代方法是定期強制刷新，每次都用新憑據替換數據存儲中的憑據。刷新作業應該在當前憑據到期之前盡早運行，以便預留一些時間，防止出現瞬間失敗。比如，可考慮先從每 15 分鍾刷新一次開始。
注意：如果在處理 API 請求時，憑據的訪問令牌到期，您的請求仍會完成。例如，如果您創建了一個運行時間很長的請求，而剩下的訪問時間不到一分鍾，系統仍會返回結果。
數據存儲
中央數據存儲可用於在進程和服務器之間共享憑據。
您既可以使用現有的數據存儲，也可以部署一個特定於服務器間憑據共享的數據存儲。解決方案既可以是緩存服務器（如 Memcached 或 Infinispan{/1），也可以是 NoSQL 數據存儲（如 MongoDB）。
對於向 API 發出請求的所有服務器，數據存儲必須提供可靠的接口。它應該面向快速讀取操作進行優化，原因是服務器或進程對當前憑據的讀取頻率要高於刷新作業的更新頻率。
請記住，對憑據必須進行安全存儲。
存儲憑據時，應該隨 access_token 存儲計算出的 expiry_time（現在要 + expires_in）和 refresh_token。expiry_time 計算為 access_token 刷新請求的時間加上 expires_in 時間。
服務器池
池中的每個服務器或進程先從數據存儲中獲取最新的憑據，然后才發出請求。只要刷新作業成功運行，憑據就會有效。但是，如果刷新作業或數據存儲失敗，您應該有一個回退機制。
如果服務器或進程無法從數據存儲獲取憑據，或者憑據已過期，則服務器應刷新自己的憑據，以允許應用繼續使用 API，直到問題解決。
在有多個線程的處理過程中，您應該使用上述共享策略在線程間共享憑據。
驗證多個帳號的身份
為 AdWords 經理帳號生成的憑據可用於訪問其所有子帳號。因此，對於具有單一經理帳號層級結構的用戶，通常只需為頂級經理帳號生成憑據，即可為其下的所有 AdWords 帳號實現應用授權。
另一些情況下，您的應用必須訪問在任何經理帳號層級結構中彼此都不相關的 AdWords 帳號。在這種情況下，對於不同的帳號（例如您訪問的每個 AdWords 客戶帳號，或您訪問的獨立層級結構中的每個頂級經理帳號），您應該生成並維護不同憑據。
只需進行最低程度的修改，即可對多線程和多進程/分布式應用采用相同的策略。使用共享數據存儲時，必須通過帳號標識符 customerId 對憑據編制索引，以確保憑據與正確的帳號相關聯。此外，刷新作業應保證對所有憑據進行刷新。如果關聯了新帳號，則可能需要觸發刷新作業。
最后，在多線程應用中，在其間共享憑據對象的線程應該操作於與該憑據對象關聯的帳號上。
OAuth2 內部
就以下所涉及的詳細信息而言，我們的客戶端庫會實現自動處理，因此只有在您對后台發生的情況感興趣時，或者您沒有使用我們的任何客戶端庫時，才需要繼續閱讀。
本部分的目標讀者是熟悉 OAuth 2.0 規范並且了解如何結合使用 OAuth2 和 Google API 的高級用戶。
范圍
同一個訪問令牌可授予對多個 API 的不同級別的訪問權限。有一個稱為 scope 的可變參數用於控制訪問令牌允許的資源和操作集。在請求訪問令牌期間，您的應用在 scope 參數中發送一個或多個值。
AdWords API 目前所使用的范圍和已棄用的范圍：
| 范圍 | 含義 |
|---|---|
https://www.googleapis.com/auth/adwords |
AdWords API 的讀/寫訪問權限。 |
https://adwords.google.com/api/adwords/ |
此范圍已棄用，不應再用於獲取未來的授權。以前獲授權的令牌將繼續工作。 |
離線訪問
AdWords API 客戶端應用通常會請求進行離線訪問。例如，當您的用戶並未實際在線瀏覽您的網站時，您的應用可能會希望運行批處理作業。
要為某網絡應用類型請求離線訪問，請確保將 access_type 參數設置為 offline。您可以在 Google 的 OAuth2 指南中找到更多信息。
對於已安裝應用類型，離線訪問在默認情況下處於啟用狀態，因此您不必專門請求離線訪問。
HTTP 請求標頭
發送到 AdWords API 服務器的每個請求中的 HTTP 標頭都必須包含以下形式的訪問令牌：
Authorization: Bearer THE_ACCESS_TOKEN
訪問令牌和刷新令牌
在大多數情況下，您需要安全地存儲刷新令牌以備將來使用。要詳細了解如何請求訪問令牌和刷新令牌，請閱讀與您的應用類型相對應的指南：
訪問令牌過期
訪問令牌有一個基於 expires_in 值的過期時間；過期后，令牌即會失效。您可以使用刷新令牌刷新過期的訪問令牌。
默認情況下，我們的客戶端庫會自動刷新過期的訪問令牌。
AdWords 查詢語言 (AWQL)
AWQL 是一種與 SQL 類似的語言，用於對最常見的 AdWords API 服務執行查詢。這種語言支持所有提供 query() 方法的服務。
AWQL 的開發靈感源自 SQL，但它並沒有全面支持所有 SQL 語匯。值得注意的是，這種語言省略了 JOIN 和 GROUP BY 子句。
對於每項服務，您可以從選擇器字段中獲取可查詢字段的列表。
此外，還可以使用 AWQL 查詢報告。有關可查詢字段的完整列表，請參閱報告類型。
在服務調用中使用 AWQL
對於相同的調用，使用 AWQL 來編寫調用代碼通常更為高效
我們的客戶端庫主要提供的是使用 AWQL 的代碼示例，
備注
- 因為請求所發送到的服務已確定數據源，所以不需要
FROM子句。 - 服務調用中不允許使用
DURING子句，但報告調用中可以使用這一子句。使用帳號的時區。 - 雖然關鍵字（如
WHERE）不區分大小寫，但字段（列）名（如Name）和字面值（如ENABLED）區分大小寫。 - 在
WHERE子句中使用IN和NOT_IN運算符時，最多可以指定 10000 個條目。
將 AWQL 用於報告
AWQL 經常用在報告中。與通常在報告的“__rdxml”POST 參數中指定 XML 片段不同，需要提供以下兩個參數：
- “
__rdquery”：包含 AWQL 查詢字符串。 - “
__fmt”：定義報告的下載格式。
下面還列出了將 AWQL 用於報告時的一些用法差異：
-
查詢必須在
FROM子句中包含報告類型，例如：SELECT Id, Criteria, AdGroupName **FROM KEYWORDS_PERFORMANCE_REPORT**請注意，盡管在服務調用中不允許使用
FROM，但在報告下載中必須使用該子句。 -
報告的日期范圍在查詢的
DURING子句中定義。可以通過以下兩種不同的方式指定日期范圍： -
要獲取所有日期的數據（等效於
ALL_TIME），可以在查詢中省略DURING子句。但是，只有當您的查詢的SELECT子句沒有包含Date或Week列時，才允許如此操作。 - 就報告而言，不支持
ORDER BY和LIMIT（排序和分頁）。在查詢中加入這些子句將發生錯誤。 - 要忽略展示次數為零的行，請加入
WHERE Impressions > 0條件。
形式語法
下面列出了 AWQL 形式語法以供參考。
Statement -> SelectClause FromClause1 WhereClause?
DuringClause2 OrderByClause?3 LimitClause?4
SelectClause -> SELECT ColumnList
FromClause -> FROM SourceName
WhereClause -> WHERE ConditionList
DuringClause -> DURING DateRange
OrderByClause -> ORDER BY Ordering (, Ordering)*
LimitClause -> LIMIT StartIndex , PageSize
ConditionList -> Condition (AND Condition)*
Condition -> ColumnName Operator Value
Value -> ValueLiteral | String | ValueLiteralList | StringList
Ordering -> ColumnName (DESC | ASC)?
DateRange -> DateRangeLiteral | Date,Date
ColumnList -> ColumnName (, ColumnName)*
ColumnName -> Literal
SourceName -> Literal
StartIndex -> Non-negative integer
PageSize -> Non-negative integer
Operator -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL
String -> StringSingleQ | StringDoubleQ
StringSingleQ -> '(char)'
StringDoubleQ -> "(char)"
StringList -> [ String (, String)* ]
ValueLiteral -> [a-zA-Z0-9_.]*
ValueLiteralList -> [ ValueLiteral (, ValueLiteral)* ]5
Literal -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK |
LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH
Date -> 8-digit integer: YYYYMMDD
注意
- 1 在服務調用中不允許使用
FROM子句，但在報告下載中必須使用該子句。 - 2 在服務調用中不允許使用
DURING子句。如果您請求的SELECT子句包含Date或Week列，則在報告下載中必須使用該子句。 - 3 在報告調用中不允許使用
ORDER BY子句。 - 4 在報告調用中不允許使用
LIMIT子句。 - 5 對於
ValueLiteralList，必須使用方括號 [ ]；方括號在其他地方用來表示范圍。 ?表示可選；*表示一個或多個。- 順序：
SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT... - 所有關鍵字均不區分大小寫。
- 列名稱和字面值是區分大小寫的。
- 空格不起作用。
- 可以在字符串中使用雙引號和單引號。相應的轉義序列為
\"、\'和\\。
-
要獲取所有日期的數據（等效於
ALL_TIME），可以在查詢中省略DURING子句。但是，只有當您的查詢的SELECT子句沒有包含Date或Week列時，才允許如此操作。 - 就報告而言，不支持
ORDER BY和LIMIT（排序和分頁）。在查詢中加入這些子句將發生錯誤。 - 要忽略展示次數為零的行，請加入
WHERE Impressions > 0條件。