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

L'API de gestion de Google Analytics permet un accès programmatique à la fonctionnalité d'importation de données de Google Analytics.

Introduction

L'API Management vous permet d'importer, de répertorier, de supprimer et de récupérer les 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:

  • La ressource Source de données personnalisées, appelée "ensemble de données" dans l'interface Web, qui sert de conteneur pour les fichiers que vous avez importés. Une collection 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 premier niveau, chacune ayant 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 sur l'e-commerce Google Analytics 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 utilisateur qui ne permettent pas d'identifier personnellement l'utilisateur à 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 des données de 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, reportez-vous à 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, ce qui vous permet de créer des rapports sur les données Google Analytics par région personnalisée. Par exemple, aux États-Unis, vous pouvez opérer dans les groupes d'États Est, Centre et Ouest. En Europe, vous pouvez opérer dans des groupes de pays Nord, Centre et Sud. Lorsque vous importez des données, vous pouvez utiliser les touches ga:regionId, ga:cityId, ga:countryIsoCode ou ga:subContinentCode. Les identifiants des villes et des pays figurent dans le tableau "Ciblage géographique". Le code pays ISO et le code du 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, pour effectuer une analyse approfondie des articles publiés sur un site Web à l'aide de Google Analytics.

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 à 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 payantes autres que Google et utiliser la plate-forme Google Analytics pour effectuer une analyse du ROI et comparer les performances de tous vos investissements publicitaires et marketing en ligne.

Pour savoir comment importer des données de coût dans Google Analytics, consultez l'article 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 aboutit, 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."
  ]
}

Somme 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 les données de coût, vous avez la possibilité d'indiquer comment gérer les cas où un fichier importé contient une ligne de données dont la clé (date, source, support) 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 précédentes.

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 des données de coût au niveau de la ligne et écrasement

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 sera ajoutée à toutes les données de coût existantes pour cette date et la combinaison source/support.

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

Les données ne peuvent être importées dans Google Analytics que dans un fichier CSV correctement formaté. Cette section décrit les contraintes qu'il doit respecter avant de pouvoir être considéré comme valide pour une importation dans tous les types d'importations de données.

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

Contraintes liées aux fichiers

  • 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 contenues dans une colonne spécifique.

Contraintes de ligne

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

Mise en forme des cellules

  • Les cellules ne peuvent pas comporter plus de 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 valeur de la deuxième 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 les guillemets doubles à l'aide d'un autre guillemet double. Exemple : source1,"medium""ether",group1,100 : la valeur de la deuxième cellule est medium"ether.