Ta strona została przetłumaczona przez Cloud Translation API.

Omówienie interfejsu YouTube Live Streaming API

Interfejs YouTube Live Streaming API umożliwia tworzenie i aktualizowanie wydarzeń na żywo w YouTube oraz zarządzanie nimi. Za jego pomocą można układać harmonogram wydarzeń (transmisji) i łączyć je ze strumieniami wideo, które stanowią właściwą treść przekazu.

Interfejs Live Streaming API składa się tak naprawdę z komponentów interfejsów YouTube Data API i YouTube Content ID API. Interfejs Data API umożliwia użytkownikom YouTube zarządzanie kontami, a YouTube Content ID API umożliwia interakcję z systemem zarządzania prawami w YouTube. Jednak wszystkie zasoby wchodzące w skład interfejsu Live Streaming API są używane tylko do tworzenia wydarzeń na żywo i zarządzania nimi.

Ten dokument jest przeznaczony dla programistów, którzy chcą napisać aplikacje ułatwiające prowadzenie transmisji na żywo w YouTube. Wyjaśnia podstawowe pojęcia dotyczące YouTube i samego interfejsu API. Znajdziesz tu też omówienie różnych funkcji obsługiwanych przez ten interfejs API.

Podstawowe pojęcia

komunikaty: Transmisja to wydarzenie, które można na bieżąco oglądać w YouTube. Transmisje można również nagrywać i zapisywać jako filmy w YouTube, aby użytkownicy mogli je obejrzeć później.
strumienie: Strumień określa treści audio i wideo przesyłane do YouTube. Każda transmisja jest powiązana z jednym strumieniem wideo.
punkty wstawienia reklamy: Punkt wstawienia reklamy reprezentuje przerwę na reklamę, którą można wstawić w transmisji na żywo.

Przypadki użycia interfejsu API

Oto kilka sposobów korzystania z interfejsu API w swojej aplikacji:

Planowanie transmisji i definiowanie ustawień transmisji. Twoja aplikacja może umożliwiać użytkownikom wstępne definiowanie ustawień transmisji, a następnie wybieranie tych ustawień, które mają być stosowane do konkretnej transmisji.
Powiązanie strumieni wideo i transmisji.
Daj nadawcom możliwość jednoczesnego definiowania informacji o transmisji i filmie (za pomocą interfejsu YouTube Data API).
Uprość przejścia między stanami transmisji (np. testing lub live) i umożliwij użytkownikom wstawianie punktów wstawienia.

Zanim rozpoczniesz

Aby uzyskać dostęp do funkcji Google API Console, poprosić o klucz interfejsu API i zarejestrować aplikację, musisz mieć konto Google.
Zarejestruj swoją aplikację w Google, aby móc przesyłać żądania interfejsu API.
Po zarejestrowaniu aplikacji wybierz YouTube Data API jako jedną z używanych przez nią usług:
1. Otwórz API Console i wybierz przed chwilą zarejestrowany projekt.
2. Otwórz stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy dla interfejsu YouTube Data API w wersji 3 ma stan WŁ., a jeśli jesteś partnerem treści w YouTube – dla interfejsu YouTube Content ID API.
Zapoznaj się z podstawowymi pojęciami związanymi z formatem danych JavaScript Object Notation (JSON). JSON to popularny format danych niezależny od języka, który oferuje prostą tekstową prezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Autoryzowanie żądań do interfejsu API

Jak już wspomnieliśmy, interfejs Live Streaming API wykorzystuje funkcje, które są technicznie częścią interfejsu YouTube Data API lub YouTube Content ID API. Za pomocą interfejsu Content ID API możesz przekazywać do YouTube metadane, informacje o własności oraz informacje o zasadach dotyczących Twoich zasobów. Przykładem zasobu jest transmisja wideo na żywo. Pozwala on też zgłaszać roszczenia do filmów i określać zasady dotyczące reklam.

