LiveBroadcasts: cuepoint

Ein Cue-Punkt wird in eine Liveübertragung eingefügt. Der Cue-Punkt kann eine Werbeunterbrechung auslösen.

Hinweis:Diese Methode ersetzt die Methode liveCuepoints.insert. Dabei müssen Anfragen von einem Konto autorisiert werden, das mit einem YouTube-Rechteinhaber verknüpft ist. Bei dieser Methode gelten nicht dieselben Autorisierungsanforderungen.

Anfragen

HTTP-Anfrage

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

Autorisierung

Diese Anfrage benötigt eine Autorisierung mit mindestens einem der folgenden Bereiche (weitere Informationen zu Authentifizierung und Autorisierung).

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

Parameter

In der folgenden Tabelle sind die Parameter aufgeführt, die von dieser Abfrage unterstützt werden. Alle aufgeführten Parameter sind Abfrageparameter.

Parameter
Erforderliche Parameter
id string
Der Parameter id gibt die Übertragung an, in die der Cue-Punkt eingefügt wird. Die Übertragung muss aktiv sein, wenn der Cue-Punkt eingefügt wird.
Optionale Parameter
onBehalfOfContentOwner string
Dieser Parameter kann nur in einer autorisierten Anfrage verwendet werden.
Hinweis:Dieser Parameter ist ausschließlich für Content-Partner von YouTube vorgesehen, die zahlreiche verschiedene YouTube-Kanäle besitzen und verwalten. Rechteinhaber können sich einmalig authentifizieren und Aktionen im Namen des im Parameterwert angegebenen Kanals ausführen, ohne unterschiedliche Authentifizierungsdaten für jeden einzelnen Kanal angeben zu müssen. Das Konto, mit dem sich der Nutzer authentifiziert, muss mit dem angegebenen YouTube-Rechteinhaber verknüpft sein.
Der Parameter onBehalfOfContentOwner gibt an, dass durch die Autorisierungsanmeldedaten ein YouTube-Nutzer identifiziert wird, der im Namen des YouTube-Rechteinhabers handelt, der im Parameterwert angegeben ist. Dieser Parameter ist für YouTube-Content-Partner vorgesehen, die Inhaber und Manager vieler verschiedener YouTube-Kanäle sind.
onBehalfOfContentOwnerChannel string
Dieser Parameter kann nur in einer autorisierten Anfrage verwendet werden.
Hinweis:Dieser Parameter ist ausschließlich für Content-Partner von YouTube vorgesehen, die zahlreiche verschiedene YouTube-Kanäle besitzen und verwalten. Rechteinhaber können sich einmalig authentifizieren und Aktionen im Namen des Kanals ausführen, der im Parameterwert angegeben ist. Dazu müssen keine Anmeldedaten für jeden einzelnen Kanal angegeben werden.
Der Parameter onBehalfOfContentOwnerChannel gibt die YouTube-Kanal-ID des Kanals an, der der Übertragung zugeordnet ist, in die der Cue-Punkt eingefügt wird. Dieser Parameter ist erforderlich, wenn in einer Anfrage ein Wert für den Parameter onBehalfOfContentOwner angegeben wird. Er kann nur in Verbindung mit diesem Parameter verwendet werden. Außerdem gelten die folgenden Anforderungen:
  • Die Anfrage muss mit einem Nutzerkonto autorisiert werden, das mit dem Rechteinhaber verknüpft ist, der im onBehalfOfContentOwner-Parameter angegeben ist.
  • Der Kanal, den der onBehalfOfContentOwnerChannel-Parameterwert angibt, muss mit dem Rechteinhaber verknüpft sein, der im onBehalfOfContentOwner-Parameter angegeben ist.

Anfragetext

Geben Sie eine cuepoint-Ressource im Anfragetext an. Die folgende JSON-Struktur zeigt das Format einer cuepoint-Ressource:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
Im Anfragetext ist das Feld cueType erforderlich und muss auf cueTypeAd festgelegt werden. Sie können auch Werte für diese Eigenschaften festlegen:
  • durationSecs
  • insertionOffsetTimeMs (muss nicht festgelegt werden, wenn walltimeMs festgelegt ist)
  • walltimeMs (muss nicht festgelegt werden, wenn insertionOffsetTimeMs festgelegt ist)

Attribute

In der folgenden Tabelle werden die Attribute definiert, die in dieser Ressource angezeigt werden:

