API DAI Early Ad Break Notification

Ao usar a plataforma de DAI do Google, é recomendável fornecer dados de segmentação para o próximo intervalo de anúncio linear/ao vivo em uma transmissão. A API Early Ad Break Notification (EABN) permite que você implemente segmentação específica de intervalo usando pares de chave-valor, o que fornece escalonabilidade para a decisão de anúncios em streams de alto volume.

As chamadas feitas para a API EABN precisam incluir a chave de recurso a ser segmentada e a duração esperada da próxima pausa. A duração precisa ser a mais próxima possível do intervalo real de anúncio. Se a duração esperada enviada for menor que o intervalo fornecido, o Tipo de preenchimento de intervalo de anúncio insuficiente (o padrão será uma barreira em branco) será usado no restante do intervalo. Se a duração esperada enviada for maior que o intervalo de anúncio fornecido, ele poderá terminar antes do fim do anúncio.

Além desses campos obrigatórios, também é possível enviar parâmetros de segmentação personalizados, o nome de um modelo de conjunto de anúncios a ser aplicado ou dados de SCTE35 Cue Out, se disponíveis.

Pré-requisitos

Crie uma conta de serviço

Para acessar a API EABN, você precisa de uma conta de serviço do Google.

  • Se você tiver uma conta do Google Cloud, poderá usar o módulo do IAM para criar uma conta de serviço. Para mais informações, consulte Como criar e gerenciar contas de serviço.
  • Se você não tiver uma conta do Google Cloud, crie uma conta de serviço no Console de APIs do Google seguindo estas etapas:
    1. Crie um novo projeto ou selecione um existente.
    2. Na página Credenciais, clique em Gerenciar contas de serviço.
    3. Na página Contas de serviço, clique em CRIAR CONTA DE SERVIÇO.
    4. Na página Criar conta de serviço, insira os detalhes da conta. Em seguida, clique em CREATE.

Depois de criar uma conta de serviço, copie a chave JSON da conta, que será usada para autenticação.

Ativar a API EABN

Depois que a conta de serviço for criada, peça ao gerente de contas para ativar a API EABN para ela.

Ativar a API DAI

Depois que a API EABN for ativada na conta de serviço, ative a API DAI na conta:

  1. Na Biblioteca de APIs do Google, pesquise "API DAI".

  2. Selecione e ative a API DAI.

Como usar a API EABN

É possível chamar a API EABN usando solicitações JSON/REST.

Autenticação

Para fazer chamadas autenticadas à API EABN, é preciso gerar credenciais da conta de serviço OAuth2 usando a chave JSON da sua conta de serviço e o escopo https://www.googleapis.com/auth/video-ads. Para mais informações, consulte Usar o OAuth 2.0 para aplicativos de servidor para servidor.

É preciso incluir o token de autenticação resultante como um cabeçalho Auth para cada chamada para a API EABN.

Como enviar uma notificação antecipada de intervalo de anúncio

Para enviar uma notificação antecipada de intervalo de anúncio, envie uma solicitação POST usando o URL e o corpo da solicitação abaixo:

POST dai.googleapis.com/v1/adBreaks

Corpo da solicitação

Objeto
adBreak Obrigatório O objeto wrapper para propriedades adBreak.
assetKey Obrigatório Identificador exclusivo do LiveStreamEvent para o qual a quebra é criada.
expectedDuration Obrigatório A duração desse intervalo comercial, usando o formato de duração padrão do Google (xx.xxxs, onde xx.xxx é o número de segundos)
scte35CueOut Opcional Dados codificados em base-64 da saída scte35. Pode incluir o comando splice_insert() ou time_signal().
Exemplos:
  • time_signal():
    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==
  • splice_insert(): /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=
custParams Opcional Pares de chave-valor serão incluídos nas solicitações de anúncio desse intervalo para segmentação de critérios personalizados no AM360, separados por = e unidos por &.
Exemplo:
key=value&key2=value2,value3
Para mais informações sobre segmentação, consulte Fornecer parâmetros de segmentação ao stream.
ptpln Opcional O nome do modelo do conjunto de anúncios

Cabeçalho de resposta

HTTP/1.1 200 OK

Corpo da resposta

O corpo da resposta contém todos os parâmetros enviados no objeto adBreak, bem como um campo daiBreakId adicional, que contém o identificador da DAI interno para o intervalo de anúncio criado no stream.

Exemplo

Solicitação

POST /v1/adBreaks HTTP/1.1
Content-Type: application/json

{
  "adBreak": {
    "assetKey": "asset1",
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "custParams": "param1=value1&param2=value2",
    "ptpln": "podtemplate"
  }
}

Resposta

HTTP/1.1 200 OK

{
  "assetKey": "asset1",
  "expectedDuration": "30s",
  "custParams": "param1=value1&param2=value2",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "ptpln": "podtemplate",
  "daiBreakId": 1
}

Exemplo de implementação (Python)

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

from absl import app

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

SERVICE_ACCOUNT_KEY_FILE = "~/eabn_key.json"
ASSET_KEY = "asset1"

SCOPES = ['https://www.googleapis.com/auth/video-ads']
EABN_API_URL = 'https://dai.googleapis.com/v1/adBreaks'


def main():
  credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_KEY_FILE, scopes=SCOPES)

  authed_session = AuthorizedSession(credentials)

  data = {
      'assetKey': ASSET_KEY,
      'expectedDuration': '120s',
      'custParams': 'param1=value1&param2=value2',
      'scte35CueOut': '/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==',
  }

  r = authed_session.post(EABN_API_URL, json={'adBreak': data})
  print(r.status_code)
  print(r.headers)
  print(r.text)

if __name__ == '__main__':
  app.run(main)