API Core Reporting - Guide du développeur

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Ce document explique comment utiliser l'API Core Reporting pour accéder aux données Google Analytics.

Introduction

L'API Core Reporting permet d'accéder aux données tabulaires dans les rapports standards et personnalisés de Google Analytics. Pour accéder aux données, vous créez une requête qui spécifie la vue (profil), les dates de début et de fin, ainsi que les dimensions et les métriques qui composent les en-têtes de colonne du tableau. Cette requête est envoyée à l'API Core Reporting, et cette dernière renvoie toutes les données sous la forme d'une table.

Si vous débutez avec l'API Core Reporting, consultez la page Présentation de l'API Core Reporting pour découvrir son fonctionnement et les données qu'elle fournit.

Avant de commencer

Ce guide explique comment accéder à l'API Google Analytics à l'aide des langages de programmation Java, Python, PHP et JavaScript.

  • Consultez la page Bibliothèques clientes pour obtenir la liste complète des bibliothèques clientes de langage de programmation compatibles avec l'API.
  • Consultez le guide de référence pour accéder à l'API sans bibliothèque cliente.

Chaque bibliothèque cliente fournit un objet de service d'analyse unique permettant d'accéder à toutes les données de l'API Core Reporting. Pour créer l'objet de service, vous devez généralement suivre la procédure suivante:

  1. Enregistrez votre application dans la console Google APIs.
  2. Autorisez l'accès aux données Google Analytics.
  3. Créer un objet de service Analytics

Si vous n'avez pas effectué ces étapes, veuillez arrêter et lire le tutoriel sur l'API Google Analytics Hello. Ce tutoriel vous explique les premières étapes de la création d'une application API Google Analytics. Une fois l'opération terminée, vous pourrez utiliser ce guide pour effectuer des tâches réelles.

L'extrait de code suivant contient une variable permettant de stocker un objet de service autorisé.

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);

La bibliothèque PHP renvoie tous les résultats d'API sous forme de tableau associatif. Pour renvoyer des objets réels, vous pouvez appeler la méthode useObject du client, comme illustré dans l'exemple ci-dessus.

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>

Le premier tag de script charge la bibliothèque JavaScript de l'API Google. Une fois chargé, loadLib s'exécute pour charger la classe de service d'analyse. Une fois l'opération terminée, l'objet gapi.client.analytics doit exister dans le DOM et être prêt à être utilisé pour interroger l'API Core Reporting.

Une fois que vous avez créé un objet de service d'analyse, vous pouvez envoyer des requêtes à l'API Core Reporting.

Remarque: L'objet de service d'analyse peut également être utilisé pour accéder à l'API Management.

Présentation

Une application qui utilise l'API Core Reporting suit généralement deux étapes:

  • Interroger l'API Core Reporting
  • Utiliser les résultats de l'API

Examinons les deux étapes.

Interroger l'API Core Reporting

Créer une requête API Core Reporting

L'objet de service d'analyse contient une méthode pour créer une requête API Core Reporting.

Chaque requête de l'API Core Reporting contient un ensemble de paramètres qui spécifient les données à renvoyer.

L'un des paramètres de requête les plus importants est le paramètre ids, ou ID de la table. Ce paramètre spécifie à partir de quelle vue (profil) Google Analytics récupérer les données. La valeur est au format ga:xxx, où xxx correspond à l'ID de la vue (profil).

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);
}

Dans cette bibliothèque, la méthode get crée non seulement une requête API Core Reporting, mais exécute également la requête adressée à l'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
  });
  // ...
}

Dans cet exemple, la fonction makeApiCall est appelée une fois la bibliothèque cliente JavaScript chargée. Dans celle-ci, la fonction crée une requête API Google Analytics et stocke l'objet dans la variable apiQuery.

La liste complète des paramètres de requête et de leur fonctionnement est disponible dans le Guide de référence de l'API Core Reporting. De plus, les paramètres de dimensions et de métriques vous permettent de spécifier les données à extraire de Google Analytics. Pour obtenir la liste complète, consultez la page de référence Dimensions et métriques.

Envoyer une demande de données de l'API Core Reporting

Une fois qu'une requête est définie, vous appelez la méthode execute pour envoyer la requête aux serveurs 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();
}

Si vous préférez accéder à la réponse d'API brute, utilisez la méthode 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);
  }
}

Cet exemple fait suite à l'étape précédente de création d'une requête API Core Reporting. Au cours de cette étape, la requête est exécutée. Le paramètre de la méthode execute est une référence à une fonction de rappel qui sera exécutée une fois les données renvoyées par l'API.

Une fois que l'API renvoie des résultats, la fonction de rappel est exécutée et transmet les données à partir de l'API. Si une erreur se produit, les résultats contiendront une propriété nommée error.

Dans cet exemple, une vérification est effectuée pour voir si error existe ou si l'API a bien été renvoyée.

