Utiliser l'API de contrôle de l'activité des flux

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 :

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 Manager
  • SESSION_ID : ID de session d'insertion d'annonce dynamique renvoyé lors de la création de la session de flux
  • OAUTH_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"
}

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 :

  1. Commencez par une entrée du tableau adBreaks.
  2. Lisez la liste podKeys pour localiser les entrées correspondantes dans le tableau adPods.
  3. Utilisez le champ adPod.adRequestKey du pod pour trouver l'élément AdRequest.adRequestKey correspondant dans le tableau adSelections.
  4. Inspectez la requête HTTP d'origine et la réponse VAST dans l'objet adRequest correspondant ou son tableau childRequests imbriqué.

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 :

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