Reports: Query

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.

  • Aby poprosić o dane dotyczące kanału w YouTube, ustaw wartość parametru ids na channel==MINE lub channel==CHANNEL_ID, gdzie CHANNEL_ID oznacza kanał w YouTube aktualnie uwierzytelnionego użytkownika.
  • Aby poprosić o dane właściciela treści w YouTube, ustaw wartość parametru ids na contentOwner==OWNER_NAME, gdzie OWNER_NAME to content owner ID użytkownika.

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łachraportó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łachraportó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, playlistchannel. 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.
  • Jeśli dodasz video do wartości parametru dimensions, odpowiedź interfejsu API będzie zawierać oddzielne statystyki źródeł wizyt dla każdego z 10 filmów.
  • Jeśli nie dodasz znaku video do wartości parametru dimensions, odpowiedź interfejsu API będzie zawierać zagregowane statystyki źródeł wizyt dla wszystkich 10 filmów.
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.
  • Prawidłowe wartości: json, csv
  • Wartość domyślna: json
callback Funkcja wywołania zwrotnego.
  • Nazwa funkcji wywołania zwrotnego JavaScript, która obsługuje odpowiedź.
  • Używane w żądaniach JSON-P JavaScriptu.
prettyPrint

Zwraca odpowiedź z wcięciami i podziałami wierszy.

  • Zwraca odpowiedź w formacie zrozumiałym dla człowieka, jeśli true.
  • Wartość domyślna: true.
  • Gdy ta wartość jest ustawiona na false, może to zmniejszyć rozmiar ładunku odpowiedzi, co w niektórych środowiskach może zwiększyć wydajność.
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:

JSON
{
  "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.

CSV
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:
  1. Utwórz projekt w Konsoli interfejsów API Google lub wybierz istniejący projekt.
  2. Włącz w projekcie interfejs YouTube Analytics API.
  3. 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.
  4. Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
  5. Wybierz typ aplikacji Aplikacja internetowa.
  6. 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 lub http://yourserver.example.com. Pole Autoryzowane identyfikatory URI przekierowania możesz pozostawić puste.
  7. Aby zakończyć tworzenie danych logowania, kliknij przycisk Utwórz.
  8. 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ę:

  1. Otwórz plik lokalny w przeglądarce i otwórz w niej konsolę debugowania. Powinna wyświetlić się strona z 2 przyciskami.
  2. 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
  3. 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.
  4. 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:
  1. Utwórz projekt w Konsoli interfejsów API Google lub wybierz istniejący projekt.
  2. Włącz w projekcie interfejs YouTube Analytics API.
  3. 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.
  4. Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
  5. Wybierz typ aplikacji Inne, wpisz nazwę „YouTube Analytics API Quickstart” i kliknij przycisk Utwórz.
  6. Aby zamknąć okno, kliknij OK.
  7. Kliknij przycisk (Pobierz JSON) po prawej stronie identyfikatora klienta.
  8. 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ę:

  1. Skopiuj poniższy przykładowy kod do katalogu roboczego.
  2. W przykładzie zaktualizuj wartość zmiennej CLIENT_SECRETS_FILE, aby odpowiadała lokalizacji pliku pobranego po skonfigurowaniu danych logowania.
  3. Uruchom przykładowy kod w oknie terminala:
    python yt_analytics_v2.py
  4. 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].
  5. 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.