W tej sekcji opisano wymagania dotyczące upoważnienia związane z żądaniami wysyłanymi do Content ID API, które różnią się od wymagań dotyczących autoryzacji innych żądań Live Streaming API.

Dzwonię pod numer Data API: Żądanie do interfejsu API musi zostać zatwierdzone przez konto Google, do którego należy kanał YouTube nadający jego transmisję.
Dzwonię pod numer Content ID API: Żądanie do interfejsu API musi zostać autoryzowane przez konto Google powiązane z właścicielem treści, do którego należy kanał YouTube nadający jego transmisję.

Zasoby i typy zasobów

Zasób to pojedynczy element danych z unikalnym identyfikatorem. Tabela poniżej zawiera różnych typów zasobów, z którymi będziesz korzystać za pomocą Live Streaming API Technicznie rzecz biorąc, wszystkie te zasoby są zdefiniowane w ramach elementu YouTube Data API lub YouTube Content ID API. Jednak liveBroadcast, liveStream i cuepoint zasobów jest nieaktualnych służą tylko do tworzenia wydarzeń na żywo i zarządzania nimi.

Zasoby
`liveBroadcast`	Zawiera informacje o wydarzeniu, które transmitujesz w YouTube. O Zasób `liveBroadcast` jest rozszerzeniem zasobu wideo YouTube i ustawia metadanych filmu, które byłyby istotne dla transmisji na żywo, ale nie w odniesieniu do innych filmów w YouTube. W związku z tym zasób `liveBroadcast` odpowiada dokładnie jednemu zasobowi wideo w YouTube. `liveBroadcast` , a zasób `video` współdzielą ten sam identyfikator. Po utworzeniu transmisji za pomocą interfejsu Live Streaming API możesz użyć przycisku YouTube Data API, aby udostępnić dodatkowe metadane filmu.
`liveStream`	Zawiera informacje o strumieniu wideo, który przesyłasz do YouTube. Strumień udostępnia treść, która będzie transmitowana użytkownikom YouTube. Po utworzeniu `liveStream` zasób można powiązać dokładnie z jednym zasobem `liveBroadcast`. Podobnie Zasób `liveBroadcast` może być powiązany tylko z 1 zasobem `liveStream`.
`cuepoint`	Wstawia punkt wstawienia w transmitowanym strumieniu wideo, który może spowodować wyświetlenie przerwy na reklamę. Użyj `liveBroadcasts.cuepoint` do wstawienia punktu wstawienia podczas transmisji.
`video`	Reprezentuje pojedynczy film w YouTube. Jak wspomnieliśmy powyżej, zasób `liveBroadcast` jest rozszerzeniem zasobu `video`. Interfejs YouTube Data API umożliwia aktualizowanie metadanych filmu, takich jak miejsce nagrania lub regiony, w których transmisja będzie dostępna.
`videoAdvertisingOptions`	Określa ustawienia reklam dla filmu (lub transmisji). YouTube Content ID API służy do ustawiania opcji reklam.
`asset`	Reprezentuje element własności intelektualnej, np. film lub odcinek programu. W takim przypadku zasobem jest przesyłany obraz. Wykorzystasz YouTube Content ID API do tworzenia zasobów `asset` i zarządzania nimi.
`claim`	Łączy film z zasobem, do którego film pasuje. Tworząc roszczenie, wykorzystując YouTube Content ID API, aby potwierdzić, że jesteś właścicielem transmitowanego filmu.
`policy`	Określają reguły określające okoliczności, w których Twoje treści mają być dostępne w YouTube lub blokowane w YouTube. Musisz zastosować zasadę do transmitowanego obrazu, a także określić zasady stosowane przez YouTube do filmów przesłanych przez użytkowników, które pasują do transmitowanego obrazu.

Obsługiwane operacje

W tabeli poniżej znajdziesz różne metody obsługiwane przez interfejs API:

