LiveBroadcasts: cuepoint

Inserta un punto de referencia en una transmisión en vivo. Es posible que el punto de inserción active una pausa publicitaria.

Nota: Este método reemplaza al método liveCuepoints.insert, que exige que una cuenta asociada con un propietario del contenido de YouTube autorice la solicitud. Este método no tiene el mismo requisito de autorización.

Solicitud

Solicitud HTTP

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

Autorización

Esta solicitud requiere autorización con al menos uno de los siguientes alcances (obtén más información acerca de la autenticación y autorización).

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

Parámetros

En la siguiente tabla, se enumeran los parámetros que admite esta consulta. Todos los parámetros mencionados son parámetros de consulta.

Parámetros
Parámetros obligatorios
id string
El parámetro id identifica la transmisión en la que se inserta el punto de referencia. La transmisión debe transmitirse de forma activa cuando se inserta el punto de referencia.
Parámetros opcionales
onBehalfOfContentOwner string
Este parámetro solo se puede usar en una solicitud autorizada debidamente.
Nota: Este parámetro está dirigido exclusivamente a socios de contenido de YouTube que poseen y administran muchos canales de YouTube diferentes. Permite a los propietarios de contenido autenticarse una vez y realizar acciones en nombre del canal especificado en el valor del parámetro, sin tener que proporcionar credenciales de autenticación diferentes para cada canal. La cuenta con la que se autentica el usuario debe estar vinculada al propietario del contenido de YouTube especificado.
El parámetro onBehalfOfContentOwner indica que las credenciales de autorización de la solicitud identifican a un usuario de YouTube que actúa en nombre del propietario del contenido de YouTube especificado en el valor del parámetro. Este parámetro está dirigido a socios de contenido de YouTube que poseen y administran muchos canales de YouTube diferentes.
onBehalfOfContentOwnerChannel string
Este parámetro solo se puede usar en una solicitud autorizada debidamente.
Nota: Este parámetro está dirigido exclusivamente a socios de contenido de YouTube que poseen y administran muchos canales de YouTube diferentes. Permite a los propietarios de contenido autenticarse una vez y realizar acciones en nombre del canal especificado en el valor del parámetro, sin tener que proporcionar credenciales de autenticación para cada canal por separado.
El parámetro onBehalfOfContentOwnerChannel especifica el ID del canal de YouTube del canal asociado con la transmisión a la que se inserta el punto de referencia. Este parámetro es obligatorio cuando una solicitud especifica un valor para el parámetro onBehalfOfContentOwner, y solo se puede usar junto con ese parámetro. También se aplican los siguientes requisitos:
  • La solicitud se debe autorizar con una cuenta de usuario vinculada al propietario del contenido que especifica el parámetro onBehalfOfContentOwner.
  • El canal que especifica el valor del parámetro onBehalfOfContentOwnerChannel debe estar vinculado al propietario del contenido que especifica el parámetro onBehalfOfContentOwner.

Cuerpo de la solicitud

Proporciona un recurso cuepoint en el cuerpo de la solicitud. La siguiente estructura JSON muestra el formato de un recurso cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
En el cuerpo de la solicitud, el campo cueType es obligatorio y debe establecerse en cueTypeAd. También puedes establecer valores para estas propiedades:
  • durationSecs
  • insertionOffsetTimeMs (no se debe establecer si se establece walltimeMs)
  • walltimeMs (no se debe establecer si se establece insertionOffsetTimeMs)

Propiedades

La siguiente tabla define las propiedades que aparecen en este recurso:

Propiedades
id string
Es un valor que YouTube asigna para identificar el punto de referencia de forma única. Ten en cuenta que este valor es diferente del parámetro id obligatorio, que identifica la transmisión. Este valor se puede omitir cuando se envía una solicitud para insertar un punto de referencia. El valor se propagará en la respuesta de la API.
insertionOffsetTimeMs long
El valor de la propiedad identifica una compensación horaria, en milisegundos, en la que se debe insertar el punto de referencia. El valor se mide desde el comienzo de la transmisión continua de monitor, y su valor predeterminado es 0, lo que indica que el punto de referencia debe insertarse lo antes posible. No debes especificar un valor para este parámetro si tu transmisión no tiene una transmisión de supervisión.

Si bien se mide en milisegundos, el valor es una aproximación, y YouTube insertará el punto de referencia lo más cerca posible en ese momento.

Los valores distintos de cero para este campo solo se admiten si la transmisión continua está demorada. Si la transmisión no se retrasa, 0 es el único valor válido. Consulta la guía de introducción para obtener más detalles.

Nota: Si la emisión tuvo una fase de prueba, la compensación se mide desde el momento en que comenzó la fase de prueba.

La API muestra un error si una solicitud intenta insertar un punto de referencia que especifica un valor para esta propiedad y la propiedad walltimeMs.
walltimeMs integer
El valor de la propiedad especifica la hora real en la que se debe insertar el punto de referencia. El valor es un número entero que representa una marca de tiempo (en milisegundos).

La API muestra un error si una solicitud intenta insertar un punto de referencia que especifique un valor para esta propiedad y la propiedad insertionOffsetTimeMs.
durationSecs unsigned integer
Es la duración del punto de referencia, en segundos. El valor debe ser un número entero positivo. El valor predeterminado es 30.
cueType string
Tipo de punto de inserción El valor de la propiedad se debe establecer como cueTypeAd.

Respuesta

Si se aplica correctamente, este método muestra el recurso cuepoint insertado en el cuerpo de la respuesta.

Errores

En la siguiente tabla, se identifican los mensajes de error que la API podría mostrar en respuesta a una llamada a este método. En la documentación sobre mensajes de error, se identifican todos los errores que puede mostrar la API de Live Streaming.

Tipo de error Detalle del error Descripción
insufficientPermissions (403) insufficientLivePermissions La solicitud no está autorizada para insertar un punto de referencia en la transmisión en vivo.
insufficientPermissions (403) liveStreamingNotEnabled El usuario que autorizó la solicitud no está habilitado para transmitir video en vivo en YouTube. El usuario puede encontrar más información en https://support.google.com/youtube/answer/2474026 y en https://www.youtube.com/features.
rateLimitExceeded (403) userRequestsExceedRateLimit El usuario envió demasiadas solicitudes en un período determinado.
required (400) idRequired El parámetro id obligatorio debe identificar la transmisión en la que deseas insertar un punto de referencia.
required (400) cueTypeRequired El campo cueType obligatorio debe especificarse en el cuerpo de la solicitud a la API.
notFound (404) liveBroadcastNotFound La transmisión especificada por el parámetro id no existe.
invalidValue (400) conflictingTimeFields Solo se puede especificar insertionOffsetTimeMs y walltimeMs. Configurar ambos valores provoca un error. Si no configuras ninguno de los valores, YouTube usará el tiempo predeterminado insertionOffsetTimeMs (0), lo que significa que el punto de inserción se insertará lo antes posible.
invalidValue (400) invalidInsertionOffsetTimeMs El recurso cuepoint especificó un valor no válido para la propiedad insertionOffsetTimeMs. El valor debe ser 0 o un número entero positivo.
invalidValue (400) invalidWalltimeMs El recurso cuepoint especificó un valor no válido para la propiedad walltimeMs. El valor debe ser un número entero que represente una marca de tiempo de época (en milisegundos).
backendError (5xx) serviceUnavailable El servicio no está disponible. Vuelve a enviar la solicitud después de unos minutos.

Pruébela.

Usa APIs Explorer para llamar a esta API y ver la solicitud y la respuesta de la API.