最佳实践
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
此页面涵盖在针对 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 应用，查看您的网络上是否有用户耗尽您的配额。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-21。
[null,null,["最后更新时间 (UTC)：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."]]
