LiveBroadcasts: cuepoint

Wstawia punkt wstawienia do transmisji na żywo. Punkt wstawienia reklamy może powodować przerwę w reklamie.

Uwaga: ta metoda zastępuje metodę liveCuepoints.insert, która wymagała autoryzacji konta powiązanego z właścicielem treści YouTube. Ta metoda nie ma takich samych wymagań dotyczących autoryzacji.

Żądanie

Żądanie HTTP

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

Upoważnienie

To żądanie wymaga autoryzacji przy użyciu co najmniej jednego z tych zakresów (więcej informacji o uwierzytelnianiu i autoryzacji).

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

Parametry

Tabela poniżej zawiera listę parametrów obsługiwanych przez to zapytanie. Wszystkie wymienione parametry są parametrami zapytania.

Parametry
Parametry wymagane
id string
Parametr id identyfikuje transmisję, do której wstawiany jest punkt wstawienia. Podczas wstawiania punktu wstawienia reklamy muszą być aktywne.
Parametry opcjonalne
onBehalfOfContentOwner string
Ten parametr może być używany tylko w prawidłowym autoryzowanym żądaniu.
Uwaga: ten parametr jest przeznaczony tylko dla dostawców treści w YouTube, którzy mają wiele różnych kanałów YouTube i nimi zarządzają. Umożliwia właścicielom treści uwierzytelnianie raz i wykonywanie działań w imieniu kanału określonego w wartości parametru, bez konieczności podawania różnych danych uwierzytelniających dla każdego kanału. Konto, z którego użytkownik się uwierzytelnia, musi być połączone ze wskazanym właścicielem treści YouTube.
Parametr onBehalfOfContentOwner wskazuje, że dane logowania żądania autoryzacji wskazują użytkownika YouTube działającego w imieniu właściciela treści YouTube określonego w wartości parametru. Ten parametr jest przeznaczony dla partnerów w sieci YouTube, którzy mają wiele różnych kanałów YouTube i nimi zarządzają.
onBehalfOfContentOwnerChannel string
Ten parametr może być używany tylko w prawidłowym autoryzowanym żądaniu.
Uwaga: ten parametr jest przeznaczony tylko dla dostawców treści w YouTube, którzy mają wiele różnych kanałów YouTube i nimi zarządzają. Umożliwia właścicielom treści uwierzytelnianie jeden raz i wykonywanie działań w imieniu kanału określonego w wartości parametru, bez konieczności podawania danych uwierzytelniających dla każdego kanału.
Parametr onBehalfOfContentOwnerChannel określa identyfikator kanału YouTube powiązanego z transmisją, do której wstawiany jest punkt wstawienia. Ten parametr jest wymagany, gdy żądanie określa wartość parametru onBehalfOfContentOwner. Można go użyć tylko w połączeniu z tym parametrem. Obowiązują też te wymagania:
  • Żądanie musi być autoryzowane przez konto użytkownika połączone z właścicielem treści, który jest określony przez parametr onBehalfOfContentOwner.
  • Kanał określony przez parametr onBehalfOfContentOwnerChannel musi być połączony z właścicielem treści określonym przez parametr onBehalfOfContentOwner.

Treść żądania

W treści żądania umieść zasób cuepoint. Poniższa struktura JSON pokazuje format zasobu cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
W treści żądania pole cueType jest wymagane i musi być ustawione na cueTypeAd. Możesz też ustawić wartości tych właściwości:
  • durationSecs
  • insertionOffsetTimeMs (nie można ustawić, jeśli ustawiono walltimeMs)
  • walltimeMs (nie można ustawić, jeśli ustawiono insertionOffsetTimeMs)

Właściwości

Tabela poniżej określa właściwości wyświetlane w tym zasobie:

Właściwości
id string
Wartość, którą YouTube przypisuje do konkretnego punktu wstawienia reklamy. Pamiętaj, że ta wartość różni się od wymaganego parametru id, który identyfikuje transmisję. Tę wartość można pominąć podczas wysyłania żądania wstawienia punktu wstawienia. Wartość zostanie uzupełniona w odpowiedzi interfejsu API.
insertionOffsetTimeMs long
Wartość właściwości określa przesunięcie czasu (w milisekundach), w którym należy wstawić punkt wstawienia. Wartość jest mierzona od początku strumienia monitorowania, a jej wartość domyślna to 0. Oznacza to, że punkt wstawienia reklamy należy wstawić jak najszybciej. Nie podawaj wartości tego parametru, jeśli w transmisji nie ma strumienia monitorowania.

