最佳做法
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁說明針對 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 應用程式，查看網路上是否有任何使用者正在耗盡配額。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-21 (世界標準時間)。
[null,null,["上次更新時間：2025-08-21 (世界標準時間)。"],[[["\u003cp\u003eThis page provides best practices for developing applications using the Google Ad Manager API to enhance performance and efficiency.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers should reuse service clients, use paging for large data sets, and batch update requests to optimize interactions with the API.\u003c/p\u003e\n"],["\u003cp\u003ePQL bind parameters are recommended for improved code readability and reusability, while user privileges should be granted judiciously.\u003c/p\u003e\n"],["\u003cp\u003eAd Manager API enforces quota limits; developers should implement strategies to handle quota errors and stay within allowed usage.\u003c/p\u003e\n"]]],["Optimize Google Ad Manager API usage by reusing service clients, creating them once per execution. When retrieving objects, use paging with `LIMIT` and `OFFSET` clauses, aiming for 200-500 items per page. For updates, batch multiple objects in a single request. Employ bind parameters in PQL for readability and reusability. Grant user privileges sparingly, avoiding unnecessary administrative roles. Respect quota limits, implementing retry strategies with exponential backoff, particularly for reporting and forecast requests.\n"],null,["# Best Practices\n\nThis page covers various best practices that should be considered when\ndeveloping applications against the Google Ad Manager API.\n\n- [Reuse service clients/stubs during the course of an execution](#ReuseServices)\n- [Use paging when fetching objects](#UsePaging)\n- [Batch update requests](#BatchUpdate)\n- [Store the Ad Manager API client object when appropriate](#StoreDfpUser)\n- [Use bind parameters in PQL](#UseBindParameter)\n- [Grant user privileges sparingly](#GrantUserPrivilegesSparingly)\n\n### Reuse service clients/stubs during the course of an\nexecution\n\nCreating a new service client/stub has a marginal cost associated with\nfetching the WSDL and allocating resources. If possible, create the service\nclient/stub once at the beginning of an execution and make it available to\nclasses and functions as needed.\n\n### Use paging when fetching objects\n\nAll of the services support a `get*ByStatement()` method, which\nallows for the filtering of results using [PQL](/ad-manager/api/pqlreference)\nsyntax. The `LIMIT` and `OFFSET` clauses can be used to\nsplit large result sets into pages, preventing time outs and keeping the\nresponse page sizes reasonable. The suggested page size is 200-500, depending\non the complexity of your objects.\n\n### Batch update requests\n\nWhen changing multiple objects of the same type, you can get better\nperformance by sending all of the objects in the same `update*()`\nrequest. There is a marginal overhead on the client and the server for each\nrequest, and batching can be an effective means of reducing the number of\nrequests. For example, use [`updateOrders`](/ad-manager/api/reference/latest/OrderService#updateOrders)\nto update a batch of [Orders](/ad-manager/api/reference/latest/OrderService.Order)\nrather than a single order in each call.\n\n### Use bind parameters in PQL\n\nBind parameters are a way to put variables into a PQL query statement. PQL\nrefers to a bind variable by a name without spaces starting with a colon,\ne.g., `:name`. A code example is provided in the [PQL syntax](/ad-manager/api/pqlreference#syntax) page.\n\nWe recommend using bind variables because they improve code readability by\nremoving the need to concatenate strings and variables into a query statement.\nThey also make it easy to reuse PQL statements, since new queries can be made\nby substituting the bind parameter values.\n\n### Grant user privileges sparingly\n\nWhen using [UserService](/ad-manager/api/reference/latest/UserService) to\ncreate/update user roles, be careful not to grant users privileges they do not\nneed. Many features of the API can be accessed with a combination of roles\nrather than assigning the user an administrator role. Please refer to the [permissions\ndocumentation](//support.google.com/admanager/answer/177403) when deciding which roles to assign a user. Also, as a [third party](/ad-manager/api/third-parties) application developer, make sure to\ndetermine what level of access your application needs when asking a network to\ncreate a user for you; a role with fewer privileges than administrator may be\nenough.\n\n### Stay under quota limits\n\nThe Ad Manager API enforces several quota limits for robustness. It's\nimportant to keep your applications under these limits and that you know how to\nrespond to any of the quota errors the API can return.\n\n#### API quota\n\nThe first quota applied to API requests is a network-level quota. For Ad Manager\n360 accounts, the limit is 8 requests per second, and for Ad Manager accounts,\nthe limit is 2 requests per second. Going beyond this limit results in a\n[`\nQuotaError.EXCEEDED_QUOTA`](/ad-manager/api/reference/latest/LineItemService.QuotaError#reason) error. All API requests made on your\nnetwork apply to this quota, including third-party applications that you or\nsomeone at your company has granted API access to your network.\n\n#### System-specific quotas\n\nThe API quota alone is not enough to adequately protect certain\nresource-intensive systems within Ad Manager. The reporting and forecast systems\ndefine their own quotas that can result in API errors:\n[`\nQuotaError.REPORT_JOB_LIMIT`](/ad-manager/api/reference/latest/ReportService.QuotaError#reason) and [`\nForecastError.EXCEEDED_QUOTA`](/ad-manager/api/reference/latest/ForecastService.ForecastError#reason), respectively.\n\n#### Handling quota errors\n\nIf your application encounters any of the above quota errors, carry out a\nstrategy for retrying the API request. We recommend waiting at least 5 seconds\nfirst, and if you continue to get the error, use [exponential backoff](//cloud.google.com/storage/docs/exponential-backoff#example_algorithm) to increase the time between retries. If retrying\ndoesn't succeed, perform an audit of your API applications to see if any users\non your network are draining your quota."]]
