借助动态广告插播 (DAI) 视频流活动监控工具 (SAM) API,您可以检索直播和视频点播 (VOD) 会话的诊断日志和投放结果。
本指南介绍了如何配置身份验证、检索顶级 DaiSession 资源,以及请求会话字段中标识的资源。
前提条件
如需使用 SAM API,您需要满足以下条件:
- 对 Google Ad Manager API 的访问权限。如需了解详情,请参阅使用入门。
- 已配置的 DAI 直播或 VOD 视频流。如需了解详情,请参阅为 DAI 设置直播和为视频点播创建内容来源。
- 来自视频流创建请求的 DAI 会话 ID 或调试密钥。如需了解详情,请参阅查找 DAI 会话 ID 或调试密钥。
请求 DaiSession 资源
如需检查 DAI 会话,请向 networks.daiSessions.get 端点发送 HTTP 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"
}