«میانای برنامهسازی کاربردی» (API) «پایشگر فعالیت جاریسازی» (SAM) «درج آگهی پویا» (DAI) به شما امکان میدهد گزارشهای عیبیابی و نتایج توزیع را برای جلسههای جاریسازی زنده و ویدیو بهدرخواست (VOD) بازیابی کنید.
این راهنما نحوه پیکربندی اصالتسنجی، بازیابی منبع سطح بالا
DaiSession، و درخواست منابع شناساییشده در فیلدهای جلسه را پوشش میدهد.
پیشنیازها
برای استفاده از SAM API، به موارد زیر نیاز دارید:
- دسترسی به Google Ad Manager API. برای اطلاعات بیشتر، به شروع به کار مراجعه کنید.
- جاریسازی زنده DAI یا جاریسازی ویدیو بهدرخواست پیکربندیشده. برای اطلاعات بیشتر، راهاندازی جاریسازی زنده برای درج آگهی پویا و ایجاد منبع محتوا برای ویدیو بهدرخواست را ببینید.
- شناسه جلسه DAI یا کلید اشکالزدایی از درخواست ایجاد جاریسازی. برای جزئیات، به پیدا کردن شناسه جلسه درج آگهی پویا یا کلید اشکالزدایی مراجعه کنید.
درخواست منبع DaiSession
برای بازرسی جلسه DAI، درخواست HTTP GET را با شناسه جلسه DAI یا کلید اشکالزدایی جاریسازی DAI به نقطه پایانی networks.daiSessions.get ارسال کنید.
بازیابی منبع 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-sam-id یا پارامتر sam_id در درخواستهای «ویدیو بهدرخواست» ارائهشده توسط Pod، کلید اشکالزدایی سفارشی اختصاص دهید. میتوانید این کلید اشکالزدایی را مستقیماً در مسیر منبع 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 و همه رویدادهای وقفه تاریخی است. برای کاهش اندازه بار مفید و واکشی فقط فیلدهای جلسه موردنیاز، یک ماسک خواندن در پارامتر پُرسمان 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 حاوی نامهای منبعی است که به منابع
جاریسازی زنده و محتوا
در Google Ad Manager API در نقطه پایانی admanager.googleapis.com
پیوند میدهند. برای تأیید پیکربندی جاریسازی و فراداده محتوا، میتوانید
درخواستهای HTTP GET را به این منابع ارسال کنید:
LiveStreamمنبع: از مقدار فیلدcreationContext.linearInfo.liveStreamبرای فراخوانیnetworks.liveStreams.getروش استفاده کنید.- منبع
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"
}