API Reporting sur les entonnoirs multicanaux – Guide du développeur

Ce document explique comment utiliser l'API de création de rapports sur les entonnoirs multicanaux pour accéder aux données des entonnoirs multicanaux.

Introduction

L'API de création de rapports sur les entonnoirs multicanaux permet d'accéder aux données tabulaires dans les rapports standards et personnalisés sur les entonnoirs multicanaux. 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 de création de rapports sur les entonnoirs multicanaux. Celle-ci renvoie toutes les données sous la forme d'une table.

Si vous ne connaissez pas l'API, consultez la page Présentation de l'API de création de rapports sur les entonnoirs multicanaux pour en savoir plus sur les fonctionnalités de cette API et sur les données qu'elle fournit.

Avant de commencer

Ce guide utilise la bibliothèque cliente Java pour accéder à l'API de création de rapports sur les entonnoirs multicanaux. Chaque bibliothèque cliente fournit un objet de service Analytics permettant d'appeler l'API de création de rapports sur les entonnoirs multicanaux afin d'obtenir les données. Si vous n'utilisez pas de bibliothèque cliente pour accéder à l'API, consultez le guide de référence de l'API sur les entonnoirs multicanaux.

Pour créer l'objet de service Analytics:

  1. Enregistrez votre application dans la console Google APIs.
  2. Autorisez l'accès aux données Google Analytics.
  3. Rédigez le code permettant de créer l'objet de service Analytics.

Si vous n'avez pas suivi ces étapes, arrêtez et lisez le tutoriel de l'API Hello Analytics, qui vous guide à travers les étapes initiales de la création d'une application API Google Analytics. Une fois le tutoriel terminé, poursuivez la lecture de ce guide.

Par exemple, le code suivant crée un objet de service Analytics autorisé :

Java

Analytics analytics = initializeAnalytics();

Utilisez l'objet de service Analytics analytics pour appeler l'API de création de rapports sur les entonnoirs multicanaux.

Présentation

Pour utiliser l'API de création de rapports sur les entonnoirs multicanaux afin de récupérer les données, écrivez une application pour:

  1. Interrogez l'API de création de rapports sur les entonnoirs multicanaux.
  2. Utiliser les résultats renvoyés par l'API

Interroger l'API de création de rapports sur les entonnoirs multicanaux

Pour demander des données à l'aide de l'API de création de rapports sur les entonnoirs multicanaux:

  1. Créez un objet de requête API Reporting Reporting pour les entonnoirs multicanaux.
  2. Utilisez l'objet de requête pour demander les données aux serveurs d'entonnoirs multicanaux.

Créer une requête API Reporting sur les entonnoirs multicanaux

Pour créer un objet de requête pour l'API de création de rapports sur les entonnoirs multicanaux, appelez cette méthode:

analytics.data.mcf.get()    // analytics is the Analytics service object

Le premier paramètre fourni à la méthode est un ID de table unique sous la forme ga:XXXX, où XXXX correspond à l'ID d'une vue (profil) Analytics qui contient les données demandées. Utilisez l'objet de requête pour spécifier des paramètres de requête setDimensions). Par exemple:

Java

Get apiQuery = analytics.data().mcf()
    .get(tableId,
        "2012-01-01",              // Start date
        "2012-03-31",              // End date
        "mcf:totalConversions")    // Metrics
    .setDimensions("mcf:sourcePath")
    .setSort("-mcf:totalConversions")
    .setMaxResults(25);

Pour obtenir la liste de tous les paramètres de requête, consultez la page Récapitulatif des paramètres de requête. Les paramètres des métriques et des dimensions vous permettent de spécifier les données des entonnoirs multicanaux à récupérer. Pour obtenir la liste de toutes les dimensions et métriques, consultez la documentation de référence sur les dimensions.

Envoyer une requête de données à l'API de création de rapports sur les entonnoirs multicanaux

Après avoir créé l'objet de requête, appelez la méthode execute sur l'objet pour demander des données aux serveurs d'entonnoirs multicanaux. Exemple :

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 brute à l'API, appelez la méthode executeUnparsed() sur l'objet de requête:

HttpResponse response = apiQuery.executeUnparsed();

Si la requête aboutit, elle renvoie les données demandées. Si une erreur se produit, la méthode execute génère une exception contenant un code d'état et une description de l'erreur. L'application doit intercepter et gérer l'exception.

Utiliser les résultats de l'API

Si la requête de l'API de création de rapports sur les entonnoirs multicanaux aboutit, elle renvoie les données de rapport et des informations sur ces données.

Données des rapports sur les entonnoirs multicanaux

La requête renvoie les données de rapport tabulaires suivantes:

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

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

La réponse à la requête comporte un champ d'en-tête de colonne qui contient les informations de l'en-tête de la table. Le champ est une liste (ou un tableau) d'objets ColumnHeaders, chacun contenant un nom de colonne, un type de colonne et un type de données de 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. Par exemple, la méthode suivante imprime les en-têtes de colonnes:

Java

private static void printColumnHeaders(McfData mcfData) {
  System.out.println("Column Headers:");

  for (ColumnHeaders header : mcfData.getColumnHeaders()) {
    System.out.println("Column Name: " + header.getName());
    System.out.println("Column Type: " + header.getColumnType());
    System.out.println("Column Data Type: " + header.getDataType());
  }
}

Données de ligne

