视频广告系列

视频广告系列可让您在 YouTube 以及 Google 视频合作伙伴的网站和应用中展示视频广告。

API 限制

Google Ads API 主要支持提取和报告现有的视频广告系列、广告组、广告和条件。无法使用 Google Ads API 制作或更改视频广告系列，但以下版本特定的例外情况和行为除外：

• VideoResponsiveAdInfo 可变性：从 v24 开始，VideoResponsiveAdInfo 对象是可变的（在早期版本中，它们是不可变的）。创建或更改 VideoResponsiveAdInfo 时，videos、business_name 和 logo_images 字段是必需字段。
• 品牌保障适宜性：自 v24起，广告系列级campaign.video_brand_safety_suitability将被移除。使用 customer.video_brand_safety_suitability 在账号一级查询品牌保障适宜性。
• 视频广告系列实验：从 v24 开始，experiment.video_experiment 可用于配置由视频广告系列组成的 YOUTUBE_CUSTOM 实验。

广告系列管理替代方案

如果您需要以编程方式制作或管理视频广告系列，请考虑以下选项：

• Google Ads 脚本：您可以使用 Google Ads 脚本管理视频广告系列。这样就可以在 Google Ads 界面中进行自动化管理。
• 需求开发广告系列：如果您的目标是在包括 YouTube 在内的 Google 产品和服务中投放视频广告，Google Ads API 完全支持创建和管理需求开发广告系列。

获取效果数据

您可以使用 GoogleAdsService.SearchStream 检索视频广告系列、广告组和条件的效果数据，只需按 campaign.advertising_channel_type = 'VIDEO' 进行过滤即可。

注意： 请使用 metrics.video_trueview_views、metrics.video_trueview_view_rate 和 metrics.trueview_average_cpv 来衡量 TrueView 观看次数指标。从 v25开始，您还可以选择 segments.ad_sub_format_type（以及 segments.ad_format_type），按时长细分不可跳过的插播广告，以及视频社交互动指标（metrics.youtube_comments、metrics.youtube_likes 和 metrics.youtube_shares）。

广告组效果

以下查询会从 ad_group 资源中检索视频广告系列和广告组指标，包括 TrueView 视频观看次数和四分位数完整播放率：

SELECT
  campaign.id,
  campaign.name,
  campaign.advertising_channel_type,
  ad_group.id,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.video_trueview_views,
  metrics.video_quartile_p100_rate
FROM ad_group
WHERE campaign.advertising_channel_type = 'VIDEO'

视频展示位置和条件报告

由于 ad_group_criterion 不直接支持指标或细分，因此请使用 managed_placement_view 等条件视图资源来检索定位到的 YouTube 视频、YouTube 频道或其他自选展示位置的效果指标：

SELECT
  campaign.id,
  ad_group.id,
  ad_group_criterion.criterion_id,
  ad_group_criterion.type,
  ad_group_criterion.youtube_video.video_id,
  ad_group_criterion.youtube_channel.channel_id,
  metrics.impressions,
  metrics.video_trueview_views
FROM managed_placement_view
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND ad_group_criterion.type IN ('YOUTUBE_VIDEO', 'YOUTUBE_CHANNEL')
  AND segments.date DURING LAST_30_DAYS

广告系列覆盖面和频次报告

对于视频广告系列，您可以查询 campaign 资源中的 Unique Reach 覆盖面指标，以衡量在特定展示频次下看到您广告的唯一身份用户数。

以下唯一身份用户指标用于衡量不同频次范围内的受众群体覆盖面：

• metrics.unique_users：在所选日期范围（最长 92 天）内至少看到过一次广告的唯一身份用户数量。无法跨行汇总。
• metrics.unique_users_two_plus 到 metrics.unique_users_ten_plus： 在最长 31 天的日期范围内，分别看过您的广告至少 2 到 10 次的唯一身份用户数（metrics.unique_users_six_plus 到 metrics.unique_users_nine_plus 完善了 v26 及更高版本中的 2+ 到 10+ 集合）。
• metrics.average_impression_frequency_per_user：在所请求的时间段（最长 92 天）内，唯一身份用户看到您广告的平均次数。它无法跨行汇总，也没有配套的 _info 字段。

在 v26 及更高版本中，每个覆盖面指标都有一个类型为 ReachMetricInfo 的配套元数据字段：metrics.unique_users_info 和 metrics.unique_users_two_plus_info 到 metrics.unique_users_ten_plus_info。

在 Google Ads 查询语言 (GAQL) 中，随播广告覆盖面字段是直接在 SELECT 子句中选择的 MESSAGE 指标（例如 metrics.unique_users_info）。请勿在 SELECT 子句中附加 .reach_metric_states，因为在 GAQL 中选择嵌套消息字段会失败，并显示 UNRECOGNIZED_FIELD。相反，选择 metrics.unique_users_info 会返回一个 ReachMetricInfo 消息，其中包含 ReachMetricState 类型的重复枚举字段 reach_metric_states，该字段描述了指标是被抑制还是完整。

每当覆盖面指标被抑制或超出保留期限（PRIVACY_SUPPRESSION、QUALITY_SUPPRESSION 或 DATE_RANGE_BEYOND_RETENTION）时，其在 Metrics 上的 optional int64 字段将处于未设置状态（如果未检查字段是否存在，则计算结果为 0），而 LOW_QUALITY 仍会填充数值指标。

ReachMetricState 枚举值表示覆盖面数据的状态：

• COMPLETE：覆盖面指标完整，未因隐私、质量或其他限制而受到抑制。
• PRIVACY_SUPPRESSION：为保护用户隐私，覆盖面数据已被隐藏（例如，当受众群体数量未达到 k-匿名性阈值时）。
• QUALITY_SUPPRESSION：由于数据质量要求，覆盖面数据被屏蔽。
• LOW_QUALITY：覆盖面指标已计算，但被标记为质量较低。
• DATE_RANGE_BEYOND_RETENTION：由于所选日期范围超出了覆盖面数据的 3 年数据保留期限，因此无法查看覆盖面指标。

以下查询会检索视频广告系列的覆盖面指标及其抑制状态：

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  segments.device,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.average_impression_frequency_per_user,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_three_plus,
  metrics.unique_users_three_plus_info,
  metrics.unique_users_four_plus,
  metrics.unique_users_four_plus_info,
  metrics.unique_users_five_plus,
  metrics.unique_users_five_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_seven_plus,
  metrics.unique_users_seven_plus_info,
  metrics.unique_users_eight_plus,
  metrics.unique_users_eight_plus_info,
  metrics.unique_users_nine_plus,
  metrics.unique_users_nine_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date BETWEEN '2026-01-01' AND '2026-01-31'

注意： 覆盖面和频次指标无法跨行汇总。虽然 metrics.unique_users 和 metrics.average_impression_frequency_per_user 支持最长 92 天的日期范围，并且可以按segments.date、segments.device、segments.adjusted_age_range 和 segments.adjusted_gender 进行细分，但 unique_users_*_plus 频次分桶指标（最长 31 天）和所有配套的 metrics.unique_users*_info 字段仅支持segments.date和segments.device。此外，随播广告 metrics.unique_users*_info 字段是具有 filterable: false 和 sortable: false 的 MESSAGE 指标，因此不能在 WHERE 或 ORDER BY 子句中使用。如需详细了解如何处理报告中被抑制的覆盖面指标，请参阅覆盖面指标抑制和零值。