Operacje
`list`	Pobiera (`GET`) listę zero lub więcej zasobów.
`insert`	Tworzy (`POST`) nowy zasób.
`update`	Modyfikuje (`PUT`) istniejący zasób, aby odzwierciedlić dane z Twojego żądania.
`bind`	Łączy zasób `liveBroadcast` z zasobem `liveStream` lub usuwa taki link.
`transition`	Zmienia stan zasobu `liveBroadcast` i inicjuje wszystkie procesy powiązane z nowym stanem. Jeśli na przykład zmienisz stan transmisji na `testing`, YouTube rozpocznie przesyłanie obrazu do jej strumienia monitorującego.
`delete`	Usuwa (`DELETE`) konkretny zasób.

Poniższa tabela przedstawia operacje, które są obsługiwane w przypadku różnych typów zasobów. Operacje wstawiania, aktualizowania lub usuwania zasobów zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach metody list obsługują zarówno żądania autoryzowane, jak i nieautoryzowane. Nieautoryzowane żądania pobierają jedynie dane publiczne, a autoryzowane żądania mogą pobierać informacje dostępne tylko w przypadku aktualnie uwierzytelnionego użytkownika.

Obsługiwane operacje
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Zasoby częściowe

Interfejs API umożliwia i w rzeczywistości wymaga pobierania częściowych zasobów, tak aby aplikacje nie przesyłały, nie analizowały i nie przechowują niepotrzebnych danych. Takie podejście gwarantuje też wydajniejsze wykorzystanie zasobów sieci, procesora i pamięci przez interfejs API.

Parametr part jest wymagany w przypadku każdego żądania do interfejsu API, które pobiera lub zwraca zasób YouTube Data API. Parametr identyfikuje co najmniej jedną właściwość zasobu najwyższego poziomu (niezagnieżdżoną), która powinna być uwzględniona w odpowiedzi interfejsu API. Na przykład zasób liveStream składa się z tych elementów:

snippet
cdn
status

Wszystkie te części są obiektami zawierającymi właściwości zagnieżdżone. Można je traktować jako grupy pól metadanych, które serwer API może (lub nie) pobrać. W związku z tym parametr part wymaga wybrania komponentów zasobów, których rzeczywiście używa Twoja aplikacja. To wymaganie ma 2 ważne cele:

Pozwala to zmniejszyć czas oczekiwania, ponieważ serwer API nie musi tracić czasu na pobieranie pól metadanych, których nie używa Twoja aplikacja.
Zmniejsza ono wykorzystanie przepustowości przez ograniczenie (lub eliminację) ilości niepotrzebnych danych, które może pobrać aplikacja.

Z czasem, w miarę jak zasoby będą dodawane do coraz większej liczby zasobów, korzyści te będą tylko zwiększać, ponieważ aplikacja nie będzie żądać nowo wprowadzonych usług, których nie obsługuje.

Porady i sprawdzone metody

Zgłaszanie praw do treści

Jeśli chcesz wyświetlać reklamy podczas transmisji, zgłoś roszczenie do obrazu transmisji przed rozpoczęciem wydarzenia. Aby zgłaszać roszczenia do treści, musisz być partnerem w zakresie treści YouTube uczestniczącym w programie Content ID.

Proces zgłaszania roszczenia do transmisji na żywo przebiega inaczej niż w przypadku zwykłej procedury zgłaszania roszczenia do filmu. Jeśli zgłaszasz roszczenie do filmu na żywo, musisz zgłosić je, zanim film faktycznie zostanie opublikowany. Interfejs API obsługuje tę funkcję, a dokument dotyczący cyklu życia transmisji zawiera informacje o wywołaniach YouTube Content ID API, które umożliwiają zgłoszenie roszczenia.

Wyświetlanie podglądu i testowanie treści

Po odebraniu przychodzącego strumienia wideo YouTube może transmitować go za pomocą dwóch różnych strumieni wychodzących:

