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:
- Um projeto na nuvem do Google Cloud com o serviço
admanagervideo.googleapis.comativado. Para mais informações, consulte Criar um projeto na nuvem. - Uma rede do Google Ad Manager com um evento de transmissão ao vivo da DAI do Google. Para mais informações, consulte Configurar uma transmissão ao vivo para DAI.
Configurar o acesso à API
Para ativar a API, conclua as seguintes etapas:
- Crie uma conta de serviço. Para mais informações, consulte Criar uma conta de serviço.
- 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.
- 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.
- 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:
- Gere o token de acesso
com o escopo
https://www.googleapis.com/auth/video-ads. - Em cada solicitação, inclua o token de acesso à API como um valor de cabeçalho HTTP
BearerdeAuthorization. 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¶m2=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¶m2=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
AdBreakdepois de atingir o limite de pendências, aguarde até que uma entidadeAdBreakpendente faça a transição para o estadoBREAK_STATE_COMPLETEou para o estadoBREAK_STATE_EXPIREDao ativar a programação de vários intervalos. - Como alternativa, é possível excluir uma entidade
AdBreakpendente 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¶m2=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¶m2=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¶m2=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¶m2=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:
- Para substituir os parâmetros de tag de anúncio de um intervalo de anúncio ou fazer a integração com sistemas de anúncios de terceiros, consulte Usar parâmetros de intervalo de anúncio.
- Para evitar erros de reprodução relacionados a anúncios, consulte Gerenciar durações de intervalos de anúncios e segmentos.