影片廣告活動

影片廣告活動可讓您在 YouTube，以及 Google 影片合作夥伴的網站和應用程式中放送影片廣告。

API 限制

Google Ads API 主要支援擷取現有影片廣告活動、廣告群組、廣告和條件，並製作相關報表。您無法使用 Google Ads API 建立或修改影片廣告活動，但有下列版本專屬例外狀況和行為：

• VideoResponsiveAdInfo 可變動性：自第 24 版起，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 觀看指標。自第 25 版起，您也可以選取 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 和 customer (自第 26 版起) 資源中查詢不重複觸及指標，評估在特定曝光頻率下，看到廣告的不重複使用者人數。

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

• 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 天) 內，不重複使用者看到廣告的平均次數。這項指標僅適用於 campaign 資源，無法跨資料列匯總，也沒有隨附的 _info 欄位。

在 v26 以上版本中，每個不重複使用者觸及指標都有一個 ReachMetricInfo 類型的隨附中繼資料欄位：metrics.unique_users_info 和 metrics.unique_users_two_plus_info 到 metrics.unique_users_ten_plus_info。

在 Google Ads 查詢語言 (GAQL) 中，隨播metrics.unique_users*_info欄位是MESSAGE指標，包含filterable: false和sortable: false，因此無法在WHERE或ORDER BY子句中使用。請直接在 SELECT 子句中選取這些欄位 (例如 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 年資料保留期限，因此無法提供觸及指標。

下列查詢會擷取影片廣告活動 30 天內簡化後的觸及指標和抑制狀態，並依裝置和廣告格式區隔。從 SELECT 子句中省略 segments.date 區隔，這樣觸及和N+頻率指標就會在整個日期範圍內簡化，而不是每天簡化：

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  segments.ad_format_type,
  segments.ad_sub_format_type,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date DURING LAST_30_DAYS

支援的資源、日期範圍和區隔

觸及和展示頻率查詢需要指標最大日期範圍內的有限 segments.date 篩選器。如果查詢未設定日期篩選條件，或超出時間範圍，則會傳回未設定的觸及率欄位：

指標	資源	日期範圍上限	相容區隔
metrics.unique_users	campaign、customer (第 26 版以上)	92 天	segments.date、segments.device、廣告格式區隔 (v26 以上版本)、廣告聯播網區隔 (v26 以上版本)，以及調整後客層區隔
metrics.average_impression_frequency_per_user	campaign	92 天	segments.date、segments.device和調整後的客層區隔
metrics.unique_users_two_plus到metrics.unique_users_ten_plus	campaign、customer (第 26 版以上)	31 天	segments.date、segments.device、廣告格式區隔 (v26 以上版本) 和廣告聯播網區隔 (v26 以上版本)
metrics.unique_users*_info (v26 以上版本)	campaign、customer	與基本指標相符	segments.date、segments.device、廣告格式區隔和廣告聯播網區隔

區隔觸及率查詢時，請套用下列聯合區隔限制：

• 廣告格式與廣告聯播網區隔：您可以依廣告格式 (segments.ad_format_type，可選用 segments.ad_sub_format_type) 或廣告聯播網 (segments.ad_network_type，可選用 segments.ad_sub_network_type) 區隔，但無法在同一查詢中合併廣告格式和廣告聯播網區隔。選取子區隔時，請一律選取父項區隔 (segments.ad_format_type 或 segments.ad_network_type)。segments.ad_sub_format_type 區隔會依時間長度細分不可略過的串流內廣告，並傳回其他廣告格式的 UNSEGMENTED，而 segments.ad_sub_network_type 區隔則會細分 YouTube 平台 (YOUTUBE_INSTREAM、YOUTUBE_INFEED 和 YOUTUBE_SHORTS)，但僅限需求開發廣告活動，並傳回影片廣告活動的 UNSEGMENTED。
• 調整後的客層區隔：segments.adjusted_age_range 和 segments.adjusted_gender 區隔僅適用於許可清單帳戶，且必須一併選取，不得與 metrics.unique_users_*_plus 指標、metrics.unique_users*_info 欄位或廣告聯播網區隔合併使用。

注意：觸及和展示頻率指標無法跨列匯總。在 customer 資源上，campaign 欄位無法篩選，且不重複使用者觸及指標會簡化帳戶中所有支援廣告活動類型的觸及。詳情請參閱「觸及指標隱藏和零值」。