LiveBroadcasts: cuepoint

Insère un point de repère dans une diffusion en direct. Le point de repère peut déclencher une coupure publicitaire.

Remarque:Cette méthode remplace la méthode liveCuepoints.insert, qui nécessitait l'autorisation d'un compte associé à un propriétaire de contenu YouTube. Cette méthode ne présente pas les mêmes exigences d'autorisation.

Demande

Requête HTTP :

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

Autorisation

Une autorisation est requise pour cette requête. Celle-ci doit inclure au moins l'un des champs d'application suivants. En savoir plus sur le processus d'authentification et d'autorisation

Champ d'application
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

Paramètres

Le tableau suivant répertorie les paramètres compatibles avec cette requête. Tous les paramètres listés sont des paramètres de requête.

Paramètres
Réglages obligatoires
id string
Le paramètre id identifie la diffusion dans laquelle le point de repère est inséré. La diffusion doit être active lors de l'insertion du point de repère.
Paramètres facultatifs
onBehalfOfContentOwner string
Ce paramètre ne peut être utilisé que dans une requête autorisée appropriée.
Remarque:Ce paramètre est réservé aux partenaires de contenu YouTube qui possèdent et gèrent de nombreuses chaînes YouTube différentes. Elle permet aux propriétaires de contenu de s'authentifier une fois et d'effectuer des actions au nom du canal spécifié dans la valeur de paramètre, sans avoir à fournir des identifiants d'authentification différents pour chaque canal distinct. Le compte avec lequel l'utilisateur s'authentifie doit être associé au propriétaire de contenu YouTube spécifié.
Le paramètre onBehalfOfContentOwner indique que les identifiants d'autorisation de la requête identifient un utilisateur YouTube qui agit au nom du propriétaire de contenu YouTube spécifié dans la valeur du paramètre. Ce paramètre est destiné aux partenaires de contenu YouTube qui possèdent et gèrent de nombreuses chaînes YouTube différentes.
onBehalfOfContentOwnerChannel string
Ce paramètre ne peut être utilisé que dans une requête autorisée appropriée.
Remarque:Ce paramètre est réservé aux partenaires de contenu YouTube qui possèdent et gèrent de nombreuses chaînes YouTube différentes. Elle permet aux propriétaires de contenu de s'authentifier une fois et d'effectuer des actions au nom du canal spécifié dans la valeur de paramètre, sans avoir à fournir d'identifiants pour chaque canal.
Le paramètre onBehalfOfContentOwnerChannel spécifie l'ID de la chaîne YouTube associée à la diffusion dans laquelle le point de repère est inséré. Ce paramètre est obligatoire lorsqu'une requête spécifie une valeur pour le paramètre onBehalfOfContentOwner. Il ne peut être utilisé qu'avec ce paramètre. Les exigences suivantes s'appliquent également :
  • La requête doit être autorisée avec un compte utilisateur associé au propriétaire de contenu spécifié par le paramètre onBehalfOfContentOwner.
  • La chaîne spécifiée par le paramètre onBehalfOfContentOwnerChannel doit être associée au propriétaire de contenu spécifié par le paramètre onBehalfOfContentOwner.

Corps de la requête

Fournissez une ressource cuepoint dans le corps de la requête. La structure JSON suivante indique le format d'une ressource cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
Dans le corps de la requête, le champ cueType est obligatoire et doit être défini sur cueTypeAd. Vous pouvez également définir des valeurs pour les propriétés suivantes :
  • durationSecs
  • insertionOffsetTimeMs (ne doit pas être défini si walltimeMs est défini)
  • walltimeMs (ne doit pas être défini si insertionOffsetTimeMs est défini)

Propriétés

Le tableau suivant définit les propriétés qui apparaissent dans cette ressource:

