YouTube Reporting API - Get Bulk Data Reports

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 odpowiednich raportów w Studio twórców. Raporty te zapewniają programowy dostęp do danych, które są też dostępne w raportach do pobrania ręcznie w menu Raporty w Studiu twórców YouTube.

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

YouTube automatycznie generuje raporty zarządzane przez system, dlatego proces pobierania tych raportów różni się od procesu pobierania raportów z dużą ilością danych Statystyk YouTube dostępnych za pomocą interfejsu API.

Pobieranie raportów

Poniżej znajdziesz instrukcje pobierania raportów zarządzanych przez system za pomocą interfejsu API.

Krok 1. Pobierz dane logowania autoryzacji

Wszystkie żądania do interfejsu YouTube Reporting API muszą być autoryzowane. W przewodniku po autoryzacji znajdziesz informacje o tym, jak używać protokołu OAuth 2.0 do pobierania tokenów autoryzacji.

Żądania do interfejsu YouTube Reporting API używają tych zakresów autoryzacji:

Krok 2. Pobierz identyfikator zadania dla wybranego raportu

Aby pobrać listę zadań zarządzanych przez system, wywołaj metodę jobs.list. Ustaw parametr includeSystemManaged na true.

Właściwość reportTypeId w każdym zwróconym zasobie Job identyfikuje typ raportu zarządzanego przez system, który jest powiązany z tym zadaniem. W następnym kroku aplikacja będzie potrzebować wartości właściwości id z tego samego zasobu.

Dokument Raporty zawiera listę dostępnych raportów, ich identyfikatory typu raportu i pola, które zawierają. Możesz też użyć metody reportTypes.list, aby pobrać listę obsługiwanych typów raportów.

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 z tych parametrów:

• Użyj parametru createdAfter, aby wskazać, że interfejs API ma zwracać tylko raporty utworzone po określonym czasie. Ten parametr może służyć do zapewnienia, że interfejs API zwraca tylko raporty, które nie zostały jeszcze przez Ciebie przetworzone.

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

• Użyj parametru startTimeAtOrAfter, aby wskazać, że odpowiedź interfejsu API powinna zawierać tylko raporty, w których najwcześniejsze dane pochodzą z określonej daty lub są późniejsze. Podobnie jak parametr 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 odnosi się do raportu, który zawiera dane z unikalnego okresu.

• Właściwości startTime i endTime zasobu określają okres, którego dotyczą dane w raporcie.
• Właściwość downloadUrl zasobu określa adres URL, z którego można pobrać raport.
• Właściwość createTime zasobu określa datę i godzinę wygenerowania raportu. Aplikacja powinna przechowywać 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 do adresu URL downloadUrl uzyskanego w kroku 4.

Raporty przetwarzania

Sprawdzone metody

Aplikacje korzystające z interfejsu YouTube Reporting API powinny zawsze postępować zgodnie z tymi zasadami:

• Aby określić kolejność kolumn w raporcie, użyj wiersza nagłówka raportu. Nie zakładaj na przykład, że wyświetlenia będą pierwszymi danymi zwróconymi w raporcie tylko dlatego, że są pierwszymi danymi wymienionymi w jego opisie. Zamiast tego użyj wiersza nagłówka raportu, aby określić, która kolumna zawiera te dane.

• Zapisuj informacje o pobranych raportach, aby uniknąć wielokrotnego przetwarzania tego samego raportu. Poniżej znajdziesz kilka sposobów, jak to zrobić.

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

    Za każdym razem, gdy pobierzesz i przetworzysz raporty, zapisz sygnaturę czasową odpowiadającą dacie i godzinie utworzenia najnowszego z nich. Następnie aktualizuj wartość parametru createdAfter w każdym kolejnym wywołaniu metody reports.list, aby za każdym razem, gdy wywołujesz interfejs API, pobierać tylko nowe raporty, w tym nowe raporty z danymi uzupełnionymi wstecznie.

    Aby się zabezpieczyć, przed pobraniem raportu sprawdź, czy jego identyfikator nie jest już wymieniony w Twojej bazie danych.

  • Zapisz identyfikator każdego pobranego i przetworzonego raportu. Możesz też przechowywać dodatkowe informacje, takie jak data i godzina wygenerowania każdego raportu lub jego startTime i endTime, które razem określają okres, za który raport zawiera dane. W przypadku raportów, które pobierają dane zbiorcze ze Statystyk YouTube, każde zadanie będzie prawdopodobnie zawierać wiele raportów, ponieważ każdy z nich zawiera dane z 24-godzinnego okresu. W przypadku zadań zarządzanych przez system, które obejmują dłuższe okresy, będzie dostępnych mniej raportów.

    Użyj identyfikatora raportu, aby zidentyfikować raporty, które musisz jeszcze pobrać i zaimportować. Jeśli jednak 2 nowe raporty mają te same wartości właściwości startTime i endTime, zaimportuj tylko raport z nowszą wartością createTime.

Charakterystyka raportu

Raporty interfejsu API to pliki .csv (z wartościami rozdzielonymi przecinkami) z wersjami, które mają te cechy:

• Każdy raport zawiera dane z unikalnego okresu, który trwa 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ą posortowane.