Monitorowanie strumienia umożliwia wyświetlenie podglądu (i przetestowanie) transmisji wideo. To strumień prywatny, do którego masz dostęp tylko Ty. Transmisję możesz przenieść do fazy testing tylko wtedy, gdy jest włączony strumień monitorowania transmisji. W strumieniu monitorowania nie widać przerw na reklamy.
Transmisja to transmisja widoczna dla Twoich odbiorców. Stan prywatności transmisji możesz ustawić na public, private lub unlisted. Transmisja prywatna jest widoczna tylko dla osób, które zostały bezpośrednio zaproszone do jej obejrzenia. Transmisja niepubliczna jest widoczna dla każdego, kto ma link, aby ją wyświetlić.

Możesz opóźnić transmisję, aby nie odbywała się jednocześnie z transmisją z monitora. Opóźniając transmisję, możesz dokładniej określić czas wstawiania punktów wstawienia reklamy.

Jednak opóźnienie transmisji utrudni osobom prowadzącym na żywo kontakt z widzami. Dodatkowo opóźnienie transmisji zwiększa prawdopodobieństwo, że widzowie odkryją najważniejsze informacje o danym wydarzeniu ze źródeł innych niż Twoja transmisja. Jeśli na przykład transmitujesz wydarzenie sportowe z 60-sekundowym opóźnieniem, widzowie mogą poznać najważniejsze momenty tego wydarzenia z innych źródeł w czasie rzeczywistym, zanim jeszcze zobaczą je w transmisji.

YouTube zaleca włączenie strumienia monitorowania swojej transmisji, aby można było przetestować treść. Zdecyduj też, czy chcesz opóźnić transmisję, biorąc pod uwagę chęć kontrolowania punktów wstawienia reklamy, a nie kontaktu z widzami lub relacjonowania wydarzeń w czasie rzeczywistym.

Wyświetlanie reklam w trakcie transmisji

Podczas transmisji możesz wstawić punkt wstawienia reklamy, aby wskazać, że przerwa na reklamę powinna się rozpocząć za transmisję jak najszybciej lub w określonym czasie. Przerwa na reklamę umożliwia wyświetlanie reklam w YouTube. reklam w trakcie transmisji.

Przerwy na reklamę mają następujące cechy:

Ma wstępnie zdefiniowany czas, który ustawiasz za pomocą zasobu cuepoint durationSecs usłudze. Po zakończeniu przerwy na reklamę widzowie wracają do transmisji na żywo.
Gdy nastąpi przerwa na reklamę, reklama będzie wyświetlać się w odtwarzaczu tylko tym widzom, którzy oglądają film. transmisję po wstawieniu punktu wstawienia. Reklama nie wyświetla się, gdy użytkownik odświeża stronę gdzie trwa transmisja lub gdy widzowie zaczynają oglądać transmisję po jej zakończeniu wstawiono punkt wstawienia.

Poniżej przedstawiliśmy sprawdzoną metodę wstawiania przerwy na reklamę podczas transmisji:

Ustaw odsunięcia czasu

Gdy wstawisz punkt wstawienia, możesz określić, czy powinien on zostać wstawiony od razu, czy też należy wstawić w określonym miejscu transmisji. Dostępne opcje zależą od tego, czy jest opóźniony.

Jeśli transmisja nie jest opóźniona, możesz wstawić punkt wstawienia reklamy od razu lub użyć walltimeMs tak, by przerwa na reklamę zaczęła się o określonej godzinie.
- Aby od razu rozpocząć przerwę na reklamę, wywołaj metodę liveBroadcasts.cuepoint. W w treści żądania, ustaw atrybut usługi insertionOffsetTimeMs na 0 lub nie określają żadnej wartości tej właściwości wartość w polu walltimeMs usłudze.
  
  Ważne: pamiętaj, że widzowie nie widzą wyświetlonej reklamy. treści. Przed wyświetleniem treści reklamy może minąć około 30 sekund widoczne dla użytkowników. Po upływie tego opóźnienia transmisja będzie nadal widoczna dla i Trzeba obejrzeć transmisję, aby ustalić, kiedy treść reklamy zamiast z monitora.
