Esta página foi traduzida pela API Cloud Translation.

Early ad break notification

Como usar a API Early Ad Break Notification

Observação: esta API ainda está na versão Beta. Fale com seu gerente de contas se quiser solicitar acesso ao programa EABN.

Com a API Early Ad Break Notification (EABN), é possível notificar o Google Ad Manager sobre o próximo intervalo de anúncio com os metadados dele antes do início do intervalo. É possível enviar uma solicitação de notificação até uma hora antes do intervalo de anúncio. Este guia explica como ativar e usar a API EABN, além de exemplos de solicitação e resposta.

Cuidado: as solicitações EABN são imutáveis. Portanto, não é possível modificar um intervalo depois que ele é criado. As solicitações subsequentes para criar intervalos de anúncio para o mesmo evento são rejeitadas até que o intervalo apareça no manifesto do evento.

As chamadas feitas à API EABN precisam incluir as seguintes informações:

O identificador da transmissão ao vivo correspondente para a qual o intervalo de anúncio está sendo criado. Esse identificador pode ser um dos seguintes:
A "Chave de recurso" da transmissão ao vivo.
A "Chave de recurso personalizada" da transmissão ao vivo, que permite que você gerencie seu próprio espaço de chave especificando sua própria string de identificador.
O "Content Source ID" e "Content ID" da transmissão ao vivo.

Observação: é necessário ter permissão para usar esse tipo de identificador. Para mais informações, entre em contato com seu gerente de contas.

É a duração esperada do próximo intervalo comercial. Ela precisa ser o mais próximo possível da duração real do intervalo de 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 Cue Out do SCTE35, se disponíveis.

Pré-requisitos

Para usar a API EABN, é preciso criar uma conta de serviço e adicioná-la à sua rede do Google Ad Manager.

Como criar uma conta de serviço

Para criar uma conta de serviço e chamar a API EABN, siga estas etapas: - Se você tiver uma conta do Google Cloud, use 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, siga estas etapas para criar uma no Console de APIs do Google:

Crie um novo projeto ou selecione um existente.
Na página Credenciais, clique em Gerenciar contas de serviço.
Na página Contas de serviço, clique em CRIAR CONTA DE SERVIÇO.
Na página Criar conta de serviço, insira os detalhes da conta. Em seguida, clique em CRIAR.

Depois de criar uma conta de serviço, copie a chave JSON dela, que é usada para autenticação.

Como adicionar sua conta de serviço à rede do Google Ad Manager

Para adicionar a conta de serviço à rede, siga as etapas em Adicionar um usuário da conta de serviço para acesso à API.

Ative a API

Depois de criar a conta de serviço, forneça as seguintes informações ao gerente da conta para ativar a API na sua conta:

Endereço de e-mail da sua conta do Google Cloud
Sua conta de serviço
É o código da sua rede do Google Ad Manager.

Depois que o gerente da conta ativar a API, siga estas etapas:

Na biblioteca de APIs do Google, pesquise "API Google Ad Manager Video".
Clique em ATIVAR.

Observação: se a API não aparecer nos resultados da pesquisa, entre em contato com o gerente de contas para confirmar se a conta foi ativada para a API DAI.

Como usar a API

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

Autorização

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

Você deve incluir o token de autorização resultante como um cabeçalho Auth para cada chamada para a API EABN.

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 para um dos três URLs EABN válidos, dependendo de como você preferir especificar a transmissão ao vivo. As seções a seguir explicam as diferenças entre os URLs e fornecem exemplos de solicitação e resposta.

URLs

Há três URLs válidos para a notificação antecipada de um intervalo de anúncio. É possível usar os três tipos para criar um intervalo de anúncio (POST) ou ver a lista de intervalos de anúncio atribuídos (GET).

Para usar a chave de recurso de uma transmissão ao vivo, utilize:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

Para usar a chave de recurso personalizada de uma transmissão ao vivo, utilize:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

Para usar a abordagem de Content Source ID e Content ID, use:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

Para todos os parâmetros:

network_code representa o código da sua rede do Google Ad Manager.
asset_key representa a chave de recurso mostrada na página de detalhes da transmissão ao vivo.
custom_asset_key representa a chave de recurso personalizada da sua transmissão ao vivo.
content_source_id representa o ID de uma origem do conteúdo no Google Ad Manager.
content_id representa o ID de um conteúdo no Google Ad Manager.

Observação: o par content_source_id/content_id especificado precisa estar associado a uma transmissão ao vivo no Google Ad Manager.

Corpo da solicitação: usado somente para criar um intervalo de anúncio (POST).

Objeto
`expectedDuration`	Obrigatório	A duração desse intervalo de anúncio, usando o formato de duração padrão do Google (xx.xxxs, em que xx.xxx é o número de segundos)
`customParams`	Opcional	Pares de chave-valor serão incluídos nas solicitações de anúncios deste intervalo para a segmentação por critérios personalizados no AM360, separados por `=` e, com a participação de `&` . Exemplo: `key=value&key2=value2,value3` Para mais informações sobre segmentação, consulte Fornecer parâmetros de segmentação ao stream.
`podTemplateName`	Opcional	Nome do modelo do conjunto de anúncios
`scte35CueOut`	Opcional	Dados codificados em Base64 da saída scte35. Podem incluir o parâmetro `splice_insert()` ou `time_signal()` bq load. Exemplos: time_signal(): `/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==` splice_insert(): `/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=`

Exemplos de solicitação

Criar um intervalo de anúncio

POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}

Corpo da resposta

O corpo da resposta contém todos os parâmetros enviados no objeto adBreak, além de um campo name adicional, que contém o ID padrão do Google do intervalo de anúncio criado. Esse campo é retornado no seguinte formato:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}

Exemplo de resposta

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}

Listar intervalos de anúncio atribuídos

GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …

Corpo da resposta

O corpo da resposta contém os intervalos de anúncio com um campo breakState adicional para cada intervalo de anúncio atribuído ao stream. O campo breakState aceita os seguintes valores:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE

Exemplo de resposta

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}