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

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

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.
  • Jeśli dodasz wartość video do wartości parametru dimensions, w odpowiedzi interfejsu API otrzymasz osobne statystyki dotyczące źródeł wizyt dla każdego z 10 filmów.
  • Jeśli nie dodasz video do wartości parametru dimensions, odpowiedź interfejsu API podsumuje statystyki źródeł wizyt dla wszystkich 10 filmów.
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.
  • Prawidłowe wartości: json, csv
  • Wartość domyślna: json
callback Funkcja wywołania zwrotnego.
  • Nazwa funkcji wywołania zwrotnego JavaScriptu odpowiedzialnej za odpowiedź.
  • Używane w żądaniach JavaScriptu JSON-P.
prettyPrint

Zwraca odpowiedź z wcięciem i znakami podziału wiersza.

  • Zwraca odpowiedź w formacie czytelnym dla człowieka, jeśli true.
  • Wartość domyślna: true.
  • Gdy ma wartość false, może zmniejszyć rozmiar ładunku odpowiedzi, co w niektórych środowiskach może poprawić wydajność.
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:

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

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 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:
  1. Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
  2. włączyć YouTube Analytics API w swoim projekcie.
  3. 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.
  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. Kliknij przycisk Utwórz, aby zakończyć tworzenie danych logowania.
  8. 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:

  1. Otwórz plik lokalny w przeglądarce, a następnie konsolę debugowania w przeglądarce. Powinna wyświetlić się strona z 2 przyciskami.
  2. 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
  3. 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.
  4. 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:
  1. Utwórz lub wybierz projekt w Konsoli interfejsów API Google.
  2. włączyć YouTube Analytics API w swoim projekcie.
  3. 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.
  4. Na stronie Dane logowania kliknij przycisk Utwórz dane logowania i wybierz Identyfikator klienta OAuth.
  5. Wybierz typ aplikacji Inne, wpisz nazwę „Krótkie wprowadzenie do YouTube Analytics API” i kliknij przycisk Utwórz.
  6. Kliknij OK, aby zamknąć wynikowe okno.
  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 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:

  1. Skopiuj poniższy przykładowy kod do katalogu roboczego.
  2. Na tym przykładzie zaktualizuj wartość zmiennej CLIENT_SECRETS_FILE tak, 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 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].
  5. 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.