Attribute
id string
Ein Wert, den YouTube zur eindeutigen Identifizierung des Cue-Punkts zuweist. Dieser Wert unterscheidet sich vom erforderlichen id-Parameter, der die Übertragung identifiziert. Dieser Wert kann beim Senden einer Anfrage zum Einfügen eines Cue-Punkts weggelassen werden. Der Wert wird in der API-Antwort eingefügt.
insertionOffsetTimeMs long
Der Property-Wert gibt einen Zeitversatz in Millisekunden an, in dem der Cue-Punkt eingefügt werden soll. Der Wert wird ab Beginn des Monitoring-Streams gemessen. Der Standardwert ist 0. Dies bedeutet, dass der Cue-Punkt so schnell wie möglich eingefügt werden soll. Sie sollten keinen Wert für diesen Parameter angeben, wenn Ihre Übertragung keinen Monitorstream hat.

Obwohl der Wert in Millisekunden gemessen wird, ist er tatsächlich ein Näherungswert. YouTube fügt den Cue-Punkt so genau wie möglich diesem Zeitpunkt hinzu.

Werte für dieses Feld ungleich null werden nur unterstützt, wenn der Übertragungsstream verzögert wird. Wenn dein Übertragungsstream nicht verzögert wird, ist 0 der einzige gültige Wert. Weitere Informationen finden Sie im Startleitfaden.

Hinweis:Wenn bei Ihrer Übertragung eine Testphase stattgefunden hat, wird der Offset ab dem Beginn der Testphase gemessen.

Die API gibt einen Fehler zurück, wenn versucht wird, einen Cue-Punkt einzufügen, der einen Wert für diese Property und für die Property walltimeMs angibt.
walltimeMs integer
Der Property-Wert gibt die Wanduhrzeit an, zu der der Cue-Punkt eingefügt werden soll. Der Wert ist eine Ganzzahl, die einen Epochenzeitstempel darstellt (in Millisekunden).

Die API gibt einen Fehler zurück, wenn eine Anfrage versucht, einen Cue-Punkt einzufügen, der einen Wert für diese Eigenschaft und für die Eigenschaft insertionOffsetTimeMs angibt.
durationSecs unsigned integer
Die Dauer des Cue-Punkts in Sekunden. Der Wert muss eine positive Ganzzahl sein. Der Standardwert ist 30.
cueType string
Der Typ des Cue-Punkts. Der Wert der Eigenschaft muss auf cueTypeAd festgelegt werden.

Antwort

Wenn der Vorgang erfolgreich abgeschlossen wurde, wird mit dieser Methode die eingefügte cuepoint-Ressource im Antworttext zurückgegeben.

Fehler

In der folgenden Tabelle sehen Sie Fehlermeldungen, die von der API als Reaktion auf einen Aufruf dieser Methode zurückgegeben werden könnten. In der Dokumentation zu Fehlermeldungen werden alle Fehler aufgeführt, die von der Live Streaming API zurückgegeben werden können.

Fehlertyp Fehlerdetails Beschreibung
insufficientPermissions (403) insufficientLivePermissions Die Anfrage ist nicht berechtigt, einen Cue-Punkt in die Liveübertragung einzufügen.
insufficientPermissions (403) liveStreamingNotEnabled Der Nutzer, der die Anfrage autorisiert hat, ist nicht berechtigt, Live-Videos auf YouTube zu streamen. Weitere Informationen findest du unter https://support.google.com/youtube/answer/2474026 und https://www.youtube.com/features.
rateLimitExceeded (403) userRequestsExceedRateLimit Der Nutzer hat in einem bestimmten Zeitraum zu viele Anfragen gesendet.
required (400) idRequired Der erforderliche id-Parameter muss die Übertragung angeben, in die Sie einen Cue-Punkt einfügen möchten.
required (400) cueTypeRequired Das Pflichtfeld cueType muss im API-Anfragetext angegeben werden.
notFound (404) liveBroadcastNotFound Die vom Parameter id angegebene Übertragung ist nicht vorhanden.
invalidValue (400) conflictingTimeFields Es kann entweder insertionOffsetTimeMs oder walltimeMs angegeben werden. Das Festlegen beider Werte führt zu einem Fehler. Wenn du keinen der Werte festlegst, verwendet YouTube die standardmäßige insertionOffsetTimeMs-Zeit (0). Das bedeutet, dass der Cue-Punkt so schnell wie möglich eingefügt wird.
invalidValue (400) invalidInsertionOffsetTimeMs Die Ressource cuepoint hat einen ungültigen Wert für die Eigenschaft insertionOffsetTimeMs angegeben. Der Wert muss 0 oder eine positive Ganzzahl sein.
invalidValue (400) invalidWalltimeMs Die Ressource cuepoint hat einen ungültigen Wert für die Eigenschaft walltimeMs angegeben. Der Wert muss eine Ganzzahl sein, die einen Epochenzeitstempel (in Millisekunden) darstellt.
backendError (5xx) serviceUnavailable Der Dienst ist nicht verfügbar. Versuchen Sie es in einigen Minuten noch einmal.

Jetzt testen

Verwenden Sie APIs Explorer, um diese API aufzurufen und die API-Anfrage und -Antwort anzusehen.