Ważne: żądania do interfejsu API wysyłane 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, np. wymiary, filtry czy instrukcje sortowania.
- Dane to indywidualne pomiary aktywności użytkowników, takie jak wyświetlenia filmów czy oceny (oceny pozytywne i negatywne).
- Wymiary to typowe kryteria używane do zbierania danych, np. data aktywności użytkownika lub kraj, w którym znajdują się użytkownicy. Każdy wiersz danych w raporcie zawiera niepowtarzalną kombinację wartości wymiarów.
- Filtry to wartości wymiarów, które określają, jakie dane będą pobierane. Możesz na przykład pobrać dane dotyczące określonego kraju, konkretnego filmu lub grupy filmów.
Uwaga: raporty właścicieli treści są dostępne tylko dla dostawców treści YouTube, którzy uczestniczą w programie partnerskim YouTube.
Typowe przypadki użycia
Prośba
Żądanie HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
Wszystkie żądania do interfejsu YouTube Analytics API muszą być autoryzowane. W przewodniku po autoryzacji dowiesz się, jak używać protokołu OAuth 2.0 do pobierania tokenów autoryzacji.
Żądania do interfejsu YouTube Analytics API używają 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 liczba 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. |
https://www.googleapis.com/auth/youtube | Zarządzaj kontem YouTube. W YouTube Analytics API właściciele kanałów używają tego zakresu do zarządzania grupami i elementami grupowania w Statystykach YouTube. |
https://www.googleapis.com/auth/youtubepartner | Wyświetlanie zasobów YouTube i powiązanych treści w YouTube oraz zarządzanie nimi. W YouTube Analytics API właściciele treści używają tego zakresu do zarządzania grupami i elementami w Statystykach YouTube. |
Parametry
W tabelach poniżej znajdziesz listę wymaganych i opcjonalnych parametrów zapytania związanych z żądaniami do interfejsu API pobierającymi raporty o zapytaniach. Standardowe parametry zapytania wymienione w tej tabeli też są opcjonalne i są obsługiwane przez wiele interfejsów API Google.
Parametry | ||
---|---|---|
Wymagane parametry | ||
endDate |
string Data końcowa pobierania danych z kategorii YouTube Analytics. Wartość powinna mieć format YYYY-MM-DD .Odpowiedź interfejsu API zawiera dane zebrane do ostatniego dnia, dla którego wszystkie wskaźniki w zapytaniu są dostępne w momencie wykonywania zapytania. Jeśli na przykład w żądaniu podana jest data końcowa 5 lipca 2017 roku, a wartości wszystkich żądanych danych są dostępne tylko do 3 lipca 2017 roku, będzie to ostatni dzień, którego dotyczy odpowiedź. (nawet jeśli dane niektórych żądanych rodzajów danych są dostępne od 4 lipca 2017 r.). Uwaga: w wersji 1 interfejsu API ten parametr nazywał się end-date |
|
ids |
string Identyfikuje kanał YouTube lub właściciela treści, dla którego pobierasz dane YouTube Analytics.
|
|
metrics |
string Rozdzielona przecinkami lista danych YouTube Analytics, 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 raportów dotyczących kanałów i raportów właściciela treści. (Dokument Dane zawiera definicje wszystkich danych).
|
|
startDate |
string Data rozpoczęcia pobierania danych z YouTube Analytics. Wartość powinna mieć format YYYY-MM-DD .Uwaga: w wersji 1 interfejsu API ten parametr nazywał się
start-date |
|
Parametry opcjonalne | ||
currency |
string Waluta, której będzie używać interfejs API do określania tych szacunkowych danych o przychodach: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm i playbackBasedCpm. Wartości, które interfejs API zwraca dla tych danych, to wartości szacunkowe obliczane na podstawie kursów wymiany, które zmieniają się codziennie. Jeśli nie użyjesz żadnego z tych rodzajów danych, parametr zostanie zignorowany. Wartością parametru jest 3-literowy kod waluty w standardzie ISO 4217, który znajdziesz na poniższej liście walut. W przypadku podania nieobsługiwanej waluty interfejs API zwraca błąd. Wartością domyślną jest USD . |
|
dimensions |
string Rozdzielona przecinkami lista wymiarów YouTube Analytics, 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łów i raportów właściciela treści. (definicje wszystkich wymiarów znajdziesz w dokumencie Wymiary).
|
|
filters |
string Lista filtrów, które należy zastosować podczas pobierania danych YouTube Analytics. Wymiary, które można wykorzystać do filtrowania poszczególnych raportów, są opisane w dokumentacji raportów kanałów i raportów właścicieli treści, a w dokumencie Dimensions (Wymiary) te wymiary są zdefiniowane. Jeśli żądanie korzysta z wielu filtrów, połącz je średnikiem ( ; ), a zwrócona tabela wyników spełni oba te filtry. Na przykład parametr filters o wartości video==dMH0bHeiRNg;country==IT ogranicza zbiór wyników tak, aby zawierał dane dotyczące danego filmu we Włoszech.Określanie wielu wartości filtra Interfejs API umożliwia określenie wielu wartości filtrów video , playlist i channel . Aby to zrobić, podaj oddzieloną listę identyfikatorów filmów, playlist lub kanałów, w przypadku których chcesz odfiltrować odpowiedź interfejsu API. Na przykład parametr filters o wartości video==pd1FJh59zxQ,Zhawgd0REhA;country==IT ogranicza zbiór wyników, aby zawierał dane dotyczące konkretnych filmów z Włoch. Wartość parametru może zawierać maksymalnie 500 identyfikatorów.Gdy określisz wiele wartości dla tego samego filtra, możesz też dodać ten filtr do listy wymiarów określonych w żądaniu. Dzieje się tak nawet wtedy, gdy filtr nie jest wymieniony na liście wymiarów obsługiwanych w danym raporcie. Jeśli dodasz filtr do listy wymiarów, interfejs API będzie używać ich też do grupowania wyników. Załóżmy np., że pobierasz raport o źródłach wizyt na kanale, który zawiera agregujące statystyki wyświetlania z uwzględnieniem tego, w jaki sposób widzowie dotarli do treści wideo kanału. Załóżmy też, że żądanie parametru filters w Twoim żądaniu wskazuje listę 10 filmów, dla których powinny zostać zwrócone dane.
|
|
includeHistoricalChannelData |
boolean Uwaga: ten parametr ma zastosowanie tylko do raportów właścicieli treści. Wskazuje, czy odpowiedź interfejsu API powinna zawierać dane o czasie oglądania i wyświetleniach kanału z okresu poprzedzającego połączenie kanałów z właścicielem treści. Domyślna wartość tego parametru to false , co oznacza, że odpowiedź interfejsu API zawiera tylko dane o czasie oglądania i wyświetleniach z okresów, w których kanały były połączone 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óżnym czasie. Jeśli żądanie do interfejsu API pobiera dane dla wielu kanałów, a wartość parametru to false , odpowiedź interfejsu API zawiera dane oparte na dacie połączenia z poszczególnych kanałów. Jeśli wartością parametru jest 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 nazywał się include-historical-channel-data |
|
maxResults |
integer Maksymalna liczba wierszy do uwzględnienia w odpowiedzi. Uwaga: w wersji 1 interfejsu API ten parametr nazywał się max-results |
|
sort |
string Rozdzielona przecinkami lista wymiarów lub danych, które określają kolejność sortowania danych w Statystykach YouTube. Domyślnie kolejność sortowania rosnąco. Prefiks - powoduje sortowanie malejąco.
|
|
startIndex |
integer Indeks zaczynający się od 1 pierwszej encji do pobrania. (Wartość domyślna to 1 ). Użyj tego parametru jako mechanizmu podziału na strony razem z parametrem max-results .Uwaga: w wersji 1 interfejsu API ten parametr nazywał się start-index |
|
Parametry standardowe | ||
access_token |
OAuth 2.0 token dla obecnego 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 już 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 już wycofana. Ten parametr nie jest obsługiwany w wersji 2 interfejsu API. |
Treść żądania
Nie wysyłaj treści żądania podczas wywoływania tej metody.
Odpowiedź
Zgodnie z definicją parametru alt
interfejs API może zwracać odpowiedzi w formacie JSON lub CSV. Poniżej znajdziesz informacje o treści odpowiedzi dla poszczególnych typów:
{ "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 uwzględnionych w odpowiedzi interfejsu API. W przypadku metody query właściwość kind będzie mieć wartość youtubeAnalytics#resultTable . Jeśli jednak interfejs API doda obsługę innych metod, odpowiedzi interfejsu API dotyczące tych metod mogą wprowadzić 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 określa pole zwrócone w wartości rows , która zawiera listę danych rozdzielonych przecinkami.Lista columnHeaders rozpoczyna się od wymiarów określonych w żądaniu do interfejsu API, po których występują dane określone w żądaniu do interfejsu API. Kolejność wymiarów i danych odpowiada 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 takiej kolejności: ageGroup ,gender ,viewerPercentage . |
columnHeaders[].name |
string Nazwa wymiaru lub danych. |
columnHeaders[].columnType |
string Typ kolumny ( DIMENSION lub METRIC ). |
columnHeaders[].dataType |
string Typ danych w kolumnie ( STRING , INTEGER , FLOAT itd.). |
rows[] |
list Lista zawiera wszystkie wiersze tabeli wyników. Każda pozycja na liście jest tablicą zawierającą dane rozdzielane przecinkami odpowiadające jednemu wierszowi danych. Kolejność pól danych rozdzielonych przecinkami będzie odpowiadać kolejności kolumn wymienionych w polu columnHeaders .Jeśli dla danego zapytania nie ma dostępnych danych, element rows zostanie pominięty w odpowiedzi.Odpowiedź na zapytanie z wymiarem day nie będzie zawierać wierszy z ostatnich 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 obejmować wszystkich obsługiwanych języków programowania. Listę obsługiwanych języków znajdziesz w dokumentacji bibliotek klienta.
JavaScript
Ten przykład wywołuje interfejs YouTube Analytics API, aby pobrać dzienną liczbę wyświetleń i inne dane z kanału autoryzacyjnego użytkownika za rok kalendarzowy 2017. W przykładzie korzystamy z biblioteki klienta JavaScript interfejsów API Google.Zanim po raz pierwszy uruchomisz ten przykład lokalnie lokalnie, musisz skonfigurować dane uwierzytelniające w swoim projekcie:
- Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
- Włącz YouTube Analytics API w swoim projekcie.
- U góry strony Dane logowania wybierz kartę Ekran akceptacji OAuth. Wybierz adres e-mail, wpisz nazwę produktu, jeśli jeszcze jej nie ustawiono, a następnie 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 URL, z którego będziesz udostępniać przykładowy kod. Możesz na przykład wpisać
http://localhost:8000
lubhttp://yourserver.example.com
. Pole Autoryzowane identyfikatory URI przekierowania możesz pozostawić puste. - Kliknij przycisk Utwórz, aby zakończyć tworzenie danych logowania.
- Przed zamknięciem okna dialogowego skopiuj identyfikator klienta, który musisz umieścić w przykładowym kodzie.
Następnie zapisz próbkę w pliku lokalnym. W przykładzie znajdź następujący wiersz i zastąp YOUR_CLIENT_ID identyfikatorem klienta uzyskanym podczas konfigurowania danych logowania.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
Teraz możesz przetestować przykład:
- Otwórz lokalny plik w przeglądarce i otwórz w niej konsolę debugowania. Powinna wyświetlić się strona z dwoma przyciskami.
- Kliknij przycisk Autoryzuj i wczytaj, aby uruchomić proces autoryzacji użytkownika. Jeśli zezwolisz aplikacji na pobieranie danych kanału, w konsoli w przeglądarce powinny wyświetlić się te wiersze:
Sign-in successful GAPI client loaded for API
- Jeśli zamiast powyższych wierszy zobaczysz komunikat o błędzie, sprawdź, czy wczytujesz skrypt z autoryzowanego identyfikatora URI przekierowania skonfigurowanego dla Twojego projektu i czy umieszczasz identyfikator klienta w kodzie w sposób opisany powyżej.
- Kliknij przycisk execute (Wykonaj), aby wywołać interfejs API. W konsoli powinien być widoczny obiekt
response
. W takim obiekcie właściwośćresult
mapuje się 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
Ten przykład wywołuje interfejs YouTube Analytics API, aby pobrać dzienną liczbę wyświetleń i inne dane z kanału autoryzacyjnego użytkownika za rok kalendarzowy 2017. W przykładzie użyto biblioteki klienta interfejsów API Google w Pythonie.Zanim po raz pierwszy uruchomisz ten przykład lokalnie lokalnie, musisz skonfigurować dane uwierzytelniające w swoim projekcie:
- Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
- Włącz YouTube Analytics API w swoim projekcie.
- U góry strony Dane logowania wybierz kartę Ekran akceptacji OAuth. Wybierz adres e-mail, wpisz nazwę produktu, jeśli jeszcze jej nie ustawiono, a następnie kliknij przycisk Zapisz.
- Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
- Wybierz typ aplikacji Other (Inne), wpisz nazwę „YouTube Analytics API – krótkie wprowadzenie” i kliknij przycisk Utwórz.
- Kliknij OK, aby zamknąć okno dialogowe.
- 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 Pythona 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ć przykład:
- Skopiuj poniższy kod do katalogu roboczego.
- W przykładzie zaktualizuj wartość zmiennej
CLIENT_SECRETS_FILE
, aby pasowała do lokalizacji pliku pobranego po skonfigurowaniu danych uwierzytelniających. - Uruchom przykładowy kod w oknie terminala:
python yt_analytics_v2.py
- Przejdź przez proces autoryzacji. Proces uwierzytelniania może wczytać się automatycznie w przeglądarce. Może być też konieczne skopiowanie adresu URL uwierzytelniania do okna przeglądarki. Jeśli to konieczne, na końcu procesu autoryzacji wklej kod autoryzacji wyświetlany w przeglądarce w oknie terminala i kliknij [return].
- Zapytanie interfejsu API zostanie wykonane, a odpowiedź JSON zostanie przesłana do okna 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 interfejsu APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź interfejsu API.