最佳做法

本頁說明針對 Google Ad Manager API 開發應用程式時應考慮的各種最佳做法。

在執行過程中重複使用服務用戶端/虛設常式

建立新的服務用戶端/虛設常式會產生與擷取 WSDL 及分配資源相關聯的邊際成本。盡可能在執行作業開始時建立服務用戶端/虛設常式，並視需求提供給類別和函式。

擷取物件時使用分頁

所有服務都支援 get*ByStatement() 方法，可使用 PQL 語法篩選結果。LIMIT 和 OFFSET 子句可用於將大型結果集分割成多個頁面，防止逾時情形，並讓回應頁面的大小保持在合理範圍內。根據物件的複雜程度而定，建議的頁面大小是 200-500 個。

批次更新要求

變更相同類型的多個物件時，您可以在同一個 update*() 要求中傳送所有物件，藉此提高效能。用戶端和伺服器都會產生每項要求的邊際成本，而批次處理可做為減少要求數量的有效方式。舉例來說，使用 updateOrders 更新一批訂單，而不是每個呼叫中的單一訂單。

在 PQL 中使用繫結參數

繫結參數是將變數放入 PQL 查詢陳述式中的一種方式。PQL 是指使用名稱繫結的變數，名稱開頭不含空格，例如:name。PQL 語法頁面提供程式碼範例。

建議使用繫結變數，因為不需要將字串和變數串連成查詢陳述式，可提升程式碼的可讀性。也能輕鬆重複使用 PQL 陳述式，因為您可以替換繫結參數值來建立新查詢。

謹慎授予使用者權限

使用 UserService 建立/更新使用者角色時，請務必小心不要將非必要的權限授予使用者。可透過一組角色組合存取 API 的許多功能，而不是為使用者指派管理員角色。決定要指派哪些角色時，請參閱權限說明文件。此外，身為第三方應用程式開發人員，在要求網路為您建立使用者時，請務必決定應用程式需要哪種存取層級。相較於管理員的權限，這類角色的權限可能不夠。

遵守配額限制

Ad Manager API 會強制執行多項配額限制，以維護穩定性。請務必將應用程式保持在這些限制內，並瞭解如何回應 API 可能傳回的任何配額錯誤。

API 配額

套用至 API 要求的第一個配額是網路層級的配額。Ad Manager 360 帳戶的每秒要求數上限為每秒 8 個要求；如果是 Ad Manager 帳戶，則上限為每秒 2 次。如果超過這項限制，就會產生 QuotaError.EXCEEDED_QUOTA 錯誤。所有在您網路發出的 API 要求都會計入這項配額，包括您或貴公司其他人已經授予 API 存取網路的第三方應用程式。

系統專屬配額

光是 API 配額不足以妥善保護 Ad Manager 中會耗用大量資源的系統。報表和預測系統會自行定義可能導致 API 錯誤的配額： QuotaError.REPORT_JOB_LIMIT 和 ForecastError.EXCEEDED_QUOTA。

處理配額錯誤

如果您的應用程式發生上述任何配額錯誤，請執行重試 API 要求的策略。建議您至少先等候 5 秒，如果持續發生錯誤，請使用 指數輪詢，以增加重試之間的時間。如果重試失敗，請稽核您的 API 應用程式，查看網路上是否有任何使用者正在耗盡配額。