Usar a API DAI Ad Break

A API de intervalo de anúncios da DAI permite criar e gerenciar os dados de tempo e segmentação de anúncios dos intervalos de anúncios nas suas transmissões ao vivo.

Este guia aborda o uso da API de intervalo de anúncios da DAI para criar, atualizar e excluir um intervalo de anúncios em um evento de transmissão ao vivo da Inserção de anúncios dinâmicos (DAI) do Google.

Pré-requisitos

Para usar a API DAI Ad Break, 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. Forneça 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 DAI Ad Break retorna apenas entidades AdBreak criadas pela API, excluindo intervalos de anúncio criados 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 pela 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 anterior fazer a transição para o estado BREAK_STATE_COMPLETE.
  • Como alternativa, exclua 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.

O exemplo de solicitação 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 for bem-sucedido, você vai ver a resposta HTTP/1.1 200 OK.

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

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