Propriétés
id string
Valeur attribuée par YouTube pour identifier le point de repère de manière unique. Notez que cette valeur est différente du paramètre id requis, qui identifie l'annonce. Cette valeur peut être omise lors de l'envoi d'une requête pour insérer un point de repère. La valeur sera insérée dans la réponse de l'API.
insertionOffsetTimeMs long
La valeur de la propriété identifie un décalage temporel, en millisecondes, pendant lequel le point de repère doit être inséré. La valeur est mesurée à partir du début du flux de surveillance. Sa valeur par défaut est 0, ce qui indique que le point de repère doit être inséré dès que possible. Vous ne devez pas spécifier de valeur pour ce paramètre si votre diffusion ne comporte pas de flux de surveillance.

Bien qu'elle soit mesurée en millisecondes, cette valeur est en réalité une approximation. YouTube insère alors le point de repère le plus près possible de ce point.

Les valeurs non nulles pour ce champ ne sont acceptées que si le flux de diffusion est retardé. Si votre flux de diffusion n'est pas retardé, 0 est la seule valeur valide. Pour en savoir plus, consultez le guide Premiers pas.

Remarque:Si votre diffusion a eu une phase de test, le décalage est mesuré à partir du début de la phase de test.

L'API renvoie une erreur si une requête tente d'insérer un point de repère qui spécifie une valeur pour cette propriété et pour la propriété walltimeMs.
walltimeMs integer
La valeur de la propriété spécifie l'heure de l'horloge murale à laquelle le point de repère doit être inséré. La valeur est un entier représentant un horodatage d'epoch (en millisecondes).

L'API renvoie une erreur si une requête tente d'insérer un point de repère spécifiant une valeur pour cette propriété et pour la propriété insertionOffsetTimeMs.
durationSecs unsigned integer
Durée du point de repère, en secondes. La valeur doit être un nombre entier positif. La valeur par défaut est 30.
cueType string
Type de point de repère. La valeur de la propriété doit être définie sur cueTypeAd.

Réponse

Si l'opération réussit, cette méthode renvoie la ressource cuepoint insérée dans le corps de la réponse.

Erreurs

Le tableau suivant identifie les messages d'erreur que l'API peut renvoyer en réponse à un appel à cette méthode. La documentation sur les messages d'erreur identifie toutes les erreurs que l'API Live Streaming peut renvoyer.

Type d'erreur Détails de l'erreur Description
insufficientPermissions (403) insufficientLivePermissions La requête n'est pas autorisée à insérer un point de repère dans la diffusion en direct.
insufficientPermissions (403) liveStreamingNotEnabled L'utilisateur qui a autorisé la demande n'est pas autorisé à diffuser des vidéos en direct sur YouTube. Pour en savoir plus, consultez les pages https://support.google.com/youtube/answer/2474026 et https://www.youtube.com/features.
rateLimitExceeded (403) userRequestsExceedRateLimit L'utilisateur a envoyé trop de requêtes sur une période donnée.
required (400) idRequired Le paramètre id obligatoire doit identifier l'annonce dans laquelle vous souhaitez insérer un point de repère.
required (400) cueTypeRequired Le champ obligatoire cueType doit être spécifié dans le corps de la requête API.
notFound (404) liveBroadcastNotFound L'annonce spécifiée par le paramètre id n'existe pas.
invalidValue (400) conflictingTimeFields Vous ne pouvez spécifier qu'un seul insertionOffsetTimeMs et un walltimeMs. La définition des deux valeurs entraîne une erreur. Si vous ne définissez aucune valeur, YouTube utilisera l'heure insertionOffsetTimeMs par défaut (0), ce qui signifie que le point de repère sera inséré dès que possible.
invalidValue (400) invalidInsertionOffsetTimeMs La ressource cuepoint a spécifié une valeur non valide pour la propriété insertionOffsetTimeMs. La valeur doit être 0 ou un entier positif.
invalidValue (400) invalidWalltimeMs La ressource cuepoint a spécifié une valeur non valide pour la propriété walltimeMs. La valeur doit être un entier représentant le code temporel de l'epoch (en millisecondes).
backendError (5xx) serviceUnavailable Le service est indisponible. Réessayez dans quelques minutes.

Essayer

Utilisez APIs Explorer pour appeler cette API, et consultez la requête et la réponse de l'API.