L'API SAM (contrôle de l'activité des flux) de l'insertion dynamique d'annonces (DAI) vous permet de récupérer les journaux de diagnostic et les résultats de diffusion de vos sessions de diffusion en direct et de vidéo à la demande (VOD).
Ce guide explique comment configurer l'authentification, récupérer une ressource DaiSession de premier niveau et demander les ressources identifiées dans les champs de la session.
Prérequis
Pour utiliser l'API SAM, vous devez disposer des éléments suivants :
- Accès à l'API Google Ad Manager. Pour plus d'informations, consultez le Guide de démarrage.
- Un flux en direct ou un flux de VOD configuré pour l'insertion dynamique d'annonce. Pour en savoir plus, consultez Configurer une diffusion en direct pour l'insertion dynamique d'annonce et Créer une source de contenu pour la vidéo à la demande.
- Un ID de session ou une clé de débogage pour l'insertion dynamique d'annonce provenant d'une demande de création de flux. Pour en savoir plus, consultez Trouver une clé de débogage ou un ID de session pour l'insertion dynamique d'annonce.
Demander une ressource DaiSession
Pour inspecter une session DAI, envoyez une requête HTTP GET au point de terminaison networks.daiSessions.get avec un ID de session DAI ou une clé de débogage de flux DAI.
Récupérer une ressource DaiSession par ID
Lorsque vous enregistrez une session de flux à l'aide du SDK IMA DAI, de l'API DAI à service complet ou de l'API DAI de diffusion de séries d'annonces, Google DAI renvoie un ID de session DAI.
L'exemple suivant récupère une ressource DaiSession à l'aide de l'ID de session :
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
-H "Authorization: Bearer OAUTH_TOKEN"
Remplacez les éléments suivants :
NETWORK_CODE: votre code de réseau Google Ad ManagerSESSION_ID: ID de session d'insertion d'annonce dynamique renvoyé lors de la création de la session de fluxOAUTH_TOKEN: votre jeton d'accès OAuth 2.0
Utiliser une clé de débogage pour une session d'insertion dynamique d'annonce
Lorsque vous enregistrez une session de flux, vous pouvez attribuer une clé de débogage personnalisée à l'aide du paramètre dai-sam-id ou sam_id dans les requêtes de diffusion de pod de VOD. Vous pouvez transmettre cette clé de débogage directement dans le chemin d'accès à la ressource DaiSession.
L'exemple suivant récupère une ressource DaiSession à l'aide de la clé de débogage :
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
-H "Authorization: Bearer OAUTH_TOKEN"
Remplacez DEBUG_KEY par une clé de débogage personnalisée spécifiée dans votre requête de création de flux.
Les deux requêtes renvoient une réponse JSON DaiSession contenant le contexte de la session, les sélections d'annonces, les séries d'annonces décidées, les coupures publicitaires et les résultats de diagnostic.
Le résultat ressemble à ce qui suit :
{
"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"
}
Ressources associées aux requêtes
Une fois que vous avez identifié une session, vous pouvez interroger des champs de session spécifiques dans la ressource DaiSession, parcourir les clés d'entité à partir des résultats de la session ou envoyer des requêtes de suivi aux ressources associées dans l'API Ad Manager.
Filtrer les champs de session avec des masques de champ
Une réponse DaiSession complète inclut les corps XML VAST et VMAP bruts, ainsi que tous les événements de coupure historiques. Pour réduire la taille de la charge utile et ne récupérer que les champs de session dont vous avez besoin, transmettez un masque de lecture dans le paramètre de requête fields ou l'en-tête HTTP X-Goog-FieldMask. Pour en savoir plus, consultez Masques de champ.
Pour vérifier si une session a rencontré des erreurs, ne demandez que le contexte de création de la session et les résultats de diagnostic :
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID?fields=name,creationContext,findings" \
-H "Authorization: Bearer OAUTH_TOKEN"
Pour ne récupérer que les champs adBreaks et adPods sans télécharger les réponses d'annonce XML brutes dans le champ adSelections, utilisez l'en-tête 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"
Inspecter les résultats de la session
Chaque entrée de la liste findings inclut un objet de résultat typé avec une clé qui pointe vers l'entité spécifique de la ressource DaiSession. Le tableau suivant montre comment résoudre les clés de résultat dans les champs de session :
| Recherche du chemin d'accès de la clé… | Zone géographique ciblée dans DaiSession |
|---|---|
adBreakFinding.breakKey |
adBreaks[breakKey] |
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey |
adSelections[adSelectionKey].adRequest et childRequests[] imbriqué |
creativeFinding.creativeKey |
Faire correspondre creativeKey dans les entrées de adPods[podKey].creatives[creativeKey] |
podFinding.podKey |
adPods[podKey] |
slateFinding |
slate |
trackingFinding.trackingPingKey |
Faire correspondre trackingPingKey dans les entrées de adBreaks[breakKey].trackingPings[trackingPingKey] |
Pour tracer les relations entre les collections, procédez comme suit :
- Commencez par une entrée du tableau
adBreaks. - Lisez la liste
podKeyspour localiser les entrées correspondantes dans le tableauadPods. - Utilisez le champ
adPod.adRequestKeydu pod pour trouver l'élémentAdRequest.adRequestKeycorrespondant dans le tableauadSelections. - Inspectez la requête HTTP d'origine et la réponse VAST dans l'objet
adRequestcorrespondant ou son tableauchildRequestsimbriqué.
Demander les ressources de diffusion en direct et de contenu
Une ressource DaiSession contient des noms de ressources qui renvoient aux ressources livestream et content de l'API Google Ad Manager sur le point de terminaison admanager.googleapis.com. Pour vérifier la configuration du flux et les métadonnées de contenu, vous pouvez envoyer des requêtes HTTP GET à ces ressources :
- Ressource
LiveStream: utilisez la valeur du champcreationContext.linearInfo.liveStreampour appeler la méthodenetworks.liveStreams.get. - Ressource VOD
Content: utilisez la valeur du champcreationContext.vodInfo.contentpour appeler la méthodenetworks.content.get.
L'exemple suivant récupère la ressource LiveStream associée référencée dans le champ creationContext.linearInfo.liveStream :
curl -X GET \
"https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreams/LIVE_STREAM_ID" \
-H "Authorization: Bearer OAUTH_TOKEN"
Remplacez LIVE_STREAM_ID par l'ID de diffusion en direct dans votre ressource DaiSession.
Le résultat ressemble à ce qui suit :
{
"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"
}