Usar a API de intervalo de anúncio DAI

A API de intervalo de anúncios da Inserção de anúncios dinâmicos (DAI) do Google permite criar e gerenciar os dados de segmentação de anúncios e de tempo dos intervalos de anúncios nas suas transmissões ao vivo.

Este guia aborda o uso da API DAI Ad Break para criar, atualizar e excluir um intervalo de anúncio para um evento de transmissão ao vivo da DAI do Google.

Pré-requisitos

Para usar a API DAI de intervalo de anúncio, você precisa do seguinte:

Configurar o acesso à API

Para ativar a API, conclua as seguintes etapas:

  1. Crie uma conta de serviço. Para mais informações, consulte Criar uma conta de serviço.
  2. Adicione a conta de serviço à sua rede do Google Ad Manager. Para mais informações, consulte Adicionar um usuário da conta de serviço para acesso à API.
  3. Informe o endereço de e-mail da conta de serviço e o código de rede do Google Ad Manager ao gerente de contas do Google.
  4. Ative a API Google Ad Manager Video no seu projeto na nuvem do Google Cloud. Para mais informações, consulte Ativar "APIs e serviços" para seu app.

Autenticar com o OAuth2

Para autorizar suas solicitações de API, siga estas etapas:

  1. Gere o token de acesso com o escopo https://www.googleapis.com/auth/video-ads.
  2. Em cada solicitação, inclua o token de acesso à API como um valor de cabeçalho HTTP Authorization Bearer. Para mais informações, consulte Chamar APIs do Google.

O exemplo a seguir gera um token do OAuth com o escopo da API DAI Ad Break:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

Se tudo der certo, você vai ver o seguinte token de acesso:

ya29.c.c0ASRK0GYUYU0...

Fazer a primeira solicitação

Para recuperar intervalos de anúncio de um evento de transmissão ao vivo, use o método GET para listar todas as entidades AdBreak pela chave de recurso gerada pelo sistema do evento ou pela sua chave de recurso personalizada.

A API de interrupção de anúncio da DAI retorna apenas entidades AdBreak criadas pela API, excluindo as interrupções de anúncio criadas com base no manifesto, na solicitação de segmento de conjunto ou na solicitação de manifesto de conjunto.

O exemplo de solicitação a seguir lista as entidades AdBreak por um valor assetKey:

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

Se for bem-sucedido, você vai receber a seguinte resposta JSON:

{
 "adBreaks": []
}

À medida que você cria mais entidades AdBreak usando a API e solicita a lista, a seguinte resposta JSON é exibida:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate",
      "breakState": "BREAK_STATE_SCHEDULED"
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate",
      "breakState": "BREAK_STATE_COMPLETE"
    },
    ...
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

Criar uma entidade AdBreak

Para informar a DAI do Google sobre um intervalo de anúncio futuro em um evento de transmissão ao vivo, use o método POST.

  • Para criar uma nova entidade AdBreak, aguarde a transição da anterior para o estado BREAK_STATE_COMPLETE.
  • Outra opção é excluir a entidade AdBreak pendente para criar uma nova.
  • Para criar mais de uma entidade AdBreak para um único evento de transmissão ao vivo, entre em contato com seu gerente de contas para fazer uma configuração avançada.

O exemplo de solicitação a seguir cria um intervalo de anúncio que deve começar em 3 de junho de 2025, às 15:00:00 UTC:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

Se for bem-sucedido, você vai receber a seguinte resposta JSON:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

O resultado contém o ID do intervalo de anúncio necessário para recuperar, modificar ou excluir o intervalo. Na resposta de exemplo, o ID do intervalo de anúncio criado é bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

Recuperar uma entidade AdBreak

Use o método GET para extrair os detalhes de uma entidade AdBreak específica, incluindo o estado do intervalo de anúncio e os metadados de marcação de tempo.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Se for bem-sucedido, você vai receber a seguinte resposta JSON:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

Atualizar uma entidade AdBreak

Para modificar um intervalo de anúncio futuro antes do início da decisão de anúncio, use o método PATCH:

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

Se for bem-sucedido, você vai receber a seguinte resposta JSON:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

Excluir uma entidade de intervalo comercial

Use o método DELETE para cancelar a decisão de anúncio de um intervalo de anúncio criado pela API antes do início da veiculação.

A solicitação de exemplo a seguir exclui um intervalo de anúncio:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Se a operação for bem-sucedida, você vai ver a resposta HTTP/1.1 200 OK.

Saiba mais sobre os recursos avançados de intervalo de anúncio

Depois de criar e gerenciar intervalos de anúncio, conheça estes recursos da API Ad Break da DAI: