Utilizza l'API Monitoraggio attività di streaming

L'API Monitoraggio attività di streaming (SAM) per l'inserimento di annunci dinamici (DAI) ti consente di recuperare i log di diagnostica e i risultati di pubblicazione per le sessioni di live streaming e video on demand (VOD).

Questa guida spiega come configurare l'autenticazione, recuperare una risorsa DaiSession di primo livello e richiedere le risorse identificate nei campi della sessione.

Prerequisiti

Per utilizzare l'API SAM, devi disporre di quanto segue:

Richiedi una risorsa DaiSession

Per ispezionare una sessione DAI, invia una richiesta HTTP GET all'endpoint networks.daiSessions.get con un ID sessione DAI o una chiave di debug dello stream DAI.

Recupera una risorsa DaiSession in base all'ID

Quando registri una sessione di stream utilizzando l'SDK IMA DAI, l'API DAI per il servizio completo o l'API DAI per la pubblicazione di pod, Google DAI restituisce un ID sessione DAI.

L'esempio seguente recupera una risorsa DaiSession utilizzando l'ID sessione:

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

Sostituisci quanto segue:

  • NETWORK_CODE: il tuo codice di rete Google Ad Manager
  • SESSION_ID: l'ID sessione DAI restituito durante la creazione della sessione di streaming
  • OAUTH_TOKEN: il tuo token di accesso OAuth 2.0

Utilizza una chiave di debug per la sessione DAI

Quando registri una sessione di streaming, puoi assegnare una chiave di debug personalizzata utilizzando il parametro dai-sam-id o il parametro sam_id nelle richieste VOD di pubblicazione di pod. Puoi passare questa chiave di debug direttamente nel percorso della risorsa DaiSession.

L'esempio seguente recupera una risorsa DaiSession utilizzando la chiave di debug:

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

Sostituisci DEBUG_KEY con una chiave di debug personalizzata specificata nella richiesta di creazione dello stream.

Entrambe le richieste restituiscono una risposta JSON DaiSession contenente il contesto della sessione, le selezioni degli annunci, i pod di annunci scelti, le interruzioni pubblicitarie e i risultati della diagnostica. L'output è simile al seguente:

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

Dopo aver identificato una sessione, puoi eseguire query su campi di sessione specifici nella risorsa DaiSession, navigare tra le chiavi delle entità dai risultati della sessione o effettuare richieste di follow-up alle risorse correlate nell'API Ad Manager.

Filtra i campi della sessione con maschere di campo

Una risposta DaiSession completa include i corpi XML VAST e VMAP non elaborati e tutti gli eventi di interruzione storici. Per ridurre le dimensioni del payload e recuperare solo i campi della sessione di cui hai bisogno, passa una maschera di lettura nel parametro di query fields o nell'intestazione HTTP X-Goog-FieldMask. Per maggiori dettagli, consulta Maschere di campo.

Per verificare se una sessione ha riscontrato errori, richiedi solo il contesto di creazione della sessione e i risultati della diagnostica:

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

Per recuperare solo i campi adBreaks e adPods senza scaricare le risposte agli annunci XML non elaborate nel campo adSelections, utilizza l'intestazione 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"

Esamina i risultati della sessione

Ogni voce nell'elenco findings include un oggetto risultato tipizzato con una chiave che punta all'entità specifica nella risorsa DaiSession. La tabella seguente mostra come risolvere le chiavi dei risultati nei campi della sessione:

Ricerca del percorso chiave Località target in DaiSession
adBreakFinding.breakKey adBreaks[breakKey]
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey adSelections[adSelectionKey].adRequest e childRequests[] nidificati
creativeFinding.creativeKey Corrispondenza di creativeKey tra le voci in adPods[podKey].creatives[creativeKey]
podFinding.podKey adPods[podKey]
slateFinding slate
trackingFinding.trackingPingKey Corrispondenza di trackingPingKey tra le voci in adBreaks[breakKey].trackingPings[trackingPingKey]

Per tracciare le relazioni tra le raccolte, segui questi passaggi:

  1. Inizia da una voce nell'array adBreaks.
  2. Leggi l'elenco podKeys per individuare le voci corrispondenti nell'array adPods.
  3. Utilizza il campo adPod.adRequestKey nel pod per trovare la AdRequest.adRequestKey corrispondente nell'array adSelections.
  4. Esamina la richiesta HTTP di origine e la risposta VAST nell'oggetto adRequest corrispondente o nell'array childRequests nidificato.

Richiedi le risorse per il live streaming e i contenuti

Una risorsa DaiSession contiene nomi di risorse che rimandano alle risorse livestream e content nell'API Google Ad Manager sull'endpoint admanager.googleapis.com. Per verificare la configurazione dello stream e i metadati dei contenuti, puoi effettuare richieste HTTP GET a queste risorse:

  • Risorsa LiveStream: utilizza il valore del campo creationContext.linearInfo.liveStream per chiamare il metodo networks.liveStreams.get.
  • Risorsa VOD Content: utilizza il valore del campo creationContext.vodInfo.content per chiamare il metodo networks.content.get.

L'esempio seguente recupera la risorsa LiveStream collegata a cui viene fatto riferimento nel campo creationContext.linearInfo.liveStream:

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

Sostituisci LIVE_STREAM_ID con l'ID del live streaming nella risorsa DaiSession.

L'output è simile al seguente:

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