最佳实践
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
ondemand_video
视频：观看 2019 年研讨会上的最佳实践讲座
本指南介绍了一些最佳做法，您可以运用它们来优化应用的效率和性能。
日常维护
为确保您的应用不间断运行，可采取以下做法：
Google Ads API 团队会定期监控论坛，因此这里非常适合发布有关 API 的问题。
- 确保您的应用遵守 Google Ads API 条款及条件 (T&C)。
如果需要，令牌审核和合规团队会通过您的联系电子邮件地址与您联系。如果您对条款及条件有任何问题或疑虑，请回复该团队在审核您的开发者令牌申请时发送给您的电子邮件，以便与他们联系。
优化
您可以通过运行批量操作和（如果适用）发送稀疏对象来优化应用。
批量操作
向 API 发出请求需要承担许多固定开销，例如往返网络延迟、序列化和反序列化处理以及对后端系统的调用。为了减少这些固定开销的影响并提高总体性能，API 中的大多数 mutate 方法都可以接受批量操作。在每个请求中包含可批处理的多个操作，可以减少所发出请求的数量和相关的固定开销。请尽可能避免发出只含一个操作的请求。
下面我们举例说明如何向某个广告系列的多个广告组添加 5 万个关键字。与其发出 5 万个请求，每个请求只包含 1 个关键字，不如发出 100 个请求，每个请求包含 500 个关键字，甚至只发出 10 个请求，每个请求包含 5000 个关键字。一个请求中所允许的操作数量是有限制的，因此您可能需要调整批处理的操作规模，以获得最佳性能。
发送稀疏对象
在将对象发送到 API 时，系统必须对字段进行反序列化处理和验证，然后将其存储在数据库中。因此，在只需更新几个字段时，传入完整对象会增加处理时间，并降低性能。为避免上述问题，Google Ads API 支持稀疏更新，允许只填充对象中需要更改或必需的字段。稀疏更新的处理速度更快，产生错误的可能性更低。
不在 update_mask（也称为 FieldMask）中的字段保持不变。
例如，使用稀疏更新可让需要更新关键字级出价的应用受益，因为只需填充广告组 ID、条件 ID 和出价字段。
错误处理和管理
在开发过程中，您可能会遇到错误。本部分介绍在应用中构建错误管理机制的注意事项和策略。除本部分之外，还可参阅问题排查指南了解有关错误管理的更多信息。
区分请求来源
一些应用主要进行交互操作，它们直接发出 API 调用来响应用户在界面中发起的操作。还有一些应用主要是脱机工作，它们将 API 调用作为定期后端进程的一部分发出。许多应用结合了这两种情况。
在考虑错误管理时，区分这些不同类型的请求会非常有用。
对于用户发起的请求，您的主要关注点应该是为用户提供良好的体验。就所发生的具体错误，在界面中尽可能多地为用户提供相关背景信息。为他们提供可以修正错误的简单步骤（查看下面的建议）。
对于后端发起的请求，请针对应用可能遇到的各种错误类型，实现相应的处理程序。请务必加入一个默认处理程序，用来处理罕见或以前未遇到过的错误。对于默认处理程序，建议将失败的操作和错误添加到队列中，供操作员查看并确定适当的解决方案。
区分错误类型
为构建有效的错误处理机制，了解 Google Ads API 中错误类型之间的差异至关重要。下面是最常见的一些错误类型：
- 身份验证错误
- 可重试错误
- 验证错误
- 与同步相关的错误
如需了解详情，请参阅错误类型和常见错误。
同步后端
如果应用用户有手动访问 Google Ads 账号的权限，他们可能会做出应用无法知晓的更改，导致应用的本地数据库不同步。如错误类型指南中所述，对于与同步相关的错误，您既可以在其发生时解决，也可尝试主动防范。一种主动策略是对所有账号每晚执行一次同步作业，获取账号中的 Google Ads 对象，并与本地数据库进行比较。
记录错误
应将所有错误都记录到日志中以便进行调试和监控。至少应记录请求 ID、引发错误的操作和错误本身。其他要记录的信息包括客户 ID、API 服务、往返请求延迟、重试次数以及原始请求和响应。
监控趋势
请务必监控 API 错误的趋势，以便可以检测和解决应用的问题。可以考虑构建自己的解决方案或从市售的众多商业工具中选择一个，以便使用您的日志来生成交互式信息中心，并自动发送提醒。
开发
在开发期间使用测试账号。
使用测试账号
测试账号是不会实际投放广告的 Google Ads 账号。您可以使用测试账号对 Google Ads API 进行实验，并测试应用的连接性、广告系列管理逻辑或其他处理过程能否正常运作。您的开发者令牌无需获得批准即可用于测试账号，因此您可以在申请开发者令牌之后（甚至在应用审核完成之前）立即开始使用 Google Ads API 进行开发。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-27。
[null,null,["最后更新时间 (UTC)：2025-08-27。"],[[["\u003cp\u003eOptimize your app's performance by using batch operations and sending sparse objects to reduce API calls and processing time.\u003c/p\u003e\n"],["\u003cp\u003eMaintain uninterrupted app function by keeping your developer contact email current, subscribing to Google Ads communication channels, and ensuring API compliance.\u003c/p\u003e\n"],["\u003cp\u003eImplement robust error handling by distinguishing request sources and error types, proactively syncing data, logging errors comprehensively, and monitoring error trends.\u003c/p\u003e\n"],["\u003cp\u003eUtilize test accounts for development and experimentation to validate app functionality without affecting live campaigns.\u003c/p\u003e\n"]]],[],null,["# Best Practices\n\nondemand_video\n[Video: Check out the best practices talk from the 2019 workshop](https://www.youtube.com/watch?v=J9zVoWT7twk&list=None&start=None)\n\nThis guide covers some best practices you can implement to optimize\nthe efficiency and performance of your apps.\n\nOngoing maintenance\n-------------------\n\nTo ensure that your app runs uninterrupted:\n\n- Keep your developer contact email in the API center up to date.\n This is the alias we use to contact you. If we're unable to contact you\n regarding compliance with the API Terms and Conditions, your API access\n may be revoked without your prior knowledge. Avoid using a personal email\n address tied to an individual or unmonitored account. To view the API\n center, you must be logged in to your manager account.\n\n- To be informed of issues such as product changes, maintenance downtime,\n deprecation dates, and so on, subscribe to our\n\n - [Forum](//groups.google.com/g/adwords-api)\n - [API blog](//ads-developers.googleblog.com/search/label/google_ads_api)\n - [Product blog](//blog.google/products/ads-commerce/)\n\nThe forum is regularly monitored by the Google Ads API team, making it the ideal place\nto post API questions.\n\n- Keep your app compliant with the Google Ads API [Terms and Conditions](/google-ads/api/terms) (T\\&C). If required, the token review and compliance team will reach out to you using your contact email. If you have questions or concerns about the T\\&C, you can reach out to the review team by responding to the email they sent you when reviewing your developer token application.\n\nOptimization\n------------\n\nYou can optimize your app by running batch operations and, if appropriate,\nsending sparse objects.\n\n### Batch operations\n\nMaking a request to the API entails a number of fixed costs, such as\nround-trip network latency, serialization and deserialization processing, and\ncalls to back-end systems. To lessen the impact of these fixed costs and\nincrease overall performance, most mutate methods in the API are designed to\naccept an array of operations. By batching multiple operations into each\nrequest, you can reduce the number of requests you make and the associated\nfixed costs. If you can, avoid making requests with only one operation.\n\nFor example, suppose you're adding 50,000 keywords to a campaign across multiple\nad groups. Instead of making 50,000 requests with 1 keyword each,\nmake 100 requests with 500 keywords each, or even 10 requests with\n5,000 keywords each. There are limits on the number of operations\nallowed in a request, so you may need to adjust your batch size to achieve\noptimal performance.\n\n### Send sparse objects\n\nWhen objects are sent to the API, fields must be deserialized, validated,\nand stored in the database. Passing in full objects when you only want to update\na few fields can result in extra processing time and decreased performance.\nTo mitigate this, the Google Ads API supports sparse updates, allowing you\nto populate only the fields in an object that you need to change or that are\nrequired. Sparse updates process faster and are less likely to produce errors.\nFields that aren't in the update_mask (also known as `FieldMask`) are left\nunchanged.\n\nFor example, an app that updates keyword-level bids can benefit from using\nsparse updates, as only the ad group ID, criterion ID, and bids fields would\nneed to be populated.\n\nError handling and management\n-----------------------------\n\nDuring development, you're likely to encounter errors. This section describes\nconsiderations and strategies for building error management into your app.\nIn addition to this section, visit the [Troubleshooting\nguide](/google-ads/api/docs/best-practices/troubleshooting) for more information on managing\nerrors.\n\n### Distinguish request sources\n\nSome apps are primarily interactive, issuing API calls directly in response\nto user-initiated actions in a UI. Others work primarily offline, issuing\nAPI calls as part of a periodic back-end process. Many apps combine the two.\nWhen thinking about error management, it can be useful to distinguish these\ndifferent types of requests.\n\nFor user-initiated requests, your primary concern should be providing a good\nexperience for your users. Use the specific error that occurred to provide the\nuser with as much context as you can in the UI. Offer easy steps they can take\nto resolve the error (check out the suggestions below).\n\nFor requests initiated on the back end, implement handlers for the different\ntypes of errors your app may encounter. Always include a default handler to\naddress rare or previously unencountered errors. A good approach for a default\nhandler is to add the failed operation and error to a queue for a human operator\nto review and determine an appropriate resolution.\n\n### Distinguish error types\n\nKnowing the differences between error types in Google Ads API is crucial when\nbuilding robust error handling. Some of the most common error types are:\n\n1. [Authentication errors](/google-ads/api/docs/best-practices/error-types#authentication_errors)\n2. [Retryable errors](/google-ads/api/docs/best-practices/error-types#retryable_errors)\n3. [Validation errors](/google-ads/api/docs/best-practices/error-types#validation_errors)\n4. [Sync-related errors](/google-ads/api/docs/best-practices/error-types#sync-related_errors)\n\nRefer to [Error Types](/google-ads/api/docs/best-practices/error-types) and\n[Common Errors](/google-ads/api/docs/common-errors) for more details.\n\n### Sync back ends\n\nIf your app's users have manual access to Google Ads accounts, they may make\nchanges that your app is not aware of, causing your app's local database to go\nout of sync. As noted in our [Error Types](/google-ads/api/docs/best-practices/error-types) guide,\nyou can address sync-related errors reactively when they occur, but you can also\ntry to prevent them proactively. One proactive strategy is to run a nightly\nsync job on all your accounts, retrieving the Google Ads objects in your\naccounts and comparing against your local database.\n\n### Log errors\n\nAll errors should be logged to facilitate debugging and monitoring. At a\nminimum, log the request ID, the operations that caused the error, and the\nerror itself. Other information to log includes customer ID, API service,\nround-trip request latency, number of retries, and the raw request and response.\n\n### Monitor trends\n\nBe sure to monitor trends in API errors so that you can detect and address\nproblems with your app. Consider building your own solution or employing one\nof many available commercial tools that can use your logs to produce interactive\ndashboards and send automated alerts.\n\nDevelopment\n-----------\n\nUse test accounts during development.\n\n### Use test accounts\n\n[Test accounts](/google-ads/api/docs/best-practices/test-accounts) are Google Ads\naccounts that don't actually serve ads. You can use a test account to\nexperiment with the Google Ads API and test that your app's connectivity, campaign\nmanagement logic, or other processing are working as expected. Your developer\ntoken does not need to be approved to be used on a test account, so you can\nstart developing with the Google Ads API immediately after requesting a developer\ntoken, even before your app is reviewed."]]
