تتيح لك واجهة برمجة التطبيقات "أداة مراقبة نشاط البث" (SAM) في ميزة "إدراج إعلان ديناميكي" (DAI) استرداد سجلّات التشخيص ونتائج العرض لجلسات البث المباشر والفيديو عند الطلب (VOD).
يتناول هذا الدليل كيفية ضبط المصادقة واسترداد مورد DaiSession ذي مستوى أعلى وطلب الموارد المحدّدة في حقول الجلسة.
المتطلبات الأساسية
لاستخدام واجهة SAM API، يجب توفّر ما يلي:
- إذن الوصول إلى Google Ad Manager API لمزيد من المعلومات، يُرجى الاطّلاع على البدء.
- بث مباشر أو بث فيديو عند الطلب تم ضبطهما لإدراج الإعلانات ديناميكيًا لمزيد من المعلومات، يُرجى الاطّلاع على المقالتَين إعداد بث مباشر لميزة "إدراج الإعلان الديناميكي" وإنشاء مصدر محتوى للفيديو عند الطلب.
- معرّف جلسة إدراج الإعلان الديناميكي أو مفتاح تصحيح الأخطاء من طلب إنشاء بث لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة تحديد موقع معرّف جلسة إدراج الإعلان الديناميكي أو مفتاح تصحيح الأخطاء.
طلب مرجع DaiSession
لفحص جلسة "إدراج إعلان ديناميكي"، أرسِل طلب HTTP GET إلى نقطة النهاية networks.daiSessions.get مع رقم تعريف جلسة "إدراج إعلان ديناميكي" أو مفتاح تصحيح أخطاء بث "إدراج إعلان ديناميكي".
استرداد مورد DaiSession حسب رقم التعريف
عند تسجيل جلسة بث باستخدام حزمة تطوير البرامج (SDK) لتقنية IMA DAI، أو واجهة برمجة التطبيقات لتقنية إدراج الإعلان الديناميكي للخدمة الكاملة، أو واجهة برمجة التطبيقات لتقنية إدراج الإعلان الديناميكي لعرض الإعلانات في مجموعات، تُعرِض تقنية إدراج الإعلان الديناميكي من Google رقم تعريف جلسة إدراج الإعلان الديناميكي.
يستردّ المثال التالي مورد DaiSession باستخدام معرّف الجلسة:
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
-H "Authorization: Bearer OAUTH_TOKEN"
غيِّر القيم في السلسلة على الشكل التالي:
-
NETWORK_CODE: رمز شبكة "إدارة إعلانات Google" -
SESSION_ID: معرّف جلسة "إدراج الإعلانات الديناميكي" الذي يتم عرضه عند إنشاء جلسة البث -
OAUTH_TOKEN: رمز الدخول OAuth 2.0
استخدام مفتاح تصحيح الأخطاء لجلسة "إدراج الإعلان ديناميكيًا"
عند تسجيل جلسة بث، يمكنك تخصيص مفتاح تصحيح أخطاء مخصّص باستخدام المَعلمة 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 بمفتاح تصحيح أخطاء مخصّص
محدّد في طلب إنشاء البث.
يعرض كلا الطلبَين ردّ 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 على أسماء الموارد التي ترتبط بموارد
البث المباشر والمحتوى
في 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"
}