Google advertiser api開發概述——最佳做法&建議
最佳做法
本指南介紹了一些最佳做法，您可以運用它們來優化 AdWords API 應用的效率和效能。
日常維護
為確保您的應用不間斷執行，可採取以下做法：
-
確保 AdWords API 中心中的開發者聯絡電子郵件是最新的，這是我們在與您聯絡時使用的別名。如果我們無法就 API 條款及條件的遵從事宜與您取得聯絡，您的 API 訪問許可權可能會在您事先不知情的情況下被撤消。因此請避免使用與個人帳號或無人監控的帳號相關聯的個人電子郵件地址。
-
如需獲知產品更改、維護停機、棄用日期等問題，請訂閱我們的
AdWords API 團隊會定期監控論壇，因此這裡非常適合釋出有關 API 的問題。
- 確保您的應用滿足 AdWords API 條款及條件 (T&C) 和最低功能要求 (RMF)。如果需要，令牌稽核和合規團隊將通過您的聯絡電子郵件與您聯絡。如果您對 T&C 或 RMF 有任何問題或疑慮，回覆稽核團隊稽核您的開發者令牌申請時傳送給您的電子郵件，即可與他們聯絡。
優化
批量操作
向 API 發出請求需要承擔許多固定開銷，例如往返網路延遲、序列化和反序列化處理以及對後端系統的呼叫
mutate() 方法都可以接受批量操作。在每個請求中包含可批處理的多個操作，可以減少所發出請求的數量和相關的固定開銷。請儘可能避免發出只含一個操作的請求。
下面我們舉例說明如何向某個廣告系列的多個廣告組新增 5 萬個關鍵字。與其發出 5 萬個請求，每個請求只包含 1 個關鍵字，不如發出 100 個請求，每個請求包含 500 個關鍵字，甚至只發出 10 個請求，每個請求包含 5000 個關鍵字。請注意，一個請求中允許的運算元量是有限制的，因此您可能需要調整批次規模，以獲得最佳效能。
對操作進行組合
針對同一廣告組或廣告系列的多項操作與同等數量針對多個不同廣告組或廣告系列的操作相比，前者的處理速度更快。將針對同一廣告組或廣告系列的多項操作組合在一起，可減少請求中作為操作物件的廣告組或廣告系列的總數，從而提高總體效能
針對同一廣告組或廣告系列發出多項併發請求可能會產生 CONCURRENT_MODIFICATION 錯誤。將修改同一廣告組或廣告系列的多項操作組合至單個請求中，可降低此類衝突發生的機率。
比如在上文的示例中，我們需要向一個廣告系列的多個廣告組新增 5 萬個關鍵字。在將操作分成批次之前，一種簡單的方法是按關鍵字定位的廣告組對關鍵字進行排序。這樣做的好處是，同一廣告組的所有關鍵字更有可能包含在同一請求中，還可以減少單個請求中作為操作物件的廣告組總數。也可以採用更高階的方法，將相關操作組合到數量儘可能少的請求中，同時每個批次的規模仍然很大。
重用訪問令牌
在不同的執行緒和程序中重用相同的 OAuth2 訪問令牌，可以減少定期重新整理令牌的開銷，您的應用因過度重新整理令牌而受到速率限制的可能性也會降低。詳細瞭解如何優化 OAuth2 請求。
傳送稀疏物件
將物件傳送到 API 時，欄位必須經過反序列化處理和驗證，然後儲存在資料庫中。如果只需要更新少數字段，將完整物件傳入就會增加處理時間並降低效能。為避免上述問題，AdWords API 支援稀疏更新，允許只填充物件中想要更改或必需的欄位。未填充或含 null 值的欄位則保持不變，以此提高請求的效能。
例如，要更新關鍵字級出價的應用就可以受益於使用稀疏更新的做法，因為只需填充 adGroupID、criterionID 和出價欄位。在一項使用 150 個關鍵字的測試中，通過使用稀疏更新而不傳遞完整填充的物件，效能提高了 20%。
使用壓縮
AdWords API 支持對請求和響應中的 SOAP 訊息進行 gzip 壓縮。要在響應中啟用 gzip 壓縮，請在請求中包含以下兩個 HTTP 標頭：
User-Agent：包含字串“gzip”。Accept-Encoding：帶有值 gzip
如果您使用客戶端庫，請參閱其有關啟用壓縮的文件。
錯誤處理和管理
在開發過程中，您可能會遇到錯誤。本節介紹在應用中構建錯誤管理機制的注意事項和策略。
除本節之外，還可參閱問題排查指南瞭解有關錯誤管理的更多資訊。
區分請求來源
一些應用主要進行互動操作，它們直接發出 API 呼叫來響應使用者在介面中發起的操作；還有一些應用主要是離線工作，它們將 API 呼叫作為定期後端程序的一部分發出。許多應用結合了這兩者。在考慮錯誤管理時，可能需要區分這些不同型別的請求。
對於使用者發起的請求，您的主要關注點應該是為使用者提供良好的體驗。就所發生的具體錯誤，在介面中儘可能多地為使用者提供相關背景資訊。在可能的情況下，為他們提供可以修正錯誤的簡單步驟（參見下面的建議）。
對於後端發起的請求，請就應用可能遇到的各種錯誤型別，實現相應的處理程式（參見下面的建議）。請務必加入一個預設處理程式，用來處理罕見或以前未曾顯現的錯誤。對於預設處理程式，推薦的方法是將失敗的操作和錯誤新增到佇列中，供操作員檢視並確定適當的解決方案。
發出少量規模較大的請求這種做法還有另一個好處，就是您的應用遭遇基於請求的速率限制的可能性有所降低。
區分錯誤型別
以下是四大類錯誤，對每一類都應該採取不同的處理方式。雖然這些類別並未窮盡所有可能的錯誤，並且某些錯誤可劃歸於一個以上的類別，但仍可從這裡著手來設計應用的錯誤處理機制。有關特定錯誤的更多詳細資訊，請參閱常見錯誤。
-
身份驗證和授權錯誤
-
身份驗證表示您的應用是否已獲得使用者授予的代表他們訪問 AdWords 的許可權。身份驗證的管理是通過 OAuth2 流程生成的憑據實現的。
-
授權指的是您的應用（已經過身份驗證，可代表使用者進行操作）是否已獲允處理其嘗試讀取或寫入的特定 AdWords 資料。
身份驗證錯誤可能是由您無法控制的因素導致的，其中最常見的一個原因是經過身份驗證的使用者撤消了他們向您的應用授予的代表他們執行操作的許可權。例如，如果您的應用為多個獨立客戶分別管理不同的 AdWords 帳號，並在管理每個客戶的帳號時分別以該客戶的身份接受身份驗證，則客戶隨時都可能撤消您應用的訪問許可權。這種情況下 API 可能會直接返回一個
AuthenticationError.OAUTH_TOKEN_REVOKED錯誤，或者客戶端庫中的內建憑據物件可能會引發令牌被撤消異常，具體取決於您的訪問許可權被撤消的時間。無論在哪種情況下，如果您的應用為客戶提供了介面，就可以要求他們重新啟動 OAuth2 流程，以重建您的應用代表他們進行操作的許可權。因您無法控制的因素而導致授權錯誤的另一個常見原因，是您的經理帳號層次結構發生了變化。處理單一經理帳號層次結構的應用，通常會以其頂級經理帳號的管理員使用者身份接受身份驗證，因為此使用者有權訪問層次結構中的所有子帳號。如果子帳號的使用者解除與經理帳號的關聯，您的應用將會在嘗試訪問該帳號時收到
AuthorizationError.USER_PERMISSION_DENIED錯誤。使用 ManagedCustomerService 可以檢查子帳號是否確實已從該層次結構中移除。如果您的應用以某個使用者的身份接受身份驗證，但該使用者的訪問許可權發生了改變，這種情況下也可能發生授權錯誤。例如，您的應用以某個使用者的身份接受身份驗證，但對 AdWords 帳號具有管理員許可權的另一使用者將該使用者的許可權更改為只讀，在這種情況下，所有轉變請求將失敗，並引發
AuthorizationError.USER_HAS_READONLY_PERMISSION錯誤。對於這兩個示例，您的應用既可以為使用者提供說明，也可以將問題呈報給客戶經理加以解決。
-
-
可重試錯誤
有些錯誤可能是臨時性問題所致，可通過在短時間暫停後重試請求來解決。這些錯誤包括
CONCURRENT_MODIFICATION、UNEXPECTED_INTERNAL_API_ERROR和RATE_EXCEEDED。對於使用者發起的請求，一種策略是立即在介面中指出錯誤，併為使用者提供進行重試的選項。另一種策略是，您的應用先自動重試請求，只有在達到最大重試次數或使用者總等待時間後才在介面中指出錯誤。
對於後端發起的請求，您的應用應該自動重試請求，直到達到最大重試次數。
重試請求時，請使用指數退避策略。例如，如果您在第一次重試前先暫停 5 秒，則可以在第二次重試後暫停 10 秒，在第三次後暫停 20 秒。指數退避有助於確保您不會過於頻繁地呼叫 API。
對於
RATE_EXCEEDED錯誤，應用在重試之前暫停的時間應至少比錯誤中retryAfterSeconds欄位值所規定的時間長。有關更多詳細資訊，請參閱速率限制指南。其他可重試錯誤可間隔更短的時間進行重試，但仍應遵循指數退避策略。 -
驗證錯誤
驗證錯誤表示操作的輸入不可接受。示例有
PolicyViolationError、DateError、DateRangeError、StringLengthError、UrlError等，不一而足。驗證錯誤最常發生的情況是，在使用者發起的請求中包含無效的使用者輸入。在這些情況下，您應該根據收到的具體 API 錯誤向用戶提供相應的錯誤訊息。您還可以在進行 API 呼叫之前驗證使用者輸入中是否有常見錯誤，從而提高您的應用的響應能力，同時提高對 API 的使用效率。
對於後端發起的請求，您的應用可以將失敗的操作新增到佇列中，供操作員進行審核。
-
與同步相關的錯誤
許多 AdWords 應用都會維護一個本地資料庫，用於儲存其 AdWords 物件。這種方法會遇到一個難題，就是本地資料庫可能與 AdWords 中的實際物件不同步。例如，使用者可能直接在 AdWords 中刪除了廣告組，但應用和本地資料庫不知道有此更改，依然發出 API 呼叫，就像廣告組仍存在一樣。這些同步問題可以表現為各種錯誤，例如
INVALID_ID、DUPLICATE_CAMPAIGN_NAME、DUPLICATE_ADGROUP_NAME、AD_NOT_UNDER_ADGROUP、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD等等，不一而足。對於使用者發起的請求，一種可能的策略是提醒使用者可能會存在同步問題，並立即啟動一個作業來獲取 AdWords 物件的相關類和更新本地資料庫，然後提示使用者重新整理介面。
對於後端發起的請求，某些錯誤會提供充足的資訊，供您的應用逐步自動更正您的本地資料庫。例如，
CANNOT_OPERATE_ON_REMOVED_ADGROUPAD錯誤應該會促使您的應用在本地資料庫中將相應廣告標記為已移除。無法以這種方式處理的錯誤可能會導致您的應用啟動更完整的同步作業，或者被新增到佇列中供操作員稽核。
處理部分失敗
預設情況下，對 API 的請求具有原子性：如果在請求中的一個操作期間發生錯誤，所有操作都將中止。原子性是一個安全的預設設定，但在許多情況下是不可取的，原因在於操作可能是各自獨立的，只有失敗的操作需要加以稽核。有兩種策略可修正這種預設行為。
第一個策略是稽核響應中的錯誤，將它們與引發錯誤的操作相關聯，然後發出一個只包含未引發錯誤的操作的新請求。這些操作現在應該能成功。您還可以將引發錯誤的操作交由錯誤處理機制（見上文）處理，或將其排入佇列供操作員稽核。
第二個策略是在您的 API 請求中啟用部分失敗標誌。啟用此標誌時，每個操作將被單獨處理，一個操作中發生錯誤不會阻止其他操作的提交。特定操作中的錯誤仍會正常返回。我們所有的客戶端庫都支援此標誌。
部分失敗標誌的主要好處是這種做法簡單易行，還能減少 API 呼叫，因為系統會自動提交有效操作，不需要使用者進行重試。對大多數應用來說，這都是合適的做法。
但是，在某些應用中，加強對錯誤處理方式的控制更為有用。例如，假設某應用不希望某個廣告中出現的違規錯誤妨礙其他廣告的提交，但卻希望出現其他一些錯誤（例如那些指示發生了更嚴重問題的錯誤）時中止整個請求。要實現這個想法，該應用應該採用上面的第一個策略。
請注意，在這兩種情況下，都可能有一些錯誤反映操作之間的依賴性，而兩個操作本身可能都是有效的。示例包括 AdGroupAdError.ENTITY_REFERENCED_IN_MULTIPLE_OPS 和 AdParamError.AD_PARAM_CANNOT_BE_SPECIFIED_MULTIPLE_TIMES。
同步後端
如果應用使用者有手動訪問 AdWords 帳號的許可權，他們可能會做出應用無法知曉的更改，導致應用的本地資料庫不同步。如上所述，您可以在發生同步相關錯誤時再做出反應，也可主動加以防範。一種主動策略是對所有帳號每晚執行一次同步作業，獲取帳號中的 AdWords 物件，並與本地資料庫進行比較。要使獲取過程可以高效完成，不妨考慮使用結構報告，而不是常規 API 服務。
記錄錯誤
應將所有錯誤都記錄到日誌中以便進行除錯和監控。至少應記錄請求 ID、引發錯誤的操作和錯誤本身。要記錄的其他資訊包括客戶 ID、API 服務、往返請求延遲、重試次數以及原始 SOAP 請求和響應。
客戶端庫提供內建的 SOAP 日誌記錄功能以及獲取 requestId 標頭的功能。
監控趨勢
請務必監控 API 錯誤的趨勢，以便可以檢測和解決應用的問題。可以考慮構建自己的解決方案或從市售的眾多商業工具中選擇一個，以便使用您的日誌來生成互動式資訊中心，並自動傳送提醒。
其他
使用測試帳號
測試帳號是不會實際投放廣告的 AdWords 帳號。可以使用測試帳號來對 AdWords API 進行實驗，並測試應用的連線性、廣告系列管理邏輯或其他處理過程能否正常運作。您的開發者令牌不需要獲得批准即可在測試帳號中使用，因此，即使應用尚未得到稽核，您仍可以在請求開發者令牌後立即開始使用 AdWords API 進行開發。
批量定位提示
使用 TargetingIdeaService 生成定位提示時，TargetingIdeaSelector 可接受型別為 IDEAS 或 STATS 的 RequestType。STATS 請求可用於獲取已知關鍵字的統計資訊。要獲取多個關鍵字的統計資訊，請在 RelatedToQuerySearchParameter 中列出關鍵字，將它們合併到單個請求中。這種做法將為每個關鍵字返回一個 TargetingIdea，比為每個關鍵字單獨發出請求更有效率。