API Reporting sur les entonnoirs multicanaux : Guide de référence

Ce document fournit des informations de référence complètes sur les requêtes et les réponses de l'API de création de rapports sur les entonnoirs multicanaux.

Introduction

L'API de création de rapports sur les entonnoirs multicanaux vous permet de demander des données de rapport sur les entonnoirs multicanaux Google Analytics. Chaque rapport se compose de statistiques issues des données que le code de suivi renvoie à Analytics, organisées en tant que dimensions et métriques. En choisissant vos propres combinaisons de dimensions et de métriques, vous pouvez utiliser l'API Reporting pour créer des rapports personnalisés et adaptés à vos propres spécifications.

L'API contient une seule méthode qui demande des données de rapport: report.get. Avec cette méthode, vous fournissez l'ID de table correspondant à la vue (profil) pour laquelle vous souhaitez récupérer des données. Vous devez également spécifier les éléments suivants:

• Une combinaison de dimensions et de métriques.
• Une période.
• Ensemble de paramètres d'option qui contrôlent les données renvoyées

L'API rend la méthode report.get disponible à un point de terminaison REST : https://www.googleapis.com/analytics/v3/data/mcf. La section suivante présente un exemple de requête et décrit chacun des paramètres.

Demande

L'API fournit une seule méthode pour demander des données:

analytics.data.mcf.get()

L'API peut également être interrogée en tant que point de terminaison REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/mcf
  ?ids=ga:12345
  &metrics=mcf:totalConversions,mcf:totalConversionValue
  &start-date=2011-10-01
  &end-date=2011-10-31

Chaque paramètre de requête d'URL spécifie un paramètre de requête d'API qui doit être encodé au format URL.

Toutes les requêtes adressées à l'API de création de rapports sur les entonnoirs multicanaux doivent être autorisées, de préférence via OAuth 2.0.

Récapitulatif des paramètres de requête

Le tableau suivant récapitule tous les paramètres de requête acceptés par l'API de création de rapports sur les entonnoirs multicanaux. Cliquez sur chaque nom de paramètre pour obtenir une description détaillée.

Détails des paramètres de requête

ids

Haut de page

date de début

  &start-date=7daysAgo
  &end-date=yesterday

Haut de page

date de fin

  &start-date=9daysAgo
  &end-date=today

Haut de page

dimensions

Haut de page

métrique

Haut de page

sort

sort=mcf:source,mcf:medium

sort=mcf:medium,mcf:source

Haut de page

filtres

https://www.googleapis.com/analytics/v3/data/mcf
?ids=mcf:12134
&dimensions=mcf:source
&metrics=mcf:totalConversions
&filters=mcf:medium%3D%3Dreferral
&start-date=2011-10-01
&end-date=2011-10-31

Haut de page

Niveau d'échantillonnage

Haut de page

résultats max

Haut de page

Réponse

Si la requête aboutit, la requête renvoie un corps de réponse avec la structure JSON définie ci-dessous.

Remarque: Le terme"résultats"désigne l'ensemble des lignes correspondant à la requête, tandis que le terme"réponse"désigne l'ensemble des lignes renvoyées sur la page de résultats actuelle. Ils peuvent être différents si le nombre total de résultats est supérieur à la taille de la page pour la réponse actuelle, comme expliqué dans itemsPerPage.

Format de réponse

{
  "kind": "analytics#mcfData",
  "id": string,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "sort": [
      string
    ],
    "filters": string,
    "samplingLevel": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "selfLink": string,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "containsSampledData": boolean,
  "sampleSize": string,
  "sampleSpace": string,
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
  "rows": [
    [
      McfData.Rows
    ]
  ],
}

Haut de page

Champs de réponse

Les propriétés de la structure du corps de la réponse sont définies comme suit:

{
  "primitiveValue": "2183"
}

