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:
- Accedere all'API Google Ad Manager. Per saperne di più, consulta Inizia.
- Un live streaming o uno stream VOD DAI configurato. Per saperne di più, consulta Configura un live streaming per DAI e Crea un'origine di contenuto per video on demand.
- Un ID sessione o una chiave di debug DAI da una richiesta di creazione dello stream. Per maggiori dettagli, consulta Trova un ID sessione o una chiave di debug DAI.
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 ManagerSESSION_ID: l'ID sessione DAI restituito durante la creazione della sessione di streamingOAUTH_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"
}
Richiedi risorse correlate
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:
- Inizia da una voce nell'array
adBreaks. - Leggi l'elenco
podKeysper individuare le voci corrispondenti nell'arrayadPods. - Utilizza il campo
adPod.adRequestKeynel pod per trovare laAdRequest.adRequestKeycorrispondente nell'arrayadSelections. - Esamina la richiesta HTTP di origine e la risposta VAST nell'oggetto
adRequestcorrispondente o nell'arraychildRequestsnidificato.
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 campocreationContext.linearInfo.liveStreamper chiamare il metodonetworks.liveStreams.get. - Risorsa VOD
Content: utilizza il valore del campocreationContext.vodInfo.contentper chiamare il metodonetworks.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"
}