
Google Ads 正式发布 API v17 主要版本更新。此次升级重点优化了资源策略、页面大小及批量报告机制,并增强了 PMax(效果最大化广告)与关键词匹配类型的报告功能。作为继 v16.1 后的重大迭代,v17 旨在提升开发效率与数据精准度。值得注意的是,旧版 AdWords API 已于今年 4 月停用,并将于 7 月底彻底停止服务,建议开发者尽快完成迁移。
核心变更概览
本次更新涵盖广告、资产、受众、批量作业、活动管理、转化数据、目标设定、本地服务、报告查询、购物广告、统一目标及视频广告等十二大模块。以下为各模块关键调整:
广告与资产优化
- 广告接口调整:移除
AdService.getAd方法,请改用“检索对象”推荐方式获取广告资源;新增ImageAdInfo.image_asset尺寸与格式验证,无效图片将抛出UNEXPECTED_SIZE或FORMAT_NOT_ALLOWED错误。 - 资产报表增强:新增
ClickType.AD_IMAGE枚举;为 Performance Max 和搜索活动新增campaign_aggregate_asset_view及channel_aggregate_asset_view报表,支持更细粒度的指标分析。
受众与批量作业
- 受众群体:新增
OfflineUserDataJobError.OPERATION_LEVEL_CONSENT_PROVIDED错误类型。 - 批量作业:当
AddBatchJobOperationsRequest超过 10,484,504 字节时触发REQUEST_TOO_LARGE错误;支持在BatchJobService中设置MutateOperation.asset_group_operation,实现通过批处理创建和管理整个 Performance Max 活动。
活动管理与命名规范
- Discovery 更名为 Demand Gen:全平台资源字段、枚举值及错误信息中的 Discovery 统一替换为 Demand Gen(如
AdvertisingChannelType.DEMAND_GEN)。 - 关键词匹配:新增
Campaign.keyword_match_type字段,支持批量设置广告系列内所有关键词的匹配类型。
转化数据与目标设定
- SKAdNetwork 转化:原
segments.sk_ad_network_conversion_value重命名为segments.sk_ad_network_fine_conversion_value,并新增segments.sk_ad_network_redistributed_fine_conversion_value。 - 零值指标返回:
all_conversions_value_by_conversion_date等四项按转化日期统计的指标,即使值为零也将包含在响应中。 - 目标状态可视化:
AdGroupCriterion新增primary_status和primary_status_reasons字段,明确展示投放状态及未投放原因。 - 新增指标支持:
gender_view下新增search_impression_share,keyword_view下新增phone_calls。
本地服务与报告查询
- 线索对话追加:新增
LocalServicesLeadService.AppendLeadConversation(),支持向特定线索追加短信等渠道对话(单次限制 1,000 条);ConversationType新增 WHATSAPP 和 ADS_API 枚举。 - 验证凭证有效期:
local_services_verification_artifact新增保险与执照验证凭证的过期时间字段。 - 查询限制:查询
product_link时禁止同时选择多个关联产品字段;GoogleAdsService.Search不再支持传递page_size参数。
购物、统一目标与视频广告
- 购物产品报告:新增
shopping_product报告,同步 Merchant Center 产品状态;支持按segments.date筛选指标,但不允许按日期细分。 - 统一目标配置:新增
UserListCustomerTypeService.MutateUserListCustomerTypes()用于配置受众客户类型,替代已移除的lifecycle_goal_customer_definition_settings;支持通过PURCHASERS类别将用户列表附加至现有客户定义。 - 视频内容标签:新增家庭适宜、游戏分级、健康敏感、新闻时效性及政治宗教等多个
ContentLabelType排除选项;支持在 DemandGenVideoResponsiveAdInfo 中设置视频库存偏好;白名单账户可修改Campaign.video_brand_safety_suitability字段。

