Usar a API de intervalo de anúncio DAI

Com a API Ad Break da Inserção de Anúncios Dinâmicos (DAI) do Google, é possível criar e gerenciar os dados de tempo e segmentação de anúncios dos intervalos de anúncio 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 em um evento de transmissão ao vivo da 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. Informe o endereço de e-mail da conta de serviço e o código de rede do Google Ad Manager ao seu gerente de contas do Google.
  4. Ative a API Video do Google Ad Manager 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 as 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 Bearer de Authorization. Para mais informações, consulte Chamar APIs do Google.

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

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

Se a operação for bem-sucedida, você vai receber 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 do recurso gerada pelo sistema do evento ou pela sua chave do recurso personalizada.

A API DAI Ad Break só retorna entidades AdBreak criadas pela API, excluindo intervalos de anúncio criados pelo manifesto, pela solicitação de segmento de conjunto ou pela 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": []
}

Ao criar outras entidades AdBreak pela API e solicitar a lista, você verá a seguinte resposta JSON:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "breakParams": {
        "adTagParams": [
          {
            "key": "ptpln",
            "value": "podtemplate"
          },
          {
            "key": "cust_params",
            "value": "param1=value1&param2=value2"
          }
        ]
      },
      "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==",
      "breakParams": {
        "adTagParams": [
          {
            "key": "ptpln",
            "value": "podtemplate"
          },
          {
            "key": "cust_params",
            "value": "param1=value1&param2=value2"
          }
        ]
      },
      "breakState": "BREAK_STATE_COMPLETE"
    },
    ...
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

Criar uma entidade AdBreak

Para informar à 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 entidade AdBreak depois de atingir o limite de pendências, aguarde até que uma entidade AdBreak pendente faça a transição para o estado BREAK_STATE_COMPLETE ou para o estado BREAK_STATE_EXPIRED ao ativar a programação de vários intervalos.
  • Como alternativa, é possível excluir uma entidade AdBreak pendente para criar uma entidade.

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==",
    "breakParams": {
      "adTagParams": [
        {
          "key": "ptpln",
          "value": "podtemplate"
        },
        {
          "key": "cust_params",
          "value": "param1=value1&param2=value2"
        }
      ]
    }
  }'

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==",
  "breakParams": {
    "adTagParams": [
      {
        "key": "ptpln",
        "value": "podtemplate"
      },
      {
        "key": "cust_params",
        "value": "param1=value1&param2=value2"
      }
    ]
  },
  "breakState": "BREAK_STATE_SCHEDULED"
}

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

Recuperar uma entidade AdBreak

Use o método GET para recuperar os detalhes de uma entidade AdBreak específica, incluindo o estado do intervalo de anúncio e os metadados 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==",
  "breakParams": {
    "adTagParams": [
      {
        "key": "ptpln",
        "value": "podtemplate"
      },
      {
        "key": "cust_params",
        "value": "param1=value1&param2=value2"
      }
    ]
  },
  "breakState": "BREAK_STATE_SCHEDULED"
}

Atualizar uma entidade AdBreak

Para modificar um intervalo de anúncio futuro antes que a decisão de anúncio comece, 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==",
  "breakParams": {
    "adTagParams": [
      {
        "key": "ptpln",
        "value": "podtemplate"
      },
      {
        "key": "cust_params",
        "value": "param1=value1&param2=value2"
      }
    ]
  },
  "breakState": "BREAK_STATE_SCHEDULED"
}

Excluir uma entidade AdBreak

Use o método DELETE para cancelar a decisão de anúncio de um intervalo de anúncio criado pela API antes que ele comece a ser veiculado.

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 a operação for bem-sucedida, você vai receber a resposta HTTP/1.1 200 OK.

Conheça os recursos avançados de intervalos de anúncio

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