Core Reporting API – przewodnik dla programistów

Dokument zawiera informacje o uzyskiwaniu dostępu do danych Google Analytics za pomocą interfejsu Core Reporting API.

Wprowadzenie

Interfejs Core Reporting API zapewnia dostęp do danych z tabeli 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, które składają się na nagłówki kolumn w tabeli. To zapytanie jest wysyłane do interfejsu Core Reporting API, a interfejs Core Reporting API zwraca wszystkie dane w formie tabeli.

Jeśli dopiero zaczynasz korzystać z interfejsu API raportowania, przeczytaj omówienie interfejsu Core Reporting API, aby dowiedzieć się więcej o celu korzystania z tego interfejsu i zawartych w nim danych.

Zanim zaczniesz

Z tego przewodnika dowiesz się, jak uzyskać dostęp do interfejsu Google Analytics API za pomocą języków programowania Java, Python, PHP i JavaScript.

  • Pełną listę bibliotek klienckich języków programowania, które obsługują interfejs API, znajdziesz na stronie Biblioteki klienta.
  • Przeczytaj Przewodnik referencyjny, aby uzyskać dostęp do interfejsu API bez biblioteki klienta.

Każda biblioteka klienta udostępnia jeden obiekt usługi analitycznej, który zapewnia dostęp do wszystkich danych interfejsu Core Reporting API. Aby utworzyć obiekt usługi, musisz wykonać te czynności:

  1. Zarejestruj aplikację w konsoli Google API.
  2. Autoryzuj dostęp do danych Google Analytics.
  3. utworzyć obiekt usługi Analytics,

Jeśli te czynności nie zostały jeszcze wykonane, zatrzymaj i przeczytaj samouczek dotyczący interfejsu API Google Analytics. W tym samouczku przeprowadzimy Cię przez pierwsze kroki tworzenia aplikacji API w Google Analytics. Gdy skończysz, możesz używać tego przewodnika do wykonywania rzeczywistych zadań.

Ten fragment kodu zawiera zmienną służącą do przechowywania autoryzowanego obiektu 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 jako tablicę stowarzyszoną. Aby zwrócić rzeczywiste obiekty, możesz wywołać metodę useObject klienta, jak pokazano w przykładzie 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 Google API. Po załadowaniu uruchamiany jest loadLib, aby wczytać klasę usługi Analytics. Gdy to zrobisz, obiekt gapi.client.analytics powinien istnieć w DOM i być gotowy do użycia w interfejsie Core Reporting API.

Po utworzeniu obiektu usługi Analytics możesz zacząć wysyłać żądania do interfejsu Core Reporting API.

Uwaga: obiektu usługi Analytics można też użyć do uzyskania dostępu do interfejsu Management API.

Przegląd

Aby użyć aplikacji, która korzysta z interfejsu Core Reporting API, trzeba wykonać 2 kroki:

  • Wykonywanie zapytań dotyczących interfejsu Core Reporting API
  • Praca z wynikami interfejsu API

Przyjrzyjmy się obu tym krokom.

Wykonywanie zapytań dotyczących interfejsu Core Reporting API

Utwórz zapytanie dotyczące interfejsu Core Reporting API

Obiekt usługi Analytics zawiera metodę tworzenia zapytania dotyczącego interfejsu Core Reporting API.

Każde zapytanie do interfejsu Core Reporting API zawiera zestaw parametrów, które określają, jakie dane mają zostać zwrócone.

Jednym z najważniejszych parametrów zapytania jest parametr ids lub identyfikator tabeli. Ten parametr określa, z którego widoku (profilu) Google Analytics ma pobrać dane. Wartość ma format ga:xxx, gdzie xxx jest identyfikatorem 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 dotyczące interfejsu Core Reporting API, 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. Ta funkcja tworzy nowe zapytanie do interfejsu Google Analytics API i przechowuje obiekt w zmiennej apiQuery.

Pełną listę wszystkich parametrów zapytania i ich działań znajdziesz w przewodniku po interfejsach Core Reporting API. Parametry i wymiary określają też, jakie dane chcesz pobierać z Google Analytics. Pełną listę znajdziesz na stronie z wymiarami i danymi.

Zgłaszanie żądania danych do interfejsu Core Reporting API

Gdy zdefiniujesz zapytanie, wywołasz jego metodę execute, aby wysłać zapytanie 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 dotyczące interfejsu Core Reporting API. W tym kroku zapytanie zostanie wykonane. Parametr metody execute to odwołanie do funkcji wywołania zwrotnego, która zostanie wykonana po zwróceniu danych z interfejsu API.

Gdy interfejs API zwróci wyniki, uruchomiona zostanie funkcja wywołania zwrotnego i przekazanie danych z interfejsu API. Jeśli wystąpi błąd, w wynikach pojawi się właściwość o nazwie error.

