استخدام أداة مراقبة نشاط البث

تتيح لك واجهة برمجة التطبيقات "أداة مراقبة نشاط البث" (SAM) في ميزة "إدراج إعلان ديناميكي" (DAI) استرداد سجلّات التشخيص ونتائج العرض لجلسات البث المباشر والفيديو عند الطلب (VOD).

يتناول هذا الدليل كيفية ضبط المصادقة واسترداد مورد DaiSession ذي مستوى أعلى وطلب الموارد المحدّدة في حقول الجلسة.

المتطلبات الأساسية

لاستخدام واجهة SAM 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]

لتتبُّع العلاقات في المجموعات، اتّبِع الخطوات التالية:

  1. ابدأ من إدخال في مصفوفة adBreaks.
  2. اقرأ قائمة podKeys لتحديد الإدخالات المقابلة في مصفوفة adPods.
  3. استخدِم حقل adPod.adRequestKey في الحاوية للعثور على AdRequest.adRequestKey المطابق في مصفوفة adSelections.
  4. افحص طلب 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"
}