استفاده از Stream Activity Monitor API

«میانای برنامه‌سازی کاربردی» (API) «پایشگر فعالیت جاری‌سازی» (SAM) «درج آگهی پویا» (DAI) به شما امکان می‌دهد گزارش‌های عیب‌یابی و نتایج توزیع را برای جلسه‌های جاری‌سازی زنده و ویدیو به‌درخواست (VOD) بازیابی کنید.

این راهنما نحوه پیکربندی اصالت‌سنجی، بازیابی منبع سطح بالا DaiSession، و درخواست منابع شناسایی‌شده در فیلدهای جلسه را پوشش می‌دهد.

پیش‌نیازها

برای استفاده از SAM API، به موارد زیر نیاز دارید:

درخواست منبع 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]

برای ردیابی روابط در مجموعه‌ها، کارهای زیر را انجام دهید:

  1. از ورودی‌ای در آرایه adBreaks شروع کنید.
  2. فهرست podKeys را بخوانید تا ورودی‌های مربوطه را در آرایه adPods پیدا کنید.
  3. از فیلد adPod.adRequestKey در pod برای پیدا کردن AdRequest.adRequestKey منطبق در آرایه adSelections استفاده کنید.
  4. درخواست 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"
}