שימוש ב-Stream Activity Monitor API

‫Dynamic Ad Insertion (DAI) Stream Activity Monitor (SAM) API מאפשר לאחזר יומני אבחון ותוצאות הצגה של סשנים של שידורים חיים ושל וידאו על פי דרישה (VOD).

במדריך הזה מוסבר איך להגדיר אימות, לאחזר משאב DaiSession ברמה העליונה ולבקש את המשאבים שזוהו בשדות של הסשן.

דרישות מוקדמות

כדי להשתמש ב-SAM API, אתם צריכים:

בקשת משאב של 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]

כדי לעקוב אחרי קשרים בין אוספים:

  1. מתחילים מרשומה במערך adBreaks.
  2. קוראים את הרשימה podKeys כדי לאתר את הרשומות התואמות במערך adPods.
  3. משתמשים בשדה adPod.adRequestKey ב-pod כדי למצוא את ה-AdRequest.adRequestKey התואם במערך adSelections.
  4. בודקים את בקשת ה-HTTP המקורית ואת התגובה של VAST באובייקט adRequest התואם או במערך childRequests שמוטמע בו.

בקשת משאבים לשידור חי ולתוכן

משאב DaiSession מכיל שמות של משאבים שמקשרים למשאבים livestream ו-content ב-Google Ad Manager API בנקודת הקצה admanager.googleapis.com. כדי לאמת את הגדרת השידור ואת המטא-נתונים של התוכן, אפשר לשלוח בקשות HTTP GET למשאבים הבאים:

  • משאב LiveStream: משתמשים בערך של השדה creationContext.linearInfo.liveStream כדי להפעיל את ה-method‏ networks.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"
}