API Core Reporting - Guide de référence

Lorsque vous utilisez dimensions dans une requête de données, tenez compte des contraintes suivantes:

• Vous pouvez indiquer un maximum de sept dimensions par requête.
• Vous ne pouvez pas envoyer de requête composée uniquement de dimensions. Vous devez combiner toutes les dimensions demandées avec au moins une métrique.
• Seules certaines variables peuvent être interrogées dans la même requête. Utilisez l'outil de combinaison valide dans la documentation de référence sur les dimensions et les métriques pour savoir quelles dimensions peuvent être utilisées ensemble.

• Chaque requête doit fournir au moins une métrique. Une requête ne peut pas être composée uniquement de dimensions.
• Vous pouvez fournir jusqu'à 10 métriques par requête.
• La plupart des combinaisons de métriques de plusieurs catégories peuvent être utilisées ensemble, à condition qu'aucune dimension ne soit spécifiée.
• Vous pouvez utiliser une métrique en combinaison avec d'autres dimensions ou métriques, mais uniquement lorsque des combinaisons valides s'appliquent à cette métrique. Pour en savoir plus, consultez la documentation de référence sur les dimensions et les métriques.

Liste de métriques et de dimensions indiquant l'ordre de tri et le sens de tri des données renvoyées.

• Le ordre de tri est indiqué par l'ordre de gauche à droite des métriques et les dimensions répertoriées.
• Par défaut, le tri de la direction est croissant et peut être modifié en ordre décroissant à l'aide du signe moins (-) dans le champ demandé.

Le tri des résultats d'une requête vous permet de poser différentes questions sur vos données. Par exemple, pour répondre à la question "Quels sont mes principaux pays et quels navigateurs utilisent-ils le plus ?". vous pouvez effectuer une requête avec le paramètre suivant. Il trie d'abord par ga:country, puis par ga:browser, dans l'ordre croissant:

sort=ga:country,ga:browser

sort=ga:browser,ga:country

Lorsque vous utilisez le paramètre sort, tenez compte des points suivants:

• Ne triez que les valeurs de dimensions ou de métriques que vous avez utilisées dans les paramètres dimensions ou metrics. Si votre requête effectue un tri sur un champ qui n'est indiqué ni dans les paramètres des dimensions, ni dans celui des métriques, une erreur s'affiche.
• Par défaut, les chaînes sont triées par ordre alphabétique croissant dans les paramètres régionaux en-US.
• Par défaut, les numéros sont triés par ordre numérique croissant.
• Par défaut, les dates sont triées dans l'ordre croissant par date.

Le paramètre de chaîne de requête filters limite les données renvoyées par votre requête. Pour utiliser le paramètre filters, indiquez une dimension ou une métrique à filtrer, suivie de l'expression de filtre. Par exemple, la requête suivante demande ga:pageviews et ga:browser pour la vue (profil) 12134, où la dimension ga:browser commence par la chaîne Firefox :

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Les requêtes filtrées limitent les lignes qui sont incluses ou non dans le résultat. Chaque ligne du résultat est testée par rapport au filtre: si le filtre correspond, la ligne est conservée et, si ce n'est pas le cas, elle est supprimée.

• Encodage d'URL : les bibliothèques clientes des API Google encodent automatiquement les opérateurs de filtrage.
• Filtrage des dimensions: le filtrage se produit avant l'agrégation de toutes les dimensions, de sorte que les métriques renvoyées ne représentent le total que pour les dimensions pertinentes. Dans l'exemple ci-dessus, le nombre de pages vues correspondrait uniquement à celles dont le navigateur correspond à Firefox.
• Filtrage des métriques: le filtrage s'effectue après l'agrégation des métriques.
• Combinaisons valides: vous pouvez filtrer selon une dimension ou une métrique qui ne fait pas partie de votre requête, à condition que toutes les dimensions/métriques de la requête et le filtre soient des combinaisons valides. Par exemple, vous pouvez rechercher une liste datée de pages vues en filtrant par navigateur. Pour en savoir plus, consultez la documentation de référence sur les dimensions et les métriques.

Syntaxe des filtres

Un filtre unique se présente sous la forme suivante:

ga:name operator expression

Dans cette syntaxe:

• name : nom de la dimension ou de la métrique à filtrer. Par exemple: ga:pageviews filtre la métrique"Pages vues".
• operator : définit le type de correspondance de filtres à utiliser. Les opérateurs sont spécifiques à une dimension ou à une métrique.
• expression : indique les valeurs à inclure ou exclure des résultats. Les expressions utilisent une syntaxe d'expression régulière.

Opérateurs de filtrage

