YouTube Reporting API - System-Managed Reports

YouTube automatycznie generuje zarządzane przez system raporty o przychodach z reklam dla właścicieli treści, którzy mają dostęp do odpowiednich raportów w Studiu twórców. Raporty te mają zapewniać programowy dostęp do danych, które są też dostępne w postaci raportów do pobrania ręcznie dostępnych w menu Raporty w Studiu twórców YouTube.

Uwaga: interfejs API daje dostęp do innego zestawu raportów niż Studio twórców, chociaż zawierają one podobne dane. Raporty interfejsu API mogą zawierać inne pola oraz używać innych nazw pól niż raporty w Studiu twórców.

Ponieważ YouTube automatycznie generuje raporty zarządzane przez system, proces pobierania tych raportów różni się od procesu pobierania zbiorczych raportów danych w Statystykach YouTube dostępnych za pomocą interfejsu API.

Pobieranie raportów

Poniżej opisujemy, 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 wyjaśnia, jak używać protokołu OAuth 2.0 do pobierania tokenów autoryzacji.

Żądania do interfejsu YouTube Reporting API korzystają z tych zakresów autoryzacji:

Zakresy
https://www.googleapis.com/auth/yt-analytics.readonly Wyświetlanie raportów Statystyk YouTube dotyczących treści w YouTube. Ten zakres zapewnia dostęp do danych o aktywności użytkowników, takich jak liczba wyświetleń i ocen.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Wyświetlanie raportów finansowych Statystyk YouTube dotyczących treści w YouTube. Ten zakres zapewnia dostęp do danych o aktywności użytkowników oraz szacunkowych danych o przychodach i skuteczności reklam.

Krok 2. Pobierz identyfikator zadania 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 w każdym zwróconym zasobie Job określa typ raportu zarządzanego przez system powiązanego z danym zadaniem. Twoja aplikacja wymaga wartości właściwości id z tego samego zasobu w następnym kroku.

Dokument Raporty zawiera listę dostępnych raportów, ich identyfikatorów typów raportów oraz zawartych w nich pól. Aby pobrać 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 zadania. W żądaniu ustaw parametr jobId na identyfikator zadania raportu, który chcesz pobrać.

Listę raportów możesz filtrować za pomocą dowolnych lub wszystkich spośród tych parametrów:

  • Użyj parametru createdAfter, aby wskazać, że interfejs API powinien zwracać tylko raporty utworzone po określonym czasie. Dzięki temu parametrowi API zwraca tylko te raporty, które nie zostały jeszcze przetworzone.

  • Użyj parametru startTimeBefore, aby wskazać, że odpowiedź interfejsu API powinna zawierać raporty tylko wtedy, gdy najwcześniejsze dane w raporcie pochodzą sprzed określonej daty. Parametr createdAfter odnosi się do czasu utworzenia raportu, ale ta data odnosi się do zawartych w nim danych.

  • Użyj parametru startTimeAtOrAfter, aby wskazać, że odpowiedź interfejsu API powinna zawierać raporty tylko wtedy, gdy najwcześniejsze dane w raporcie pochodzą z określonej daty lub później. Podobnie jak w przypadku parametru startTimeBefore, wartość tego parametru odpowiada danym w raporcie, a nie czasowi jego utworzenia.

Odpowiedź interfejsu API zawiera listę zasobów Report dla tego zadania. Każdy zasób oznacza raport zawierający dane z unikalnego okresu.

  • Właściwości startTime i endTime zasobu określają okres, którego dotyczą dane raportu.
  • Właściwość downloadUrl zasobu określa adres URL, z którego można pobierać raport.

  • Właściwość createTime zasobu określa datę i godzinę wygenerowania raportu. Aplikacja powinna zapisać tę wartość i używać jej do określania, czy wcześniej pobrane raporty nie uległy zmianie.

Krok 4. Pobierz raport

Aby pobrać raport, wyślij żądanie HTTP GET do metody downloadUrl uzyskane w kroku 4.

Raporty z przetwarzania

Sprawdzone metody

W aplikacjach korzystających z interfejsu YouTube Reporting API należy zawsze przestrzegać tych praktyk:

  • Kolejność kolumn raportu możesz określać za pomocą wiersza nagłówka raportu. Nie zakładaj np., że wyświetlenia będą pierwszym rodzajem danych w raporcie tylko dlatego, że są to pierwsze dane wymienione w jego opisie. Aby określić, która kolumna zawiera te dane, użyj wiersza nagłówka raportu.

  • Zapisuj pobrane raporty, by uniknąć wielokrotnego przetwarzania tego samego raportu. Poniższa lista podpowiada, jak to zrobić.

    • W przypadku wywoływania metody reports.list użyj parametru createdAfter, aby pobrać tylko raporty utworzone po określonej dacie. (pomiń parametr createdAfter przy pierwszym pobieraniu raportów).

      Za każdym razem, gdy pobierasz i przetwarzasz raporty, zapisz sygnaturę czasową odpowiadającą datie i godziny utworzenia najnowszego raportu. Następnie zaktualizuj wartość parametru createdAfter przy każdym kolejnym wywołaniu metody reports.list, aby mieć pewność, że za każdym razem, gdy wywołujesz interfejs API, będą pobierane tylko nowe raporty, w tym nowe raporty z uzupełnionymi danymi.

      Ze względów bezpieczeństwa przed pobraniem raportu sprawdź, czy jego identyfikator nie znajduje się już w Twojej bazie danych.

    • Zachowaj identyfikator każdego pobranego i przetworzonego raportu. Możesz też przechowywać dodatkowe informacje, takie jak data i godzina wygenerowania każdego raportu lub startTime i endTime raportu, które razem określają okres, z którego raport zawiera dane. W przypadku raportów pobierających dane zbiorcze do Statystyk YouTube każde zadanie będzie prawdopodobnie zawierać wiele raportów, ponieważ każdy z nich zawiera dane z okresu 24 godzin. Zadania zarządzane przez system, które obejmują dłuższe okresy, będą miały mniej raportów.

      Na podstawie identyfikatora raportu możesz sprawdzić, które raporty musisz pobrać i zaimportować. Jeśli jednak 2 nowe raporty mają takie same wartości właściwości startTime i endTime, zaimportuj tylko ten z nowszą wartością createTime.

Charakterystyka raportu

Raporty interfejsu API mają wersje .csv (wartości rozdzielone przecinkami), które mają te cechy:

  • Każdy raport zawiera dane z unikalnego okresu, trwającego od godziny 00:00 czasu pacyficznego w dniu rozpoczęcia raportu do godziny 23:59 czasu pacyficznego w dniu zakończenia raportu.

  • Dane w raporcie nie są sortowane.