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 i zakończenia oraz co najmniej 1 rodzaju danych. Możesz też podać dodatkowe parametry zapytania, takie jak wymiary, filtry i instrukcje sortowania.
- Dane to indywidualne pomiary aktywności użytkowników, takie jak wyświetlenia filmów lub oceny (oceny pozytywne i negatywne).
- Wymiary to typowe kryteria używane do agregowania danych, takie jak data aktywności użytkownika lub kraj zamieszkania. W każdym wierszu danych w raporcie występuje unikalna kombinacja wartości wymiaru.
- Filtry to wartości wymiarów określające dane, które zostaną 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 biorą udział w programie partnerskim YouTube.
Typowe przypadki użycia
Żądanie
Żądanie HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
Wszystkie żądania do interfejsu YouTube Analytics API muszą być autoryzowane. Przewodnik po autoryzacji zawiera instrukcje pobierania tokenów autoryzacji za pomocą protokołu OAuth 2.0.
Żądania do interfejsu YouTube Analytics 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. |
https://www.googleapis.com/auth/youtube | Zarządzaj swoim kontem YouTube. W interfejsie YouTube Analytics API właściciele kanałów używają tego zakresu do zarządzania grupami i elementami grup w YouTube Analytics. |
https://www.googleapis.com/auth/youtubepartner | Wyświetlanie zasobów YouTube i powiązanych treści w YouTube oraz zarządzanie nimi. W interfejsie YouTube Analytics API właściciele treści używają tego zakresu do zarządzania grupami i elementami grup w YouTube Analytics. |
Parametry
W poniższych tabelach podano wymagane i opcjonalne parametry zapytania dla żądań do interfejsu API służące do pobierania raportów zapytań. Standardowe parametry zapytania wymienione w tabeli również są opcjonalne i obsługiwane przez wiele interfejsów API Google.
Parametry | ||
---|---|---|
Wymagane parametry | ||
endDate |
string Data zakończenia pobierania danych (YouTube Analytics). Wartość powinna być w formacie YYYY-MM-DD .Odpowiedź interfejsu API zawiera dane zebrane do ostatniego dnia, dla którego wszystkie dane zapytań są dostępne w momencie wyszukiwania. Jeśli na przykład żądanie ma datę zakończenia przypadającą 5 lipca 2017 r., a wartości wszystkich żądanych danych są dostępne tylko do 3 lipca 2017 r., jest to data ostatniego uwzględniania danych w odpowiedzi. Dotyczy to także danych z niektórych żądanych kategorii, które są dostępne od 4 lipca 2017 roku. Uwaga: w wersji 1 interfejsu API ten parametr nosi nazwę end-date |
|
ids |
string Określa kanał YouTube lub właściciela treści, dla którego pobierasz dane YouTube Analytics.
|
|
metrics |
string Lista rozdzielonych przecinkami danych (YouTube Analytics), np. views lub likes,dislikes . Listę raportów, które możesz pobrać, oraz dane dostępne w ich raportach znajdziesz w dokumentacji raportów o kanałach lub właścicielach treści. (Dokument Wskaźniki zawiera definicje wszystkich danych).
|
|
startDate |
string Data rozpoczęcia pobierania danych (YouTube Analytics). Wartość powinna być w formacie YYYY-MM-DD .Uwaga: w wersji 1 interfejsu API ten parametr nosi nazwę
start-date |
|
Parametry opcjonalne | ||
currency |
string Waluta, której interfejs API użyje do określenia tych szacunkowych danych o przychodach: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. Wartości zwracane przez interfejs API dla tych danych są szacowane przy użyciu kursów wymiany, które zmieniają się codziennie. Jeśli nie wysyłasz żadnego z tych wskaźników, parametr jest ignorowany. Wartość parametru to trzyliterowy kod waluty w formacie ISO 4217, widoczny na liście walut poniżej. Interfejs API zwraca błąd, jeśli określono nieobsługiwaną walutę. Wartością domyślną jest USD . |
|
dimensions |
string Lista rozdzielonych przecinkami 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 o kanałach i właścicielach 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 dotyczących kanałów i raportów właściciela treści wskazuje wymiary, których można używać do filtrowania poszczególnych raportów, a w dokumencie Wymiary są zdefiniowane te wymiary. Jeśli w żądaniu jest wiele filtrów, połącz je średnikami ( ; ), a zwrócona tabela wyników będzie spełniać oba warunki. Na przykład wartość parametru filters wynosząca video==dMH0bHeiRNg;country==IT ogranicza zestaw wyników, by zawierał dane dotyczące 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ć, określ oddzielną listę identyfikatorów filmów, playlist lub kanałów, dla których chcesz odfiltrować odpowiedź interfejsu API. Na przykład wartość video==pd1FJh59zxQ,Zhawgd0REhA;country==IT parametru filters ogranicza zbiór wyników do danych dotyczących filmów we Włoszech. Wartość parametru może zawierać maksymalnie 500 identyfikatorów.Jeśli podajesz wiele wartości 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 znajduje się na liście obsługiwanych wymiarów w danym raporcie. Jeśli dodasz filtr do listy wymiarów, interfejs użyje ich też do grupowania wyników. Załóżmy na przykład, że masz pobrany raport o źródłach wizyt dotyczący kanału, który zawiera statystyki wyświetleń na podstawie sposobu, w jaki widzowie dotarli do treści filmu. Załóżmy też, że żądanie filters w żądaniu zawiera listę 10 filmów, dla których mają zostać zwrócone dane.
|
|
includeHistoricalChannelData |
boolean Uwaga: ten parametr ma zastosowanie tylko do raportów właściciela treści. Wskazuje, czy odpowiedź API powinna uwzględniać czas oglądania i liczbę wyświetleń kanałów z okresu poprzedzającego połączenie kanałów z właścicielem treści. Domyślna wartość parametru to false . Oznacza to, że odpowiedź interfejsu API zawiera tylko dane o czasie oglądania i wyświetleniach z okresu, w którym 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óżnych terminach. Jeśli żądanie API pobiera dane dla wielu kanałów, a wartość parametru to false , odpowiedź interfejsu API zawiera dane zebrane na podstawie daty połączenia każdego z nich. 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 nosi nazwę include-historical-channel-data |
|
maxResults |
integer Maksymalna liczba wierszy w odpowiedzi. Uwaga: w wersji 1 interfejsu API ten parametr nosi nazwę max-results |
|
sort |
string Lista rozdzielonych przecinkami wymiarów lub danych, która określa kolejność sortowania danych w YouTube Analytics Domyślnie kolejność sortowania jest rosnąca. Prefiks - powoduje malejącą kolejność sortowania.
|
|
startIndex |
integer Indeks oparty na 1 pierwszym elemencie do pobrania. (wartością domyślną jest 1 ). Używaj tego parametru jako mechanizmu podziału na strony wraz z parametrem max-results .Uwaga: w wersji 1 interfejsu API ten parametr nosi nazwę start-index |
|
Parametry standardowe | ||
access_token |
Token OAuth 2.0 dla bieżącego użytkownika.
|
|
alt |
Ten parametr nie jest obsługiwany w wersji 2 interfejsu API, który obsługuje tylko odpowiedzi JSON.Format danych odpowiedzi API.
|
|
callback |
Funkcja wywołania zwrotnego.
|
|
prettyPrint |
Zwraca odpowiedź z wcięciem i znakami podziału wiersza.
|
|
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ą w parametrze alt
interfejs API może zwracać odpowiedzi w formacie JSON lub CSV. Informacje o treści odpowiedzi w przypadku poszczególnych typów znajdziesz poniżej:
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
Usługi | |
---|---|
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 dodaje obsługę innych metod, odpowiedzi API dla tych metod mogą wprowadzać inne wartości właściwości kind . |
columnHeaders[] |
list Ta wartość określa informacje o danych zwróconych w polach rows . Każda pozycja na liście columnHeaders zawiera pole zwrócone w wartości rows , która zawiera listę danych rozdzielanych przecinkami.Lista columnHeaders zaczyna się od wymiarów określonych w żądaniu do interfejsu API, po których następuje 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 itp.). |
rows[] |
list Lista zawiera wszystkie wiersze tabeli wyników. Każda pozycja na liście to tablica zawierająca dane rozdzielone przecinkami odpowiadające pojedynczemu wierszowi danych. Kolejność pól danych rozdzielanych przecinkami jest taka sama jak kolejność kolumn podanych w polu columnHeaders .Jeśli nie ma dostępnych danych dla danego zapytania, 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 prezentować 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, który pobiera dzienne wyświetlenia i inne dane służące do autoryzacji kanału użytkownika na rok kalendarzowy 2017. W przykładzie użyto biblioteki klienta JavaScript Google API.Zanim uruchomisz ten przykładowy kod lokalnie po raz pierwszy, musisz skonfigurować dane logowania do autoryzacji swojego projektu:
- Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
- włączyć YouTube Analytics API w swoim projekcie.
- U góry strony Dane logowania wybierz kartę Ekran zgody OAuth. Wybierz adres e-mail, wpisz nazwę produktu (jeśli nie jest jeszcze skonfigurowana) 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. - Kliknij przycisk Utwórz, aby zakończyć tworzenie danych logowania.
- Przed zamknięciem okna dialogowego skopiuj identyfikator klienta, którego musisz użyć w przykładowym kodzie.
Następnie zapisz przykładowy plik w pliku lokalnym. W tym 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ć fragment:
- Otwórz plik lokalny w przeglądarce, a następnie konsolę debugowania w przeglądarce. Powinna wyświetlić się strona z 2 przyciskami.
- Kliknij przycisk Autoryzuj i wczytaj, aby uruchomić procedurę autoryzacji użytkownika. Jeśli zezwolisz aplikacji na pobieranie danych kanału, w konsoli powinny wyświetlić się następujące wiersze:
Sign-in successful GAPI client loaded for API
- Jeśli zamiast wierszy powyżej zobaczysz komunikat o błędzie, sprawdź, czy wczytywany jest skrypt z autoryzowanego identyfikatora URI przekierowania skonfigurowanego dla projektu i czy został w nim umieszczony identyfikator klienta w sposób opisany powyżej.
- Kliknij przycisk execute, aby wywołać interfejs API. W przeglądarce powinien wyświetlić się obiekt
response
w konsoli. 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
Ten przykład wywołuje interfejs YouTube Analytics API, który pobiera dzienne wyświetlenia i inne dane służące do autoryzacji kanału użytkownika na rok kalendarzowy 2017. W przykładzie użyto biblioteki klienta Pythona dla interfejsów API Google.Zanim uruchomisz ten przykładowy kod lokalnie po raz pierwszy, musisz skonfigurować dane logowania do autoryzacji swojego projektu:
- Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
- włączyć YouTube Analytics API w swoim projekcie.
- U góry strony Dane logowania wybierz kartę Ekran zgody OAuth. Wybierz adres e-mail, wpisz nazwę produktu (jeśli nie jest jeszcze skonfigurowana) 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ę „Krótkie wprowadzenie do YouTube Analytics API” i kliknij przycisk Utwórz.
- Kliknij OK, aby zamknąć wynikowe okno.
- 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 innych bibliotek:
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
Teraz możesz przetestować fragment:
- Skopiuj poniższy przykładowy kod do katalogu roboczego.
- Na tym przykładzie zaktualizuj wartość zmiennej
CLIENT_SECRETS_FILE
tak, 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 się automatycznie wczytać w przeglądarce lub może być konieczne skopiowanie adresu URL uwierzytelniania do okna przeglądarki. W razie potrzeby na końcu procesu autoryzacji wklej kod autoryzacji widoczny w przeglądarce i kliknij [return].
- Zapytanie do interfejsu API zostanie wykonane, a odpowiedź JSON pojawi się 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 wyświetlić żądanie oraz odpowiedź interfejsu API.