In diesem Dokument wird erläutert, wie Sie mit der Core Reporting API auf Google Analytics-Daten zugreifen.
Einleitung
Die Core Reporting API bietet Zugriff auf die tabellarischen Daten in Standard- und benutzerdefinierten Berichten von Google Analytics. Um auf Daten zuzugreifen, erstellen Sie eine Abfrage, die Folgendes angibt: die Datenansicht (Profil), das Start- und Enddatum sowie die Dimensionen und Messwerte, aus denen die Spaltenüberschriften in der Tabelle bestehen. Diese Abfrage wird an die Core Reporting API gesendet und die Core Reporting API gibt alle Daten in Form einer Tabelle zurück.
Wenn Sie die API noch nicht kennen, finden Sie in der Übersicht zur Core Reporting API eine Einführung in den Zweck der Core Reporting API und die damit bereitgestellten Daten.
Vorbereitung
In diesem Leitfaden wird erläutert, wie Sie mit den Programmiersprachen Java, Python, PHP und JavaScript auf die Google Analytics API zugreifen.
- Auf der Seite Clientbibliotheken finden Sie eine vollständige Liste der programmiersprachenspezifischen Clientbibliotheken, die mit der API funktionieren.
- Informationen zum Zugriff auf die API ohne Clientbibliothek finden Sie im Referenzhandbuch.
Jede Clientbibliothek stellt ein einzelnes Analysedienstobjekt für den Zugriff auf alle Core Reporting API-Daten bereit. In der Regel müssen Sie die folgenden Schritte ausführen, um das Dienstobjekt zu erstellen:
- Registrieren Sie Ihre Anwendung in der Google API Console.
- Autorisieren Sie den Zugriff auf Google Analytics-Daten.
- Erstellen Sie ein Analytics-Dienstobjekt.
Falls Sie diese Schritte noch nicht ausgeführt haben, beenden Sie bitte und lesen Sie die Anleitung zur Hello Google Analytics API. In dieser Anleitung werden Sie durch die ersten Schritte zum Erstellen einer Google Analytics API-Anwendung geführt. Anschließend können Sie mithilfe dieses Leitfadens reale Aufgaben ausführen.
Das folgende Code-Snippet enthält eine Variable zum Speichern eines autorisierten Dienstobjekts.
Java
Analytics analytics = // Read Hello Analytics Tutorial for details.
Python
analytics = # Read Hello Analytics Tutorial for details.
PHP
$client = // Read Hello Analytics Tutorial for details. // Return results as objects. $client->setUseObjects(true); $analytics = new apiAnalyticsService($client);
Die PHP-Bibliothek gibt alle API-Ergebnisse als assoziatives Array zurück. Wenn stattdessen echte Objekte zurückgegeben werden sollen, können Sie die Client-Methode useObject
aufrufen, wie im obigen Beispiel gezeigt.
JavaScript
<script src="https://apis.google.com/js/client.js?onload=loadLib"</script> <script> function loadLib() { // Handle all the authorization work. // Read Hello Analytics Tutorial for details. gapi.client.load('analytics', 'v3', makeApiCall); } </script>
Mit dem ersten Skript-Tag wird die Google API-JavaScript-Bibliothek geladen. Nach dem Laden wird loadLib
ausgeführt, um die Analysedienstklasse zu laden.
Danach sollte das Objekt gapi.client.analytics
im DOM vorhanden sein und zum Abfragen der Core Reporting API verwendet werden können.
Nachdem Sie ein Analysedienstobjekt erstellt haben, können Sie Anfragen an die Core Reporting API senden.
Hinweis: Das Analysedienstobjekt kann auch für den Zugriff auf die Management API verwendet werden.
Überblick
In einer Anwendung, in der die Core Reporting API verwendet wird, sind in der Regel zwei Schritte erforderlich:
- Core Reporting API abfragen
- Mit den API-Ergebnissen arbeiten
Sehen wir uns beide Schritte an.
Core Reporting API abfragen
Core Reporting API-Abfrage erstellen
Das Analysedienstobjekt enthält eine Methode zum Erstellen einer Core Reporting API-Abfrage.
Jede Core Reporting API-Abfrage enthält eine Reihe von Parametern, die festlegen, welche Daten zurückgegeben werden sollen.Einer der wichtigsten Abfrageparameter ist der Parameter ids
oder die Tabellen-ID. Dieser Parameter gibt an, aus welcher Google Analytics-Datenansicht (Profil) Daten abgerufen werden sollen. Der Wert hat das Format ga:xxx
, wobei xxx
die ID der Datenansicht (des Profils) ist.
Java
Get apiQuery = analytics.data().ga() .get(tableId, // Table Id. "2012-01-01", // Start date. "2012-01-15", // End date. "ga:sessions") // Metrics. .setDimensions("ga:source,ga:keyword") .setSort("-ga:sessions,ga:source") .setFilters("ga:medium==organic") .setMaxResults(25);
Python
api_query = service.data().ga().get( ids=TABLE_ID, start_date='2012-01-01', end_date='2012-01-15', metrics='ga:sessions', dimensions='ga:source,ga:keyword', sort='-ga:sessions,ga:source', filters='ga:medium==organic', max_results='25')
PHP
private function queryCoreReportingApi() { $optParams = array( 'dimensions' => 'ga:source,ga:keyword', 'sort' => '-ga:sessions,ga:source', 'filters' => 'ga:medium==organic', 'max-results' => '25'); return $service->data_ga->get( TABLE_ID, '2010-01-01', '2010-01-15', 'ga:sessions', $optParams); }
In dieser Bibliothek erstellt die get
-Methode nicht nur eine Core Reporting API-Abfrage, sondern führt auch die Anfrage an die API aus.
JavaScript
function makeApiCall() { var apiQuery = gapi.client.analytics.data.ga.get({ 'ids': TABLE_ID, 'start-date': '2010-01-01', 'end-date': '2010-01-15', 'metrics': 'ga:sessions', 'dimensions': 'ga:source,ga:keyword', 'sort': '-ga:sessions,ga:source', 'filters': 'ga:medium==organic', 'max-results': 25 }); // ... }
In diesem Beispiel wird die Funktion makeApiCall
aufgerufen, sobald die JavaScript-Clientbibliothek geladen wurde. Darin erstellt die Funktion eine neue Google Analytics API-Abfrage und speichert das Objekt in der Variablen apiQuery
.
Eine vollständige Liste aller Abfrageparameter und ihrer Funktion finden Sie im Referenzhandbuch zur Core Reporting API. Mit den Dimensions- und Messwertparametern können Sie auch angeben, welche Daten von Google Analytics abgerufen werden sollen. Eine vollständige Liste finden Sie auf der Referenzseite für Dimensionen und Messwerte.
Core Reporting API-Datenanfrage stellen
Nachdem Sie eine Abfrage definiert haben, rufen Sie ihre execute
-Methode auf, um sie an die Google Analytics-Server zu senden.
Java
try { apiQuery.execute(); // Success. Do something cool! } catch (GoogleJsonResponseException e) { // Catch API specific errors. handleApiError(e); } catch (IOException e) { // Catch general parsing network errors. e.printStackTrace(); }
Wenn Sie stattdessen auf die API-Rohantwort zugreifen möchten, verwenden Sie die Methode executeUnparsed()
:
HttpResponse response = apiQuery.executeUnparsed();
Python
try: results = get_api_query(service).execute() print_results(results) except TypeError, error: # Handle errors in constructing a query. print ('There was an error in constructing your query : %s' % error) except HttpError, error: # Handle API service errors. print ('There was an API error : %s : %s' % (error.resp.status, error._get_reason()))
PHP
try { $results = queryCoreReportingApi(); // Success. Do something cool! } catch (apiServiceException $e) { // Handle API service exceptions. $error = $e->getMessage(); }
JavaScript
function makeApiCall() { // ... apiQuery.execute(handleCoreReportingResults); } function handleCoreReportingResults(results) { if (!results.error) { // Success. Do something cool! } else { alert('There was an error: ' + results.message); } }
Dieses Beispiel folgt auf den vorherigen Schritt, in dem eine Core Reporting API-Abfrage erstellt wurde. In diesem Schritt wird die Abfrage ausgeführt.
Der Parameter der Methode execute
ist ein Verweis auf eine Callback-Funktion, die ausgeführt wird, sobald Daten von der API zurückgegeben werden.
Sobald die API Ergebnisse zurückgibt, wird die Callback-Funktion ausgeführt und die Daten werden von der API übergeben. Wenn ein Fehler auftritt, enthalten die Ergebnisse ein Attribut mit dem Namen error
.
In diesem Beispiel wird geprüft, ob error
vorhanden ist oder ob die API erfolgreich zurückgegeben wurde.
Wenn die Abfrage erfolgreich war, gibt die API die angeforderten Daten zurück. Wenn Fehler auftreten, gibt die API einen bestimmten Statuscode und eine Meldung zurück, in der der Fehler beschrieben wird. Alle Anwendungen sollten Fehler ordnungsgemäß erfassen und verarbeiten.
Mit den API-Ergebnissen arbeiten
Wenn die Abfrage der Core Reporting API erfolgreich war, gibt die API die Analytics-Berichtsdaten und andere zugehörige Informationen zu den Daten zurück.
Analytics-Berichtsdaten
Die von der API zurückgegebenen Hauptdaten können als Tabelle mit zwei Haupttypen von Daten betrachtet werden:
- Die Überschrift, die die Wertetypen in den einzelnen Spalten beschreibt
- Die Datenzeilen in der Tabelle
Daten zu Spaltenüberschriften
Jede API-Antwort enthält ein Spaltenüberschrift, das die Kopfzeileninformationen der Tabelle darstellt. Das Feld ist eine Liste (oder ein Array) von Objekten, wobei jedes Objekt den Datentyp in der Spalte beschreibt. Die Spaltenreihenfolge entspricht den Dimensionsspalten gefolgt von Messwertspalten in derselben Reihenfolge wie in der ursprünglichen Abfrage.
Java
private void printColumnHeaders(GaData gaData) { System.out.println("Column Headers:"); for (GaDataColumnHeaders header : gaData.getColumnHeaders()) { System.out.println("Column Name: " + header.getName()); System.out.println("Column Type: " + header.getColumnType()); System.out.println("Column Data Type: " + header.getDataType()); } }
Python
def print_column_headers(): headers = results.get('columnHeaders') for header in headers: # Print Dimension or Metric name. print 'Column name = %s' % header.get('name')) print 'Column Type = %s' % header.get('columnType') print 'Column Data Type = %s' % header.get('dataType')
PHP
private function printColumnHeaders(&results) { $html = ''; $headers = $results->getColumnHeaders(); foreach ($headers as $header) { $html .= <<<HTML Column Name = {$header->getName()} Column Type = {$header->getColumnType()} Column Data Type = {$header->getDataType()} HTML; print $html; }
JavaScript
function printColumnHeaders(results) { var output = []; for (var i = 0, header; header = results.columnHeaders[i]; ++i) { output.push( 'Name = ', header.name, '\n', 'Column Type = ', header.columnType, '\n', 'Data Type = ', header.dataType, '\n' ); } alert(output.join('')); }
Zeilendaten
Die von der API zurückgegebenen Hauptdaten werden als zweidimensionale List
von Strings zurückgegeben. Die äußere Liste enthält alle Datenzeilen.
Jede innere Liste stellt eine einzelne Zeile dar, in der die Reihenfolge der Zellen in einer Zeile der Reihenfolge der Felder im oben beschriebenen Spaltenüberschriftsobjekt entspricht.
Da die Daten in jeder Zelle als String zurückgegeben werden, ist das Feld DataType
in jedem Spaltenüberschriftsobjekt besonders nützlich, da es verwendet werden kann, um Stringwerte in einen geeigneten Typ zu parsen. Informationen zu allen möglichen Datentypen finden Sie in der
Metadata API-Antwort.
In den folgenden Beispielen werden sowohl die Kopfzeilen als auch die Zeilen der Tabelle ausgegeben.
Java
private void printDataTable(GaData gaData) { if (gaData.getTotalResults() > 0) { System.out.println("Data Table:"); // Print the column names. for (GaDataColumnHeaders header : gaData.getColumnHeaders()) { System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')'); } System.out.println(); // Print the rows of data. for (List<String> rowValues : gaData.getRows()) { for (String value : rowValues) { System.out.format("%-32s", value); } System.out.println(); } } else { System.out.println("No Results Found"); }
Python
def print_data_table(results): # Print headers. output = [] for header in results.get('columnHeaders'): output.append('%30s' % header.get('name')) print ''.join(output) # Print rows. if results.get('rows', []): for row in results.get('rows'): output = [] for cell in row: output.append('%30s' % cell) print ''.join(output) else: print 'No Results Found'
PHP
private function printDataTable(&$results) { if (count($results->getRows()) > 0) { $table .= '<table>'; // Print headers. $table .= '<tr>'; foreach ($results->getColumnHeaders() as $header) { $table .= '<th>' . $header->name . '</th>'; } $table .= '</tr>'; // Print table rows. foreach ($results->getRows() as $row) { $table .= '<tr>'; foreach ($row as $cell) { $table .= '<td>' . htmlspecialchars($cell, ENT_NOQUOTES) . '</td>'; } $table .= '</tr>'; } $table .= '</table>'; } else { $table .= '<p>No Results Found.</p>'; } print $table; }
JavaScript
function printRows(results) { output = []; if (results.rows && results.rows.length) { var table = ['<table>']; // Put headers in table. table.push('<tr>'); for (var i = 0, header; header = results.columnHeaders[i]; ++i) { table.push('<th>', header.name, '</th>'); } table.push('</tr>'); // Put cells in table. for (var i = 0, row; row = results.rows[i]; ++i) { table.push('<tr><td>', row.join('</td><td>'), '</td></tr>'); } table.push('</table>'); output.push(table.join('')); } else { output.push('<p>No Results Found</p>'); } alert(output.join('')); }
Berichtsinformationen
Zusammen mit den Haupttabellendaten enthalten die von der API zurückgegebenen Daten einige allgemeine Informationen zur Antwort. Sie können ihn folgendermaßen drucken:
Java
private void printResponseInfo(GaData gaData) { System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData()); System.out.println("Kind: " + gaData.getKind()); System.out.println("ID:" + gaData.getId()); System.out.println("Self link: " + gaData.getSelfLink()); }
Python
def print_response_info(results): print 'Contains Sampled Data = %s' % results.get('containsSampledData') print 'Kind = %s' % results.get('kind') print 'ID = %s' % results.get('id') print 'Self Link = %s' % results.get('selfLink')
PHP
private function printReportInfo(&$results) { $html = <<<HTML <pre> Contains Sampled Data = {$results->getContainsSampledData()} Kind = {$results->getKind()} ID = {$results->getId()} Self Link = {$results->getSelfLink()} </pre> HTML; print $html; }
JavaScript
function printReportInfo(results) { var output = []; output.push( 'Contains Sampled Data = ', results.containsSampledData, '\n', 'Kind = ', results.kind, '\n', 'ID = ', results.id, '\n', 'Self Link = ', results.selfLink, '\n'); alert(output.join('')); }
Das Feld containsSampledData
ist wichtig, da es beschreibt, ob die API-Antwort erfasst wurde.
Eine Stichprobenerhebung kann sich auf die Ergebnisse Ihrer Daten auswirken sowie auf einen gemeinsamen Grund dafür zurückzuführen sein, dass die von der API zurückgegebenen Werte nicht mit der Weboberfläche übereinstimmen. Weitere Informationen finden Sie im Konzeptleitfaden Stichproben.
(Profil-)Informationen abrufen
Jede Antwort enthält eine Gruppe von Parametern, die das Konto, die Web-Property und die Datenansicht (Profil) angeben, zu denen diese Daten gehören.
Java
private void printProfileInfo(GaData gaData) { GaDataProfileInfo profileInfo = gaData.getProfileInfo(); System.out.println("Account ID: " + profileInfo.getAccountId()); System.out.println("Web Property ID: " + profileInfo.getWebPropertyId()); System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId()); System.out.println("View (Profile) ID: " + profileInfo.getProfileId()); System.out.println("View (Profile) Name: " + profileInfo.getProfileName()); System.out.println("Table ID: " + profileInfo.getTableId()); }
Python
def print_profile_info(result): info = results.get('profileInfo') print 'Account Id = %s' % info.get('accountId') print 'Web Property Id = %s' % info.get('webPropertyId') print 'Web Property Id = %s' % info.get('internalWebPropertyId') print 'View (Profile) Id = %s' % info.get('profileId') print 'Table Id = %s' % info.get('tableId') print 'View (Profile) Name = %s' % info.get('profileName')
PHP
private function printProfileInformation(&$results) { $profileInfo = $results->getProfileInfo(); $html = <<<HTML <pre> Account ID = {$profileInfo->getAccountId()} Web Property ID = {$profileInfo->getWebPropertyId()} Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()} Profile ID = {$profileInfo->getProfileId()} Table ID = {$profileInfo->getTableId()} Profile Name = {$profileInfo->getProfileName()} </pre> HTML; print $html; }
JavaScript
function printProfileInfo(results) { var output = []; var info = results.profileInfo; output.push( 'Account Id = ', info.accountId, '\n', 'Web Property Id = ', info.webPropertyId, '\n', 'View (Profile) Id = ', info.profileId, '\n', 'Table Id = ', info.tableId, '\n', 'View (Profile) Name = ', info.profileName); alert(output.join('')); }
Jede dieser IDs entspricht verschiedenen Entitäten in der Management API-Hierarchie. Sie können diese IDs für Management API-Abfragen verwenden, um zusätzliche Konfigurationsinformationen zur Ansicht (Profil) abzurufen. Sie können beispielsweise die Zielvorhabensammlung der Management API abfragen, um zu sehen, welche Zielvorhaben mit den konfigurierten Zielvorhabennamen aktiv sind.
Abfrageinformationen
Jede Core Reporting API-Antwort enthält ein Objekt mit allen Abfrageparametern, die zum Erstellen der Antwort verwendet wurden.
Java
private void printQueryInfo(GaData gaData) { GaDataQuery query = gaData.getQuery(); System.out.println("Ids: " + query.getIds()); System.out.println("Start Date: " + query.getStartDate()); System.out.println("End Date: " + query.getEndDate()); System.out.println("Metrics: " + query.getMetrics()); // List System.out.println("Dimensions: " + query.getDimensions()); System.out.println("Sort: " + query.getSort()); // List System.out.println("Segment: " + query.getSegment()); System.out.println("Filters: " + query.getFilters()); System.out.println("Start Index: " + query.getStartIndex()); System.out.println("Max Results: " + query.getMaxResults()); }
Python
def print_query_info(results): query = results.get('query') for key, value in query.iteritems(): print '%s = %s' % (key, value)
PHP
private function printQueryParameters(&$results) { $query = $results->getQuery(); $html = '<pre>'; foreach ($query as $paramName => $value) { $html .= "$paramName = $value\n"; } $html .= '</pre>'; print $html; }
JavaScript
function printQuery(results) { output = []; for (var key in results.query) { output.push(key, ' = ', results.query[key], '\n'); } alert(output.join('')); }
Die Parameter metrics
und sort
werden als Werte in einer Liste zurückgegeben, während die anderen Parameter als Strings zurückgegeben werden.
Paginierungsinformationen
Jede Core Reporting API-Anfrage kann mit Hunderttausenden von Zeilen mit Google Analytics-Daten übereinstimmen. Die Core Reporting API gibt zu einem bestimmten Zeitpunkt nur einen Teil der Daten zurück. Dies kann als einzelne Seite mit Daten bezeichnet werden. Sie verwenden die Paginierungsfelder, um alle Seiten mit Daten abzurufen.
Java
private void printPaginationInfo(GaData gaData) { System.out.println("Items Per Page: " + gaData.getItemsPerPage()); System.out.println("Total Results: " + gaData.getTotalResults()); System.out.println("Previous Link: " + gaData.getPreviousLink()); System.out.println("Next Link: " + gaData.getNextLink()); }
Python
def print_pagination_info(results): print 'Items per page = %s' % results.get('itemsPerPage') print 'Total Results = %s' % results.get('totalResults') print 'Previous Link = %s' % results.get('previousLink') print 'Next Link = %s' % results.get('nextLink')
PHP
private function getPaginationInfo(&$results) { $html = <<<HTML <pre> Items per page = {$results->getItemsPerPage()} Total results = {$results->getTotalResults()} Previous Link = {$results->getPreviousLink()} Next Link = {$results->getNextLink()} </pre> HTML; print $html; }
JavaScript
function printPaginationInfo(results) { var output = []; output.push( 'Items Per Page = ', results.itemsPerPage, '\n', 'Total Results = ', results.totalResults, '\n', 'Previous Link = ', results.previousLink, '\n', 'Next Link = ', results.nextLink, '\n'); alert(output.join('')); }
Das Feld totalResults
gibt die Gesamtzahl der Datenzeilen an, denen Ihre Abfrage in Google Analytics zugeordnet wurde. Dieser Wert kann größer sein als die tatsächliche Anzahl der Zeilen, die auf einer einzelnen Seite der Antwort zurückgegeben werden.
Das Feld itemsPerPage
gibt die Anzahl der auf dieser Seite zurückgegebenen Zeilen an.
Die Parameter previousLink
und nextLink
sind nur vorhanden, wenn eine vorherige oder nächste Seite vorhanden ist. Über diese Links können Sie feststellen, ob mehr Seiten mit Daten von der Core Reporting API abgerufen werden können.
Summen für alle Ergebnisse
Wie bereits im Abschnitt Informationen zur Paginierung erwähnt, können bei einer Abfrage an die Core Reporting API viele Datenzeilen in Google Analytics gefunden werden, aber nur ein Teil der Daten wird zurückgegeben.
Die Gesamtmesswerte für alle übereinstimmenden Zeilen werden im totalsForAllResults
-Objekt zurückgegeben.
Diese Daten sind hilfreich für die Berechnung von Durchschnitten.
Java
private void printTotalsForAllResults(GaData gaData) { MaptotalsMap = gaData.getTotalsForAllResults(); for (Map.Entry entry : totalsMap.entrySet()) { System.out.println(entry.getKey() + " : " + entry.getValue()); } }
Python
def print_totals_for_all_results(results): totals = results.get('totalsForAllResults') for metric_name, metric_total in totals.iteritems(): print 'Metric Name = %s' % metric_name print 'Metric Total = %s' % metric_total
PHP
private function printTotalsForAllResults(&$results) { $totals = $results->getTotalsForAllResults(); foreach ($totals as $metricName => $metricTotal) { $html .= "Metric Name = $metricName\n"; $html .= "Metric Total = $metricTotal"; } print $html; }
JavaScript
function printTotalsForAllResults(results) { var output = []; var totals = results.totalsForAllResults; for (metricName in totals) { output.push( 'Metric Name = ', metricName, '\n', 'Metric Total = ', totals[metricName], '\n'); } alert(output.join('')); }
Arbeitsbeispiele
Die vollständig funktionierenden Beispiele finden Sie im Beispielverzeichnis der einzelnen Clientbibliotheken im Core Reporting API-Beispiel.
Java
Google API-Java-Clientbibliothek Beispiel für Core Reporting API
Python
Google API-Clientbibliothek für Python Beispiel für die Core Reporting API
PHP
PHP-Clientbibliothek der Google API Beispiel für die Core Reporting API
JavaScript
Google API-JavaScript-Clientbibliothek Beispiel für Core Reporting API