Stream Activity Monitor API verwenden

Mit der API für die Überprüfung der Streamingaktivitäten (Stream Activity Monitor, SAM) für die dynamische Anzeigenbereitstellung (Dynamic Ad Insertion, DAI) können Sie Diagnoseprotokolle und Auslieferungsergebnisse für Ihre Livestream- und Video-on-Demand-Sitzungen (VOD) abrufen.

In diesem Leitfaden wird beschrieben, wie Sie die Authentifizierung konfigurieren, eine DaiSession-Ressource auf oberster Ebene abrufen und die in den Feldern der Sitzung angegebenen Ressourcen anfordern.

Vorbereitung

Für die Verwendung der SAM API benötigen Sie Folgendes:

DaiSession-Ressource anfordern

Wenn du eine DAI-Sitzung prüfen möchtest, sende eine HTTP-GET-Anfrage mit einer DAI-Sitzungs-ID oder einem Schlüssel zur Fehlerbehebung für den DAI-Stream an den Endpunkt networks.daiSessions.get.

DaiSession-Ressource nach ID abrufen

Wenn Sie eine Streamsitzung mit dem IMA DAI SDK, der Komplettservice-DAI API oder der Pod-Serving-DAI API registrieren, gibt die dynamische Anzeigenbereitstellung von Google eine DAI-Sitzungs-ID zurück.

Im folgenden Beispiel wird eine DaiSession-Ressource mithilfe der Sitzungs-ID abgerufen:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Ersetzen Sie Folgendes:

  • NETWORK_CODE: Ihr Google Ad Manager-Netzwerkcode
  • SESSION_ID: die DAI-Sitzungs-ID, die beim Erstellen der Streamsitzung zurückgegeben wird
  • OAUTH_TOKEN: Ihr OAuth 2.0-Zugriffstoken

Schlüssel zur Fehlerbehebung für die Sitzung mit dynamischer Anzeigenbereitstellung verwenden

Wenn Sie eine Streamsitzung registrieren, können Sie einen benutzerdefinierten Debug-Schlüssel zuweisen. Verwenden Sie dazu den Parameter dai-sam-id oder den Parameter sam_id in Pod-Bereitstellungs-VOD-Anfragen. Sie können diesen Debug-Schlüssel direkt im DaiSession-Ressourcenpfad übergeben.

Im folgenden Beispiel wird eine DaiSession-Ressource mit dem Debug-Schlüssel abgerufen:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Ersetzen Sie DEBUG_KEY durch einen benutzerdefinierten Debug-Schlüssel, der in Ihrer Anfrage zur Streamerstellung angegeben ist.

Beide Anfragen geben eine DaiSession-JSON-Antwort zurück, die den Sitzungskontext, die Anzeigenauswahl, die ausgewählten Anzeigen-Pods, die Werbeunterbrechungen und die Diagnoseergebnisse enthält. Die Ausgabe sieht etwa so aus:

{
  "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"
}

Nachdem Sie eine Sitzung identifiziert haben, können Sie bestimmte Sitzungsfelder in der Ressource DaiSession abfragen, Entitätsschlüssel aus Sitzungsergebnissen aufrufen oder Folgeanfragen an zugehörige Ressourcen in der Ad Manager API senden.

Sitzungsfelder mit Feldmasken filtern

Eine vollständige DaiSession-Antwort enthält unbearbeitete VAST- und VMAP-XML-Texte sowie alle bisherigen Unterbrechungsereignisse. Wenn Sie die Nutzlastgröße reduzieren und nur die benötigten Sitzungsfelder abrufen möchten, übergeben Sie eine Lesemaske im Suchparameter fields oder im HTTP-Header X-Goog-FieldMask. Weitere Informationen finden Sie unter Feldmasken.

Wenn Sie prüfen möchten, ob bei einer Sitzung Fehler aufgetreten sind, fordern Sie nur den Kontext der Sitzungserstellung und die Diagnoseergebnisse an:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID?fields=name,creationContext,findings" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Wenn Sie nur die Felder adBreaks und adPods abrufen möchten, ohne die rohen XML-Anzeigenantworten im Feld adSelections herunterzuladen, verwenden Sie den Header 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"

Sitzungsergebnisse prüfen

Jeder Eintrag in der Liste findings enthält ein typisiertes Ergebnisobjekt mit einem Schlüssel, der auf die spezifische Entität in der Ressource DaiSession verweist. In der folgenden Tabelle wird gezeigt, wie Sie Ergebnisschlüssel in Sitzungsfelder auflösen:

Schlüsselpfad finden Zielregion in DaiSession
adBreakFinding.breakKey adBreaks[breakKey]
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey adSelections[adSelectionKey].adRequest und verschachtelte childRequests[]
creativeFinding.creativeKey creativeKey mit Einträgen in adPods[podKey].creatives[creativeKey] abgleichen
podFinding.podKey adPods[podKey]
slateFinding slate
trackingFinding.trackingPingKey trackingPingKey mit Einträgen in adBreaks[breakKey].trackingPings[trackingPingKey] abgleichen

So verfolgen Sie Beziehungen über Sammlungen hinweg:

  1. Beginnen Sie mit einem Eintrag im Array adBreaks.
  2. Lesen Sie die Liste podKeys, um die entsprechenden Einträge im Array adPods zu finden.
  3. Verwenden Sie das Feld adPod.adRequestKey im Pod, um die entsprechende AdRequest.adRequestKey im Array adSelections zu finden.
  4. Prüfen Sie die ursprüngliche HTTP-Anfrage und die VAST-Antwort im entsprechenden adRequest-Objekt oder im verschachtelten childRequests-Array.

Livestream- und Inhaltsressourcen anfordern

Eine DaiSession-Ressource enthält Ressourcennamen, die mit den Ressourcen livestream und content in der Google Ad Manager API am Endpunkt admanager.googleapis.com verknüpft sind. Wenn Sie die Streamkonfiguration und die Inhaltsmetadaten prüfen möchten, können Sie HTTP-GET-Anfragen an diese Ressourcen senden:

  • LiveStream-Ressource: Verwenden Sie den Wert des Felds creationContext.linearInfo.liveStream, um die Methode networks.liveStreams.get aufzurufen.
  • VOD-Content-Ressource: Verwenden Sie den Wert des Felds creationContext.vodInfo.content, um die Methode networks.content.get aufzurufen.

Im folgenden Beispiel wird die verknüpfte LiveStream-Ressource abgerufen, auf die im Feld creationContext.linearInfo.liveStream verwiesen wird:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreams/LIVE_STREAM_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Ersetzen Sie LIVE_STREAM_ID durch die Livestream-ID in Ihrer DaiSession-Ressource.

Die Ausgabe sieht etwa so aus:

{
  "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"
}