W tym przykładzie sprawdzamy, czy interfejs error istnieje i czy interfejs API został zwrócony.

Jeśli zapytanie się powiedzie, interfejs API zwróci wymagane dane. Jeśli wystąpią błędy, interfejs API zwróci konkretny kod stanu i komunikat z komunikatem o błędzie. Wszystkie aplikacje powinny wykrywać i obsługiwać błędy.

Praca z wynikami interfejsu API

Jeśli zapytanie interfejsu Core Reporting API się powiedzie, interfejs API zwróci dane raportowania Analytics i inne powiązane informacje.

Dane raportowania 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 każdej kolumnie
  • Wiersze danych w tabeli

Dane nagłówka kolumny

Każda odpowiedź interfejsu API zawiera pole nagłówka kolumny przedstawiające informacje z nagłówka tabeli. Pole to lista (lub tablica) obiektów, w których każdy obiekt opisuje typ danych w kolumnie. Kolejność kolumn to kolumny wymiarów, a następnie kolumny danych w takiej samej kolejności jak w pierwotnym 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 wiersza

Główne dane zwracane przez interfejs API są zwracane jako dwuwymiarowy List ciągów znaków. Zewnętrzna lista reprezentuje wszystkie wiersze danych. Każda lista wewnętrzna reprezentuje jeden wiersz, gdzie kolejność komórek w wierszu jest taka sama jak w polach obiektu nagłówka kolumny opisanego powyżej.

Dane w każdej komórce są zwracane jako ciąg znaków, więc pole DataType w każdym obiekcie nagłówka kolumny jest szczególnie przydatne, ponieważ może służyć do analizowania wartości ciągu w odpowiednim typie. Wszystkie możliwe typy danych znajdziesz w odpowiedzi interfejsu API metadanych.

W podanych niżej przykładach znajdziesz 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(''));
}

Zgłoś informacje

Oprócz danych głównej tabeli dane zwracane przez interfejs API zawierają pewne ogólne informacje dotyczące odpowiedzi. Możesz ją wydrukować, używając:

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ż opisuje, czy odpowiedź interfejsu API została spróbkowana. Próbkowanie może wpłynąć na wyniki Twoich danych oraz częstą przyczynę braku wartości zwracanych przez interfejs API. Więcej informacji znajdziesz w przewodniku po próbkach próbkowania.

Wyświetlanie informacji (profil)

Każda odpowiedź zawiera grupę parametrów, które wskazują konto, usługę internetową i widok danych (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 API zarządzania Google Analytics. Możesz używać tych identyfikatorów do tworzenia zapytań dotyczących interfejsu API do zarządzania, aby uzyskać dodatkowe informacje o konfiguracji tego widoku (profilu). Możesz na przykład wysłać zapytanie do kolekcji celów interfejsu Management API, aby sprawdzić, które cele są aktywne wraz ze skonfigurowanymi nazwami celów.

Informacje o zapytaniu

Każda odpowiedź interfejsu Core Reporting API 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 jako ciągi znaków.

Informacje o podziału na strony

Każde żądanie dotyczące interfejsu Core Reporting API może odpowiadać setkom tysięcy wierszy danych Google Analytics. Interfejs Core Reporting API w określonym czasie zwróci podzbiór danych, który można określić jako jedną stronę danych. Korzystając z pól podziału na strony, można pobrać wszystkie strony z danymi.

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 reprezentuje łączną liczbę wierszy danych pasujących do zapytania w Google Analytics. Ta wartość może być większa od rzeczywistej liczby wierszy zwróconych na jednej stronie odpowiedzi. Pole itemsPerPage określa liczbę wierszy zwracanych na tej stronie.

Parametry previousLink i nextLink występują tylko wtedy, gdy istnieje poprzednia lub następna strona. Sprawdź, czy możesz pobrać więcej stron danych z interfejsu Core Reporting API.

Łącznie dla wszystkich wyników

Jak wspomnieliśmy powyżej w sekcji o podziale na strony, zapytanie kierowane do interfejsu Core Reporting API może odpowiadać wielu wierszom danych w Google Analytics, ale zwraca tylko podzbiór danych. Wszystkie wartości wskaźników dla wszystkich pasujących wierszy są zwracane w obiekcie totalsForAllResults. Te dane są przydatne przy obliczaniu średnich.

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 do pracy

Aby zobaczyć pełne działające próbki, zapoznaj się z przykładowym interfejsem Core Reporting API w każdej bibliotece klienta.

Java

Biblioteka klienta Java w interfejsie API Google Przykład interfejsu Core Reporting API

Python

Biblioteka klienta Google API w Pythonie Przykład interfejsu Core Reporting API

PHP

Biblioteka klienta PHP interfejsu API Google Przykład interfejsu Core Reporting API

JavaScript

Biblioteka klienta JavaScript interfejsu API Google Przykład interfejsu Core Reporting API

Źródło JavaScriptu