Wichtig: API-Anfragen an diese Methode benötigen jetzt Zugriff auf den Bereich https://www.googleapis.com/auth/youtube.readonly
.
Mit dieser Methode lassen sich viele verschiedene Analytics-Berichte abrufen. In jeder Anfrage werden Abfrageparameter verwendet, um eine Kanal-ID oder einen Rechteinhaber, ein Startdatum, ein Enddatum und mindestens einen Messwert anzugeben. Sie können auch zusätzliche Suchparameter wie Dimensionen, Filter und Sortieranweisungen angeben.
- Messwerte sind individuelle Messungen der Nutzeraktivität, wie z. B. Videoaufrufe oder Bewertungen („Mag ich“- und „Mag ich nicht“-Bewertungen).
- Dimensionen sind gängige Kriterien, mit denen Daten zusammengefasst werden, z. B. das Datum, an dem die Nutzeraktivität stattgefunden hat, oder das Land, in dem sich die Nutzer befanden. In einem Bericht hat jede Datenzeile eine eindeutige Kombination von Dimensionswerten.
- Filter sind Dimensionswerte, die die abzurufenden Daten angeben. So lassen sich beispielsweise Daten für ein bestimmtes Land, ein bestimmtes Video oder eine Gruppe von Videos abrufen.
Hinweis: Berichte zu Rechteinhabern sind nur für YouTube-Contentpartner verfügbar, die am YouTube-Partnerprogramm teilnehmen.
Gängige Anwendungsfälle
Anfragen
HTTP-Anfrage
GET https://youtubeanalytics.googleapis.com/v2/reports
Alle Anfragen an die YouTube Analytics API müssen autorisiert werden. Im Autorisierungsleitfaden wird erläutert, wie mithilfe des OAuth 2.0-Protokolls Autorisierungstokens abgerufen werden.
YouTube Analytics API-Anfragen verwenden die folgenden Autorisierungsbereiche:
Ebenen | |
---|---|
https://www.googleapis.com/auth/yt-analytics.readonly | Sieh dir YouTube Analytics-Berichte für deine YouTube-Inhalte an. Über diesen Bereich erhalten Sie Zugriff auf Messwerte zur Nutzeraktivität, z. B. die Anzahl der Aufrufe und Bewertungen. |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | YouTube Analytics-Finanzberichte für deine YouTube-Inhalte abrufen. So erhalten Sie Zugriff auf Messwerte zur Nutzeraktivität sowie auf Messwerte zum geschätzten Umsatz und zur Anzeigenleistung. |
https://www.googleapis.com/auth/youtube | Verwalte dein YouTube-Konto. In der YouTube Analytics API verwenden Kanalinhaber diesen Bereich, um Gruppen und Gruppenelemente in YouTube Analytics zu verwalten. |
https://www.googleapis.com/auth/youtubepartner | YouTube-Assets und zugehörige Inhalte auf YouTube abrufen und verwalten. In der YouTube Analytics API können Rechteinhaber diesen Bereich nutzen, um Gruppen und Gruppenelemente in YouTube Analytics zu verwalten. |
Parameter
In den folgenden Tabellen sind die erforderlichen und optionalen Abfrageparameter für API-Anfragen zum Abrufen von Anfrageberichten aufgeführt. Die in der Tabelle aufgeführten Standardsuchparameter sind ebenfalls optional und werden von vielen Google APIs unterstützt.
Parameter | ||
---|---|---|
Erforderliche Parameter | ||
endDate |
string Das Enddatum für das Abrufen von YouTube Analytics-Daten. Der Wert muss das Format YYYY-MM-DD haben.Die API-Antwort enthält Daten bis zum letzten Tag, für den zum Zeitpunkt der Abfrage alle Messwerte in der Abfrage verfügbar sind. Wenn in der Anfrage beispielsweise der 5. Juli 2017 als Enddatum angegeben ist und die Werte für alle angeforderten Messwerte nur bis zum 3. Juli 2017 verfügbar sind, werden in der Antwort keine Daten mehr berücksichtigt. Das gilt auch dann, wenn Daten für einige der angeforderten Messwerte für den 4. Juli 2017 verfügbar sind. Hinweis: In Version 1 der API wurde dieser Parameter end-date |
|
ids |
string Identifiziert den YouTube-Kanal oder Rechteinhaber, für den du YouTube Analytics-Daten abrufst.
|
|
metrics |
string Eine durch Kommas getrennte Liste von YouTube Analytics-Messwerten, z. B. views oder likes,dislikes . In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern findest du eine Liste der Berichte, die du abrufen kannst, und der Messwerte, die in den einzelnen Berichten verfügbar sind. Das Dokument Messwerte enthält Definitionen für alle Messwerte.
|
|
startDate |
string Das Startdatum für das Abrufen von YouTube Analytics-Daten Der Wert muss das Format YYYY-MM-DD haben.Hinweis: In Version 1 der API wurde dieser Parameter
start-date |
|
Optionale Parameter | ||
currency |
string Die Währung, in der die API die folgenden geschätzten Umsatzmesswerte angibt: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm Die vom API zurückgegebenen Werte für diese Messwerte sind Schätzungen, die auf Grundlage von Wechselkursen berechnet werden, die sich täglich ändern. Wird keiner dieser Messwerte angefordert, wird der Parameter ignoriert. Der Parameterwert ist ein dreistelliger Währungscode gemäß ISO 4217 aus der Liste der Währungen unten. Die API gibt einen Fehler zurück, wenn eine nicht unterstützte Währung angegeben ist. Der Standardwert ist USD . |
|
dimensions |
string Eine durch Kommas getrennte Liste von YouTube Analytics-Dimensionen, z. B. video oder ageGroup,gender . In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern findest du eine Liste der Berichte, die du abrufen kannst, und der dafür verwendeten Dimensionen. Das Dokument Dimensionen enthält Definitionen für alle Dimensionen.
|
|
filters |
string Eine Liste von Filtern, die beim Abrufen von YouTube Analytics-Daten angewendet werden sollen. In der Dokumentation zu Kanalberichten und Berichten zu Rechteinhabern sind die Dimensionen aufgeführt, die zum Filtern der einzelnen Berichte verwendet werden können. Im Dokument Dimensionen sind diese Dimensionen definiert. Wenn in einer Anfrage mehrere Filter verwendet werden, führen Sie diese mit einem Semikolon ( ; ) zusammen. Die zurückgegebene Ergebnistabelle erfüllt dann beide Filter. Beispiel: Wenn der filters -Parameterwert video==dMH0bHeiRNg;country==IT lautet, werden nur Daten für das jeweilige Video in Italien berücksichtigt.Mehrere Werte für einen Filter angeben Die API unterstützt die Möglichkeit, mehrere Werte für die Filter video , playlist und channel anzugeben. Geben Sie dazu eine separate Liste der Video-, Playlist- oder Kanal-IDs an, für die die API-Antwort gefiltert werden soll. Wenn der Parameterwert filters beispielsweise video==pd1FJh59zxQ,Zhawgd0REhA;country==IT lautet, werden nur Daten für die angegebenen Videos in Italien berücksichtigt. Für den Parameterwert können bis zu 500 IDs angegeben werden.Wenn Sie mehrere Werte für denselben Filter angeben, können Sie ihn der Liste der Dimensionen hinzufügen, die Sie für die Anfrage angeben. Das gilt auch dann, wenn der Filter für einen bestimmten Bericht nicht als unterstützte Dimension aufgeführt ist. Wenn Sie den Filter zur Liste der Dimensionen hinzufügen, verwendet die API die Filterwerte auch zum Gruppieren der Ergebnisse. Angenommen, du rufst den Bericht zu Zugriffsquellen eines Kanals ab, in dem Statistiken zu Aufrufen zusammengefasst werden, die darauf basieren, wie Zuschauer auf die Videoinhalte des Kanals zugegriffen haben. Angenommen, die Parameteranfrage filters Ihrer Anfrage enthält eine Liste mit zehn Videos, für die Daten zurückgegeben werden sollen.
|
|
includeHistoricalChannelData |
boolean Hinweis:Dieser Parameter gilt nur für Berichte zu Rechteinhabern. Gibt an, ob die API-Antwort die Wiedergabezeit- und Aufrufdaten der Kanäle aus dem Zeitraum vor der Verknüpfung der Kanäle mit dem Rechteinhaber enthalten soll. Der Standardparameterwert lautet false . Das bedeutet, dass die API-Antwort nur Daten zu Wiedergabezeit und Aufrufen für die Zeiträume enthält, an denen Kanäle mit dem Rechteinhaber verknüpft wurden.Es kann sein, dass verschiedene Kanäle zu unterschiedlichen Zeiten mit einem Rechteinhaber verknüpft wurden. Wenn mit der API-Anfrage Daten für mehrere Kanäle abgerufen werden und der Parameterwert false lautet, enthält die API-Antwort Daten, die auf dem Verknüpfungsdatum für den jeweiligen Kanal basieren. Wenn der Parameterwert true lautet, enthält die API-Antwort Daten, die mit den in der API-Anfrage angegebenen Datumsangaben übereinstimmen.Hinweis: In Version 1 der API wurde dieser Parameter include-historical-channel-data |
|
maxResults |
integer Die maximale Anzahl von Zeilen, die in die Antwort aufgenommen werden sollen. Hinweis: In Version 1 der API wurde dieser Parameter max-results |
|
sort |
string Eine durch Kommas getrennte Liste von Dimensionen oder Messwerten, mit denen die Sortierreihenfolge der YouTube Analytics-Daten festgelegt wird. standardmäßig ist die Sortierfolge aufsteigend Das Präfix - sorgt für eine absteigende Sortierreihenfolge.
|
|
startIndex |
integer Der 1-basierte Index der ersten abzurufenden Entität. Der Standardwert ist 1 . Verwenden Sie diesen Parameter als Paginierungsmechanismus zusammen mit dem Parameter max-results .Hinweis: In Version 1 der API wurde dieser Parameter start-index |
|
Standardparameter | ||
access_token |
OAuth 2.0-Token für den aktuellen Nutzer.
|
|
alt |
Dieser Parameter wird in Version 2 der API, die nur JSON-Antworten unterstützt, nicht unterstützt. Das Datenformat für die API-Antwort.
|
|
callback |
Callback-Funktion
|
|
prettyPrint |
Gibt die Antwort mit Einzügen und Zeilenumbrüchen zurück.
|
|
quotaUser |
Dieser Parameter wurde in Version 1 der API unterstützt, die jetzt eingestellt ist. Dieser Parameter wird in Version 2 der API nicht unterstützt. | |
userIp |
Dieser Parameter wurde in Version 1 der API unterstützt, die jetzt eingestellt ist. Dieser Parameter wird in Version 2 der API nicht unterstützt. |
Anfragetext
Beim Aufrufen dieser Methode wird kein Anfragetext gesendet.
Antwort
Wie in der Parameterdefinition alt
angegeben, kann die API Antworten im JSON- oder CSV-Format zurückgeben. Informationen zum Antworttext für jeden Typ finden Sie unten:
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
Attribute | |
---|---|
kind |
string Dieser Wert gibt den Datentyp an, der in der API-Antwort enthalten ist. Für die Methode query ist der Attributwert kind youtubeAnalytics#resultTable . Wenn die API jedoch weitere Methoden unterstützt, können API-Antworten für diese Methoden andere kind -Attributwerte einführen. |
columnHeaders[] |
list Dieser Wert gibt Informationen zu den Daten an, die in den rows -Feldern zurückgegeben werden. Jedes Element in der columnHeaders -Liste identifiziert ein Feld, das im rows -Wert zurückgegeben wird, der eine Liste mit durch Kommas getrennten Daten enthält.Die Liste columnHeaders beginnt mit den in der API-Anfrage angegebenen Dimensionen, gefolgt von den in der API-Anfrage angegebenen Messwerten. Die Reihenfolge von Dimensionen und Messwerten entspricht der Reihenfolge in der API-Anfrage.Wenn die API-Anfrage beispielsweise die Parameter dimensions=ageGroup,gender&metrics=viewerPercentage enthält, gibt die API-Antwort Spalten in dieser Reihenfolge zurück: ageGroup , gender , viewerPercentage . |
columnHeaders[].name |
string Der Name der Dimension oder des Messwerts. |
columnHeaders[].columnType |
string Der Typ der Spalte ( DIMENSION oder METRIC ). |
columnHeaders[].dataType |
string Der Typ der Daten in der Spalte ( STRING , INTEGER , FLOAT usw.). |
rows[] |
list Die Liste enthält alle Zeilen der Ergebnistabelle. Jedes Element in der Liste ist ein Array mit durch Kommas getrennten Daten, die einer einzelnen Datenzeile entsprechen. Die Reihenfolge der durch Kommas getrennten Datenfelder entspricht der Reihenfolge der im Feld columnHeaders aufgeführten Spalten.Wenn für die gegebene Abfrage keine Daten verfügbar sind, wird das Element rows in der Antwort weggelassen.Die Antwort auf eine Abfrage mit der Dimension day enthält keine Zeilen für die letzten Tage. |
day, views, likes, ... "2012-01-01", 12.0, 3, ... "2012-01-02", 16.0, 2, ... "2012-01-03", 18.0, 8, ... ...
Beispiele
Hinweis:Die folgenden Codebeispiele repräsentieren möglicherweise nicht alle unterstützten Programmiersprachen. Eine Liste der unterstützten Sprachen finden Sie in der Dokumentation zu Clientbibliotheken.
JavaScript
In diesem Beispiel wird die YouTube Analytics API aufgerufen, um die täglichen Aufrufe und andere Messwerte für den Kanal des autorisierenden Nutzers für das Kalenderjahr 2017 abzurufen. In diesem Beispiel wird die Google API-Clientbibliothek für JavaScript verwendet.Bevor Sie dieses Beispiel zum ersten Mal lokal ausführen, müssen Sie Anmeldedaten für die Autorisierung für Ihr Projekt einrichten:
- Erstelle ein Projekt in der Google API Console oder wähle eines aus.
- Aktiviere die YouTube Analytics API für dein Projekt.
- Wählen Sie oben auf der Seite Anmeldedaten den Tab OAuth-Zustimmungsbildschirm aus. Wählen Sie eine E-Mail-Adresse aus, geben Sie einen Produktnamen ein, falls noch nicht festgelegt, und klicken Sie auf die Schaltfläche Speichern.
- Klicken Sie auf der Seite Anmeldedaten auf die Schaltfläche Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
- Wählen Sie den Anwendungstyp „Webanwendung“ aus.
- Geben Sie im Feld „Autorisierte JavaScript-Quellen“ die URL ein, von der aus Sie das Codebeispiel bereitstellen. Sie können z. B.
http://localhost:8000
oderhttp://yourserver.example.com
verwenden. Sie können das Feld „Autorisierte Weiterleitungs-URIs“ leer lassen. - Klicken Sie auf Erstellen, um die Erstellung Ihrer Anmeldedaten abzuschließen.
- Bevor Sie das Dialogfeld schließen, kopieren Sie die Client-ID, die Sie in das Codebeispiel eingeben müssen.
Speichern Sie das Sample dann in einer lokalen Datei. Suchen Sie im Beispiel die folgende Zeile und ersetzen Sie YOUR_CLIENT_ID durch die Client-ID, die Sie beim Einrichten Ihrer Autorisierungsanmeldedaten erhalten haben.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
Jetzt können Sie das Beispiel tatsächlich testen:
- Öffnen Sie die lokale Datei in einem Webbrowser und dann die Debugging-Konsole im Browser. Es sollte eine Seite mit zwei Schaltflächen angezeigt werden.
- Klicken Sie auf die Schaltfläche Autorisieren und laden, um die Nutzerautorisierung zu starten. Wenn Sie die App zum Abrufen Ihrer Kanaldaten autorisieren, sollten die folgenden Zeilen in der Konsole im Browser ausgegeben werden:
Sign-in successful GAPI client loaded for API
- Wenn anstelle der oben genannten Zeilen eine Fehlermeldung angezeigt wird, prüfen Sie, ob Sie das Skript über den autorisierten Weiterleitungs-URI laden, den Sie für Ihr Projekt eingerichtet haben, und ob Sie Ihre Client-ID wie oben beschrieben in den Code eingefügt haben.
- Klicken Sie auf die Schaltfläche execute, um die API aufzurufen. Es sollte ein
response
-Objekt angezeigt werden, das im Browser an die Konsole gedruckt wird. In diesem Objekt ist die Eigenschaftresult
einem Objekt zugeordnet, das die API-Daten enthält.
<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
In diesem Beispiel wird die YouTube Analytics API aufgerufen, um die täglichen Aufrufe und andere Messwerte für den Kanal des autorisierenden Nutzers für das Kalenderjahr 2017 abzurufen. In diesem Beispiel wird die Google API-Clientbibliothek für Python verwendet.Bevor Sie dieses Beispiel zum ersten Mal lokal ausführen, müssen Sie Anmeldedaten für die Autorisierung für Ihr Projekt einrichten:
- Erstelle ein Projekt in der Google API Console oder wähle eines aus.
- Aktiviere die YouTube Analytics API für dein Projekt.
- Wählen Sie oben auf der Seite Anmeldedaten den Tab OAuth-Zustimmungsbildschirm aus. Wählen Sie eine E-Mail-Adresse aus, geben Sie einen Produktnamen ein, falls noch nicht festgelegt, und klicken Sie auf die Schaltfläche Speichern.
- Klicken Sie auf der Seite Anmeldedaten auf die Schaltfläche Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
- Wähle den Anwendungstyp Andere aus, gib den Namen „YouTube Analytics API Kurzanleitung“ ein und klicke auf die Schaltfläche „Erstellen“.
- Klicken Sie auf OK, um das angezeigte Dialogfeld zu schließen.
- Klicken Sie rechts neben der Client-ID auf die Schaltfläche (JSON herunterladen).
- Verschieben Sie die heruntergeladene Datei in Ihr Arbeitsverzeichnis.
Sie müssen auch die Google APIs-Clientbibliothek für Python und einige zusätzliche Bibliotheken installieren:
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
Jetzt können Sie das Beispiel tatsächlich testen:
- Kopieren Sie das Codebeispiel unten in Ihr Arbeitsverzeichnis.
- Aktualisieren Sie im Beispiel den Wert der Variablen
CLIENT_SECRETS_FILE
so, dass er mit dem Speicherort der Datei übereinstimmt, die Sie nach Einrichtung Ihrer Anmeldedaten für die Autorisierung heruntergeladen haben. - Führen Sie den Beispielcode in einem Terminalfenster aus:
python yt_analytics_v2.py
- Autorisierungsvorgang durchlaufen. Der Autorisierungsablauf wird möglicherweise automatisch im Browser geladen oder Sie müssen die Authentifizierungs-URL in ein Browserfenster kopieren. Fügen Sie am Ende des Autorisierungsvorgangs, falls erforderlich, den im Browser angezeigten Autorisierungscode in Ihr Terminalfenster ein und klicken Sie auf [return].
- Die API-Abfrage wird ausgeführt und die JSON-Antwort wird im Terminalfenster ausgegeben.
# -*- 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' )
Jetzt testen
Verwenden Sie APIs Explorer, um diese API aufzurufen und die API-Anfrage und -Antwort anzusehen.