Dynamic Ad Insertion (DAI) Stream Activity Monitor (SAM) API מאפשר לאחזר יומני אבחון ותוצאות הצגה של סשנים של שידורים חיים ושל וידאו על פי דרישה (VOD).
במדריך הזה מוסבר איך להגדיר אימות, לאחזר משאב DaiSession ברמה העליונה ולבקש את המשאבים שזוהו בשדות של הסשן.
דרישות מוקדמות
כדי להשתמש ב-SAM API, אתם צריכים:
- גישה ל-Google Ad Manager API. מידע נוסף זמין במאמר תחילת העבודה.
- שידור חי או שידור VOD מוגדר של DAI. מידע נוסף זמין במאמרים הגדרת שידור חי להחדרת מודעות דינמית (DAI) ויצירת מקור תוכן לווידאו על פי דרישה (VOD).
- מזהה סשן של DAI או מפתח ניפוי באגים מבקשה ליצירת שידור. לפרטים נוספים, ראו איתור מזהה סשן של DAI או מפתח ניפוי באגים.
בקשת משאב של DaiSession
כדי לבדוק סשן של DAI, שולחים בקשת HTTP GET לנקודת הקצה (endpoint) networks.daiSessions.get עם מזהה סשן של DAI או מפתח לניפוי באגים של שידור DAI.
אחזור משאב של DaiSession לפי מזהה
כשרושמים סשן של שידור באמצעות IMA DAI SDK, Full-service DAI API או Pod serving 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: קוד הרשת שלכם ב-Google Ad Manager -
SESSION_ID: מזהה הסשן של DAI שמוחזר כשיוצרים את סשן השידור -
OAUTH_TOKEN: טוקן הגישה שלכם מסוג OAuth 2.0
שימוש במפתח ניפוי באגים לסשן DAI
כשרושמים סשן של שידור, אפשר להקצות מפתח ניפוי באגים מותאם אישית באמצעות הפרמטר dai-sam-id או הפרמטר sam_id בבקשות להצגת מודעות ב-VOD. אפשר להעביר את מפתח ניפוי הבאגים הזה ישירות בנתיב המשאב DaiSession.
בדוגמה הבאה מאחזרים משאב DaiSession באמצעות מפתח ניפוי הבאגים:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
-H "Authorization: Bearer OAUTH_TOKEN"
מחליפים את DEBUG_KEY במפתח ניפוי באגים בהתאמה אישית שצוין בבקשה ליצירת השידור.
שתי הבקשות מחזירות תגובת 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 ואת כל אירועי ההפסקות ההיסטוריים. כדי להקטין את המטען הייעודי (payload) ולאחזר רק את שדות הסשן שאתם צריכים, מעבירים מסכת קריאה בפרמטרים של שאילתה 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ב-pod כדי למצוא את ה-AdRequest.adRequestKeyהתואם במערךadSelections. - בודקים את בקשת ה-HTTP המקורית ואת התגובה של VAST באובייקט
adRequestהתואם או במערךchildRequestsשמוטמע בו.
בקשת משאבים לשידור חי ולתוכן
משאב DaiSession מכיל שמות של משאבים שמקשרים למשאבים livestream ו-content ב-Google Ad Manager API בנקודת הקצה admanager.googleapis.com. כדי לאמת את הגדרת השידור ואת המטא-נתונים של התוכן, אפשר לשלוח בקשות HTTP GET למשאבים הבאים:
- משאב
LiveStream: משתמשים בערך של השדהcreationContext.linearInfo.liveStreamכדי להפעיל את ה-methodnetworks.liveStreams.get. - משאב
Contentשל VOD: משתמשים בערך של השדה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"
}