YouTube automatycznie generuje zestaw raportów o przychodach z reklam zarządzanych przez system dla właścicieli treści, którzy mają dostęp do odpowiadających im raportów w Studiu twórców. Raporty te umożliwiają automatyczny dostęp do danych, które są też dostępne w ręcznie pobieranych raportach, dostępnych w sekcji Raporty w YouTube Studio.
Uwaga: interfejs API zapewnia dostęp do innego zestawu raportów niż Studio twórców, ale zawierają one podobne dane. Raporty w interfejsie API mogą zawierać inne pola i różnić się od nazw pól w raportach Studia twórców.
YouTube automatycznie generuje raporty zarządzane przez system, więc ich proces pobierania wygląda inaczej niż w przypadku raportów zbiorczych w Statystykach YouTube, które są dostępne za pomocą interfejsu API.
Pobieram raporty
Poniżej opisano, jak pobierać raporty zarządzane przez system za pomocą interfejsu API.
Krok 1. Pobierz dane logowania
Wszystkie żądania do interfejsu YouTube Reporting API muszą być autoryzowane. Przewodnik po autoryzacji zawiera instrukcje pobierania tokenów autoryzacji za pomocą protokołu OAuth 2.0.
Żądania do interfejsu YouTube Reporting API używają tych zakresów autoryzacji:
| Zakresy | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics.readonly | Wyświetlaj raporty Statystyk YouTube dotyczące treści w YouTube. Zakres ten zapewnia dostęp do danych o aktywności użytkowników, takich jak liczba wyświetleń i oceny. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Wyświetlanie raportów finansowych Statystyk YouTube dotyczących treści w YouTube Zakres ten umożliwia dostęp do danych o aktywności użytkowników oraz szacunkowych danych o przychodach i skuteczności reklam. |
Krok 2. Pobierz identyfikator zadania dla wybranego raportu
Wywołaj metodę jobs.list, aby pobrać listę zadań zarządzanych przez system. Ustaw wartość parametru includeSystemManaged na true.
Właściwość reportTypeId każdego zwracanego zasobu Job wskazuje typ raportu zarządzanego przez system powiązanego z tym zadaniem. Twoja aplikacja potrzebuje wartości właściwości id z tego samego zasobu w kolejnym kroku.
Dokument Raporty zawiera listę dostępnych raportów i ich identyfikatory, a także pola, które one zawierają. Aby uzyskać listę obsługiwanych typów raportów, możesz też użyć metody reportTypes.list.
Krok 3. Pobierz adres URL pobierania raportu
Wywołaj metodę jobs.reports.list, aby pobrać listę raportów utworzonych dla tego zadania. W żądaniu ustaw parametr jobId na identyfikator zadania raportu, który chcesz pobrać.
Listę raportów możesz filtrować przy użyciu dowolnych lub wszystkich następujących parametrów:
-
Używaj parametru
createdAfter, aby wskazać, że interfejs API powinien zwracać tylko raporty utworzone po określonym czasie. Ten parametr pozwala zagwarantować, że interfejs API zwróci tylko te raporty, których jeszcze nie przetworzono. -
Użyj parametru
startTimeBefore, aby wskazać, że odpowiedź interfejsu API powinna zawierać raporty tylko wtedy, gdy najwcześniej dane w raporcie są określone przed podaną datą. ParametrcreatedAfterodnosi się do czasu utworzenia raportu, a data dotyczy danych w raporcie. -
Użyj parametru
startTimeAtOrAfter, aby wskazać, że odpowiedź interfejsu API powinna zawierać raporty tylko wtedy, gdy najwcześniejsze dane w raporcie przypadają w określonym dniu lub później. Podobnie jak parametrstartTimeBefore, wartość parametru odpowiada danym w raporcie, a nie dacie utworzenia raportu.
Odpowiedź interfejsu API zawiera listę Report zasobów dla tego zadania. Każdy zasób odnosi się do raportu zawierającego dane z unikalnego okresu.
- Właściwości
startTimeiendTimezasobu określają okres objęty danymi w raporcie. - Właściwość
downloadUrlzasobu określa adres URL, z którego można pobrać raport. - Właściwość
createTimezasobu określa datę i godzinę wygenerowania raportu. Aplikacja powinna zapisać tę wartość i używać jej do określania, czy wcześniej pobrane raporty uległy zmianie.
Krok 4. Pobierz raport
Aby pobrać raport, wyślij żądanie HTTP GET na adres downloadUrl uzyskany w kroku 4.
Raporty z przetwarzania
Sprawdzone metody
Aplikacje, które używają interfejsu API do raportowania YouTube, zawsze powinni stosować te metody:
-
Aby określić kolejność kolumn raportu, użyj wiersza nagłówka raportu. Na przykład nie zakładaj, że wyświetlenia będą pierwszymi danymi zwróconymi w raporcie, ponieważ są to pierwsze dane wymienione w jego opisie. Aby określić, która kolumna zawiera te dane, skorzystaj z wiersza nagłówka raportu.
-
Zapisuj pobrane raporty, by uniknąć powtórnego przetwarzania tego samego raportu. Oto kilka sposobów wykonania tej czynności.
-
Wywołując metodę
reports.list, używaj parametru createAfter, aby pobierać tylko raporty utworzone po określonej dacie. (Podczas pierwszego pobierania raportów pomiń parametrcreatedAfter).Za każdym razem, gdy pobierasz i przetwarzasz raporty, zapisuj sygnaturę czasową odpowiadającą data i godzina utworzenia najnowszych raportów. Następnie zaktualizuj wartość parametru
createdAfterprzy każdym kolejnym wywołaniu metodyreports.list, aby mieć pewność, że przy każdym wywołaniu interfejsu API pobierasz tylko nowe raporty, w tym nowe raporty z uzupełnionymi danymi.Ze względów bezpieczeństwa przed pobraniem raportu upewnij się, że w bazie danych nie ma już identyfikatora raportu.
-
Zapisz identyfikator każdego raportu, który został pobrany i przetworzony. Możesz też przechowywać dodatkowe informacje, takie jak data i godzina wygenerowania każdego raportu lub
startTimeiendTime, które wskazują razem okres, z którego pochodzą dane. Raporty, które pobierają dane zbiorcze z YouTube Analytics, będą prawdopodobnie zawierać wiele raportów, ponieważ każdy raport zawiera dane z 24 godzin. Zadania zarządzane przez system, które obejmują dłuższe okresy, mają mniej raportów.Identyfikator raportu pozwala zidentyfikować raporty, które nadal musisz pobrać i zaimportować. Jeśli jednak 2 nowe raporty mają te same wartości właściwości
startTimeiendTime, importuj raport tylko z nowszą wartościącreateTime.
-
Cechy raportu
Raporty interfejsu API mają wersje .csv (wartości rozdzielone przecinkami), które mają następujące cechy:
-
Każdy raport zawiera dane z unikalnego okresu trwającego od 00:00 czasu pacyficznego od daty rozpoczęcia raportu do godziny 23:59 czasu pacyficznego w dniu zakończenia raportu.
-
Dane w raporcie nie są sortowane.