您可以使用動態廣告插播 (DAI) 串流播放活動監控器 (SAM) API,擷取直播和隨選影片 (VOD) 工作階段的診斷記錄和放送結果。
本指南說明如何設定驗證、擷取頂層 DaiSession 資源,以及要求工作階段欄位中識別的資源。
必要條件
如要使用 SAM API,您需要具備下列項目:
- Google Ad Manager API 存取權。詳情請參閱「入門指南」。
- 已設定的 DAI 直播或 VOD 串流。詳情請參閱「設定 DAI 直播」和「為隨選影片建立內容來源」。
- 串流建立請求中的 DAI 工作階段 ID 或偵錯鍵。詳情請參閱「找出 DAI 工作階段 ID 或偵錯鍵」。
要求DaiSession資源
如要檢查 DAI 工作階段,請將 HTTP GET 要求傳送至 networks.daiSessions.get 端點,並附上 DAI 工作階段 ID 或 DAI 串流偵錯金鑰。
依 ID 擷取 DaiSession 資源
使用 IMA DAI SDK、全服務 DAI API 或廣告連播放送 DAI API 註冊串流工作階段時,Google DAI 會傳回 DAI 工作階段 ID。
以下範例使用工作階段 ID 擷取 DaiSession 資源:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
-H "Authorization: Bearer OAUTH_TOKEN"
更改下列內容:
NETWORK_CODE:您的 Google Ad Manager 聯播網代碼SESSION_ID:建立串流工作階段時傳回的 DAI 工作階段 IDOAUTH_TOKEN:您的 OAuth 2.0 存取權杖
使用 DAI 工作階段的偵錯金鑰
註冊串流工作階段時,您可以使用 dai-sam-id 參數或 Pod 放送 VOD 請求中的 sam_id 參數,指派自訂偵錯金鑰。您可以直接在 DaiSession 資源路徑中傳遞這個偵錯金鑰。
以下範例使用偵錯金鑰擷取 DaiSession 資源:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
-H "Authorization: Bearer OAUTH_TOKEN"
將 DEBUG_KEY 替換為串流建立要求中指定的自訂偵錯金鑰。
這兩項要求都會傳回 DaiSession JSON 回應,其中包含工作階段情境、廣告選擇、決策廣告連播、廣告插播和診斷結果。輸出結果會與下列內容相似:
{
"name": "networks/21775744923/daiSessions/9587e2c1-d745-4bf1-9f6a-e9092127cb48:ATL",
"creationContext": {
"streamCreateRequest": {
"requestTime": "2026-10-16T19:59:57.365124Z",
"latency": "0.045s",
"url": "/ssai/event/c-rArva4ShKVIAkNfy6HUQ/streams",
"userAgent": "Mozilla/5.0",
"responseCode": 201
},
"linearInfo": {
"liveStream": "networks/21775744923/liveStreams/20000016294786",
"assetKey": "c-rArva4ShKVIAkNfy6HUQ",
"prefetchEnabled": false,
"podTrimmingEnabled": true,
"podTrimTolerance": "2s",
"eventStartTime": "2020-06-09T20:00:00Z",
"eventEndTime": "2037-01-01T08:00:00Z"
},
"debugKey": "my-custom-debug-key-001",
"contentTitle": "IMA sample HLS live stream",
"stitchingType": "STITCHED",
"reportingType": "CLIENT",
"interstitialEnabled": false
},
"slate": {
"idType": "CREATIVE_ID",
"idValue": "138544327419",
"adSystem": "GDFP",
"duration": "10s"
},
"adSelections": {
"2021043961286562353": {
"type": "VAST",
"adRequest": {
"adRequestKey": "2021043961286562353",
"adTag": "https://pubads.g.doubleclick.net/gampad/live/ads?iu=/21775744923/external/vmap_ads_for_dai&cust_params=sample_ar%3Dstreammidonly&output=xml_vast4&pmxd=30000",
"httpRequest": {
"requestTime": "2026-10-16T19:59:57.177283526Z",
"latency": "0.138s",
"url": "https://pubads.g.doubleclick.net/gampad/live/ads?iu=/21775744923/external/vmap_ads_for_dai&cust_params=sample_ar%3Dstreammidonly&output=xml_vast4&pmxd=30000",
"responseCode": 200,
"responseBody": "<VAST version=\"4.0\"><Ad id=\"5937252921\" sequence=\"1\"><InLine><AdSystem>GDFP</AdSystem><AdTitle>External - Pod Midroll 1</AdTitle><Creatives><Creative id=\"138383221557\" sequence=\"1\"><Linear><Duration>00:00:10</Duration></Linear></Creative></Creatives></InLine></Ad></VAST>"
},
"childRequests": []
}
}
},
"adPods": {
"9204525715521575580": {
"requestedBreakType": "MIDROLL",
"adRequestKey": "2021043961286562353",
"prefetchStage": "DISABLED",
"adBreakId": "-3821178632466845617",
"label": "3196133",
"creatives": {
"6086226973783046639": {
"idType": "GOOGLE_VIDEO_REGISTRY_ID",
"idValue": "tVFdo4-fFVE",
"adSystem": "GDFP",
"duration": "10.010s",
"podSequence": 1,
"adBuffet": false,
"vastInfos": [
{
"adSystem": "GDFP",
"adTitle": "External - Pod Midroll 1",
"creativeId": "138383221557"
}
]
}
}
}
},
"adBreaks": {
"-3821178632466845617": {
"podKeys": [
"9204525715521575580"
],
"adBreakId": "-3821178632466845617",
"breakType": "MIDROLL",
"breakSequence": "3196133",
"servedAdsDuration": "30.999999999s",
"executedBreakDuration": "30.999999999s",
"linear": {
"breakStartTime": "2026-10-16T20:22:28.130329Z",
"expectedBreakDuration": "31s",
"slateDuration": "0s",
"underlyingDuration": "0s"
},
"trackingPings": {
"3641994172850159057": {
"originalTrackingEventId": "google_4445276280058090123",
"request": {
"requestTime": "2026-10-16T20:22:29.393993Z",
"latency": "0.030s",
"url": "https://dai.google.com/view/p/service/linear/impression/stream/1dccd632-5028-45be-a68a-6c90645cd237:ATL/network/21775744923/event/xDte1UxoSxmtRrB6lqHdmg/media/7083951761/stream_ad_id/EfzeSEQzFPU",
"responseCode": 200
}
}
}
}
},
"findings": [
{
"severity": "INFO",
"description": "Minimum slate inserted into underfilled ad break.",
"slateFinding": {
"type": "SLATE_STATUS_MINIMUM_INSERTED"
}
},
{
"severity": "INFO",
"description": "Ad break was decisioned, but not served during playback.",
"adBreakFinding": {
"type": "UNSERVED_BREAK",
"breakKey": "-3821178632466845617"
}
}
],
"sessionDuration": "31.453022s"
}
要求相關資源
識別工作階段後,您可以在 DaiSession 資源中查詢特定工作階段欄位、從工作階段發現項目中瀏覽實體金鑰,或向 Ad Manager API 中的相關資源提出後續要求。
使用欄位遮罩篩選工作階段欄位
完整的 DaiSession 回應包含原始 VAST 和 VMAP XML 主體,以及所有歷來廣告插播事件。如要縮減酬載大小,並只擷取所需的階段欄位,請在 fields 查詢參數或 X-Goog-FieldMask HTTP 標頭中傳遞讀取遮罩。詳情請參閱「欄位遮罩」。
如要檢查工作階段是否發生錯誤,請僅要求工作階段建立情境和診斷結果:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID?fields=name,creationContext,findings" \
-H "Authorization: Bearer OAUTH_TOKEN"
如要只擷取 adBreaks 和 adPods 欄位,而不下載 adSelections 欄位中的原始 XML 廣告回應,請使用 X-Goog-FieldMask 標頭:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
-H "Authorization: Bearer OAUTH_TOKEN" \
-H "X-Goog-FieldMask: name,adBreaks,adPods"
檢查工作階段發現項目
findings 清單中的每個項目都包含一個類型化發現項目物件,其索引鍵指向 DaiSession 資源中的特定實體。下表說明如何將發現項目索引鍵解析為工作階段欄位:
| 尋找金鑰路徑 | DaiSession中的指定地區 |
|---|---|
adBreakFinding.breakKey |
adBreaks[breakKey] |
adRequestFinding.adSelectionKey、adRequestFinding.adRequestKey |
adSelections[adSelectionKey].adRequest 和巢狀 childRequests[] |
creativeFinding.creativeKey |
比對 adPods[podKey].creatives[creativeKey] 中的項目是否符合 creativeKey |
podFinding.podKey |
adPods[podKey] |
slateFinding |
slate |
trackingFinding.trackingPingKey |
比對 adBreaks[breakKey].trackingPings[trackingPingKey] 中的項目是否符合 trackingPingKey |
如要追蹤不同集合之間的關係,請按照下列步驟操作:
- 從
adBreaks陣列中的項目開始。 - 讀取
podKeys清單,找出adPods陣列中的對應項目。 - 使用 Pod 上的
adPod.adRequestKey欄位,在adSelections陣列中找出相符的AdRequest.adRequestKey。 - 在相符的
adRequest物件或其巢狀childRequests陣列中,檢查原始 HTTP 要求和 VAST 回應。
索取直播和內容資源
DaiSession 資源包含資源名稱,可連結至 admanager.googleapis.com 端點上 Google Ad Manager API 中的直播和內容資源。如要驗證串流設定和內容中繼資料,您可以向下列資源發出 HTTP GET 要求:
LiveStream資源:使用creationContext.linearInfo.liveStream欄位的值呼叫networks.liveStreams.get方法。- VOD
Content資源:使用creationContext.vodInfo.content欄位的值呼叫networks.content.get方法。
以下範例會擷取 creationContext.linearInfo.liveStream 欄位中參照的連結 LiveStream 資源:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreams/LIVE_STREAM_ID" \
-H "Authorization: Bearer OAUTH_TOKEN"
將 LIVE_STREAM_ID 替換為 DaiSession 資源中的直播 ID。
輸出結果會與下列內容相似:
{
"name": "networks/21775744923/liveStreams/20000016294786",
"displayName": "IMA sample HLS live stream",
"status": "ACTIVE",
"createTime": "2020-06-09T20:00:07Z",
"updateTime": "2026-08-18T15:37:05Z",
"startTime": "2020-06-09T20:00:00Z",
"endTime": "2037-01-01T08:00:00Z",
"endTimeUnlimited": true,
"contentUrls": [
"https://contentsim.sandbox.google.com/content/590f95c5-c3ee-4a56-a10c-0cc660e91faa/linear/multivariant.m3u8"
],
"adTags": [
"https://pubads.g.doubleclick.net/gampad/live/ads?sz=640x480&output=xml_vast3&iu=/21775744923/external/vmap_ads_for_dai&env=vp&impl=s&gdfp_req=1&unviewed_position_start=1&ad_rule=0&cust_params=sample_ar%3Dstreammidonly&lseco=%%ASSET_KEY%%"
],
"assetKey": "c-rArva4ShKVIAkNfy6HUQ",
"slate": "networks/21775744923/slates/138544327419",
"enableDaiAuthenticationKeys": false,
"adBreakFillType": "SLATE",
"underfillAdBreakFillType": "SLATE",
"adHolidayDuration": "0s",
"enableMaxFillerDuration": false,
"enableDurationlessAdBreaks": false,
"hlsSettings": {
"playlistType": "LIVE",
"masterPlaylistSettings": {
"refreshType": "AUTOMATIC"
}
},
"allowlistedIpsEnabled": false,
"dynamicAdInsertionType": "LINEAR",
"relativePlaylistDeliveryEnabled": false,
"streamingFormat": "HLS",
"prefetchEnabled": false,
"forcedCueInEnabled": false,
"shortSegmentDroppingEnabled": false,
"adBreakMarkupTypesEnabled": false,
"earlyBreakNotificationMultiBreakSchedulingEnabled": false,
"dvrWindowDuration": "60s"
}