使用视频流活动监控工具 API

借助动态广告插播 (DAI) 视频流活动监控工具 (SAM) API,您可以检索直播和视频点播 (VOD) 会话的诊断日志和投放结果。

本指南介绍了如何配置身份验证、检索顶级 DaiSession 资源,以及请求会话字段中标识的资源。

前提条件

如需使用 SAM API,您需要满足以下条件:

请求 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 会话 ID
  • OAUTH_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

如需跟踪集合之间的关系,请执行以下操作:

  1. 从 adBreaks 数组中的条目开始。
  2. 读取 podKeys 列表,在 adPods 数组中找到相应的条目。
  3. 使用 Pod 上的 adPod.adRequestKey 字段在 adSelections 数组中查找匹配的 AdRequest.adRequestKey。
  4. 在匹配的 adRequest 对象或其嵌套的 childRequests 数组中检查原始 HTTP 请求和 VAST 响应。

请求直播和内容资源

DaiSession 资源包含资源名称,这些名称会链接到 admanager.googleapis.com 端点上 Google Ad Manager API 中的直播和内容资源。如需验证直播配置和内容元数据,您可以向以下资源发出 HTTP 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"
}