LiveBroadcasts: cuepoint

Wstawia punkt cue w transmisji na żywo. Sygnał może wywołać przerwę na reklamę.

Uwaga: ta metoda zastępuje metodę liveCuepoints.insert, która wymagała autoryzacji żądań przez konto powiązane z właścicielem treści w YouTube. Ta metoda nie wymaga takiego samego upoważnienia.

Żądanie

Żądanie HTTP

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

Autoryzacja

To żądanie wymaga autoryzacji z co najmniej jednym z tych zakresów. Więcej informacji o uwierzytelnianiu i autoryzacji znajdziesz w artykule Wdrażanie uwierzytelniania OAuth 2.0.

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

Parametry

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

Parametry
Parametry wymagane
id string
Parametr id wskazuje transmisję, do której jest wstawiany punkt cue. Podczas wstawiania punktu cue transmisja musi być aktywna.
Parametry opcjonalne
onBehalfOfContentOwner string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu.
Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów treści YouTube, którzy są właścicielami wielu kanałów YouTube i nimi zarządzają. Umożliwia on właścicielom treści jednorazowe uwierzytelnianie 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 osobnego kanału. Konto, na którym użytkownik się uwierzytelnia, musi być powiązane z określonym właścicielem treści w YouTube.
Parametr onBehalfOfContentOwner wskazuje, że poświadczenia autoryzacji w żądaniu identyfikują użytkownika YouTube, który działa w imieniu właściciela treści w YouTube określonego w wartości parametru. Ten parametr jest przeznaczony dla partnerów treści YouTube, którzy są właścicielami wielu kanałów YouTube i nimi zarządzają.
onBehalfOfContentOwnerChannel string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu.
Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów treści YouTube, którzy są właścicielami wielu kanałów YouTube i nimi zarządzają. Umożliwia on właścicielom treści jednorazowe uwierzytelnienie i wykonywanie działań w imieniu kanału określonego w wartości parametru, bez konieczności podawania danych uwierzytelniających dla każdego osobnego kanału.
Parametr onBehalfOfContentOwnerChannel określa identyfikator kanału YouTube powiązanego z transmisją, do której jest wstawiany punkt cue. Ten parametr jest wymagany, gdy żądanie określa wartość parametru onBehalfOfContentOwner. Można go używać tylko w połączeniu z tym parametrem. Obowiązują też te wymagania:
  • Prośba musi być autoryzowana przez konto użytkownika powiązane z właścicielem treści, który jest określony przez parametr onBehalfOfContentOwner.
  • Kanał określony przez wartość parametru onBehalfOfContentOwnerChannel musi być powiązany z właścicielem treści określonym przez parametr onBehalfOfContentOwner.

Treść żądania

W treści żądania podaj zasób cuepoint. Struktura JSON przedstawiona poniżej 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 mieć wartość cueTypeAd. Możesz też ustawić wartości tych właściwości:
  • durationSecs
  • insertionOffsetTimeMs (nie musi być ustawione, jeśli walltimeMs jest ustawione)
  • walltimeMs (nie musi być ustawione, jeśli insertionOffsetTimeMs jest ustawione)

Właściwości

Właściwości występujące w tym zasobie są opisane w tabeli poniżej:

Właściwości
id string
Wartość, którą YouTube przypisuje do punktu cuepoint, aby jednoznacznie go zidentyfikować. Pamiętaj, że ta wartość jest inna niż wymagany parametr id, który identyfikuje transmisję. Ta wartość może zostać pominięta podczas wysyłania żądania wstawienia punktu cue. Wartość zostanie wypełniona w odpowiedzi interfejsu API.
insertionOffsetTimeMs long
Wartość właściwości określa przesunięcie czasowe (w milisekundach), w którym należy wstawić punkt wstawienia reklamy. Wartość jest mierzona od początku strumienia monitorowania, a jej domyślna wartość to 0, co oznacza, że punkt cuepoint powinien zostać wstawiony jak najszybciej. Jeśli w Twoim przekazie nie ma strumienia monitorowania, nie podawaj wartości tego parametru.

Chociaż wartość jest mierzona w milisekundach, jest to wartość przybliżona, a YouTube wstawia punkt cuepoint w czasie jak najbardziej zbliżonym do tego.

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

Uwaga: jeśli transmisja miała fazę testowania, przesunięcie jest mierzone od momentu rozpoczęcia fazy testowania.

Interfejs API zwraca błąd, jeśli żądanie próbuje wstawić punkt cuepoint, który określa wartość dla tej usługi i usługi walltimeMs.
walltimeMs integer
Wartość właściwości określa czas zegarowy, w którym należy wstawić punkt wstawienia reklamy. 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 cuepoint, który określa wartość tej właściwości i właściwości insertionOffsetTimeMs.
durationSecs unsigned integer
Czas trwania punktu sygnału w sekundach. Wartość musi być dodatnią liczbą całkowitą. Wartością domyślną jest 30.
cueType string
Typ punktu odniesienia. Wartość właściwości musi być ustawiona na cueTypeAd.

Odpowiedź

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

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. Więcej informacji znajdziesz w artykule Interfejs YouTube Live Streaming API – błędy.

Typ błędu Szczegóły błędu Opis
insufficientPermissions (403) insufficientLivePermissions Żądanie nie jest upoważnione do wstawiania punktu cue w transmisji na żywo.
insufficientPermissions (403) liveStreamingNotEnabled Użytkownik, który zatwierdził prośbę, nie ma włączonej transmisji na żywo w YouTube. Użytkownik może znaleźć więcej informacji w artykułach Zaczynamy korzystać z transmisji na żywo i Wymagania dotyczące funkcji.
rateLimitExceeded (403) userRequestsExceedRateLimit Użytkownik wysłał zbyt wiele żądań w danym przedziale czasu.
required (400) idRequired Wymagany parametr id musi identyfikować transmisję, w której chcesz wstawić punkt cuepoint.
required (400) cueTypeRequired W treści żądania API należy podać wymagane pole cueType.
notFound (404) liveBroadcastNotFound Transmisja określona przez parametr id nie istnieje.
invalidValue (400) conflictingTimeFields Można ustawić tylko jedną z opcji insertionOffsetTimeMs lub walltimeMs. Ustawienie obu wartości powoduje błąd. Jeśli nie ustawisz żadnej z tych wartości, YouTube użyje domyślnego czasu insertionOffsetTimeMs (0), co oznacza, że punkt cuepoint zostanie wstawiony tak szybko, jak to możliwe.
invalidValue (400) invalidInsertionOffsetTimeMs Zasób cuepoint ma nieprawidłową wartość właściwości insertionOffsetTimeMs. Wartość musi być 0 lub dodatnią liczbą całkowitą.
invalidValue (400) invalidWalltimeMs Zasób cuepoint ma nieprawidłową wartość właściwości walltimeMs. Wartość musi być liczbą całkowitą, która reprezentuje sygnaturę czasową epoki (w milisekundach).
backendError (5xx) serviceUnavailable Usługa jest niedostępna. Spróbuj ponownie za kilka minut.

Wypróbuj

Użyj adresu APIs Explorer, aby wywołać ten interfejs API i zobaczyć żądanie oraz odpowiedź interfejsu API.