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.

W rzeczywistości interfejs Live Streaming API składa się z komponentów YouTube Data API oraz YouTube Content ID API. Interfejs Data API umożliwia użytkownikom YouTube zarządzanie ich kontami, a YouTube Content ID API umożliwia interakcję z systemem zarządzania prawami YouTube. Jednak wszystkie zasoby, które składają się na interfejs 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ą tworzyć aplikacje ułatwiające transmisję na żywo w YouTube. Wyjaśniono w nim podstawowe pojęcia związane z YouTube i samym interfejsem API. Artykuł zawiera też omówienie różnych funkcji obsługiwanych przez interfejs API.

Podstawowe pojęcia

transmisje: Transmisja to wydarzenie, które można oglądać w YouTube na bieżąco. Transmisje mogą też być nagrywane i zapisywane jako filmy w YouTube, dzięki czemu użytkownicy mogą je później obejrzeć.
strumienie: Strumień określa treści audio-wideo przekazywane do YouTube. Każda transmisja jest powiązana z jednym strumieniem wideo.
punkty wstawienia reklamy: Punkt wstawienia reklamy to przerwę na reklamę, którą można wstawić do transmisji na żywo.

Przypadki użycia interfejsów API

Poniższa lista sugeruje kilka sposobów wykorzystania interfejsu API w Twojej aplikacji:

Planowanie transmisji i określanie ustawień transmisji. Twoja aplikacja może umożliwić użytkownikom wstępne zdefiniowanie ustawień transmisji, a następnie wybranie ustawień, które mają zostać zastosowane do konkretnej transmisji.
Powiąż strumienie wideo i transmisje.
Zezwól nadawcy na definiowanie informacji o transmisji i jej filmie (za pomocą interfejsu YouTube Data API) w tym samym czasie.
Uprość przechodzenie między stanami transmisji (testing, live itp.) i umożliw użytkownikom wstawianie punktów wstawienia reklamy.

Zanim zaczniesz

Aby uzyskać dostęp do narzędzia Google API Console, poprosić o klucz 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 zarejestrowany przed chwilą projekt.
2. Otwórz stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy YouTube Data API w wersji 3 ma stan WŁ., a jeśli jesteś dostawcą treści w YouTube – interfejs YouTube Content ID API.
Poznaj podstawowe pojęcia związane z formatem danych JSON (JavaScript Object Notation). JSON to popularny, niezależny od języka format danych, który pozwala w prosty sposób przedstawiać dowolne struktury danych w formie tekstowej. Więcej informacji znajdziesz na stronie json.org.

Autoryzacja żądań do interfejsu API

Jak wspomnieliśmy powyżej, interfejs Live Streaming API wykorzystuje funkcje, które technicznie stanowią część interfejsu YouTube Data API lub YouTube Content ID API. Za pomocą interfejsu Content ID API możesz przesłać 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). Umożliwia on też zgłaszanie roszczeń do filmów i ustawianie zasad dotyczących reklam.

W tej sekcji opisano wymagania dotyczące autoryzacji dla żądań kierowanych do Content ID API. Wymagania te różnią się od wymagań dotyczących autoryzacji innych żądań Live Streaming API.

Dzwonię pod numer Data API: Żądanie do interfejsu API musi być autoryzowane przez konto Google, do którego należy kanał YouTube.
Dzwonię pod numer Content ID API: Żądanie do interfejsu API musi być autoryzowane przez konto Google powiązane z właścicielem treści, który jest właścicielem kanału YouTube transmitującego.

Zasoby i typy zasobów

Zasób to pojedynczy element danych z unikalnym identyfikatorem. W tabeli poniżej opisujemy różne typy zasobów, z których będziesz korzystać podczas korzystania z Live Streaming API. Technicznie rzecz biorąc, wszystkie te zasoby są zdefiniowane jako część YouTube Data API lub YouTube Content ID API. Jednak zasoby liveBroadcast, liveStream i cuepoint są używane tylko do tworzenia wydarzeń na żywo i zarządzania nimi.