{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

Haut de page

Codes d'erreur

L'API de création de rapports sur les entonnoirs multicanaux renvoie un code d'état HTTP 200 si la requête aboutit. Si une erreur se produit lors du traitement d'une requête, l'API renvoie un code d'erreur et une description. Chaque application qui utilise l'API d'analyse doit mettre en œuvre la bonne logique de traitement des erreurs. Pour en savoir plus sur les codes d'erreur et sur la façon de les gérer, consultez le guide de référence sur les réponses d'erreur.

Haut de page

Haut de page

Échantillonnage

Google Analytics calcule instantanément certaines combinaisons de dimensions et de métriques. Pour renvoyer les données dans un délai raisonnable, Google Analytics ne peut traiter qu'un échantillon des données.

Vous pouvez spécifier le niveau d'échantillonnage à utiliser pour une requête en définissant le paramètre samplingLevel.

Si une réponse de l'API Reporting de MCF contient des données échantillonnées, le champ de la réponse containsSampledData sera true. En outre, deux propriétés fournissent des informations sur le niveau d'échantillonnage de la requête: sampleSize et sampleSpace. Ces deux valeurs permettent de calculer le pourcentage de sessions utilisées pour la requête. Par exemple, si sampleSize est 201,000 et sampleSpace est 220,000,le rapport est basé sur (201 000 / 220 000) * 100 = 91,36 % des sessions.

Pour obtenir une description générale de l'échantillonnage et de son utilisation dans Google Analytics, consultez la page Échantillonnage.

Haut de page

Gérer les résultats de données volumineux

Si vous pensez que votre requête renverra un ensemble de résultats volumineux, suivez les consignes ci-dessous pour optimiser votre requête API, éviter les erreurs et limiter les dépassements de quota. Notez que nous définissons un benchmark des performances en autorisant un maximum de sept dimensions et 10 métriques par requête API. Même si certaines requêtes spécifiant un grand nombre de métriques et de dimensions peuvent prendre plus de temps que d'autres, limiter le nombre de métriques demandées n'est pas suffisant pour améliorer les performances des requêtes. Pour des performances optimales, vous pouvez utiliser les techniques suivantes.

Réduire les dimensions par requête

L'API permet de spécifier jusqu'à sept dimensions par requête. Souvent, Google Analytics doit calculer les résultats de ces requêtes complexes à la volée. Cela peut prendre beaucoup de temps si le nombre de lignes obtenues est élevé. Par exemple, l'interrogation de mots clés par ville et par heure peut correspondre à des millions de lignes de données. Vous pouvez améliorer les performances en réduisant le nombre de lignes que Google Analytics doit traiter en limitant le nombre de dimensions dans votre requête.

Diviser la requête par plage de dates

Plutôt que de parcourir les résultats clés d'une longue plage de dates, pensez à former des requêtes distinctes pour une semaine, voire un jour, à la fois. Bien sûr, pour un ensemble de données volumineux, une requête portant sur une seule journée de données peut renvoyer plus de max-results. Dans ce cas, la pagination ne peut pas être évitée. Toutefois, dans tous les cas, si le nombre de lignes correspondantes pour votre requête est supérieur à max-results, le fait de séparer la plage de dates peut réduire le temps total nécessaire à la récupération des résultats. Cette approche peut améliorer les performances des requêtes monothread et parallèles.

Paging

Parcourir les résultats peut s'avérer utile pour diviser des ensembles de résultats volumineux en segments gérables. Le champ totalResults indique le nombre de lignes correspondantes et itemsPerPage indique le nombre maximal de lignes pouvant être renvoyées dans le résultat. Si le ratio entre totalResults et itemsPerPage est élevé, les requêtes individuelles peuvent prendre plus de temps que nécessaire. Si vous n'avez besoin que d'un nombre limité de lignes, par exemple à des fins d'affichage, il peut être pratique de définir une limite explicite de taille des réponses via le paramètre max-results. Toutefois, si votre application doit traiter un grand nombre de résultats dans son intégralité, il peut être plus efficace de demander le nombre maximal de lignes autorisées.

Utiliser gzip

Un moyen simple et pratique de réduire la bande passante requise pour chaque requête consiste à activer la compression gzip. Même si la décompression des résultats nécessite un temps CPU supplémentaire, la compression est généralement très avantageuse en termes de coûts de réseau. Pour recevoir une réponse encodée au format gzip, vous devez effectuer deux opérations: définir un en-tête Accept-Encoding et modifier votre user-agent pour qu'il contienne la chaîne gzip. Voici un exemple d'en-têtes HTTP correctement formatés pour activer la compression gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)