批量操作Google Ads不卡顿google-ads-python的add_mutation操作与Batch Job批量任务实战【免费下载链接】google-ads-pythonGoogle Ads API Client Library for Python项目地址: https://gitcode.com/gh_mirrors/go/google-ads-pythongoogle-ads-python是 Google Ads API 的官方 Python 客户端库也是用 Python 批量管理广告计划、广告组、关键词的首选工具。本文面向新手讲清楚两件事如何用 Mutation变更操作一次性提交大批量增删改请求以及在操作量超出单次调用上限时如何用 Batch Job 批量任务让服务器排队慢慢跑彻底告别请求卡顿、限流报错。为什么批量操作 Google Ads 容易卡顿很多新手的第一反应是循环 1 万次每次调用 API 建一个关键词。结果很快遇到两个问题问题原因后果单次调用被拒每次mutate_*调用最多携带10000 个操作批量任务中途失败RateExceededError 限流单位时间内请求量超出账号配额脚本卡顿、反复重试超时断开一次性同步请求耗时过长本地网络超时核心思路不要多次小请求而要一次大请求实在太大就交给 Batch Job 在服务器端排队执行。最快写法一次 mutate 调用携带上千个操作在 google-ads-python 中所有增删改操作统一叫Mutation提交方式是各服务客户端的mutate_*方法这就是add_mutation操作在代码中的真实形态。关键点只有一个它接收的是 Operation 列表一次可以打包几千个操作。以 examples/basic_operations/add_campaigns.py 为例先建预算、再建广告计划campaign_budget_response campaign_budget_service.mutate_campaign_budgets( customer_idcustomer_id, operations[campaign_budget_operation], # 列表可一次放多个 )想批量创建 500 个广告组把 500 个AdGroupOperation全部放进operations列表一次调用搞定。这就是批量操作不卡顿的第一层方案。 每次调用携带 10000 个操作批量 5 万条数据也只需 5 次调用远比 5 万次调用安全。操作量超限时Batch Job 批量任务登场当操作数超过 10000/次甚至需要几十万条时就该上BatchJobService了。它把整批操作交给 Google 服务器排队执行你只管轮询进度、最后取结果。完整参考示例examples/campaign_management/add_complete_campaigns_using_batch_job.py它演示了如何用 Batch Job 一次性创建预算 计划 广告组 关键词 广告的完整广告结构。Batch Job 五步流程第 1 步创建批量任务—— 调用mutate_batch_job拿到资源名resource name后续所有步骤都靠它定位任务。第 2 步上传操作—— 调用add_batch_job_operations。首次调用sequence_token传空响应的next_sequence_token用于下一批上传防止重复提交response batch_job_service.add_batch_job_operations( resource_nameresource_name, sequence_tokenNone, # 首次传空 mutate_operationsoperations, ) print(response.next_sequence_token) # 记住它下次上传用单个 Batch Job 最多可容纳100000 个操作是常规 mutate 调用的 10 倍容量。第 3 步运行任务——run_batch_job返回一个长时操作LRO对象。第 4 步轮询等待—— 通过回调等待任务完成示例中用asyncio.Event优雅地挂起主流程。第 5 步获取结果—— 任务完成后分页拉取每条操作的执行状态for result in batch_job_service.list_batch_job_results(requestrequest): print(result.operation_index, result.status.message)临时 ID如何引用还没创建成功的实体批量创建时广告组要挂在广告计划下可计划本身也在这批操作里还没建出来。解决办法是用负数临时 ID如-1、-2占位任务执行时 Google 会自动替换成真实 ID。示例中get_next_temporary_id()函数就是干这个的_temporary_id: int 0 def get_next_temporary_id() - int: _temporary_id - 1 return _temporary_id # 依次返回 -1、-2、-3...⚠️ 注意操作列表的顺序要符合依赖关系——预算在前、计划在中、广告组和关键词在后临时 ID 引用才能正确解析。批量操作的错误处理部分失败与限流批量操作最怕全部回滚好在 Google Ads API 采用**部分失败Partial Failure**机制某一条关键词写错只影响那一条其余照常创建。Batch Job 结果中每条操作都带独立状态正好用来定位坏数据。两个实战示例值得收藏部分失败examples/error_handling/handle_partial_failure.py —— 故意创建含非法字符的广告组演示如何从响应中提取partial_failure.errors并打印具体位置。限流重试examples/error_handling/handle_rate_exceeded_error.py —— 捕获RateExceededError后指数退避重试示例配置了 3 次重试 递增等待时间这是批量脚本的标配兜底逻辑。相关错误类型定义可参考 google/ads/googleads/v24/errors/types/quota_error.py。快速开始安装与配置 google-ads-python一键安装步骤三种方式任选pip install google-ads # 方式一PyPI 安装 git clone https://gitcode.com/gh_mirrors/go/google-ads-python # 方式二获取源码 pip install ./google-ads-python配置方法在用户主目录创建google-ads.yaml填入开发者令牌、客户 ID 与 OAuth2 凭据GoogleAdsClient.load_from_storage()会自动读取。配置模板见项目根目录的 google-ads.yaml初始化细节在 examples/utils/example_helpers.py 中都有演示。from google.ads.googleads.client import GoogleAdsClient client GoogleAdsClient.load_from_storage(versionv24)总结该用哪种方案操作量级推荐方案关键 API≤ 1 万条单次 mutate 调用打包mutate_* Operation 列表1 万 ~ 10 万条分批多次 mutate每批 ≤1 万同上 10 万条Batch Job 批量任务BatchJobService五步流程记住三个关键词Operation 列表打包、sequence_token 防重、临时 ID 解依赖再配上部分失败与限流重试兜底你的批量脚本就能又快又稳。动手改改add_complete_campaigns_using_batch_job.py里的示例数字跑通你的第一个 Batch Job 吧【免费下载链接】google-ads-pythonGoogle Ads API Client Library for Python项目地址: https://gitcode.com/gh_mirrors/go/google-ads-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考