LiveBroadcasts: cuepoint

Insere um ponto de referência em uma transmissão ao vivo. O ponto de referência pode acionar um intervalo de anúncio.

Observação:esse método substitui o método liveCuepoints.insert, que exigia que as solicitações fossem autorizadas por uma conta associada a um proprietário de conteúdo do YouTube. Esse método não tem a mesma exigência de autorização.

Solicitação

Solicitação HTTP

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

Autorização

Esta solicitação requer autorização com pelo menos um dos seguintes escopos. Para saber mais sobre autenticação e autorização, consulte Como implementar a autenticação OAuth 2.0.

Escopo
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

Parâmetros

A tabela a seguir lista os parâmetros compatíveis com essa consulta. Todos os parâmetros listados são os parâmetros de consulta.

Parâmetros
Parâmetros obrigatórios
id string
O parâmetro id identifica a transmissão em que o ponto de referência está sendo inserido. A transmissão precisa estar em streaming ativo ao inserir o ponto de referência.
Parâmetros opcionais
onBehalfOfContentOwner string
Esse parâmetro só pode ser usado em uma solicitação autorizada.
Observação:esse parâmetro é destinado exclusivamente a parceiros de conteúdo do YouTube que são proprietários e gerenciam muitos canais diferentes. Ele permite que os proprietários de conteúdo façam a autenticação uma vez e realizem ações em nome do canal especificado no valor do parâmetro, sem precisar fornecer credenciais de autenticação diferentes para cada canal. A conta que o usuário autenticar precisa estar vinculada ao proprietário do conteúdo do YouTube especificado.
O parâmetro onBehalfOfContentOwner indica que as credenciais de autorização da solicitação identificam um usuário do YouTube que está agindo em nome do detentor de conteúdo do YouTube especificado no valor do parâmetro. Esse parâmetro é destinado a parceiros de conteúdo do YouTube que possuem e gerenciam muitos canais diferentes.
onBehalfOfContentOwnerChannel string
Esse parâmetro só pode ser usado em uma solicitação autorizada.
Observação:esse parâmetro é destinado exclusivamente a parceiros de conteúdo do YouTube que são proprietários e gerenciam muitos canais diferentes. Ele permite que os proprietários de conteúdo façam a autenticação uma vez e realizem ações em nome do canal especificado no valor do parâmetro, sem precisar fornecer credenciais de autenticação para cada canal separado.
O parâmetro onBehalfOfContentOwnerChannel especifica o ID do canal do YouTube associado à transmissão em que o ponto de inserção está sendo inserido. Esse parâmetro é obrigatório quando uma solicitação especifica um valor para o parâmetro onBehalfOfContentOwner e só pode ser usado com esse parâmetro. Os seguintes requisitos também se aplicam:
  • A solicitação precisa ser autorizada com uma conta de usuário vinculada ao proprietário do conteúdo especificado pelo parâmetro onBehalfOfContentOwner.
  • O canal especificado pelo valor do parâmetro onBehalfOfContentOwnerChannel precisa estar vinculado ao proprietário de conteúdo especificado pelo parâmetro onBehalfOfContentOwner.

Corpo da solicitação

Forneça um recurso cuepoint no corpo da solicitação. A estrutura JSON a seguir mostra o formato de um recurso cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
 No corpo da solicitação, o campo cueType é obrigatório e precisa ser definido como cueTypeAd. Também é possível definir valores para estas propriedades:
  • durationSecs
  • insertionOffsetTimeMs (não precisa ser definido se walltimeMs estiver definido)
  • walltimeMs (não precisa ser definido se insertionOffsetTimeMs estiver definido)

Propriedades

A tabela a seguir define as propriedades que aparecem neste recurso:

