API de création de rapports 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 sur les entonnoirs multicanaux.

Introduction

L'API de création de rapports sur les entonnoirs multicanaux permet d'accéder aux données tabulaires des 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 constituent 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, qui renvoie toutes les données sous forme de tableau.

Si vous débutez avec l'API, consultez la présentation de l'API de création de rapports sur les entonnoirs multicanaux pour en savoir plus sur l'objectif 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 seul objet de service Analytics pour 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 de création de rapports 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. Écrivez du code pour créer l'objet de service Analytics.

Si vous n'avez pas effectué ces étapes, arrêtez et lisez le tutoriel sur l'API Hello Analytics, qui vous guide tout au long des étapes initiales de création d'une application à l'aide de l'API Google Analytics. Une fois le tutoriel terminé, poursuivez la lecture du guide suivant.

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

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 récupérer des données à l'aide de l'API de création de rapports sur les entonnoirs multicanaux, écrivez une application:

1. Envoyer une requête à l'API de création de rapports sur les entonnoirs multicanaux.
2. Utilisez 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'API de création de rapports sur les entonnoirs multicanaux:

1. Créer un objet de requête de l'API de création de rapports sur les entonnoirs multicanaux
2. Utilisez l'objet de requête pour demander les données aux serveurs des entonnoirs multicanaux.

Créer une requête dans l'API de création de rapports sur les entonnoirs multicanaux

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

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

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

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 de métriques et de 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 et les métriques.

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 :

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

HttpResponse response = apiQuery.executeUnparsed();

Si la requête aboutit, les données demandées sont renvoyées. Si une erreur se produit, la méthode execute génère une exception contenant un code d'état et une description pour 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 Reporting sur les entonnoirs multicanaux aboutit, elle renvoie les données du 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 des lignes

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 d'en-tête de table. Le champ est une liste (ou un tableau) d'objets ColumnHeaders, chacun contenant le nom de la colonne, le type de colonne et le type de données de la colonne. L'ordre des colonnes se compose des colonnes de dimensions, suivies des 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:

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 des lignes

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 est soit une valeur primitive de type String, soit une valeur de chemin de conversion de type McfData.Rows.ConversionPathValue. L'ordre des cellules sur une ligne est le même que celui des champs de l'objet d'en-tête de colonne décrit ci-dessus.

Étant donné que les données de chaque cellule sont renvoyées sous forme de chaîne ou de type de séquence d'entonnoirs multicanaux, le champ DataType de chaque objet d'en-tête de colonne est particulièrement utile pour analyser les valeurs en types appropriés. Consultez le guide de référence pour connaître tous les types de données possibles.

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

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 de type de séquence d'entonnoirs multicanaux et le convertir en chaîne:

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

Signaler des informations

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

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 vous 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 sur le (profil)

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

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 requête de données. Par exemple, la méthode suivante imprime les valeurs de ces paramètres:

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 (un String) du rapport.

Informations de pagination

Toute requête de l'API Reporting sur les entonnoirs multicanaux peut correspondre à des centaines de milliers de lignes de données sur les entonnoirs multicanaux. L'API de création de rapports sur les entonnoirs multicanaux ne renvoie qu'un sous-ensemble, appelé page unique des données, à un moment donné. Pour récupérer toutes les pages de données, utilisez le champ de pagination. La méthode suivante imprime les informations de pagination:

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 de la requête, qui peut être supérieur au nombre total de lignes renvoyées par la requête. 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 de tous les résultats

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

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

Exemple de travail