Sử dụng API Trình giám sát hoạt động phát trực tuyến

API Trình giám sát hoạt động phát trực tuyến (SAM) của tính năng Chèn quảng cáo động (DAI) cho phép bạn truy xuất nhật ký chẩn đoán và kết quả phân phối cho các phiên phát trực tiếp và video theo yêu cầu (VOD).

Hướng dẫn này trình bày cách định cấu hình quy trình xác thực, truy xuất tài nguyên DaiSession cấp cao nhất và yêu cầu các tài nguyên được xác định trong các trường của phiên.

Điều kiện tiên quyết

Để sử dụng SAM API, bạn cần có:

Yêu cầu tài nguyên DaiSession

Để kiểm tra một phiên DAI, hãy gửi yêu cầu HTTP GET đến điểm cuối networks.daiSessions.get bằng mã phiên DAI hoặc khoá gỡ lỗi luồng DAI.

Truy xuất tài nguyên DaiSession theo mã nhận dạng

Khi bạn đăng ký một phiên phát trực tuyến bằng IMA DAI SDK, API DAI đầy đủ dịch vụ hoặc API DAI phân phát nhóm, Google DAI sẽ trả về một mã phiên DAI.

Ví dụ sau đây truy xuất tài nguyên DaiSession bằng mã phiên:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Thay thế nội dung sau:

  • NETWORK_CODE: mã mạng Google Ad Manager của bạn
  • SESSION_ID: mã phiên DAI được trả về khi tạo phiên phát trực tiếp
  • OAUTH_TOKEN: mã truy cập OAuth 2.0 của bạn

Sử dụng khoá gỡ lỗi cho phiên DAI

Khi đăng ký một phiên phát trực tuyến, bạn có thể chỉ định một khoá gỡ lỗi tuỳ chỉnh bằng cách sử dụng tham số dai-sam-id hoặc tham số sam_id trong các yêu cầu VOD phân phát nhóm quảng cáo. Bạn có thể truyền trực tiếp khoá gỡ lỗi này vào đường dẫn tài nguyên DaiSession.

Ví dụ sau đây truy xuất tài nguyên DaiSession bằng khoá gỡ lỗi:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Thay thế DEBUG_KEY bằng khoá gỡ lỗi tuỳ chỉnh được chỉ định trong yêu cầu tạo sự kiện phát trực tiếp.

Cả hai yêu cầu đều trả về phản hồi JSON DaiSession chứa bối cảnh phiên, lựa chọn quảng cáo, nhóm quảng cáo đã quyết định, điểm chèn quảng cáo và kết quả chẩn đoán. Kết quả sẽ tương tự như sau:

{
  "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"
}

Sau khi xác định một phiên, bạn có thể truy vấn các trường phiên cụ thể trong tài nguyên DaiSession, di chuyển các khoá thực thể từ kết quả phiên hoặc đưa ra yêu cầu tiếp theo cho các tài nguyên có liên quan trong API Ad Manager.

Lọc các trường phiên bằng mặt nạ trường

Phản hồi DaiSession đầy đủ bao gồm nội dung XML thô của VAST và VMAP cũng như tất cả các sự kiện điểm chèn trước đây. Để giảm kích thước tải trọng và chỉ tìm nạp các trường phiên mà bạn cần, hãy truyền mặt nạ đọc trong tham số truy vấn fields hoặc tiêu đề HTTP X-Goog-FieldMask. Để biết thông tin chi tiết, hãy xem phần Mặt nạ trường.

Để kiểm tra xem một phiên có gặp lỗi hay không, chỉ yêu cầu bối cảnh tạo phiên và kết quả chẩn đoán:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID?fields=name,creationContext,findings" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Để chỉ truy xuất các trường adBreaks và adPods mà không tải phản hồi quảng cáo XML thô xuống trong trường adSelections, hãy sử dụng tiêu đề 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"

Kiểm tra kết quả của phiên

Mỗi mục trong danh sách findings bao gồm một đối tượng phát hiện đã nhập có khoá trỏ đến thực thể cụ thể trong tài nguyên DaiSession. Bảng sau đây cho biết cách giải quyết việc tìm khoá cho các trường phiên:

Đang tìm đường dẫn đến khoá Vị trí mục tiêu ở DaiSession
adBreakFinding.breakKey adBreaks[breakKey]
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey adSelections[adSelectionKey].adRequest và childRequests[] lồng nhau
creativeFinding.creativeKey Khớp creativeKey trên các mục trong adPods[podKey].creatives[creativeKey]
podFinding.podKey adPods[podKey]
slateFinding slate
trackingFinding.trackingPingKey So khớp trackingPingKey trên các mục trong adBreaks[breakKey].trackingPings[trackingPingKey]

Để theo dõi mối quan hệ giữa các tập hợp, hãy làm như sau:

  1. Bắt đầu từ một mục trong mảng adBreaks.
  2. Đọc danh sách podKeys để tìm các mục tương ứng trong mảng adPods.
  3. Sử dụng trường adPod.adRequestKey trên pod để tìm AdRequest.adRequestKey phù hợp trong mảng adSelections.
  4. Kiểm tra yêu cầu HTTP ban đầu và phản hồi VAST trong đối tượng adRequest phù hợp hoặc mảng childRequests lồng nhau của đối tượng đó.

Yêu cầu tài nguyên nội dung và sự kiện phát trực tiếp

Tài nguyên DaiSession chứa tên tài nguyên liên kết đến tài nguyên livestream và content trong API Google Ad Manager trên điểm cuối admanager.googleapis.com. Để xác minh cấu hình luồng và siêu dữ liệu nội dung, bạn có thể gửi yêu cầu HTTP GET đến các tài nguyên sau:

  • Tài nguyên LiveStream: Sử dụng giá trị của trường creationContext.linearInfo.liveStream để gọi phương thức networks.liveStreams.get.
  • Tài nguyên Content VOD: Sử dụng giá trị của trường creationContext.vodInfo.content để gọi phương thức networks.content.get.

Ví dụ sau đây truy xuất tài nguyên LiveStream được liên kết và tham chiếu trong trường creationContext.linearInfo.liveStream:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreams/LIVE_STREAM_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Thay thế LIVE_STREAM_ID bằng mã nhận dạng sự kiện phát trực tiếp trong tài nguyên DaiSession.

Kết quả sẽ tương tự như sau:

{
  "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"
}