Reports: Query

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.

  • Aby wysłać żądanie danych do kanału YouTube, ustaw wartość parametru ids na channel==MINE lub channel==CHANNEL_ID, gdzie CHANNEL_ID identyfikuje kanał YouTube aktualnie uwierzytelnionego użytkownika.
  • Aby przesłać prośbę o dostęp do danych właściciela treści YouTube, ustaw wartość parametru ids na contentOwner==OWNER_NAME, gdzie OWNER_NAME to content owner ID identyfikatora użytkownika.

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.
  • Jeśli dodasz video do wartości parametru dimensions, odpowiedź interfejsu API będzie zawierała osobne statystyki źródeł wizyt dla każdego z 10 filmów.
  • Jeśli nie dodasz video do wartości parametru dimensions, w odpowiedzi interfejsu API zostaną zebrane statystyki źródeł wizyt dla wszystkich 10 filmów.
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.
  • Prawidłowa wartość: json, csv
  • Wartość domyślna: json
callback Funkcja wywołania zwrotnego.
  • Nazwa funkcji wywołania zwrotnego JavaScriptu, która obsługuje odpowiedź.
  • Używany 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
  • Jeśli ma wartość false, może to zmniejszyć rozmiar ładunku odpowiedzi, co może zwiększyć wydajność w niektórych środowiskach.
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:

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 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.

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 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:
  1. Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
  2. Włącz YouTube Analytics API w swoim projekcie.
  3. 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.
  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 URL, z którego będziesz udostępniać przykładowy kod. Możesz na przykład wpisać http://localhost:8000 lub http://yourserver.example.com. Pole Autoryzowane identyfikatory URI przekierowania możesz pozostawić puste.
  7. Kliknij przycisk Utwórz, aby zakończyć tworzenie danych logowania.
  8. 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:

  1. Otwórz lokalny plik w przeglądarce i otwórz w niej konsolę debugowania. Powinna wyświetlić się strona z dwoma przyciskami.
  2. 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
  3. 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.
  4. 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>

yt_analytics_v2.html

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:
  1. Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
  2. Włącz YouTube Analytics API w swoim projekcie.
  3. 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.
  4. Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
  5. Wybierz typ aplikacji Other (Inne), wpisz nazwę „YouTube Analytics API – krótkie wprowadzenie” i kliknij przycisk Utwórz.
  6. Kliknij OK, aby zamknąć okno dialogowe.
  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 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:

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

yt_analytics_v2.py

Wypróbuj

Użyj interfejsu APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź interfejsu API.