Propriedades
id string
Um valor que o YouTube atribui para identificar exclusivamente o ponto de referência. Esse valor é diferente do parâmetro id obrigatório, que identifica a transmissão. Esse valor pode ser omitido ao enviar uma solicitação para inserir um ponto de referência. O valor será preenchido na resposta da API.
insertionOffsetTimeMs long
O valor da propriedade identifica um ajuste de horário, em milissegundos, quando o ponto de partida precisa ser inserido. O valor é medido a partir do início do fluxo de monitoração, e o valor padrão é 0, o que indica que o ponto de inserção precisa ser inserido o mais rápido possível. Não especifique um valor para esse parâmetro se a transmissão não tiver uma transmissão de monitor.

Embora medido em milissegundos, o valor é uma aproximação, e o YouTube vai inserir o ponto de referência o mais próximo possível desse tempo.

Valores diferentes de zero para esse campo são aceitos apenas se o fluxo de transmissão for atrasado. Se o fluxo de transmissão não estiver atrasado, 0 será o único valor válido. Para mais detalhes, consulte Primeiros passos.

Observação:se a transmissão teve uma fase de teste, o deslocamento é medido a partir do início da fase de teste.

A API vai retornar um erro se uma solicitação tentar inserir um ponto de gatilho que especifique um valor para essa propriedade e para a propriedade walltimeMs.
walltimeMs integer
O valor da propriedade especifica o horário em que o ponto de referência precisa ser inserido. O valor é um número inteiro que representa um carimbo de data/hora de época (em milissegundos).

A API retorna um erro se uma solicitação tentar inserir um ponto de gatilho que especifique um valor para essa propriedade e para a propriedade insertionOffsetTimeMs.
durationSecs unsigned integer
A duração do ponto de partida, em segundos. O valor precisa ser um inteiro positivo. O valor padrão é 30.
cueType string
O tipo de ponto de inserção. O valor da propriedade precisa ser definido como cueTypeAd.

Resposta

Se for bem-sucedido, esse método retornará o recurso cuepoint inserido no corpo da resposta.

Erros

A tabela a seguir identifica as mensagens de erro que a API pode retornar em resposta a uma chamada para esse método. Para mais detalhes, consulte API YouTube Live Streaming: erros.

Tipo de erro Detalhe do erro Descrição
insufficientPermissions (403) insufficientLivePermissions A solicitação não está autorizada a inserir um ponto de referência na transmissão ao vivo.
insufficientPermissions (403) liveStreamingNotEnabled O usuário que autorizou a solicitação não tem permissão para transmitir vídeos ao vivo no YouTube. O usuário pode encontrar mais informações em Comece a fazer transmissões ao vivo e Qualificação para o recurso.
rateLimitExceeded (403) userRequestsExceedRateLimit O usuário enviou muitas solicitações em um determinado período.
required (400) idRequired O parâmetro id necessário precisa identificar a transmissão em que você quer inserir um ponto de referência.
required (400) cueTypeRequired O campo cueType obrigatório precisa ser especificado no corpo da solicitação da API.
notFound (404) liveBroadcastNotFound A transmissão especificada pelo parâmetro id não existe.
invalidValue (400) conflictingTimeFields Só é possível especificar insertionOffsetTimeMs ou walltimeMs. Definir os dois valores causa um erro. Se você não definir nenhum valor, o YouTube vai usar o tempo padrão de insertionOffsetTimeMs (0), o que significa que o ponto de inserção será inserido assim que possível.
invalidValue (400) invalidInsertionOffsetTimeMs O recurso cuepoint especificou um valor inválido para a propriedade insertionOffsetTimeMs. O valor precisa ser 0 ou um número inteiro positivo.
invalidValue (400) invalidWalltimeMs O recurso cuepoint especificou um valor inválido para a propriedade walltimeMs. O valor precisa ser um número inteiro que represente um carimbo de data/hora de época (em milissegundos).
backendError (5xx) serviceUnavailable O serviço está indisponível. Tente fazer a solicitação novamente após alguns minutos.

Confira!

Use APIs Explorer para chamar essa API e conferir a solicitação e a resposta dela.