Zasoby
`liveBroadcast`	Zawiera informacje o wydarzeniu transmitowanym w YouTube. Zasób `liveBroadcast` jest rozszerzeniem zasobu wideo w YouTube i ustawia metadane filmu, które mają związek z transmisją na żywo, ale nie mają związku z innymi filmami w YouTube. Dlatego zasób `liveBroadcast` odpowiada dokładnie 1 zasobowi wideo w YouTube. Zasób `liveBroadcast` i zasób `video` mają ten sam identyfikator. Po utworzeniu transmisji za pomocą interfejsu Live Streaming API możesz za pomocą YouTube Data API udostępnić dodatkowe metadane filmu.
`liveStream`	Zawiera informacje o strumieniu wideo przesyłanym do YouTube. W strumieniu znajdują się treści, które będą transmitowane użytkownikom YouTube. Po utworzeniu zasób `liveStream` może być powiązany tylko z jednym zasobem `liveBroadcast`. Podobnie zasób `liveBroadcast` można powiązać tylko z jednym zasobem `liveStream`.
`cuepoint`	Wstawia punkt wstawienia w transmisji wideo, który może wywołać przerwę na reklamę. Aby wstawić punkt wstawienia podczas transmisji, użyj metody `liveBroadcasts.cuepoint`.
`video`	Reprezentuje pojedynczy film w YouTube. Jak wspomniano powyżej, zasób `liveBroadcast` jest rozszerzeniem zasobu `video`. Za pomocą interfejsu YouTube Data API możesz zaktualizować metadane filmu, na przykład miejsce nagrania lub regiony, w których transmisja będzie widoczna.
`videoAdvertisingOptions`	Określa ustawienia reklam dla filmu (lub transmisji). YouTube Content ID API służy do ustawiania opcji reklam.
`asset`	Własność intelektualna, np. film, odcinek serialu lub program telewizyjny. W tym przypadku zasób to transmisja wideo. YouTube Content ID API służy do tworzenia zasobów `asset` i zarządzania nimi.
`claim`	Łączy film z zasobem, do którego film pasuje. Tworzysz roszczenie, używając YouTube Content ID API, aby potwierdzić, że jesteś właścicielem transmisji wideo.
`policy`	Definiują reguły określające okoliczności, w jakich Twoje treści mają być dostępne w YouTube lub blokowane. Musisz zastosować zasady do transmitowanego obrazu oraz określić zasadę, którą YouTube będzie stosować wobec przesłanych przez użytkowników filmów pasujących do transmitowanego obrazu.

Obsługiwane operacje

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

