Accès automatisé aux données Google Analytics dans Google Sheets

Nick Mihailovski, équipe API Google Analytics – Août 2012

Ce tutoriel explique comment accéder aux API de gestion et de création de rapports principales dans Google Sheets à l'aide d'Apps Script.


Introduction

Vous pouvez utiliser l'API Google Analytics et Google Apps Script pour accéder à vos données Google Analytics à partir de Google Sheets. Elle est extrêmement efficace, car elle vous permet d'exploiter toutes les fonctionnalités intéressantes de Google Sheets avec vos données d'analyse, telles que les outils de partage, de collaboration, de création de graphiques et de visualisation en toute simplicité.

Ce tutoriel vous présente le code nécessaire pour accéder à vos données Google Analytics dans Google Sheets à l'aide de Google Apps Script.

Présentation

Ce tutoriel vous explique comment enregistrer et configurer l'environnement Apps Script pour utiliser l'API Google Analytics. Une fois configuré, le tutoriel vous explique comment récupérer un ID de vue (de profil) pour l'utilisateur autorisé à l'aide de l' API Management. Découvrez ensuite comment utiliser l'ID de vue (profil) pour interroger l' API Core Reporting et extraire de Google les 250 principaux mots clés de la recherche pour mobile. Enfin, les résultats seront insérés dans une feuille de calcul Google. Une fois que vous disposez de données, le tutoriel explique également comment automatiser leur récupération.

Lorsque vous créez une application à l'aide de l'API Google Analytics et d'Apps Script, vous devez généralement suivre les étapes suivantes:

  • Activer les API Google Analytics dans Google Sheets
  • Utiliser les API Google Analytics

Examinons chaque étape en détail.

Activer l'API Google Analytics dans Apps Script

Pour autoriser l'accès à vos données Google Analytics à partir de Google Sheets, procédez comme suit:

  1. Créez un fichier Google Sheets. Donnez-lui un nom cool.
  2. Créez un script Apps Script.
    1. Dans le menu, accédez à Extensions > Apps Script.
    2. Si un menu s'affiche, cliquez simplement sur Blank Project (Projet vide).
    3. Attribuez un nom au projet. Assurez-vous qu'il porte un nom cool.

Une fois que vous disposez d'un nouveau script, vous devez activer le service Google Analytics.

  1. Dans l'éditeur de scripts, sélectionnez Ressources > Services avancés Google.
  2. Dans la boîte de dialogue qui s'affiche, cliquez sur le bouton d'activation/de désactivation à côté de l'API Google Analytics.
  3. Au bas de la boîte de dialogue, cliquez sur le lien de la Google Developers Console.
  4. Dans la nouvelle console, cliquez de nouveau sur le bouton Activé/Désactivé situé à côté de l'API Google Analytics. (Une fois la fonctionnalité activée, elle s'affichera en haut de la page.)
  5. Revenez à l'éditeur de script et cliquez sur OK dans la boîte de dialogue.

Une petite boîte de dialogue jaune doit s'afficher pour vous indiquer que vous avez ajouté un service d'API Google à votre script. Vous êtes maintenant prêt à commencer à écrire votre premier script.

Utiliser l'API Google Analytics

Le script de ce tutoriel interroge l'API Google Analytics pour obtenir les 250 principaux mots clés de la recherche pour mobile Google, puis affiche les résultats dans Google Sheets. Pour ce faire, le script doit suivre les étapes suivantes:

  • Récupérez la première vue (profil) de l'utilisateur autorisé.
  • Interrogez l'API Core Reporting pour obtenir des données.
  • Insérer des données dans une feuille de calcul

Ajoutez la fonction suivante au projet vide.

function runDemo() {
  try {

    var firstProfile = getFirstProfile();
    var results = getReportDataForProfile(firstProfile);
    outputToSpreadsheet(results);

  } catch(error) {
    Browser.msgBox(error.message);
  }
}

Dans le code ci-dessus, un bloc try...catch est utilisé pour gérer les erreurs d'API. En cas d'erreur, l'exécution du programme s'interrompt et l'erreur s'affiche dans une zone de message. Dans le bloc try, une fonction est utilisée pour effectuer chacune des étapes par le script. Ajoutons maintenant le code de chacune de ces fonctions.

Récupérer la première vue (profil) de l'utilisateur autorisé

Dans Google Analytics, chaque rapport appartient à une vue (profil) et est identifié par un ID de vue (profil). Ainsi, lorsque vous spécifiez une requête pour des données de rapport, vous devez également spécifier l'ID de la vue (profil) à partir de laquelle vous souhaitez récupérer des données.

L' API de gestion de Google Analytics donne accès à l'ensemble des comptes, propriétés Web et entités de vue (profil) appartenant à un utilisateur. Chacune de ces entités appartient à une hiérarchie, et vous pouvez balayer cette hiérarchie de manière programmatique pour récupérer un ID de vue (profil) pour l'utilisateur autorisé.

La deuxième fonction que nous allons écrire balayera la hiérarchie de l'API Management et renverra la première vue (profil) de l'utilisateur. Copiez le code suivant et collez-le dans votre projet Apps Script:

function getFirstProfile() {
  var accounts = Analytics.Management.Accounts.list();
  if (accounts.getItems()) {
    var firstAccountId = accounts.getItems()[0].getId();

    var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
    if (webProperties.getItems()) {

      var firstWebPropertyId = webProperties.getItems()[0].getId();
      var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);

      if (profiles.getItems()) {
        var firstProfile = profiles.getItems()[0];
        return firstProfile;

      } else {
        throw new Error('No views (profiles) found.');
      }
    } else {
      throw new Error('No webproperties found.');
    }
  } else {
    throw new Error('No accounts found.');
  }
}

Dans cette fonction, la collection "Accounts" (Comptes) est d'abord interrogée à l'aide de la méthode Analytics.Management.Accounts.list. Si l'utilisateur autorisé possède des comptes Google Analytics, l'ID du premier compte est récupéré. Ensuite, la collection de propriétés Web est interrogée en appelant la méthode Analytics.Management.Webproperties.list et en transmettant à la méthode l'ID de compte récupéré à l'étape précédente. Si des propriétés Web existent, la collection de vues (profil) est finalement interrogée à l'aide de la méthode Analytics.Management.Profiles.list. L'ID de compte et les ID de propriété Web sont transmis en tant que paramètres à cette méthode. S'il existe des vues (profils), la première vue (profil) est renvoyée.

Si une erreur d'API se produit, ou si la réponse de l'API ne contient aucun résultat, une erreur est générée et un message indique qu'aucun résultat n'a été trouvé. Le bloc catch dans la fonction runDemo ci-dessus intercepte cette erreur et affiche le message auprès de l'utilisateur.

Une fois le script renvoyé, il peut interroger les données de rapport.

Interrogez l'API Core Reporting pour obtenir des données.

Une fois que vous disposez d'un ID de vue (profil), utilisez l'API principale de création de rapports pour interroger les données de rapport Google Analytics. Dans cette section, vous allez apprendre à interroger cette API à l'aide d'Apps Script.

Ajoutez le code suivant à votre projet Apps Script:

function getReportDataForProfile(firstProfile) {

  var profileId = firstProfile.getId();
  var tableId = 'ga:' + profileId;
  var startDate = getLastNdays(14);   // 2 weeks (a fortnight) ago.
  var endDate = getLastNdays(0);      // Today.

  var optArgs = {
    'dimensions': 'ga:keyword',              // Comma separated list of dimensions.
    'sort': '-ga:sessions,ga:keyword',       // Sort by sessions descending, then keyword.
    'segment': 'dynamic::ga:isMobile==Yes',  // Process only mobile traffic.
    'filters': 'ga:source==google',          // Display only google traffic.
    'start-index': '1',
    'max-results': '250'                     // Display the first 250 results.
  };

  // Make a request to the API.
  var results = Analytics.Data.Ga.get(
      tableId,                    // Table id (format ga:xxxxxx).
      startDate,                  // Start-date (format yyyy-MM-dd).
      endDate,                    // End-date (format yyyy-MM-dd).
      'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
      optArgs);

  if (results.getRows()) {
    return results;

  } else {
    throw new Error('No views (profiles) found');
  }
}

function getLastNdays(nDaysAgo) {
  var today = new Date();
  var before = new Date();
  before.setDate(today.getDate() - nDaysAgo);
  return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}

La première partie du code construit une requête de l'API Core Reporting à l'aide de la méthode Analytics.Data.Ga.get. Cette méthode accepte un grand nombre de paramètres qui spécifient le type de rapport à récupérer. Chaque requête de l'API Core Reporting se compose d'un ensemble de paramètres obligatoires et facultatifs. Les paramètres requis sont transmis à la méthode en tant que paramètres, tandis que les paramètres facultatifs sont transmis en tant qu'objet.

Le paramètre table ID est obligatoire. Il est formé en combinant le préfixe ga: avec l'ID de la vue (profil). Le code crée l'ID de table à l'aide de l'ID de vue (profil) récupéré à l'étape précédente. Les dates de début et de fin sont également obligatoires et spécifient la plage de dates des données à récupérer. Les deux sont calculés en fonction de la date du jour à l'aide de la fonction getLastNdays. Enfin, tous les paramètres facultatifs sont transmis à la fonction à l'aide de l'objet optArgs.

Lorsque la méthode Analytics.Data.Ga.get s'exécute, une requête est envoyée à l'API Core Reporting. Si une erreur se produit, elle est détectée dans le bloc try...catch défini dans la méthode runDemo externe. Si la requête a abouti, les résultats sont renvoyés.

Insérer des données dans une feuille de calcul

La dernière étape de notre script consiste à générer les résultats de l'API Core Reporting dans Google Sheets. La méthode outputToSpreadsheet effectue cette opération. Ajoutez le code suivant à votre projet:

function outputToSpreadsheet(results) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Print the headers.
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  sheet.getRange(1, 1, 1, headerNames.length)
      .setValues([headerNames]);

  // Print the rows of data.
  sheet.getRange(2, 1, results.getRows().length, headerNames.length)
      .setValues(results.getRows());
}

Cette fonction insère d'abord une nouvelle feuille dans la feuille de calcul active. Toutes les données d'en-tête et de rapport sont ensuite insérées dans la feuille. Pour obtenir d'autres conseils sur l'insertion de données dans Google Sheets, consultez la section Écrire des données à partir d'objets JavaScript dans une feuille de calcul du tutoriel sur le stockage de données dans des feuilles de calcul.

Exécuter le script

Une fois que vous avez ajouté tout le code au projet, vous pouvez l'exécuter.

  • Dans la barre d'outils de l'éditeur de script, dans le menu déroulant "Sélectionner une fonction", sélectionnez runDemo.
  • Cliquez ensuite sur le bouton play.

La première fois que vous exécutez cette commande, une fenêtre pop-up s'affiche. Elle vous invite à autoriser ce script à accéder aux données de votre compte Google Analytics.

Cliquez sur "Autoriser".

Lorsque vous cliquez dessus, une nouvelle page hébergée sur google.com s'ouvre et vous invite à autoriser ce script à accéder à vos données. Après avoir cliqué sur "Autoriser", vous serez redirigé vers une page de confirmation. À ce stade, le script peut accéder à vos données Google Analytics et continuer de s'exécuter.

Une fois le script exécuté, cliquez sur la fenêtre contenant Google Sheets. Vous devriez voir toutes les données de mots clés renvoyées par l'API ou une boîte de message avec un message d'erreur.

Automatiser le script

À ce stade, vous devez disposer d'un script qui interroge l'API Google Analytics. Vous pouvez maintenant automatiser ce script pour récupérer de nouvelles données chaque nuit. Apps Script facilite considérablement l'automatisation grâce à la fonctionnalité triggers.

Pour automatiser ce script, procédez comme suit:

  • Dans la barre d'outils de l'éditeur de script, cliquez sur Resources -> All your triggers....
  • Cliquez sur Add a new trigger. La boîte de dialogue des déclencheurs s'affiche.
  • Configurez le déclencheur pour qu'il exécute la méthode runDemo chaque nuit.
    • Le menu déroulant Run doit être défini sur: runDemo
    • Le menu déroulant Events doit être défini sur Time-driven, Day timer et Midnight to 1am.

Une fois configuré, ce script s'exécutera toutes les nuits, et vous obtiendrez de nouvelles données le matin.

Si des erreurs se produisent la nuit, vous voudrez en être informé. Apps Script vous permet également d'envoyer une alerte par e-mail en cas d'échec. Pour ce faire, dans la boîte de dialogue "Déclencheurs", cliquez sur le lien notifications. Une nouvelle boîte de dialogue s'affiche. Elle vous permet de configurer l'adresse e-mail à laquelle vous souhaitez que les erreurs soient envoyées.

Conclusion

vous avez bien enregistré votre script et autorisé l'accès à celui-ci. Vous avez interrogé l'API Management à plusieurs reprises pour récupérer un ID de vue (profil). Vous avez ensuite utilisé l'ID de vue (profil) pour interroger l'API Core Reporting afin de récupérer des données et les générer dans Google Sheets.

L'utilisation des techniques décrites dans le tutoriel vous permettra d'effectuer des analyses plus complexes, d'obtenir des insights plus complets, de créer des tableaux de bord personnalisés et de réduire le temps nécessaire à l'exécution de rapports manuels.

Voici d'autres tutoriels intéressants qui vous aideront à tirer le meilleur parti de l'API Google Analytics et de Google Apps Script: