라이브 스트림 활동 모니터링 도구 API 사용

동적 광고 삽입(DAI) 라이브 스트림 활동 모니터링 도구(SAM) API를 사용하면 라이브 스트림 및 VOD 세션의 진단 로그와 전송 결과를 가져올 수 있습니다.

이 가이드에서는 인증을 구성하고, 최상위 DaiSession 리소스를 가져오고, 세션 필드에서 식별된 리소스를 요청하는 방법을 설명합니다.

기본 요건

SAM API를 사용하려면 다음이 필요합니다.

DaiSession 리소스 요청

DAI 세션을 검사하려면 DAI 세션 ID 또는 DAI 스트림 디버그 키를 사용하여 HTTP GET 요청을 networks.daiSessions.get 엔드포인트로 전송합니다.

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 세션에 디버그 키 사용

스트림 세션을 등록할 때 VOD를 제공하는 광고 모음 요청에서 dai-sam-id 매개변수 또는 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"

adSelections 필드에서 원시 XML 광고 응답을 다운로드하지 않고 adBreaks 및 adPods 필드만 가져오려면 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. 포드의 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"
}