Z tego dokumentu dowiesz się, jak uzyskiwać dostęp do danych Google Analytics za pomocą interfejsu API podstawowego raportowania.
Wstęp
Interfejs API podstawowego raportowania zapewnia dostęp do danych tabelarycznych w raportach standardowych i niestandardowych Google Analytics. Aby uzyskać dostęp do danych, utwórz zapytanie, które określa: widok (profil), daty rozpoczęcia i zakończenia oraz wymiary i dane składające się na nagłówki kolumn w tabeli. To zapytanie jest wysyłane do interfejsu API podstawowego raportowania, który zwraca wszystkie dane w postaci tabeli.
Jeśli korzystasz z interfejsu API po raz pierwszy, przeczytaj omówienie interfejsu API podstawowego raportowania, by dowiedzieć się, jaki jest jego cel i jakie dane dostarcza.
Zanim zaczniesz
Z tego przewodnika dowiesz się, jak uzyskać dostęp do interfejsu Google Analytics API, korzystając z języków programowania Java, Python, PHP i JavaScript.
- Pełną listę bibliotek klienta dla poszczególnych języków programowania, które obsługują interfejs API, znajdziesz na stronie bibliotek klienta.
- Aby uzyskać dostęp do interfejsu API bez biblioteki klienta, przeczytaj przewodnik informacyjny.
Każda biblioteka klienta zapewnia pojedynczy obiekt usługi analityki, który zapewnia dostęp do wszystkich danych interfejsu Core Reporting API. Aby utworzyć obiekt usługi, musisz zwykle wykonać te czynności:
- Zarejestruj aplikację w Konsoli interfejsów API Google.
- Autoryzacja dostępu do danych Google Analytics.
- Utwórz obiekt usługi Analytics.
Jeśli nie udało Ci się wykonać tych czynności, zatrzymaj się i przeczytaj samouczek Hello Google Analytics API. W tym samouczku omawiamy pierwsze kroki tworzenia aplikacji interfejsu Google Analytics API. Po ukończeniu kursu możesz używać tego przewodnika do wykonywania rzeczywistych zadań.
Ten fragment kodu zawiera zmienną przechowującą obiekt autoryzowanej usługi.
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);
Biblioteka PHP zwróci wszystkie wyniki interfejsu API w postaci tablicy powiązaniowej. Aby zamiast tego zwrócić rzeczywiste obiekty, możesz wywołać metodę useObject klienta w sposób pokazany powyżej.
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>
Pierwszy tag skryptu wczytuje bibliotekę JavaScript interfejsu API Google. Po załadowaniu klasy wykonywany jest loadLib.
Gdy skończysz, obiekt gapi.client.analytics powinien istnieć w DOM i być gotowy do użycia do wysyłania zapytań do interfejsu Core Reporting API.
Po utworzeniu obiektu usługi analizy możesz wysyłać żądania do interfejsu API podstawowego raportowania.
Uwaga: za pomocą obiektu usługi analityki możesz też uzyskać dostęp do interfejsu Management API.
Przegląd
Aplikacja, która korzysta z interfejsu API podstawowego raportowania, składa się zwykle z 2 kroków:
- Wysyłanie zapytań do interfejsu API podstawowego raportowania
- Praca z wynikami interfejsu API
Przyjrzyjmy się obu tym etapom.
Wysyłanie zapytań do interfejsu API podstawowego raportowania
Tworzenie zapytania w interfejsie API podstawowego raportowania
Obiekt usługi Analytics zawiera metodę do tworzenia zapytań interfejsu API podstawowego raportowania.
Każde zapytanie interfejsu API podstawowego raportowania zawiera zestaw parametrów, które określają, jakie dane mają być zwracane.Jednym z najważniejszych parametrów zapytania jest parametr ids, czyli identyfikator tabeli. Ten parametr określa, z którego widoku (profilu) Google Analytics mają być pobierane dane. Wartość ma format ga:xxx, gdzie xxx to identyfikator widoku danych (profilu).
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);
}
W tej bibliotece metoda get nie tylko tworzy zapytanie do interfejsu API podstawowego raportowania, ale także wykonuje żądanie do interfejsu API.
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
});
// ...
}
W tym przykładzie funkcja makeApiCall jest wywoływana po wczytaniu biblioteki klienta JavaScript. Funkcja ta tworzy nowe zapytanie interfejsu Google Analytics API i zapisuje obiekt w zmiennej apiQuery.
Pełną listę wszystkich parametrów zapytania i ich działania znajdziesz w Przewodniku po interfejsie API Core Reporting. Parametry wymiarów i danych pozwalają też określać, które dane mają być pobierane z Google Analytics. Pełną listę znajdziesz na stronie z informacjami o wymiarach i danych.
Tworzenie żądania danych do interfejsu API podstawowego raportowania
Po zdefiniowaniu zapytania użyj metody execute, aby wysłać je do serwerów Google Analytics.
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();
}
Jeśli wolisz uzyskać dostęp do nieprzetworzonej odpowiedzi interfejsu API, użyj metody 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);
}
}
Ten przykład pochodzi z poprzedniego kroku, w którym utworzono zapytanie interfejsu API podstawowego raportowania. W tym kroku zapytanie jest wykonywane.
Parametr metody execute jest odniesieniem do funkcji wywołania zwrotnego, która zostanie wykonana po zwróceniu danych przez interfejs API.
Gdy interfejs API zwróci wyniki, funkcja wywołania zwrotnego zostanie wykonana i przekaże dane z interfejsu API. Jeśli wystąpi błąd, wyniki będą zawierać właściwość o nazwie error.
W tym przykładzie sprawdzany jest, czy error istnieje i czy interfejs API został zwrócony.
Jeśli zapytanie się uda, interfejs API zwróci żądane dane. W przypadku wystąpienia błędów interfejs API zwróci określony kod stanu i komunikat z opisem błędu. Wszystkie aplikacje powinny prawidłowo wychwytywać i obsługiwać błędy.
Praca z wynikami interfejsu API
Jeśli zapytanie do interfejsu API podstawowego raportowania zakończy się powodzeniem, interfejs API zwróci wyniki z danymi raportowania Analytics oraz innymi powiązanymi informacjami.
Dane do raportów Analytics
Główne dane zwracane przez interfejs API można traktować jako tabelę z 2 głównymi typami danych:
- Nagłówek opisujący typy wartości w poszczególnych kolumnach.
- Wiersze danych w tabeli
Dane nagłówka kolumny
Każda odpowiedź interfejsu API zawiera pole nagłówka kolumny, które reprezentuje informacje nagłówka tabeli. Pole zawiera listę (lub tablica) obiektów, w której każdy obiekt opisuje typ danych w kolumnie. Kolejność kolumn to kolumny wymiarów, po których występują kolumny danych, w kolejności określonej w oryginalnym zapytaniu.
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(''));
}
Dane w wierszach
Główne dane zwracane przez interfejs API są zwracane jako dwuwymiarowe List ciągów znaków. Lista zewnętrzna przedstawia wszystkie wiersze danych.
Każda lista wewnętrzna to pojedynczy wiersz, w którym kolejność komórek w wierszu jest taka sama jak pola w obiekcie nagłówka kolumny opisanym powyżej.
Dane w każdej komórce są zwracane jako ciąg znaków, dlatego pole DataType w każdym obiekcie nagłówka kolumny jest szczególnie przydatne, ponieważ może służyć do analizowania wartości w postaci ciągów znaków do odpowiedniego typu. Listę wszystkich możliwych typów danych znajdziesz w
odpowiedzi interfejsu metadanych interfejsu API.
W podanych niżej przykładach są wyświetlane zarówno nagłówki, jak i wiersze tabeli.
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(''));
}
Informacje o raporcie
Oprócz danych w głównej tabeli dane zwrócone przez interfejs API zawierają ogólne informacje o odpowiedzi. Możesz je wydrukować za pomocą:
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(''));
}
Pole containsSampledData jest ważne, ponieważ wskazuje, czy odpowiedź interfejsu API została próbkowana.
Próbkowanie może wpływać na wyniki danych oraz na najczęstszą przyczynę niezgodności wartości zwracanych przez interfejs API z interfejsem internetowym. Więcej informacji znajdziesz w przewodniku po pojęciu próbkowania.
Wyświetl informacje (profil)
Każda odpowiedź zawiera grupę parametrów wskazujących konto, usługę internetową i widok (profil), do których należą te dane.
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(''));
}
Każdy z tych identyfikatorów odpowiada różnym elementom w hierarchii interfejsu Management API. Możesz ich używać do tworzenia zapytań do interfejsu Management API, aby uzyskać dodatkowe informacje o konfiguracji widoku (profilu). Możesz na przykład wysłać zapytanie do kolekcji celów interfejsu Management API, aby sprawdzić, które cele są aktywne i które mają skonfigurowane nazwy.
Informacje o zapytaniu
Każda odpowiedź interfejsu API podstawowego raportowania zawiera obiekt zawierający wszystkie wartości parametrów zapytania użyte do utworzenia odpowiedzi.
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(''));
}
Parametry metrics i sort są zwracane jako wartości na liście, a pozostałe parametry są zwracane w postaci ciągów znaków.
Informacje o podziale na strony
Każde żądanie do interfejsu API podstawowego raportowania może odpowiadać setkom tysięcy wierszy danych Google Analytics. Interfejs Core Reporting API zwraca w danym momencie tylko podzbiór danych, który można określić jako pojedynczą stronę danych. Pola podziału na strony służą do pobierania wszystkich stron danych.
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(''));
}
Pole totalResults podaje łączną liczbę wierszy z danymi, które pasują do Twojego zapytania w Google Analytics. Wartość ta może być większa od rzeczywistej liczby wierszy zwróconych na pojedynczej stronie odpowiedzi.
Pole itemsPerPage podaje liczbę wierszy zwróconych na tej stronie.
Parametry previousLink i nextLink występują tylko wtedy, gdy istnieje poprzednia lub następna strona. Sprawdź te linki, aby zobaczyć, czy można pobrać więcej stron danych za pomocą interfejsu API podstawowego raportowania.
Sumy dla wszystkich wyników
Jak wspomnieliśmy powyżej w sekcji z informacjami o podziale na strony, zapytanie wysyłane do interfejsu API podstawowego raportowania może dopasować wiele wierszy danych w Google Analytics, ale zwrócić tylko ich podzbiór.
Łączne wartości danych dla wszystkich pasujących wierszy są zwracane w obiekcie totalsForAllResults.
Dane te przydają się do obliczania średnich wartości.
Java
private void printTotalsForAllResults(GaData gaData) {
Map totalsMap = 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(''));
}
Próbki robocze
Aby zobaczyć pełne działające przykłady, zapoznaj się z przykładem interfejsu Core Reporting API w przykładowym katalogu każdej biblioteki klienta.
Java
Biblioteka klienta interfejsu API Google w języku Java Przykładowy interfejs API podstawowego raportowania
Python
Biblioteka klienta interfejsu API Google w Pythonie Przykładowy interfejs API podstawowego raportowania
PHP
Biblioteka klienta interfejsu API Google w języku PHP Przykładowy interfejs API podstawowego raportowania
JavaScript
Biblioteka klienta JavaScript interfejsu Google API Przykładowy interfejs API podstawowego raportowania