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 | stringData 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 | stringOkreśla kanał w YouTube lub właściciela treści, dla którego pobierasz YouTube Analytics dane. 
 | |
| metrics | stringLista rozdzielonych przecinkami YouTube Analytics danych, np. viewslublikes,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 | stringData 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 | stringWaluta, 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 | stringLista rozdzielonych przecinkami wymiarów Statystyk YouTube, np. videolubageGroup,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 | stringLista 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ść parametrufiltersrównavideo==dMH0bHeiRNg;country==ITogranicza 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,playlistichannel. 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ść parametrufiltersrównavideo==pd1FJh59zxQ,Zhawgd0REhA;country==ITogranicza 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 filtersw Twoim żądaniu identyfikuje listę 10 filmów, dla których mają zostać zwrócone dane.
 | |
| includeHistoricalChannelData | booleanUwaga: 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 totrue, 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 | integerMaksymalna liczba wierszy do uwzględnienia w odpowiedzi. Uwaga: w wersji 1 interfejsu API ten parametr miał nazwę  max-results | |
| sort | stringLista 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 | integerIndeks pierwszej jednostki do pobrania (liczony od 1). (Wartość domyślna to 1). Używaj tego parametru jako mechanizmu stronicowania wraz z parametremmax-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 | stringTa wartość określa typ danych zawartych w odpowiedzi interfejsu API. W przypadku metody querywartość właściwościkindbę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ścikind. | 
| columnHeaders[] | listTa wartość określa informacje o danych zwracanych w polach rows. Każdy element na liściecolumnHeadersidentyfikuje pole zwrócone w wartościrows, która zawiera listę danych oddzielonych przecinkami.Lista columnHeaderszaczyna 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 | stringNazwa wymiaru lub rodzaju danych. | 
| columnHeaders[].columnType | stringTyp kolumny ( DIMENSIONlubMETRIC). | 
| columnHeaders[].dataType | stringTyp danych w kolumnie ( STRING,INTEGER,FLOATitp.). | 
| rows[] | listLista 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 rowszostanie pominięty w odpowiedzi.Odpowiedź na zapytanie z wymiarem daynie 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:8000lubhttp://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śćresultjest 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.