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:
- Otwórz API Console i wybierz zarejestrowany przed chwilą projekt.
- 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
lubunlisted
. 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
zasobucuepoint
. 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ściinsertionOffsetTimeMs
na0
lub nie określaj wartości tej właściwości ani nie podawaj wartości właściwościwalltimeMs
.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ściwalltimeMs
, aby określić odpowiedni czas. Wartość właściwości jest liczbą całkowitą, która reprezentuje sygnaturę czasową epoki.
-
Aby natychmiast rozpocząć przerwę na reklamę, wywołaj metodę
-
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 nalive
.Podczas wstawiania punktu wstawienia ustaw żądane przesunięcie we właściwości
insertionOffsetTimeMs
zasobucuepoint
.
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 metodyliveBroadcasts.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 zready
natesting
, YouTube ustawi stan transmisji natestStarting
, a następnie wykona działania związane ze zmianą stanu. Po wykonaniu wszystkich tych czynności YouTube zmieni stan transmisji natesting
, wskazując, że migracja została zakończona.Jeśli transmisja utknie i będzie mieć stan
testStarting
lubliveStarting
, 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ścistatus.streamStatus
strumienia powiązanego z Twoją transmisją wynosiactive
.