Operacje
`list`	Pobiera listę (`GET`) bez lub większej liczby zasobów.
`insert`	Tworzy (`POST`) nowy zasób.
`update`	Modyfikuje (`PUT`) istniejący zasób, aby odzwierciedlał dane zawarte w Twoim żądaniu.
`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. Na przykład po zmianie stanu transmisji na `testing` YouTube zacznie przesyłać obraz do strumienia monitorowania tej transmisji.
`delete`	Usuwa (`DELETE`) określony zasób.

Tabela poniżej 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ą tylko dane publiczne, podczas gdy autoryzowane żądania mogą również pobrać informacje ograniczone do obecnie uwierzytelnionego użytkownika.

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

Częściowe zasoby

Interfejs API umożliwia pobieranie części zasobów, tak aby aplikacje unikały przesyłania, analizowania i przechowywania niepotrzebnych danych, a w rzeczywistości tego wymaga. Takie podejście zapewnia też, że interfejs API efektywniej wykorzystuje zasoby sieci, procesora i pamięci.

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

snippet
cdn
status

Wszystkie te części to obiekty zawierające właściwości zagnieżdżone. Możesz je sobie wyobrazić jako grupy pól metadanych, które serwer API może pobrać (lub nie). W związku z tym parametr part wymaga wyboru komponentów zasobów, których aplikacja faktycznie używa. Ten wymóg służy 2 ważnym celom:

Pozwala to skrócić czas oczekiwania, ponieważ serwer API nie będzie tracić czasu na pobieranie pól metadanych, które nie są używane przez Twoją aplikację.
Ogranicza wykorzystanie przepustowości, ograniczając (czyli eliminując) ilość niepotrzebnych danych, które może pobierać aplikacja.

Z czasem w miarę dodawania kolejnych elementów korzyści będą się zwiększać, ponieważ aplikacja nie będzie żądać nowo wprowadzonych usług, których nie obsługuje.

Porady i sprawdzone metody

Zgłaszanie roszczenia do treści

Jeśli chcesz wyświetlać reklamy w trakcie transmisji, musisz zgłosić prawa do transmisji przed rozpoczęciem wydarzenia. Aby zgłaszać roszczenia do treści, musisz być dostawcą treści YouTube uczestniczącym w programie Content ID.

Procedura zgłaszania roszczenia do transmisji wideo na żywo różni się od zwykłego procesu zgłaszania roszczenia do filmu. Zgłaszając roszczenie do transmisji na żywo, musisz zgłosić roszczenie, zanim film faktycznie zostanie utworzony. Jest to możliwe w interfejsie API, a w dokumencie cyklu transmisji opisano wywołania YouTube Content ID API, które umożliwiają złożenie roszczenia.

Wyświetlanie podglądu i testowanie treści

Po odebraniu przychodzącego strumienia wideo YouTube może rozpocząć transmisję filmu 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 etapu testing tylko wtedy, gdy włączony jest strumień jej monitorowania. Strumień monitorowania nie wyświetla przerw na reklamy.
Transmisja na żywo to strumień widoczny dla odbiorców. Możesz ustawić stan prywatności transmisji na public, private lub unlisted. Transmisja prywatna jest widoczna tylko dla użytkowników, którzy zostali wyraźnie zaproszeni do jej obejrzenia, natomiast transmisja niepubliczna jest widoczna dla każdego, kto ma link, aby ją obejrzeć.

Możesz opóźnić transmisję, aby nie wyświetlała się jednocześnie ze strumieniem monitorowania. Opóźniając transmisję, możesz dokładniej kontrolować czas, w którym wstawiasz punkty wstawienia reklamy.

Pamiętaj jednak, że opóźnianie transmisji utrudnia prowadzącym na żywo kontakt z odbiorcami. Ponadto zwiększa się prawdopodobieństwo, że widzowie poznają najważniejsze informacje na temat wydarzenia ze źródeł innych niż Twoja transmisja. Jeśli na przykład transmitujesz wydarzenie sportowe z 60-sekundowym opóźnieniem, widzowie mogą dowiedzieć się o ważnych momentach z innych źródeł wiadomości dostępnych w czasie rzeczywistym, jeszcze zanim zobaczą je w transmisji.

YouTube zaleca włączenie strumienia monitorowania, aby można było testować treści. Trzeba też zdecydować, czy opóźnić transmisję tylko z uwzględnieniem chęci sterowania momentami wstawienia reklamy, czy też chęci interakcji z odbiorcami czy relacjonować wydarzenie 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ąć jak najszybciej lub o określonej godzinie. Przerwa na reklamę umożliwia YouTube wyświetlanie reklam w trakcie transmisji.

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

Ma on wstępnie zdefiniowany czas trwania, który możesz ustawić za pomocą właściwości durationSecs zasobu cuepoint. Po zakończeniu przerwy na reklamę widzowie wracają do transmisji na żywo.
Gdy nastąpi przerwa na reklamę, reklama wyświetli się w odtwarzaczu tylko u tych użytkowników, którzy oglądają transmisję po wstawieniu punktu wstawienia. Reklama nie wyświetla się, gdy widz odświeży stronę, na której jest odtwarzana transmisja, lub gdy użytkownicy zaczną oglądać transmisję po wstawieniu punktu wstawienia.

Poniżej przedstawiamy sprawdzoną metodę wstawiania przerwy na reklamę podczas transmisji:

Ustaw przesunięcie czasu

Gdy wstawiasz punkt wstawienia, możesz określić, że powinien on być wstawiany od razu lub w konkretnym miejscu transmisji. Dostępne opcje zależą od tego, czy transmisja Twojego filmu jest opóźniona.

Jeśli strumień transmisji nie jest opóźniony, możesz wstawić punkt wstawienia od razu lub użyć właściwości walltimeMs, aby przerwa na reklamę rozpoczęła się o określonej godzinie.
- Aby natychmiast rozpocząć przerwę na reklamę, wywołaj metodę liveBroadcasts.cuepoint. W zasobie w treści żądania ustaw wartość właściwości insertionOffsetTimeMs na 0 lub nie określaj wartości tej właściwości ani nie podawaj wartości właściwości walltimeMs.
  
  Ważne: użytkownicy nie zobaczą treści reklamy od razu. Zanim treść reklamy stanie się widoczna dla użytkowników, może minąć około 30 sekund. W tym czasie Twoja transmisja będzie nadal widoczna dla widzów. Musisz ją obejrzeć, aby dowiedzieć się, kiedy zamiast strumienia z monitora wyświetli się treść reklamy.
- Aby rozpocząć przerwę na reklamę o określonym czasie, wywołaj metodę liveBroadcasts.cuepoint i użyj właściwości walltimeMs, aby określić odpowiedni czas. 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 w sposób opisany powyżej, podać godzinę w sposób opisany powyżej lub określić przesunięcie czasu, by określić, kiedy ma się rozpocząć przerwa na reklamę. Przesunięcie w czasie pozwala określić moment transmisji, w którym widzowie powinni zobaczyć reklamę.

Wartość przesunięcia jest mierzona w milisekundach od początku strumienia monitorowania transmisji. Pamiętaj, że jeśli transmisja ma fazę testowania, strumień monitorowania rozpocznie się, gdy transmisja zmieni się na testing. W przeciwnym razie strumień monitorowania rozpocznie się, gdy transmisja zmieni stan na live.

Podczas wstawiania punktu wstawienia ustaw żądane przesunięcie we właściwości insertionOffsetTimeMs zasobu cuepoint.

Oblicz wartość przesunięcia czasu

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

Możliwe wartości czasu przesunięcia można obliczyć w następujący sposób:

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

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

Transmisja ma 5-minutową fazę testowania.
Transmisja transmisji jest opóźniona o 60 sekund po odtworzeniu strumienia monitorowania.
Nadawca wstawia punkt wstawienia reklamy 4 minuty po zmianie stanu transmisji na „live”. (3 minuty od momentu, gdy strumień stanie się widoczny).

W tym przypadku możliwy zakres czasów przesunięcia wynosi [(485,000), (535,000)].

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

elapsed_time=540000 – strumień monitorowania działał przez dziewięć 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, w którym nie można prawidłowo wstawić punktu wstawienia.

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

Poniższe wytyczne wyjaśniają, jak rozwiązywać konkretne problemy. W dokumentacji błędów znajdziesz listę błędów, które mogą zostać zwrócone przez każdą metodę interfejsu API.

Gdy transmisja zmieni się z jednego stanu na inny, może ona tymczasowo otrzymać inny stan, gdy YouTube wykona odpowiednie działania. Jeśli na przykład wyślesz prośbę liveBroadcasts.transition o zmianę stanu transmisji z ready na testing, YouTube ustawi stan transmisji na testStarting, a następnie wykona działania związane ze zmianą stanu. Po wykonaniu wszystkich tych czynności YouTube zmieni stan transmisji na testing, wskazując, że migracja została zakończona.

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

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