使用串流播放活動監控器 API

您可以使用動態廣告插播 (DAI) 串流播放活動監控器 (SAM) API,擷取直播和隨選影片 (VOD) 工作階段的診斷記錄和放送結果。

本指南說明如何設定驗證、擷取頂層 DaiSession 資源,以及要求工作階段欄位中識別的資源。

必要條件

如要使用 SAM API,您需要具備下列項目:

要求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 工作階段 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"
}