LiveBroadcasts: cuepoint

Insere um marcador em uma transmissão ao vivo. O marcador pode acionar um intervalo comercial.

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 o mesmo requisito 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 (leia mais sobre autenticação e autorização).

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 esta 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 na qual o marcador está sendo inserido. A transmissão deve estar sendo executada ativamente durante a inserção do marcador.
Parâmetros opcionais
onBehalfOfContentOwner string
Esse parâmetro só pode ser usado em uma solicitação autorizada adequadamente.
Observação: este parâmetro é destinado exclusivamente a parceiros de conteúdo do YouTube que possuem e gerenciam diversos canais do YouTube. Ele permite que os proprietários de conteúdo se autentiquem 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 separado. A conta que o usuário usa para 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 proprietário do conteúdo especificado no valor do parâmetro. Ele é destinado a parceiros de conteúdo do YouTube que possuem e gerenciam diversos canais do YouTube.
onBehalfOfContentOwnerChannel string
Esse parâmetro só pode ser usado em uma solicitação autorizada adequadamente.
Observação: este parâmetro é destinado exclusivamente a parceiros de conteúdo do YouTube que possuem e gerenciam diversos canais do YouTube. Ele permite que os proprietários de conteúdo se autentiquem uma vez e realizem ações em nome do canal especificado no valor do parâmetro, sem ter que 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 marcador está sendo inserido. Esse parâmetro é obrigatório quando uma solicitação especifica um valor para o parâmetro onBehalfOfContentOwner, e ele 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 de conteúdo especificado pelo parâmetro onBehalfOfContentOwner.
  • O canal especificado pelo valor do parâmetro onBehalfOfContentOwnerChannel precisa estar vinculado ao proprietário do 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 pode ser definido se walltimeMs for definido)
  • walltimeMs (não pode ser definido se insertionOffsetTimeMs for 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 marcador. 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 marcador. O valor será preenchido na resposta da API.
insertionOffsetTimeMs long
O valor da propriedade identifica um ajuste de horário, em milissegundos, quando o marcador é inserido. O valor é medido a partir do início do stream de monitoramento, e o valor padrão é 0, que indica que o marcador precisa ser inserido o mais rápido possível. Não especifique um valor para esse parâmetro se sua transmissão não tiver um stream de monitor.

Embora medido em milissegundos, o valor é uma aproximação, e o YouTube inserirá o marcador o mais próximo possível desse momento.

Valores diferentes de zero neste campo são compatíveis somente se o stream de transmissão estiver atrasado. Se o stream de transmissão não estiver atrasado, 0 será o único valor válido. Consulte o guia Primeiros passos para mais detalhes.

Observação:se a transmissão tiver uma fase de teste, o deslocamento será medido a partir do momento em que a fase de teste foi iniciada.

A API retornará um erro se uma solicitação tentar inserir um marcador que especifica um valor para essa propriedade e para a propriedade walltimeMs.
walltimeMs integer
O valor da propriedade especifica o horário do relógio em que o marcador deve ser inserido. O valor é um número inteiro que representa um carimbo de data/hora de época (em milissegundos).

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

Resposta

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

Erros

A tabela a seguir identifica mensagens de erro que a API pode retornar em resposta a uma chamada para esse método. A documentação da mensagem de erro identifica todos os erros que a API Live Streaming pode retornar.

Tipo de erro Detalhe do erro Descrição
insufficientPermissions (403) insufficientLivePermissions A solicitação não está autorizada a inserir um marcador na transmissão ao vivo.
insufficientPermissions (403) liveStreamingNotEnabled O usuário que autorizou a solicitação não está habilitado para transmitir vídeo ao vivo no YouTube. O usuário pode encontrar mais informações em https://support.google.com/youtube/answer/2474026 e https://www.youtube.com/features.
rateLimitExceeded (403) userRequestsExceedRateLimit O usuário enviou muitas solicitações em um determinado período.
required (400) idRequired O parâmetro id obrigatório precisa identificar a transmissão em que você quer inserir um marcador.
required (400) cueTypeRequired O campo obrigatório cueType 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 Somente um entre insertionOffsetTimeMs e walltimeMs pode ser especificado. Definir os dois valores causa um erro. Se nenhum valor for definido, o YouTube usará o insertionOffsetTimeMs padrão (0), o que significa que o marcador será inserido o mais rápido 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 o APIs Explorer para chamar essa API e ver a solicitação e a resposta da API.