Usar a API Monitoramento da atividade de streaming

A API Monitoramento da Atividade de Streaming (SAM, na sigla em inglês) da Inserção de Anúncios Dinâmicos (DAI, na sigla em inglês) permite recuperar registros de diagnóstico e resultados de exibição para suas sessões de transmissão ao vivo e vídeo on demand (VOD).

Este guia aborda como configurar a autenticação, recuperar um recurso DaiSession de nível superior e solicitar os recursos identificados nos campos da sessão.

Pré-requisitos

Para usar a API SAM, você precisa do seguinte:

Solicitar um recurso do DaiSession

Para inspecionar uma sessão de DAI, envie uma solicitação HTTP GET ao endpoint networks.daiSessions.get com um ID de sessão de DAI ou uma chave de depuração de stream de DAI.

Recuperar um recurso DaiSession por ID

Quando você registra uma sessão de stream usando o SDK da DAI do IMA, a API DAI com serviço completo ou a API DAI de veiculação de conjunto, a DAI do Google retorna um ID de sessão da DAI.

O exemplo a seguir recupera um recurso DaiSession usando o ID da sessão:

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

Substitua:

  • NETWORK_CODE: o código de rede do Google Ad Manager.
  • SESSION_ID: o ID da sessão de DAI retornado ao criar a sessão de stream.
  • OAUTH_TOKEN: seu token de acesso do OAuth 2.0.

Usar uma chave de depuração para a sessão da DAI

Ao registrar uma sessão de stream, é possível atribuir uma chave de depuração personalizada usando o parâmetro dai-sam-id ou sam_id em solicitações de VOD de veiculação de conjunto. É possível transmitir essa chave de depuração diretamente no caminho do recurso DaiSession.

O exemplo a seguir recupera um recurso DaiSession usando a chave de depuração:

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

Substitua DEBUG_KEY por uma chave de depuração personalizada especificada na solicitação de criação de stream.

As duas solicitações retornam uma resposta JSON DaiSession que contém o contexto da sessão, as seleções de anúncios, os pods de anúncios decididos, os intervalos de anúncio e as descobertas de diagnóstico. O resultado será assim:

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

Depois de identificar uma sessão, você pode consultar campos específicos dela no recurso DaiSession, navegar pelas chaves de entidade das descobertas da sessão ou fazer solicitações de acompanhamento para recursos relacionados na API Ad Manager.

Filtrar campos de sessão com máscaras de campo

Uma resposta DaiSession completa inclui corpos XML VAST e VMAP brutos e todos os eventos de intervalo históricos. Para reduzir o tamanho do payload e buscar apenas os campos de sessão necessários, transmita uma máscara de leitura no parâmetro de consulta fields ou no cabeçalho HTTP X-Goog-FieldMask. Para mais detalhes, consulte Máscaras de campo.

Para verificar se uma sessão encontrou erros, solicite apenas o contexto de criação da sessão e as descobertas de diagnóstico:

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

Para recuperar apenas os campos adBreaks e adPods sem fazer o download das respostas de anúncio XML brutas no campo adSelections, use o cabeçalho 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"

Inspecionar descobertas da sessão

Cada entrada na lista findings inclui um objeto de descoberta digitado com uma chave que aponta para a entidade específica no recurso DaiSession. A tabela a seguir mostra como resolver chaves de descoberta para campos de sessão:

Como encontrar o caminho da chave Região de segmentação em DaiSession
adBreakFinding.breakKey adBreaks[breakKey]
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey adSelections[adSelectionKey].adRequest e childRequests[] aninhado
creativeFinding.creativeKey Corresponder creativeKey em entradas em adPods[podKey].creatives[creativeKey]
podFinding.podKey adPods[podKey]
slateFinding slate
trackingFinding.trackingPingKey Corresponder trackingPingKey em entradas em adBreaks[breakKey].trackingPings[trackingPingKey]

Para rastrear relações entre coleções, faça o seguinte:

  1. Comece com uma entrada na matriz adBreaks.
  2. Leia a lista podKeys para localizar as entradas correspondentes na matriz adPods.
  3. Use o campo adPod.adRequestKey no pod para encontrar o AdRequest.adRequestKey correspondente na matriz adSelections.
  4. Inspecione a solicitação HTTP de origem e a resposta VAST no objeto adRequest correspondente ou na matriz childRequests aninhada.

Solicitar os recursos de transmissão ao vivo e conteúdo

Um recurso DaiSession contém nomes de recursos que se vinculam aos recursos de transmissão ao vivo e conteúdo na API Google Ad Manager no endpoint admanager.googleapis.com. Para verificar a configuração do stream e os metadados de conteúdo, faça solicitações HTTP GET para estes recursos:

O exemplo a seguir recupera o recurso LiveStream vinculado referenciado no campo creationContext.linearInfo.liveStream:

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

Substitua LIVE_STREAM_ID pelo ID da transmissão ao vivo no recurso DaiSession.

O resultado será assim:

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