Les données principales renvoyées par l'API sont renvoyées sous la forme d'un List bidimensionnel de McfData.Rows. Chaque McfData.Rows représente une seule cellule, qui correspond soit à une valeur primitive de type String, soit à une valeur de chemin de conversion de type McfData.Rows.ConversionPathValue. 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 ou de type de séquence d'entonnoirs multicanaux, le champ DataType dans chaque objet d'en-tête de colonne est particulièrement utile pour analyser les valeurs dans les types appropriés. Consultez le guide de référence pour découvrir tous les types de données possibles.

Par exemple, la méthode suivante imprime les en-têtes et les lignes du tableau:

Java

private static void printDataTable(McfData mcfData) {
  System.out.println("Data Table:");
  if (mcfData.getTotalResults() > 0) {
    // Print the column names.
    List<ColumnHeaders> headers = mcfData.getColumnHeaders();
    for (ColumnHeaders header : headers) {
      System.out.print(header.getName());
    }
    System.out.println();

    // Print the rows of data.
    for (List<McfData.Rows> row : mcfData.getRows()) {
      for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
        ColumnHeaders header = headers.get(columnIndex);
        McfData.Rows cell = row.get(columnIndex);
        if (header.getDataType().equals("MCF_SEQUENCE")) {
          System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
        } else {
          System.out.print(cell.getPrimitiveValue());
        }
      }
      System.out.println();
    }
  } else {
    System.out.println("No rows found");
  }
}

L'exemple suivant montre comment analyser un objet Type de séquence d'entonnoirs multicanaux et le convertir en chaîne:

Java

private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
  StringBuilder stringBuilder = new StringBuilder();
  for (McfData.Rows.ConversionPathValue pathElement : path) {
    if (stringBuilder.length() > 0)
      stringBuilder.append(" > ");
    stringBuilder.append(pathElement.getNodeValue());
  }
  return stringBuilder.toString();
}

Informations sur le rapport

En plus des données de rapport, la requête renvoie des informations sur les données (par exemple, l'ID du rapport). Par exemple, la méthode suivante imprime les informations du rapport:

Java

private static void printReportInfo(McfData mcfData) {
  System.out.println("Report Info:");
  System.out.println("ID:" + mcfData.getId());
  System.out.println("Self link: " + mcfData.getSelfLink());
  System.out.println("Kind: " + mcfData.getKind());
  System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}

Le champ containsSampledData indique si la réponse à la requête a été échantillonnée. Étant donné que l'échantillonnage peut affecter les résultats de la requête, les valeurs échantillonnées renvoyées par la requête (API) ne correspondent pas à celles affichées sur l'interface Web. Pour en savoir plus, consultez la section Échantillonnage.

Afficher les informations (profil)

La réponse à la requête inclut l'ID de propriété Web, le nom et l'ID de la vue (profil) et l'ID du compte Analytics contenant la vue (profil). Par exemple, la méthode suivante les affiche dans le terminal (sortie standard):

Java

private static void printProfileInfo(McfData mcfData) {
  ProfileInfo profileInfo = mcfData.getProfileInfo();

  System.out.println("View (Profile) Info:");
  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());
}

Informations sur la requête

La réponse à la requête inclut un objet Query qui contient les valeurs de tous les paramètres de requête de données. Par exemple, la méthode suivante affiche les valeurs de ces paramètres:

Java

private static void printQueryInfo(McfData mcfData) {
  Query query = mcfData.getQuery();

  System.out.println("Query Info:");
  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 of Analytics metrics
  System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
  System.out.println("Sort: " + query.getSort());             // List of sorte metrics or dimensions
  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());
}

Les méthodes autres que query.getMetrics(), query.getDimensions() et query.getSort() renvoient un String. Par exemple, query.getStartDate() renvoie la date de début (String) du rapport.

Informations de pagination

Toute demande de l'API de création de rapports sur les entonnoirs multicanaux peut correspondre à des centaines de milliers de lignes de données. L'API de création de rapports sur les entonnoirs multicanaux ne renvoie qu'un sous-ensemble de données, à savoir une seule page de données à la fois. Pour récupérer toutes les pages de données, utilisez le champ de pagination. La méthode suivante imprime les informations de pagination:

Java

private static void printPaginationInfo(McfData mcfData) {
  System.out.println("Pagination Info:");
  System.out.println("Previous Link: " + mcfData.getPreviousLink());
  System.out.println("Next Link: " + mcfData.getNextLink());
  System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
  System.out.println("Total Results: " + mcfData.getTotalResults());
}

L'appel de méthode mcfData.getTotalResults() renvoie le nombre total de lignes pour la requête, qui peut être supérieur au nombre total de lignes renvoyées par la requête. Et l'appel de méthode mcfData.getItemsPerPage() renvoie le nombre maximal de lignes que la réponse à la requête peut contenir.

L'appel de méthode mcfData.getPreviousLink() renvoie le lien vers la page précédente et mcfData.getNextLink() renvoie le lien vers la page suivante.

Totaux pour tous les résultats

Pour obtenir le total des valeurs des métriques demandées pour tous les résultats, pas seulement les résultats renvoyés dans la réponse à la requête, appelez la méthode getTotalsForAllResults() sur la réponse à la requête, un objet McfData. Utilisez les valeurs totales pour calculer les moyennes.

Java

private static void printTotalsForAllResults(McfData mcfData) {
  System.out.println("Metric totals over all results:");
  Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
  for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Échantillon de travail

Java

Bibliothèque cliente Java de l'API Google Exemple d'API de création de rapports sur les entonnoirs multicanaux