Si la requête aboutit, l'API renvoie les données demandées. En cas d'erreur, l'API renvoie un code d'état spécifique et un message décrivant l'erreur. Toutes les applications doivent intercepter et gérer correctement les erreurs.

Utiliser les résultats de l'API

Si la requête API Core Reporting a abouti, l'API renvoie les données de rapport Analytics, ainsi que d'autres informations associées sur les données.

Données des rapports Analytics

Les données principales renvoyées par l'API peuvent être considérées comme une table avec deux types de données principaux:

  • En-tête décrivant les types de valeurs de chaque colonne
  • Lignes de données du tableau

Données d'en-tête de colonne

Chaque réponse de l'API contient un champ d'en-tête de colonne qui représente les informations d'en-tête de la table. Le champ est une liste (ou un tableau) d'objets dans laquelle chaque objet décrit le type de données de la colonne. L'ordre des colonnes correspond aux colonnes de dimensions, qui sont suivies de colonnes de métriques, dans le même ordre que celui spécifié dans la requête d'origine.

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(''));
}

Données de ligne

Les données principales renvoyées par l'API sont renvoyées sous la forme d'une chaîne List à deux dimensions. La liste externe représente toutes les lignes de données. Chaque liste interne représente une seule ligne, dans laquelle l'ordre des cellules dans une ligne est identique à celui des champs de l'objet d'en-tête de colonne décrit ci-dessus.

Les données de chaque cellule étant renvoyées sous forme de chaîne, le champ DataType dans chaque objet d'en-tête de colonne est particulièrement utile, car il peut être utilisé pour analyser les valeurs de chaîne dans un type approprié. Consultez la réponse de l'API de métadonnées pour tous les types de données possibles.

Les exemples suivants impriment les en-têtes et les lignes du tableau.

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(''));
}

Informations sur le rapport

En plus des données du tableau principal, les données renvoyées par l'API contiennent des informations générales sur la réponse. Vous pouvez l'imprimer avec:

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(''));
}

Le champ containsSampledData est important, car il indique si la réponse de l'API a été échantillonnée. L'échantillonnage peut avoir une incidence sur les résultats de vos données et sur la raison courante pour laquelle les valeurs renvoyées par l'API ne correspondent pas à l'interface Web. Pour en savoir plus, consultez le guide conceptuel Échantillonnage.

Afficher les informations (profil)

Chaque réponse contient un groupe de paramètres indiquant le compte, la propriété Web et la vue (profil) auxquels ces données appartiennent.

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(''));
}

Chacun de ces ID correspond à différentes entités dans la hiérarchie de l'API Management. Vous pouvez utiliser ces ID pour former des requêtes d'API Management afin d'obtenir des informations de configuration supplémentaires sur la vue (profil). Par exemple, vous pouvez interroger la collection d'objectifs de l'API Management pour voir les objectifs actifs et leurs noms d'objectif configurés.

Informations sur la requête

Chaque réponse de l'API Core Reporting contient un objet contenant toutes les valeurs des paramètres de requête utilisées pour créer la réponse.

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(''));
}

Les paramètres metrics et sort sont renvoyés sous forme de valeurs dans une liste, tandis que les autres paramètres sont renvoyés sous forme de chaînes.

Informations de pagination

Toute demande de l'API Core Reporting peut correspondre à des centaines de milliers de lignes de données Google Analytics. L'API Core Reporting ne renvoie qu'un sous-ensemble à un moment donné, c'est-à-dire une seule page de données. Vous pouvez utiliser les champs de pagination pour récupérer toutes les pages de données.

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(''));
}

Le champ totalResults représente le nombre total de lignes de données correspondant à votre requête dans Google Analytics. Ce nombre peut être supérieur au nombre réel de lignes renvoyées dans une seule page de la réponse. Le champ itemsPerPage représente le nombre de lignes renvoyées sur cette page.

Les paramètres previousLink et nextLink ne sont présents que s'il existe une page précédente ou suivante. Consultez ces liens pour savoir si d'autres pages de données peuvent être récupérées à partir de l'API Core Reporting.

Totaux pour tous les résultats

Comme indiqué dans la section Informations sur la pagination ci-dessus, une requête envoyée à l'API Core Reporting peut correspondre à de nombreuses lignes de données dans Google Analytics, mais ne renvoie qu'un sous-ensemble de données. Le nombre total de valeurs de métriques pour toutes les lignes correspondantes est renvoyé dans l'objet totalsForAllResults. Ces données sont utiles pour calculer les moyennes.

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(''));
}

Échantillons de travail

Pour voir les exemples de travail complets, consultez l'exemple d'API Core Reporting dans chaque répertoire de modèle de la bibliothèque cliente.

Java

Bibliothèque cliente des API Google pour Java Exemple d'API Core Reporting

Python

Bibliothèque cliente Python de l'API Google Exemple d'API Core Reporting

PHP

Bibliothèque cliente des API Google pour PHP Exemple d'API Core Reporting

JavaScript

Bibliothèque cliente des API JavaScript de Google : Exemple d'API Core Reporting

Source JavaScript