Exporter des données depuis Analytics

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Configurer les autorisations des agents de service attribués

Pour configurer les autorisations des agents de service attribués, en vue des modifications décrites ci-dessus, procédez comme suit.

1. Recherchez le nom de votre agent de service Google Cloud en saisissant la commande suivante :

   curl -X GET \
     "https://api.enterprise.apigee.com/v1/organizations/ORG" \
     -u email:password \
     | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

   où ORG est votre organisation. Cette commande renvoie le nom et la valeur de l'agent de service, comme indiqué ci-dessous :

   "property" : [
     {
      "name" : "serviceAgent.analytics",
      "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
      },

2. Ouvrez le tableau de bord IAM dans la console Google Cloud.
3. Sélectionnez votre projet Google Cloud.
4. Cliquez sur Ajouter en haut du volet IAM.
5. Dans le champ Nouveaux comptes principaux, saisissez l'agent de service value renvoyé à l'étape 1. Par exemple, le value affiché à l'étape 1 est service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Cliquez sur le bouton + Ajouter un autre rôle, puis ajoutez les rôles suivants :
   • Utilisateur BigQuery
   • Administrateur Storage
7. Cliquez sur Enregistrer.

Données Apigee Analytics

Format des données d'exportation

Exportez les données d'analyse dans l'un des formats suivants :

• CSV (Comma-Separated Values)

  Le délimiteur par défaut est une virgule (,). Les caractères de délimitation acceptés comprennent les virgules (,), les barres verticales (|) et les tabulations (\t). Configurez la valeur à l'aide de la propriété csvDelimiter, comme décrit dans la documentation de référence sur les propriétés de requête d'exportation.

• JSON (délimité par un retour à la ligne)

  Permet d'utiliser le caractère de retour à la ligne comme délimiteur.

Les données exportées incluent toutes les métriques et dimensions d'analyse intégrées à Edge, ainsi que toutes les données d'analyse personnalisée que vous ajoutez. Pour obtenir une description des données exportées, consultez l'article Métriques, dimensions et filtres Analytics.

Vous pouvez exporter des données d'analyse dans les dépôts de données suivants :

• Google Cloud Storage
• Google BigQuery

Présentation du processus d'exportation

Les étapes suivantes récapitulent le processus utilisé pour exporter vos données d'analyse :

1. Configurez votre dépôt de données (Cloud Storage ou BigQuery) pour l'exportation de données. Vous devez vous assurer que votre dépôt de données a été configuré correctement et que le compte de service utilisé pour écrire des données dans le dépôt de données dispose des autorisations appropriées.

2. Créez un magasin de données qui définit les propriétés du référentiel de données (Cloud Storage ou BigQuery) vers lequel vous exportez vos données, y compris les informations d'identification permettant d'accéder au référentiel de données.

   Lorsque vous créez un magasin de données, vous téléchargez les informations d'identification du référentiel de données dans le coffre-fort des informations d'identification Edge pour les stocker de manière sécurisée. Le mécanisme d'exportation de données utilise ensuite ces informations d'identification pour écrire des données dans votre référentiel de données.

3. Utilisez l'API d'exportation de données pour lancer l'exportation de données. L'exportation de données s'exécute de manière asynchrone en arrière-plan.

4. Utilisez l'API d'exportation de données pour déterminer quand l'exportation est terminée.

5. Une fois l'exportation terminée, accédez aux données exportées dans votre référentiel de données.

Les sections suivantes décrivent ces étapes plus en détail.

Configurer votre dépôt de données

Le mécanisme d'exportation de données d'analyse écrit les données dans Cloud Storage ou BigQuery. Pour que cette écriture se produise, vous devez:

• Créez un compte de service Google Cloud Platform.
• Définissez le rôle du compte de service afin qu'il puisse accéder à Cloud Storage ou à BigQuery.

Créer un compte de service pour Cloud Storage ou BigQuery

Un compte de service est un type de compte Google qui appartient à votre application et non à un utilisateur individuel. Votre application utilise ensuite le compte de service pour accéder à un service.

Un compte de service a une clé de compte de service représentée par une chaîne JSON. Lorsque vous créez le magasin de données Edge qui définit la connexion à votre référentiel de données, vous lui transmettez cette clé. Le mécanisme d'exportation de données utilise ensuite la clé pour accéder à votre référentiel de données.

Le compte de service associé à la clé doit être un propriétaire de projet Google Cloud Platform et avoir un accès en écriture au compartiment Google Cloud Storage. Pour créer une clé de service et télécharger la charge utile requise, consultez Créer et gérer des clés de compte de service dans la documentation Google Cloud Platform.

Par exemple, lorsque vous téléchargez pour la première fois votre clé, celle-ci est formatée en tant qu'objet JSON:

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Configurer Google Cloud Storage

Avant de pouvoir exporter des données vers Google Cloud Storage :

• Assurez-vous que les API BigQuery et Cloud Resource Manager sont activées dans votre projet Google Cloud Platform. Consultez la section Activer des API pour obtenir des instructions. Apigee utilise l'API BigQuery pour exploiter les fonctionnalités d'exportation de BigQuery lors de l'exportation vers Cloud Storage et l'API Cloud Resource Manager pour vérifier les autorisations avant chaque exportation.

• Assurez-vous que le compte de service est attribué aux rôles suivants:

  • Utilisateur de tâche BigQuery
  • Créateur d'objets Storage
  • Administrateur de stockage (requis uniquement pour tester le magasin de données, comme décrit dans la section Test d'une configuration de magasin de données). Si ce rôle est trop large, vous pouvez plutôt ajouter l'autorisation storage.buckets.get à un rôle existant.)

  Si vous souhaitez modifier un rôle existant ou créer un rôle personnalisé, vous pouvez également ajouter les autorisations suivantes au rôle :

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (requis uniquement pour tester le magasin de données, comme décrit dans la section Test d'une configuration de magasin de données)

Configurer Google BigQuery

Avant de pouvoir exporter des données vers Google BigQuery :

• Assurez-vous que les API BigQuery et Cloud Resource Manager sont activées dans votre projet Google Cloud Platform. Consultez la section Activer des API pour obtenir des instructions. Apigee utilise l'API Cloud Resource Manager pour vérifier les autorisations avant chaque exportation.
• Assurez-vous que l'API BigQuery est activée dans votre projet Google Cloud Platform. Pour obtenir des instructions, consultez Activer et désactiver des API.

• Assurez-vous que le compte de service est attribué aux rôles suivants:

  • Utilisateur de tâche BigQuery
  • Éditeur de données BigQuery

  Si vous souhaitez modifier un rôle existant ou créer un rôle personnalisé, ajoutez les autorisations suivantes au rôle :

  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData

Créer un data store

Le magasin de données définit la connexion à votre référentiel de données d'exportation (Cloud Storage, BigQuery), y compris les informations d'identification utilisées pour accéder au référentiel de données.

À propos du coffre des informations d'identification Edge

Edge utilise le coffre-fort des informations d'identification pour stocker en toute sécurité les informations d'identification utilisées pour accéder à votre référentiel de données d'exportation. Pour qu'un service puisse accéder aux informations d'identification dans le coffre-fort des informations d'identification Edge, vous devez définir un consommateur d' informations d'identification.

Lors de la création d'un magasin de données à l'aide de l'interface utilisateur Edge, comme décrit ci-dessous, Edge crée automatiquement le consommateur utilisé pour accéder aux informations d'identification.

Tester une configuration de magasin de données

Lorsque vous créez le magasin de données, Edge ne teste ni ne valide la validité de vos informations d'identification et de la configuration du référentiel de données. Cela signifie que vous pouvez créer le magasin de données sans détecter les erreurs tant que vous n'avez pas exécuté votre première exportation de données.

Vous pouvez également tester la configuration du magasin de données avant de le créer. Le test est utile car un processus d'exportation de données volumineux peut prendre beaucoup de temps. En testant vos identifiants et la configuration du magasin de données avant de commencer à télécharger de grandes quantités de données, vous pouvez résoudre rapidement les problèmes liés à vos paramètres.

Si le test réussit, créez le magasin de données. Si le test échoue, corrigez les erreurs, puis testez à nouveau la configuration. Vous créez le magasin de données uniquement une fois les tests réussis.

Pour activer la fonctionnalité de test, vous devez:

• Assurez-vous que l'API Cloud Resource Manager est activée dans votre projet Google Cloud Platform. Pour obtenir des instructions, consultez Activer et désactiver des API.

Créer un data store

Pour créer un magasin de données dans l'interface utilisateur:

1. Connectez-vous à https://apigee.com/edge en tant qu'administrateur d'organisation et sélectionnez votre organisation.

   REMARQUE: Vous devez être un administrateur de l'organisation Edge pour pouvoir créer un magasin de données.

2. Sélectionnez Admin > Datastores Analytics dans la barre de navigation de gauche. La page "Analyseurs de données analytiques" s'affiche.

3. Sélectionnez le bouton + Ajouter une banque de données. Vous êtes invité à sélectionner le type de magasin de données:

   

4. Choisissez un type de cible de données d'exportation:

   • Google Cloud Storage
   • Google BigQuery

   La page de configuration s'affiche:

   

5. Entrez le nom du data store.

6. Sélectionnez un identifiant utilisé pour accéder au référentiel de données. Une liste déroulante des informations d'identification disponibles apparaît.

   Les informations d'identification sont spécifiques à un type de référentiel de données. Pour en savoir plus, consultez Créer un compte de service pour Cloud Storage ou BigQuery.

   • Si vous avez déjà importé les identifiants, sélectionnez-les dans la liste déroulante. Assurez-vous de sélectionner les informations d'identification appropriées pour le type de référentiel de données.

   • Si vous ajoutez de nouvelles informations d'identification au magasin de données, sélectionnez Ajouter. Dans la boîte de dialogue, saisissez:

     1. Le nom des identifiants.
     2. Le contenu Credentials est la clé du compte de service JSON spécifique à votre dépôt de données, comme défini dans Créer un compte de service pour Cloud Storage ou BigQuery.
     3. Sélectionnez Créer.

7. Entrez les propriétés spécifiques au type de référentiel de données:

   • Google Cloud Storage :

     Propriété	Description	Obligatoire ?
     ID du projet	ID du projet Google Cloud Platform. Pour créer un projet Google Cloud Platform, consultez Créer et gérer des projets dans la documentation Google Cloud Platform.	Oui
     Nom du bucket	Nom du bucket Cloud Storage vers lequel vous souhaitez exporter des données d'analyse. Le bucket doit exister avant d'effectuer une exportation de données. Pour créer un bucket Cloud Storage, consultez Créer des buckets de stockage dans la documentation de Google Cloud Platform.	Oui
     Chemin	Répertoire dans lequel stocker les données d'analyse dans le bucket Cloud Storage.	Oui

   • BigQuery :

     Propriété	Description	Obligatoire ?
     ID du projet	ID du projet Google Cloud Platform. Pour créer un projet Google Cloud Platform, consultez Créer et gérer des projets dans la documentation Google Cloud Platform.	Oui
     Nom de l'ensemble de données	Nom de l'ensemble de données BigQuery vers lequel exporter des données d'analyse. Avant de demander une exportation de données, assurez-vous que l'ensemble de données est créé. Pour créer un ensemble de données BigQuery, consultez Créer et utiliser des ensembles de données dans la documentation de Google Cloud Platform.	Oui
     Préfixe de table	Préfixe des noms des tables créées pour les données d'analyse dans l'ensemble de données BigQuery.	Oui

8. Sélectionnez Tester la connexion pour vous assurer que les informations d'identification peuvent être utilisées pour accéder au référentiel de données.

   Si le test réussit, enregistrez votre magasin de données.

   Si le test échoue, corrigez les problèmes et relancez le test. Déplacez la souris sur le message d'erreur dans l'interface utilisateur pour afficher des informations supplémentaires dans une info-bulle.

9. Une fois le test de connexion réussi, enregistrez le magasin de données.

Modifier un magasin de données

Pour modifier un magasin de données:

1. Connectez-vous à https://apigee.com/edge en tant qu'administrateur d'organisation et sélectionnez votre organisation.

2. Sélectionnez Admin > Datastores Analytics dans la barre de navigation de gauche. La page "Analyseurs de données analytiques" s'affiche.

3. Déplacez le pointeur de la souris sur la colonne Modifié du rapport à modifier. Une icône Modifier et Supprimer apparaît.

4. Modifier ou supprimer le magasin de données.

5. Si vous avez modifié le magasin de données, sélectionnez Tester la connexion pour vous assurer que les informations d'identification peuvent être utilisées pour accéder au magasin de données.

   Si le test réussit, vous pouvez afficher les exemples de données dans votre référentiel de données.

   Si le test échoue, corrigez les problèmes et relancez-le.

6. Une fois le test de connexion réussi, mettez à jour le magasin de données.

Exporter des données d'analyse

Pour exporter des données d'analyse, envoyez une requête POST à l'API /analytics/exports. Transmettez les informations suivantes dans le corps de la requête :

• Nom et description de la requête d'exportation
• Plage de dates des données exportées (la valeur ne doit pas dépasser un jour)
• Format des données exportées
• Nom du data store
• Si la monétisation est activée ou pas dans l'organisation

Des exemples de requêtes d'exportation sont fournis ci-dessous. Pour une description complète des propriétés du corps de la requête, consultez la page Documentation de référence sur les propriétés de requête d'exportation.

La réponse de la requête POST se présente sous la forme suivante :

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

Notez que la propriété state dans la réponse est définie sur enqueued. La requête POST fonctionne de manière asynchrone. Cela signifie que son exécution se poursuit en arrière-plan après que la requête a renvoyé une réponse. Les valeurs possibles pour state sont les suivantes : enqueued, running, completed, failed.

Utilisez l'URL renvoyée dans la propriété self pour afficher l'état de la requête d'exportation de données, comme décrit dans la section Afficher l'état d'une requête d'exportation de données d'analyse. Lorsque la requête se termine, la valeur de la propriété state dans la réponse est définie sur completed. Vous pouvez ensuite accéder aux données d'analyse dans votre référentiel de données.

Exemple 1 : Exporter des données vers Cloud Storage

La requête suivante exporte un ensemble complet de données brutes des dernières 24 heures à partir de l'environnement de test de l'organisation myorg. Le contenu est exporté vers Cloud Storage au format JSON :

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

Utilisez l'URI spécifié par la propriété self pour surveiller l'état de la tâche, comme décrit dans Afficher l'état d'une requête d'exportation d'analyse.

Exemple 2 : Exporter des données vers BigQuery

La requête suivante exporte un fichier CSV séparé par des virgules vers BigQuery:

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

Remarque : Le fichier CSV exporté crée une table BigQuery avec le préfixe suivant :

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

Utilisez l'URI spécifié par la propriété self pour surveiller l'état de la tâche, comme décrit dans Afficher l'état d'une requête d'exportation de données d'analyse.

Exemple 3 : Exporter des données de monétisation

Si la monétisation est activée dans un environnement de l'organisation, vous pouvez effectuer deux types d'exportation de données 

• Exportation de données standard, comme indiqué dans les deux exemples précédents.
• Exportation des données de monétisation pour exporter des données spécifiques à la monétisation.

Pour effectuer une exportation de données de monétisation, spécifiez "dataset":"mint" dans la charge utile de la requête. L'organisation et l'environnement doivent accepter la monétisation pour définir cette option. Sinon, omettez la propriété dataset de la charge utile :

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

À propos des quotas d'exportation de l'API

Pour éviter toute utilisation excessive d'appels d'API d'exportation de données coûteux, Edge applique un quota aux appels à l'API /analytics/exports:

• Pour les organisations et les environnements pour lesquels la monétisation n'est pas activée, le quota est le suivant :

  • 70 appels par mois et par organisation/environnement.

  Par exemple, si votre organisation comporte deux environnements, prod et test, vous pouvez effectuer 70 appels d'API par mois pour chaque environnement.

• Pour les organisations et les environnements dont la monétisation est activée, le quota est le suivant :

  • 70 appels par mois pour chaque organisation et environnement pour les données standards.
  • 70 appels par mois pour chaque organisation et chaque environnement pour les données de monétisation.

  Par exemple, si vous activez la monétisation sur votre organisation prod, vous pouvez effectuer 70 appels d'API pour les données standards et 70 appels d'API supplémentaires pour les données de monétisation.

Si vous dépassez le quota d'appels, l'API renvoie une réponse HTTP 429.

Afficher l'état de toutes les requêtes d'exportation de données d'analyse

Pour afficher l'état de toutes les demandes d'exportation d'analyse, envoyez une requête GET à /analytics/exports.

Par exemple, la requête suivante renvoie l'état de toutes les requêtes d'exportation de données d'analyse pour l'environnement test de l'organisation myorg :

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

Voici un exemple de réponse répertoriant deux requêtes d'exportation, l'une mise en file d'attente (créée et placée dans la file d'attente) et l'autre terminée :

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

Afficher l'état d'une requête d'exportation de données d'analyse

Pour afficher l'état d'une requête d'exportation de données d'analyse spécifique, émettez une requête GET à /analytics/exports/{exportId}, où {exportId} est l'ID associé à la requête d'exportation de données d'analyse.

Par exemple, la requête suivante renvoie l'état de la requête d'exportation de données d'analyse avec l'ID 4d6d94ad-a33b-4572-8dba-8677c9c4bd98.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

Voici un exemple de réponse :

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Si l'exportation de données d'analyse ne renvoie aucune donnée, executionTime est défini sur "0 seconde".

Documentation de référence sur les propriétés de requête d'exportation

Le tableau suivant décrit les propriétés que vous pouvez transmettre dans le corps de la requête au format JSON lors de l'exportation de données d'analyse.

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

Exemple :

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }