Guide du développeur sur l'importation de données

L'API Management de Google Analytics permet d'accéder de manière programmatique à la fonctionnalité Importation de données de Google Analytics.

Introduction

L'API Management vous permet d'importer, de répertorier, de supprimer et d'obtenir des fichiers importés, ainsi que de répertorier des ensembles de données. Pour une présentation générale des avantages de la fonctionnalité d'importation de données, consultez l'article À propos de l'importation de données dans le centre d'aide.

Les deux ressources de l'API de gestion qui permettent l'importation de données sont les suivantes:

  • Ressource Source de données personnalisée, appelée "ensemble de données" dans l'interface Web, qui sert de conteneur pour les fichiers importés. Un ensemble de sources de données personnalisées représente tous les ensembles de données associés à une propriété Google Analytics.
  • La ressource Importer, qui représente un fichier importé. Une collection de ressources d'importation représente tous les fichiers que vous avez importés dans un ensemble de données.

Cas d'utilisation

La fonctionnalité d'importation de données comporte trois catégories de niveau supérieur, chacune possédant ses propres cas d'utilisation. L'organisation est la suivante:

Importation de données d'appel

Données de remboursement

Les transactions e-commerce qui ont été entièrement ou partiellement remboursées peuvent être importées dans Google Analytics. Vous pouvez ainsi rapprocher automatiquement les données de vos rapports Google Analytics sur l'e-commerce avec les remboursements traités.

Pour savoir comment importer des données de remboursement dans Google Analytics, consultez Exemple d'importation de données de remboursement.

Importation de données étendues

Données utilisateur

Vous pouvez importer des données qui ne permettent pas d'identifier personnellement les utilisateurs à partir d'outils CRM externes et créer des audiences de remarketing Google Ads pour vos segments d'utilisateurs les plus intéressants.

Pour savoir comment importer des données utilisateur dans Google Analytics afin de créer des audiences de remarketing Google Ads, consultez les ressources suivantes:

Données de la campagne

Vous pouvez importer les données d'une campagne dans Google Analytics afin de personnaliser l'analyse des performances de votre campagne pour votre entreprise.

Pour savoir comment importer des données de campagne dans Google Analytics, consultez Importer des données de campagne à l'aide de l'API de gestion.

Données géographiques

Vous pouvez importer des mappages d'ID géographiques avec des régions afin de créer des rapports sur les données Google Analytics par région personnalisée. Par exemple, aux États-Unis, vous pouvez exercer votre activité dans des groupes d'États "Est", "Centre" et "Ouest". En Europe, vous pouvez opérer dans des groupes de pays du Nord, du Centre et du Sud. Lorsque vous importez des données, vous pouvez utiliser les clés ga:regionId, ga:cityId, ga:countryIsoCode ou ga:subContinentCode. Les ID de ville et de pays figurent dans le tableau de ciblage géographique. Le code pays ISO et le code de sous-continent sont indiqués dans les tableaux ISO-3166-1 alpha-2 et UN M.49 respectivement.

Pour en savoir plus sur l'importation de données géographiques, consultez l'exemple d'importation de données géographiques.

Données relatives au contenu

Vous pouvez importer des métadonnées liées au contenu, telles que l'auteur et le sujet, afin d'utiliser Google Analytics pour effectuer une analyse approfondie des articles publiés sur un site Web.

Pour savoir comment importer des données de contenu dans Google Analytics, consultez Exemple d'importation de données de contenu.

Données produit

L'importation de données relatives aux produits dans Google Analytics simplifie et réduit la quantité de données d'e-commerce que vous devez envoyer avec les appels, comme les pages vues et les événements. Vous pouvez associer un code produit ou un ID produit unique à vos données produit importées pour renseigner les dimensions et les métriques sur les produits dans vos rapports.

Pour savoir comment importer vos données produit dans Google Analytics, consultez Importer des données produit à l'aide de l'API de gestion.

Importation de données récapitulatives

Données de coût

Vous pouvez importer les données de coût de campagnes autres que Google et utiliser la plate-forme Google Analytics pour effectuer une analyse du ROI et comparer les performances de vos campagnes pour tous vos investissements publicitaires et marketing en ligne.

Pour savoir comment importer des données de coût dans Google Analytics, consultez la page Importer des données de coût à l'aide de l'API de gestion.

Concepts

État du traitement

Une fois le fichier importé, son état est PENDING jusqu'à ce qu'elle soit validée et traitée. Si le traitement est réussi, l'état passe à COMPLETED.

Si une erreur s'est produite lors du traitement et que l'importation a échoué, l'état de l'importation est FAILED. Une liste d'erreurs est fournie pour vous aider à identifier le ou les problèmes liés au fichier. Voici un exemple de réponse à une importation dont la validation a échoué:

{
  id: "YU4DersR_ORzyzXC_AoWw",
  kind: "analytics#upload",
  accountId: "12345",
  customDataSourceId: "poaU7EPcR4WGU-dkNghYKQ",
  status: "FAILED",
  errors:
  [
    "Invalid cell data 12.99 at row 1 column 6. expected data type LONG.",
    "Invalid cell data 12.99 at row 2 column 6. expected data type LONG.",
    "Invalid cell data 23.81 at row 3 column 6. expected data type LONG.",
    "Invalid cell data 199.99 at row 4 column 6. expected data type LONG."
  ]
}

Synthèse des données de coût ou remplacement

Lorsque vous créez une source de données personnalisée ou un ensemble de données pour des données de coût, vous pouvez indiquer comment gérer les cas où un fichier importé contient une ligne de données dont la clé (date, source, support, par exemple) correspond à une ligne existante. Vous disposez des options suivantes :

  • summation (par défaut) : les nouvelles données sont ajoutées à toutes les données correspondantes précédentes, et les métriques sont additionnées.
  • overwrite : les nouvelles données écrasent toutes les données correspondantes antérieures.

Pour savoir quel type a été défini pour un ensemble de données, utilisez la méthode Liste de sources de données personnalisées afin de vérifier si la propriété importBehavior est définie sur OVERWRITE ou SUMMATION.

Somme et écrasement des données de coût au niveau des lignes

Vous pouvez également remplacer le comportement de l'ensemble de données pour chaque fichier importé en incluant la colonne ga:importBehavior dans l'en-tête. Pour chaque ligne, vous pouvez définir la valeur de ga:importBehavior sur SUMMATION ou OVERWRITE.

Par exemple, le fichier suivant remplace toutes les données de coût précédentes pour Facebook/cpc et Yahoo/cpc, mais la ligne Bing/cpc est ajoutée à toutes les données de coût existantes pour cette date et la combinaison source/support en question.

ga:date,ga:source, ga:medium,ga:adCost,ga:importBehavior
20140604,facebook,cpc,12.23,OVERWRITE
20140604,bing,cpc,3.23,SUMMATION
20140604,yahoo,cpc,11.23,OVERWRITE

Format et contraintes

Pour que les données soient importées dans Google Analytics, elles doivent se présenter dans un fichier CSV correctement formaté. Cette section décrit les contraintes qu'elle doit respecter pour que l'importation puisse être considérée comme valide pour tous les types d'importation de données.

Si l'une des contraintes ci-dessous n'est pas respectée ou en cas d'erreur d'analyse syntaxique, la demande d'importation échouera et renverra des messages d'erreur. L'API peut signaler jusqu'à 10 erreurs dans une seule réponse afin d'aider les utilisateurs à réduire le nombre d'importations non valides.

Contraintes de fichier

  • Encodage: UTF-8
  • Taille maximale du fichier: 1 Go

Contraintes d'en-tête

  • La première ligne est considérée comme un en-tête de colonne et est obligatoire. Elle doit définir les dimensions et les métriques que contiendra une colonne spécifique.

Contraintes de ligne

  • Le nombre de lignes est limité à 1 Mo.

Mise en forme des cellules

  • Les cellules ne doivent pas dépasser 2 048 caractères.
  • Les espaces au début et à la fin d'une cellule sont supprimés.
  • Pour spécifier une virgule dans une cellule, la valeur de la cellule doit être placée entre guillemets doubles. Exemple : source1,"medium,ether",group1,100 : la deuxième valeur de la cellule est "medium,ether".
  • Pour spécifier des guillemets doubles dans une cellule, en plus des guillemets doubles de début et de fin, échappez le guillemet double avec un autre guillemet double. Exemple : source1,"medium""ether",group1,100 : la deuxième valeur de la cellule est medium"ether.