Chociaż wartość jest mierzona w milisekundach, wartość jest przybliżona, a punkt wstawienia reklamy YouTube zostanie w jak największym stopniu wstawiony do tego momentu.

Wartości inne niż 0 w tym polu są obsługiwane tylko wtedy, gdy transmisja jest opóźniona. Jeśli transmisja nie jest opóźniona, jedyną prawidłową wartością jest 0. Więcej informacji znajdziesz w przewodniku Pierwsze kroki.

Uwaga: jeśli w transmisji wystąpił etap testowy, przesunięcie jest mierzone od momentu rozpoczęcia fazy testowania.

Interfejs API zwraca błąd, jeśli żądanie próbuje wstawić punkt wstawienia określający wartość tej właściwości i właściwości walltimeMs.
walltimeMs integer
Wartość właściwości określa czas zegara ściennego, w którym należy wstawić punkt wstawienia. Wartość jest liczbą całkowitą, która reprezentuje sygnaturę czasową epoki (w milisekundach).

Interfejs API zwraca błąd, jeśli żądanie próbuje wstawić punkt wstawienia określający wartość tej właściwości i właściwości insertionOffsetTimeMs.
durationSecs unsigned integer
Czas trwania punktu wstawienia (w sekundach). Wartość musi być dodatnią liczbą całkowitą. Wartością domyślną jest 30.
cueType string
Typ punktu wstawienia. Wartość właściwości musi być ustawiona na cueTypeAd.

Odpowiedź

Jeśli operacja się uda, ta metoda zwróci wstawiony w treści treści cuepoint zasób.

Błędy

W tabeli poniżej znajdziesz komunikaty o błędach, które interfejs API może zwrócić w odpowiedzi na wywołanie tej metody. Dokumentacja komunikatu o błędzie wskazuje wszystkie błędy, które interfejs Live Streaming API może zwrócić.

Typ błędu Szczegóły błędu Opis
insufficientPermissions (403) insufficientLivePermissions Żądanie nie ma uprawnień do wstawiania punktu wstawienia w transmisji na żywo.
insufficientPermissions (403) liveStreamingNotEnabled Użytkownik, który autoryzował żądanie, nie ma dostępu do transmitowania na żywo w YouTube. Użytkownik może uzyskać więcej informacji na stronach https://support.google.com/youtube/answer/2474026 i https://www.youtube.com/features.
rateLimitExceeded (403) userRequestsExceedRateLimit Użytkownik wysłał zbyt wiele żądań w danym okresie.
required (400) idRequired Wymagany parametr id musi identyfikować transmisję, w której chcesz wstawić punkt wstawienia.
required (400) cueTypeRequired Wymagane pole cueType musi być określone w treści żądania do interfejsu API.
notFound (404) liveBroadcastNotFound Komunikat określony w parametrze id nie istnieje.
invalidValue (400) conflictingTimeFields Można tylko użyć albo opcji insertionOffsetTimeMs, albo walltimeMs. Jeśli ustawisz obie te wartości, wystąpi błąd. Jeśli nie ustawisz żadnej wartości, YouTube użyje domyślnego czasu insertionOffsetTimeMs (0), co oznacza, że punkt wstawienia reklamy zostanie wstawiony jak najszybciej.
invalidValue (400) invalidInsertionOffsetTimeMs Zasób cuepoint określa nieprawidłową wartość właściwości insertionOffsetTimeMs. Wartość musi być dodatnią liczbą całkowitą (0).
invalidValue (400) invalidWalltimeMs Zasób cuepoint określa nieprawidłową wartość właściwości walltimeMs. Wartość musi być liczbą całkowitą i reprezentować sygnaturę czasową epoki (w milisekundach).
backendError (5xx) serviceUnavailable Usługa jest niedostępna. Spróbuj wysłać żądanie ponownie za kilka minut.

Wypróbuj

Użyj APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź API.