- Aby rozpocząć przerwę na reklamę w określonym momencie, wywołaj liveBroadcasts.cuepoint i użyj funkcji walltimeMs w celu określenia żądanego czasu. Wartość właściwości jest liczbą całkowitą, która reprezentuje sygnaturę czasową epoki.
Jeśli transmisja jest opóźniona, możesz od razu wstawić punkt wstawienia jako opisane powyżej, określ godzinę w sposób opisany powyżej. Możesz też podać przesunięcie czasu określić czas rozpoczęcia przerwy na reklamę. Przesunięcie czasu określa punkt w transmisji kiedy widzowie powinni zobaczyć reklamę.

Wartość przesunięcia jest mierzona w milisekundach od początku strumienia monitorowania dla podczas transmisji. Pamiętaj, że jeśli Twoja transmisja jest w fazie testów, rozpocznie się, gdy transmisja zmieni się na testing. W przeciwnym razie strumień monitorowania rozpocznie się po przejściu na transmisję w stanie live.

Podczas wstawiania punktu wstawienia określ parametr cuepoint insertionOffsetTimeMs z właściwością żądanego przesunięcia.

Oblicz wartość przesunięcia czasu

Aby pobrać wartość przesunięcia, wywołaj funkcję getCurrentTime interfejsu YouTube Player API dla odtwarzacza, który odtwarza strumień monitora. Użyj pobranej wartości, aby wstawić punkt wstawienia do strumienia transmisji w danym momencie.

Możliwe wartości czasu przesunięcia można obliczyć za pomocą tego zakresu:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Element Δ to 5-sekundowy bufor na początku i na końcu możliwych przesunięciach czasu, gdy YouTube nie może dokładnie wstawić punktu wstawienia. Na przykład:

Transmisja obejmuje 5-minutową fazę testów.
Transmisja jest opóźniona o 60 sekund po zakończeniu transmisji na monitorze.
Nadawca wstawia punkt wstawienia reklamy po 4 minutach od przejścia transmisji na Stan: live. (Są to trzy minuty od momentu, gdy transmisja stanie się widoczna).

W tym przypadku możliwy zakres czasu przesunięcia to [(485,000), (535,000)].

Czasy są podane w milisekundach i obliczane za pomocą następujących wartości:

elapsed_time=540000 – strumień monitorowania był aktywny przez 9 dni. minut (540 sekund i 540 000 milisekund) po wywołaniu metody liveBroadcasts.cuepoint.
broadcast_delay=60000 – transmisja jest opóźniona o 60 sekund, czyli 60 000 milisekund.
Δ=5000 – 5-sekundowy bufor, którego nie można prawidłowo wstawić punktu wstawienia.

Rozwiązywanie problemów i obsługa błędów

Z poniższych wskazówek dowiesz się, jak rozwiązywać określone problemy, które mogą się pojawić. Na potrzeby list Błędy, które mogą zwrócić poszczególne metody API, znajdziesz w sekcji Interfejs YouTube Live Streaming API – błędy.

Gdy transmisja zmienia się z jednego stanu na inny, może ona tymczasowo otrzymać inny stan, w czasie gdy YouTube wykonuje działania związane z przejściem. Jeśli na przykład wyślesz żądanie liveBroadcasts.transition z prośbą o zmianę stanu transmisji z ready na testing, YouTube ustawi stan transmisji na testStarting, a następnie wykona działania powiązane ze zmianą stanu. Po wykonaniu tych wszystkich czynności YouTube zmieni stan transmisji na testing, co oznacza, że przenoszenie zostało zakończone.

Jeśli transmisja utknie na stanie testStarting lub liveStarting, musisz wywołać metodę liveBroadcasts.delete i ją usunąć. Następnie utwórz nową transmisję, powiąż ją ze swoją transmisją na żywo i kontynuuj proces testowania.

Zgodnie z dokumentacją metody liveBroadcasts.transition przed jej wywołaniem musisz potwierdzić, że wartość właściwości status.streamStatus w przypadku strumienia powiązanego z Twoją transmisją wynosi active.