
Google Ads API 已正式发布 12.0 版本。作为继 6 月 11.0 版及 8 月 11.1 版后的重大更新,此次升级涉及账户管理、广告素材、出价策略及报告等多个核心模块。需要注意的是,AdWords API 已于今年 4 月停用并将于 7 月底彻底下线,建议开发者尽快完成迁移。
账户管理与广告类型调整
- 新增账户链接类型:引入 ADVERTISING_PARTNER 链接类型,用于关联客户账户,为后续功能迭代预留接口;非管理员用户创建链接时将触发 AccountLinkError.PERMISSION_DENIED 错误。
- Gmail 广告变更:停止支持创建新的 Gmail 广告,官方建议迁移至 Discovery(探索)广告系列。
素材资源与位置定向增强
素材检索与管理优化
- 支持通过 GoogleAdsService.SearchStream/Search 使用 LeadFormSubmissionData 检索 CustomLeadFormSubmissionField。
- CampaignAsset 和 AdGroupAsset 新增对 AD_IMAGE 字段类型的增删改支持(限白名单客户),并可通过 asset_field_type_view 报表获取 Image 素材统计数据。
- asset_set_asset 报表现已支持指标与细分维度;ad_group_ad_asset_view 新增 pinned_field 筛选及 segment.conversion_action 支持。
- 测试账户支持将客户/活动组与素材集关联,并新增 CustomerAssetSetService 及 AdGroupAssetSetService 用于管理相关链接关系。
位置素材资源扩展
- 测试账户支持修改和获取位置素材资源。新增 Asset.location_asset 字段及 location_group_parent_asset_set_id 等资产集来源字段。
- Campaign 和 AdGroup 新增 excluded_parent_asset_set_types 字段;枚举值新增 AssetType.LOCATION 及 LOCATION_SYNC、BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP 等多种资产集类型。
- 报告层面,per_store_view 返回按 Place ID 层级的统计数据,asset_set_type_view 返回按资产集类型层级的统计(目前仅支持位置资产集)。
智能广告系列与投放状态洞察
- 关键词主题建议升级:SmartCampaignSuggestService.SuggestKeywordThemes 可生成更多建议,包括自由格式关键词主题,同时优化了面向用户的错误代码提示。
- 智能展示广告限制:不再支持创建新的智能展示广告系列(现有系列不受影响),尝试创建将抛出 OperationAccessDeniedError.CREATE_OPERATION_NOT_PERMITTED 错误。
- 投放状态诊断:Campaign 对象新增 primary_status 及 primary_status_reasons 字段,用于解释广告系列未投放或未达最佳状态的具体原因。
- 本地服务广告定位:支持添加/移除位置定向(邻近定向除外),并针对无效操作新增了 AT_LEAST_ONE_POSITIVE_LOCATION_REQUIRED_FOR_LOCAL_SERVICES_CAMPAIGN 等多项 CampaignCriterionError 错误类型。
出价策略、计费与转化追踪
出价与预算关联
- 支持通过批量修改操作关联组合出价策略与广告系列预算,新增 BiddingStrategy.aligned_campaign_budget_id 及 CampaignBudget.aligned_bidding_strategy_id 字段。
计费对账优化
- Invoice.account_summaries[] 新增 AccountSummary 以支持账单对账(限白名单客户);新增 BillingSetupError.TOO_MANY_BILLING_SETUPS_FOR_PAYMENTS_ACCOUNT 及 AccountBudgetProposalError.INVALID_MASTER_SERVICE_AGREEMENT 错误类型。
转化数据规范化
- conversion_tracking_id 对所有客户始终大于 0,解决了此前未创建转化行为时可能为 0 的问题。
- 上传增强型转化时新增 debug_enabled 参数,便于在执行检查后直接返回发现的错误信息。
实验、规划与建议功能更新
- 实验架构调整:移除 CampaignExperimentService,统一使用新实验功能;ExperimentArm.trial 重命名为 ExperimentArm.experiment;使用 MutateExperimentArms 创建实验臂时,若 response_content_type 设为 MUTABLE_RESOURCE,将自动填充 ExperimentArm.in_design_campaigns。
- 受众洞察扩展:AudienceInsightsService.ListAudienceInsightsAttributes 新增 GEO_TARGET_COUNTRY 和 SUB_COUNTRY_LOCATION 维度;ListInsightsEligibleDates(限白名单)支持发现可用日期范围;ReachPlanService 移除 GenerateProductMixIdeas;Targeting.plannable_location_ids 支持同一父级地理位置下的多地点定位。
- 智能推荐新增:新增 RaiseTargetCpaBidTooLowRecommendation 帮助启动投放,以及 ForecastingSetTargetRoasRecommendation 以捕捉预期流量增长带来的转化价值。
报告指标与其他技术变更
报告数据丰富化
- landing_page_view 报告在 segments.click_type = SITELINKS 时支持返回点击次数。
- 新增 metrics.publisher_purchased_clicks、metrics.publisher_organic_clicks 及 metrics.publisher_unknown_clicks 三项已购流量指标。
其他技术细节
- 受众群体:OfflineUserDataJobFailureReason 新增 HIGH_AVERAGE_TRANSACTION_VALUE、LOW_AVERAGE_TRANSACTION_VALUE 及 NEWLY_OBSERVED_CURRENCY_CODE 枚举值。
- 标准与Feed:测试账户 LocationGroupInfo 新增 location_group_asset_sets 字段及启用客户级位置资产设置选项;CriterionError 新增多项资产集相关错误值;CampaignFeedError 等枚举类型添加 LEGACY_FEED_TYPE_READ_ONLY。
- 错误代码变更:BiddingStrategy.currency_code/scheme/type、TargetCpa.target_cpa_micros、TargetImpressionShare.cpc_bid_ceiling_micros 及 TargetSpend.target_spend_micros(已弃用)等字段的无效操作错误代码已更新。