Il existe six opérateurs de filtre pour les dimensions et six opérateurs de filtre pour les métriques. Les opérateurs doivent être encodés en URL pour pouvoir être inclus dans les chaînes de requête d'URL.

Conseil : Utilisez l'explorateur de requêtes de flux de données pour créer des filtres nécessitant un encodage d'URL. En effet, l'explorateur de requêtes encode automatiquement les URL contenant des chaînes et des espaces.

Expressions de filtre

Il existe deux règles importantes pour les expressions de filtre:

• Caractères réservés aux URL : les caractères tels que & doivent être encodés pour les URL comme d'habitude.
• Caractères réservés : les points-virgules et les virgules doivent être précédés d'une barre oblique inverse lorsqu'ils apparaissent dans une expression :
  • point-virgule \;
  • virgule \,
• Expressions régulières : vous pouvez également utiliser des expressions régulières dans les expressions de filtre à l'aide des opérateurs =~ et !~. Leur syntaxe est semblable à celle des expressions régulières Perl et comportent les règles supplémentaires suivantes :
  • Longueur maximale de 128 caractères : les expressions régulières de plus de 128 caractères génèrent un code d'état 400 Bad Request renvoyé par le serveur.
  • Sensibilité à la casse : la correspondance d'expression régulière n'est pas sensible à la casse.

Combiner des filtres

Les filtres peuvent être combinés à l'aide des logiques booléennes OR et AND. Cela vous permet d'étendre efficacement la limite de 128 caractères d'une expression de filtre.

OU

L'opérateur OR est défini à l'aide d'une virgule (,). Il est prioritaire sur l'opérateur AND et ne peut PAS être utilisé pour combiner des dimensions et des métriques dans la même expression.

ET

L'opérateur AND est défini à l'aide d'un point-virgule (;). Il est précédé de l'opérateur OR et peut être utilisé pour combiner des dimensions et des métriques dans la même expression.

Pour en savoir plus sur la demande de segments dans l'API Core Reporting, consultez le Guide de développement des segments.

Pour obtenir une présentation conceptuelle des segments, consultez la documentation de référence sur les fonctionnalités des segments et la page Segments du centre d'aide.

Dimensions et métriques autorisées dans les segments.
Certaines dimensions et métriques ne peuvent pas être utilisées dans les segments. Pour connaître les dimensions et les métriques autorisées dans les segments, accédez à l'explorateur de dimensions et de métriques.

• DEFAULT : renvoie une réponse avec un échantillon qui équilibre la vitesse et la justesse.
• FASTER : renvoie une réponse rapide avec un échantillon de taille plus petit.
• HIGHER_PRECISION : renvoie une réponse plus précise avec une taille d'échantillon importante, mais cela peut ralentir la réponse.

• json : génère la propriété rows par défaut dans la réponse et contient un objet JSON.
• dataTable : renvoie une propriété dataTable dans la réponse, contenant un objet Table de données. Cet objet Data Table peut être utilisé directement avec les visualisations Google Charts.

Spécifie les champs à afficher dans une réponse partielle. Si vous n'utilisez qu'un sous-ensemble des champs de la réponse de l'API, vous pouvez utiliser le paramètre fields pour spécifier les champs à inclure.

Le format de la valeur du paramètre de requête des champs est vaguement basé sur la syntaxe XPath. La syntaxe acceptée est résumée ci-dessous.

• Incluez une liste dont les éléments sont séparés par une virgule pour sélectionner plusieurs champs.
• Utilisez a/b pour sélectionner un champ b imbriqué dans le champ a. Utilisez a/b/c pour sélectionner un champ c imbriqué dans le champ b.
• Utilisez un sous-sélecteur pour demander un ensemble de sous-champs spécifiques de tableaux ou d'objets en plaçant des expressions entre parenthèses "( )".
  Par exemple, fields=columnHeaders(name,dataType) ne renvoie que les champs name et dataType du tableau columnHeaders. Vous pouvez également spécifier un seul sous-champ, où fields=columnHeader(name) équivaut à fields=columnHeader/name.

Renvoie la réponse dans un format lisible si true. Valeur par défaut: false.

Vous permet d'appliquer des quotas par utilisateur à partir d'une application côté serveur, même lorsque l'adresse IP de l'utilisateur est inconnue. Cela peut se produire, par exemple, avec des applications qui exécutent des tâches Cron sur App Engine pour le compte d'un utilisateur. Vous pouvez choisir n'importe quelle chaîne arbitraire permettant d'identifier un utilisateur de manière unique, mais elle est limitée à 40 caractères.

Cette valeur remplace userIp si les deux sont fournis.