影片廣告活動

影片廣告活動可讓您在 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 資源的不重複觸及指標，評估在特定曝光頻率下，看到廣告的不重複使用者人數。

下列不重複使用者指標可評估各頻率分組的目標對象觸及數：

• 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 欄位是 MESSAGE 指標，含有 filterable: false 和 sortable: false，因此無法用於 WHERE 或 ORDER BY 子句。如要進一步瞭解如何處理報表中隱藏的觸及指標，請參閱「觸及指標隱藏和零值」。