API ของเครื่องมือตรวจสอบกิจกรรมการสตรีม (SAM) สำหรับการแทรกโฆษณาแบบไดนามิก (DAI) ช่วยให้คุณเรียกข้อมูลบันทึกการวินิจฉัยและผลการแสดงโฆษณาสำหรับเซสชันไลฟ์สดและวิดีโอออนดีมานด์ (VOD) ได้
คู่มือนี้ครอบคลุมวิธีกำหนดค่าการตรวจสอบสิทธิ์ ดึงข้อมูลทรัพยากร DaiSession ระดับบนสุด และขอทรัพยากรที่ระบุในช่องของเซสชัน
ข้อกำหนดเบื้องต้น
หากต้องการใช้ SAM API คุณต้องมีสิ่งต่อไปนี้
- สิทธิ์เข้าถึง Google Ad Manager API ดูข้อมูลเพิ่มเติมได้ที่การเริ่มต้นใช้งาน
- ไลฟ์สด DAI หรือสตรีม VOD ที่กำหนดค่าไว้ ดูข้อมูลเพิ่มเติมได้ที่ตั้งค่าไลฟ์สดสำหรับ DAI และสร้างแหล่งที่มาของเนื้อหาสำหรับวิดีโอออนดีมานด์
- รหัสเซสชัน DAI หรือคีย์การแก้ไขข้อบกพร่องจากคำขอสร้างสตรีม ดูรายละเอียดได้ที่หัวข้อค้นหารหัสเซสชัน DAI หรือคีย์การแก้ไขข้อบกพร่อง
ขอทรัพยากร DaiSession
หากต้องการตรวจสอบเซสชัน DAI ให้ส่งคำขอ HTTP GET ไปยังปลายทาง networks.daiSessions.get พร้อมรหัสเซสชัน DAI หรือคีย์การแก้ไขข้อบกพร่องของสตรีม DAI
ดึงข้อมูลทรัพยากร DaiSession ตามรหัส
เมื่อคุณลงทะเบียนเซสชันสตรีมโดยใช้ IMA DAI SDK, DAI API แบบเต็มบริการ หรือ DAI API แบบแสดงโฆษณาที่จัดกลุ่ม Google DAI จะแสดงรหัสเซสชัน DAI
ตัวอย่างต่อไปนี้จะดึงข้อมูลทรัพยากร DaiSession โดยใช้รหัสเซสชัน
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
-H "Authorization: Bearer OAUTH_TOKEN"
แทนที่ค่าต่อไปนี้
NETWORK_CODE: รหัสเครือข่าย Ad Manager ของ GoogleSESSION_ID: รหัสเซสชัน DAI ที่แสดงผลเมื่อสร้างเซสชันสตรีมOAUTH_TOKEN: โทเค็นเพื่อการเข้าถึง OAuth 2.0
ใช้คีย์การแก้ไขข้อบกพร่องสำหรับเซสชัน DAI
เมื่อลงทะเบียนเซสชันสตรีม คุณสามารถกำหนดคีย์การแก้ไขข้อบกพร่องที่กำหนดเองได้โดยใช้พารามิเตอร์ dai-sam-id หรือพารามิเตอร์ sam_id ในคำขอ VOD ที่ใช้ Pod Serving คุณสามารถส่งคีย์การแก้ไขข้อบกพร่องนี้ได้โดยตรงในเส้นทางทรัพยากร DaiSession
ตัวอย่างต่อไปนี้จะดึงข้อมูลทรัพยากร DaiSession โดยใช้คีย์การแก้ไขข้อบกพร่อง
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
-H "Authorization: Bearer OAUTH_TOKEN"
แทนที่ DEBUG_KEY ด้วยคีย์การแก้ไขข้อบกพร่องที่กำหนดเองซึ่งระบุไว้ในคำขอสร้างสตรีม
คำขอทั้ง 2 รายการจะแสดงผลการตอบกลับเป็น JSON DaiSession ที่มีบริบทเซสชัน การเลือกโฆษณา พ็อดโฆษณาที่เลือก ช่วงพักโฆษณา และผลการวินิจฉัย
เอาต์พุตจะคล้ายกับตัวอย่างต่อไปนี้
{
"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 แบบเต็มจะรวมเนื้อหา XML ของ VAST และ VMAP ดิบ รวมถึงเหตุการณ์ช่วงพักโฆษณาทั้งหมดที่ผ่านมา หากต้องการลดขนาดเพย์โหลดและดึงข้อมูลเฉพาะช่องเซสชันที่ต้องการ ให้ส่งมาสก์การอ่านในพารามิเตอร์การค้นหา fields หรือส่วนหัว HTTP X-Goog-FieldMask โปรดดูรายละเอียดที่หัวข้อมาสก์ฟิลด์
หากต้องการตรวจสอบว่าเซสชันพบข้อผิดพลาดหรือไม่ ให้ขอเฉพาะบริบทการสร้างเซสชันและผลการวินิจฉัย ดังนี้
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 โดยไม่ต้องดาวน์โหลดการตอบกลับโฆษณา XML ดิบในช่อง adSelections ให้ใช้ส่วนหัว 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 |
จับคู่ creativeKey กับรายการใน adPods[podKey].creatives[creativeKey] |
podFinding.podKey |
adPods[podKey] |
slateFinding |
slate |
trackingFinding.trackingPingKey |
จับคู่ trackingPingKey กับรายการใน adBreaks[breakKey].trackingPings[trackingPingKey] |
หากต้องการติดตามความสัมพันธ์ในคอลเล็กชันต่างๆ ให้ทำดังนี้
- เริ่มจากรายการในอาร์เรย์
adBreaks - อ่านรายการ
podKeysเพื่อค้นหารายการที่เกี่ยวข้องในอาร์เรย์adPods - ใช้ช่อง
adPod.adRequestKeyในพ็อดเพื่อค้นหาAdRequest.adRequestKeyที่ตรงกันในอาร์เรย์adSelections - ตรวจสอบคำขอ HTTP ต้นทางและการตอบกลับ VAST ในออบเจ็กต์
adRequestที่ตรงกันหรืออาร์เรย์childRequestsที่ฝังอยู่
ขอรับไลฟ์สดและแหล่งข้อมูลเนื้อหา
ทรัพยากร DaiSession มีชื่อทรัพยากรที่ลิงก์กับทรัพยากร livestream และ content ใน Google Ad Manager API บนปลายทาง admanager.googleapis.com หากต้องการยืนยันการกำหนดค่าสตรีมและข้อมูลเมตาของเนื้อหา คุณสามารถส่งคำขอ HTTP GET ไปยังแหล่งข้อมูลต่อไปนี้
- ทรัพยากร
LiveStream: ใช้ค่าของฟิลด์creationContext.linearInfo.liveStreamเพื่อเรียกใช้เมธอดnetworks.liveStreams.get - ทรัพยากร VOD
Content: ใช้ค่าของช่องcreationContext.vodInfo.contentเพื่อเรียกใช้เมธอดnetworks.content.get
ตัวอย่างต่อไปนี้จะดึงข้อมูลทรัพยากร LiveStream ที่ลิงก์ซึ่งอ้างอิงใน
ช่อง creationContext.linearInfo.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
เอาต์พุตจะคล้ายกับตัวอย่างต่อไปนี้
{
"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"
}