Ważne: żądania API do tej metody wymagają teraz dostępu do zakresu https://www.googleapis.com/auth/youtube.readonly
.
Ta metoda umożliwia pobieranie wielu różnych raportów Analytics. Każde żądanie używa parametrów zapytania do określenia identyfikatora kanału lub właściciela treści, daty rozpoczęcia, daty zakończenia i co najmniej 1 rodzaju danych. Możesz też podać dodatkowe parametry zapytania, takie jak wymiary, filtry i instrukcje sortowania.
- Dane to poszczególne pomiary aktywności użytkowników, takie jak wyświetlenia filmu czy oceny (polubienia i głosy na nie).
- Wymiary to typowe kryteria używane do agregowania danych, np. data, w której wystąpiła aktywność użytkownika, lub kraj, w którym znajdowali się użytkownicy. W raporcie każdy wiersz danych ma unikalną kombinację wartości wymiarów.
- Filtry to wartości wymiarów, które określają, jakie dane mają zostać pobrane. Możesz na przykład pobrać dane dotyczące konkretnego kraju, konkretnego filmu lub grupy filmów.
Uwaga: raporty właściciela treści są dostępne tylko dla partnerów YouTube, którzy uczestniczą w programie partnerskim YouTube.
Częste przypadki użycia
Żądanie
Żądanie HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
Wszystkie żądania do interfejsu YouTube Analytics 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 Analytics 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 do szacunkowych danych o przychodach i skuteczności reklam. |
https://www.googleapis.com/auth/youtube | Zarządzanie kontem YouTube. Właściciele kanałów używają tego zakresu w interfejsie YouTube Analytics API do zarządzania grupami Statystyk YouTube i elementami grup. |
https://www.googleapis.com/auth/youtubepartner | Przeglądaj zasoby YouTube oraz powiązane treści i zarządzaj nimi w serwisie YouTube. W interfejsie YouTube Analytics API właściciele treści używają tego zakresu do zarządzania grupami Statystyk YouTube i elementami grup. |
Parametry
W tabelach poniżej znajdziesz wymagane i opcjonalne parametry zapytań w przypadku żądań do interfejsu API służących do pobierania raportów z zapytań. Standardowe parametry zapytania wymienione w tabeli są też opcjonalne i obsługiwane przez wiele interfejsów API Google.
Parametry | ||
---|---|---|
Wymagane parametry | ||
endDate |
string Data zakończenia pobierania danych YouTube Analytics. Wartość powinna mieć format YYYY-MM-DD .Odpowiedź interfejsu API zawiera dane do ostatniego dnia, dla którego w momencie zapytania dostępne są wszystkie rodzaje danych w zapytaniu. Jeśli na przykład w żądaniu podano datę zakończenia 5 lipca 2017 r., a wartości wszystkich żądanych danych są dostępne tylko do 3 lipca 2017 r., będzie to ostatnia data, dla której dane zostaną uwzględnione w odpowiedzi. (Dotyczy to nawet sytuacji, gdy dane niektórych żądanych rodzajów są dostępne za 4 lipca 2017 r.). Uwaga: w wersji 1 interfejsu API ten parametr miał nazwę end-date |
|
ids |
string Określa kanał w YouTube lub właściciela treści, dla którego pobierasz YouTube Analytics dane.
|
|
metrics |
string Lista rozdzielonych przecinkami YouTube Analytics danych, np. views lub likes,dislikes . Listę raportów, które możesz pobrać, oraz dane dostępne w każdym z nich znajdziesz w dokumentacji dotyczącej raportów o kanałach i raportów właściciela treści. (Dokument Dane zawiera definicje wszystkich danych).
|
|
startDate |
string Data rozpoczęcia pobierania danych YouTube Analytics. Wartość powinna mieć format YYYY-MM-DD .Uwaga: w wersji 1 interfejsu API ten parametr miał nazwę
start-date |
|
Parametry opcjonalne | ||
currency |
string Waluta, w której interfejs API będzie podawać te szacunkowe dane o przychodach: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. Wartości zwracane przez interfejs API w przypadku tych rodzajów danych to szacunki obliczane na podstawie kursów wymiany walut, które zmieniają się codziennie. Jeśli nie zażądasz żadnych z tych danych, parametr zostanie zignorowany. Wartość parametru to trzyliterowy kod waluty w standardzie ISO 4217 z listy walut poniżej. Jeśli podano nieobsługiwaną walutę, interfejs API zwraca błąd. Wartością domyślną jest USD . |
|
dimensions |
string Lista rozdzielonych przecinkami wymiarów Statystyk YouTube, np. video lub ageGroup,gender . Listę raportów, które możesz pobrać, oraz wymiary używane w tych raportach znajdziesz w dokumentacji raportów dotyczących kanału lub raportów dotyczących właściciela treści. (Dokument Wymiary zawiera definicje wszystkich wymiarów).
|
|
filters |
string Lista filtrów, które mają być stosowane podczas pobierania danych YouTube Analytics. Dokumentacja raportów o kanałach i raportów właściciela treści zawiera listę wymiarów, których można używać do filtrowania poszczególnych raportów, a dokument Wymiary zawiera definicje tych wymiarów. Jeśli w żądaniu używasz wielu filtrów, połącz je średnikiem ( ; ). Zwrócona tabela wyników będzie spełniać oba filtry. Na przykład wartość parametru filters równa video==dMH0bHeiRNg;country==IT ogranicza zestaw wyników do danych dotyczących danego filmu we Włoszech.Określanie wielu wartości filtra Interfejs API umożliwia określanie wielu wartości filtrów video , playlist i channel . Aby to zrobić, podaj rozdzieloną listę identyfikatorów filmów, playlist lub kanałów, dla których odpowiedź interfejsu API ma być filtrowana. Na przykład wartość parametru filters równa video==pd1FJh59zxQ,Zhawgd0REhA;country==IT ogranicza zestaw wyników do danych dotyczących podanych filmów we Włoszech. Wartość parametru może zawierać maksymalnie 500 identyfikatorów.Jeśli w przypadku tego samego filtra podajesz wiele wartości, możesz też dodać ten filtr do listy wymiarów określonych w żądaniu. Dzieje się tak nawet wtedy, gdy filtr nie jest wymieniony jako obsługiwany wymiar w przypadku danego raportu. Jeśli dodasz filtr do listy wymiarów, interfejs API będzie też używać wartości filtra do grupowania wyników. Załóżmy na przykład, że pobierasz raport o źródłach wizyt na kanale, który zawiera zbiorcze statystyki oglądania na podstawie sposobu, w jaki widzowie trafili na treści wideo na kanale. Załóżmy też, że parametr filters w Twoim żądaniu identyfikuje listę 10 filmów, dla których mają zostać zwrócone dane.
|
|
includeHistoricalChannelData |
boolean Uwaga: ten parametr dotyczy tylko raportów właściciela treści. Określa, czy odpowiedź interfejsu API ma zawierać dane o czasie oglądania i wyświetleniach kanałów z okresu przed powiązaniem kanałów z właścicielem treści. Domyślna wartość parametru to false , co oznacza, że odpowiedź interfejsu API zawiera tylko dane o czasie oglądania i wyświetleniach z okresu, w którym kanały były powiązane z właścicielem treści.Pamiętaj, że różne kanały mogły zostać połączone z właścicielem treści w różnych terminach. Jeśli żądanie API pobiera dane z wielu kanałów, a wartość parametru to false , odpowiedź API zawiera dane na podstawie daty połączenia poszczególnych kanałów. Jeśli wartość parametru to true , odpowiedź interfejsu API zawiera dane pasujące do dat określonych w żądaniu do interfejsu API.Uwaga: w wersji 1 interfejsu API ten parametr miał nazwę include-historical-channel-data |
|
maxResults |
integer Maksymalna liczba wierszy do uwzględnienia w odpowiedzi. Uwaga: w wersji 1 interfejsu API ten parametr miał nazwę max-results |
|
sort |
string Lista rozdzielonych przecinkami wymiarów lub danych, które określają kolejność sortowania danych Statystyk YouTube. Domyślnie kolejność sortowania jest rosnąca. Prefiks - powoduje sortowanie w kolejności malejącej.
|
|
startIndex |
integer Indeks pierwszej jednostki do pobrania (liczony od 1). (Wartość domyślna to 1 ). Używaj tego parametru jako mechanizmu stronicowania wraz z parametrem max-results .Uwaga: w wersji 1 interfejsu API ten parametr miał nazwę start-index |
|
Parametry standardowe | ||
access_token |
OAuth 2.0 token dla bieżącego użytkownika.
|
|
alt |
Ten parametr nie jest obsługiwany w wersji 2 interfejsu API, która obsługuje tylko odpowiedzi JSON. Format danych odpowiedzi interfejsu API.
|
|
callback |
Funkcja wywołania zwrotnego.
|
|
prettyPrint |
Zwraca odpowiedź z wcięciami i podziałami wierszy.
|
|
quotaUser |
Ten parametr był obsługiwany w wersji 1 interfejsu API, która została wycofana. Ten parametr nie jest obsługiwany w wersji 2 interfejsu API. | |
userIp |
Ten parametr był obsługiwany w wersji 1 interfejsu API, która została wycofana. Ten parametr nie jest obsługiwany w wersji 2 interfejsu API. |
Treść żądania
Podczas wywoływania tej metody nie wysyłaj treści żądania.
Odpowiedź
Zgodnie z definicją parametru alt
interfejs API może zwracać odpowiedzi w formacie JSON lub CSV. Informacje o treści odpowiedzi dla każdego typu znajdziesz poniżej:
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
Właściwości | |
---|---|
kind |
string Ta wartość określa typ danych zawartych w odpowiedzi interfejsu API. W przypadku metody query wartość właściwości kind będzie wynosić youtubeAnalytics#resultTable . Jeśli jednak interfejs API doda obsługę innych metod, odpowiedzi interfejsu API dla tych metod mogą zawierać inne wartości właściwości kind . |
columnHeaders[] |
list Ta wartość określa informacje o danych zwracanych w polach rows . Każdy element na liście columnHeaders identyfikuje pole zwrócone w wartości rows , która zawiera listę danych oddzielonych przecinkami.Lista columnHeaders zaczyna się od wymiarów określonych w żądaniu interfejsu API, a następnie zawiera dane określone w żądaniu interfejsu API. Kolejność wymiarów i danych jest zgodna z kolejnością w żądaniu do interfejsu API.Jeśli na przykład żądanie do interfejsu API zawiera parametry dimensions=ageGroup,gender&metrics=viewerPercentage , odpowiedź interfejsu API zwraca kolumny w tej kolejności: ageGroup ,gender ,viewerPercentage . |
columnHeaders[].name |
string Nazwa wymiaru lub rodzaju danych. |
columnHeaders[].columnType |
string Typ kolumny ( DIMENSION lub METRIC ). |
columnHeaders[].dataType |
string Typ danych w kolumnie ( STRING , INTEGER , FLOAT itp.). |
rows[] |
list Lista zawiera wszystkie wiersze tabeli wyników. Każdy element na liście to tablica zawierająca dane rozdzielone przecinkami, które odpowiadają jednemu wierszowi danych. Kolejność pól danych rozdzielonych przecinkami będzie zgodna z kolejnością kolumn wymienionych w polu columnHeaders .Jeśli dla danego zapytania nie są dostępne żadne dane, element rows zostanie pominięty w odpowiedzi.Odpowiedź na zapytanie z wymiarem day nie będzie zawierać wierszy z danymi z najnowszych dni. |
day, views, likes, ... "2012-01-01", 12.0, 3, ... "2012-01-02", 16.0, 2, ... "2012-01-03", 18.0, 8, ... ...
Przykłady
Uwaga: poniższe przykłady kodu mogą nie odzwierciedlać wszystkich obsługiwanych języków programowania. Listę obsługiwanych języków znajdziesz w dokumentacji bibliotek klienta.
JavaScript
W tym przykładzie wywoływany jest interfejs YouTube Analytics API w celu pobrania dziennych wyświetleń i innych danych dotyczących kanału autoryzującego użytkownika w roku kalendarzowym 2017. W przykładzie używana jest biblioteka klienta JavaScript interfejsów API Google.Zanim po raz pierwszy uruchomisz ten przykład lokalnie, musisz skonfigurować dane logowania do autoryzacji w projekcie:
- Utwórz projekt w Konsoli interfejsów API Google lub wybierz istniejący projekt.
- Włącz w projekcie interfejs YouTube Analytics API.
- U góry strony Dane logowania wybierz kartę Ekran zgody OAuth. Wybierz adres e-mail, wpisz nazwę produktu (jeśli nie jest jeszcze ustawiona) i kliknij przycisk Zapisz.
- Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
- Wybierz typ aplikacji Aplikacja internetowa.
- W polu Autoryzowane źródła JavaScript wpisz adres URL, z którego będziesz udostępniać przykładowy kod. Możesz na przykład użyć
http://localhost:8000
lubhttp://yourserver.example.com
. Pole Autoryzowane identyfikatory URI przekierowania możesz pozostawić puste. - Aby zakończyć tworzenie danych logowania, kliknij przycisk Utwórz.
- Zanim zamkniesz okno, skopiuj identyfikator klienta, który musisz umieścić w przykładowym kodzie.
Następnie zapisz próbkę w pliku lokalnym. W przykładzie znajdź ten wiersz i zastąp YOUR_CLIENT_ID identyfikatorem klienta uzyskanym podczas konfigurowania danych logowania do autoryzacji.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
Teraz możesz przetestować próbkę:
- Otwórz plik lokalny w przeglądarce i otwórz w niej konsolę debugowania. Powinna wyświetlić się strona z 2 przyciskami.
- Kliknij przycisk authorize and load (autoryzuj i wczytaj), aby uruchomić proces autoryzacji użytkownika. Jeśli autoryzujesz aplikację do pobierania danych o kanale, w konsoli w przeglądarce powinny się wyświetlić te wiersze:
Sign-in successful GAPI client loaded for API
- Jeśli zamiast powyższych wierszy widzisz komunikat o błędzie, sprawdź, czy skrypt jest wczytywany z autoryzowanego identyfikatora URI przekierowania skonfigurowanego w projekcie oraz czy w kodzie znajduje się identyfikator klienta zgodnie z opisem powyżej.
- Aby wywołać interfejs API, kliknij przycisk execute (wykonaj). W konsoli w przeglądarce powinien pojawić się obiekt
response
. W tym obiekcie właściwośćresult
jest mapowana na obiekt zawierający dane interfejsu API.
<script src="https://apis.google.com/js/api.js"></script> <script> function authenticate() { return gapi.auth2.getAuthInstance() .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"}) .then(function() { console.log("Sign-in successful"); }, function(err) { console.error("Error signing in", err); }); } function loadClient() { return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2") .then(function() { console.log("GAPI client loaded for API"); }, function(err) { console.error("Error loading GAPI client for API", err); }); } // Make sure the client is loaded and sign-in is complete before calling this method. function execute() { return gapi.client.youtubeAnalytics.reports.query({ "ids": "channel==MINE", "startDate": "2017-01-01", "endDate": "2017-12-31", "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained", "dimensions": "day", "sort": "day" }) .then(function(response) { // Handle the results here (response.result has the parsed body). console.log("Response", response); }, function(err) { console.error("Execute error", err); }); } gapi.load("client:auth2", function() { gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'}); }); </script> <button onclick="authenticate().then(loadClient)">authorize and load</button> <button onclick="execute()">execute</button>
Python
W tym przykładzie wywoływany jest interfejs YouTube Analytics API w celu pobrania dziennych wyświetleń i innych danych dotyczących kanału autoryzującego użytkownika w roku kalendarzowym 2017. W przykładzie użyto biblioteki klienta interfejsów API Google w języku Python.Zanim po raz pierwszy uruchomisz ten przykład lokalnie, musisz skonfigurować dane logowania do autoryzacji w projekcie:
- Utwórz projekt w Konsoli interfejsów API Google lub wybierz istniejący projekt.
- Włącz w projekcie interfejs YouTube Analytics API.
- U góry strony Dane logowania wybierz kartę Ekran zgody OAuth. Wybierz adres e-mail, wpisz nazwę produktu (jeśli nie jest jeszcze ustawiona) i kliknij przycisk Zapisz.
- Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
- Wybierz typ aplikacji Inne, wpisz nazwę „YouTube Analytics API Quickstart” i kliknij przycisk Utwórz.
- Aby zamknąć okno, kliknij OK.
- Kliknij przycisk (Pobierz JSON) po prawej stronie identyfikatora klienta.
- Przenieś pobrany plik do katalogu roboczego.
Musisz też zainstalować bibliotekę klienta interfejsów API Google dla języka Python i kilka dodatkowych bibliotek:
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
Teraz możesz przetestować próbkę:
- Skopiuj poniższy przykładowy kod do katalogu roboczego.
- W przykładzie zaktualizuj wartość zmiennej
CLIENT_SECRETS_FILE
, aby odpowiadała lokalizacji pliku pobranego po skonfigurowaniu danych logowania. - Uruchom przykładowy kod w oknie terminala:
python yt_analytics_v2.py
- Przejdź proces autoryzacji. Proces uwierzytelniania może się automatycznie wczytać w przeglądarce. Możesz też skopiować adres URL uwierzytelniania do okna przeglądarki. Na końcu procesu autoryzacji wklej w razie potrzeby kod autoryzacji wyświetlony w przeglądarce do okna terminala i kliknij [return].
- Zapytanie do interfejsu API zostanie wykonane, a odpowiedź JSON zostanie wyświetlona w oknie terminala.
# -*- coding: utf-8 -*- import os import google.oauth2.credentials import google_auth_oauthlib.flow from googleapiclient.discovery import build from googleapiclient.errors import HttpError from google_auth_oauthlib.flow import InstalledAppFlow SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly'] API_SERVICE_NAME = 'youtubeAnalytics' API_VERSION = 'v2' CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json' def get_service(): flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES) credentials = flow.run_console() return build(API_SERVICE_NAME, API_VERSION, credentials = credentials) def execute_api_request(client_library_function, **kwargs): response = client_library_function( **kwargs ).execute() print(response) if __name__ == '__main__': # Disable OAuthlib's HTTPs verification when running locally. # *DO NOT* leave this option enabled when running in production. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' youtubeAnalytics = get_service() execute_api_request( youtubeAnalytics.reports().query, ids='channel==MINE', startDate='2017-01-01', endDate='2017-12-31', metrics='estimatedMinutesWatched,views,likes,subscribersGained' dimensions='day', sort='day' )
Wypróbuj
Użyj APIs Explorer, aby wywołać ten interfejs API i zobaczyć żądanie oraz odpowiedź interfejsu API.