Exporter des données depuis Analytics

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Configurer les autorisations pour les 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. Le nom et la valeur de l'agent de service sont renvoyés, 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 indiqué à l'étape 1 est service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Cliquez sur le bouton + Ajouter un autre rôle et ajoutez les rôles suivants :
   • Utilisateur BigQuery
   • Administrateur Storage
7. Cliquez sur Enregistrer.

Données Apigee Analytics

Format d'exportation des données

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 dépôt de données (Cloud Storage ou BigQuery) vers lequel vous exportez vos données, y compris les identifiants utilisés pour accéder au dépôt de données.

   Lorsque vous créez un datastore, vous importez les identifiants du dépôt de données dans le coffre-fort Edge Credentials Vault pour les stocker de manière sécurisée. Le mécanisme d'exportation de données utilise ensuite ces identifiants pour écrire des données dans votre dépôt de données.

3. Utilisez l'API d'exportation de données pour lancer l'exportation des 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 dépôt 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 des données d'analyse écrit les données dans Cloud Storage ou BigQuery. Pour que cette écriture ait lieu, 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 possède une clé de compte de service représentée par une chaîne JSON. Lorsque vous créez le datastore Edge qui définit la connexion à votre dépôt de données, vous lui transmettez cette clé. Le mécanisme d'exportation de données utilise ensuite la clé pour accéder à votre dépôt de données.

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

Par exemple, lorsque vous téléchargez votre clé pour la première fois, elle est mise en forme 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 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 job BigQuery
  • Créateur d'objets Storage
  • Administrateur Storage (requis uniquement pour tester le datastore, comme décrit dans Tester une configuration de datastore). Si ce rôle est trop large, vous pouvez ajouter l'autorisation storage.buckets.get à un rôle existant à la place.)

  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 (obligatoire uniquement pour tester le datastore, comme décrit dans Tester une configuration de datastore)

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 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 job 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 datastore

Le datastore définit la connexion à votre dépôt de données d'exportation (Cloud Storage, BigQuery), y compris les identifiants utilisés pour accéder au dépôt de données.

À propos du coffre-fort d'identifiants Edge

Edge utilise le coffre d'identifiants pour stocker de manière sécurisée les identifiants utilisés pour accéder à votre dépôt de données d'exportation. Pour qu'un service puisse accéder aux identifiants du coffre-fort Edge Credentials Vault, vous devez définir un consommateur d'identifiants.

Lorsque vous créez un datastore à l'aide de l'interface utilisateur Edge, comme décrit ci-dessous, Edge crée automatiquement le consommateur utilisé pour accéder aux identifiants.

Tester une configuration de datastore

Lorsque vous créez le datastore, Edge ne teste pas et ne valide pas la configuration de vos identifiants et de votre dépôt de données. Cela signifie que vous pouvez créer le datastore et ne détecter aucune erreur tant que vous n'avez pas exécuté votre première exportation de données.

Vous pouvez également tester la configuration du datastore avant de le créer. Les tests sont utiles, car un processus d'exportation de données volumineuses peut prendre beaucoup de temps. En testant vos identifiants et la configuration de votre datastore avant de commencer à télécharger de grandes quantités de données, vous pouvez rapidement résoudre les problèmes liés à vos paramètres.

Si le test réussit, créez le datastore. Si le test échoue, corrigez les erreurs, puis testez à nouveau la configuration. Vous ne créez le datastore qu'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 datastore

Pour créer un datastore dans l'UI :

1. Connectez-vous à https://apigee.com/edge en tant qu'administrateur de l'organisation, puis sélectionnez votre organisation.

   NOTE : Vous devez être administrateur de l'organisation Edge pour pouvoir créer un datastore.

2. Dans la barre de navigation de gauche, sélectionnez Admin > Datastores Analytics. La page Analytics Datastores (Dépôts de données Analytics) s'affiche.

3. Sélectionnez le bouton + Ajouter un datastore. Vous êtes invité à sélectionner le type de datastore :

   

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

   • Google Cloud Storage
   • Google BigQuery

   La page de configuration s'affiche :

   

5. Saisissez le Nom du datastore.

6. Sélectionnez un identifiant utilisé pour accéder au dépôt de données. Une liste déroulante des identifiants disponibles s'affiche.

   Les identifiants sont spécifiques à un type de dépôt 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 des identifiants adaptés au type de dépôt de données.

   • Si vous ajoutez des identifiants au datastore, sélectionnez Ajouter. Dans la boîte de dialogue, saisissez :

     1. Le nom des identifiants.
     2. Le contenu des identifiants correspond à la clé de 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. Saisissez les propriétés spécifiques au type de dépôt 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. Avant de pouvoir exporter les données, le bucket doit exister. 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 de stockage des 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 vérifier que les identifiants peuvent être utilisés pour accéder au dépôt de données.

   Si le test réussit, enregistrez votre datastore.

   Si le test échoue, corrigez les éventuels problèmes et réessayez. Pointez sur le message d'erreur dans l'UI pour afficher des informations supplémentaires dans une info-bulle.

9. Une fois le test de connexion réussi, enregistrez le datastore.

Modifier un datastore

Pour modifier un datastore :

1. Connectez-vous à https://apigee.com/edge en tant qu'administrateur de l'organisation, puis sélectionnez votre organisation.

2. Dans la barre de navigation de gauche, sélectionnez Admin > Datastores Analytics. La page Analytics Datastores (Dépôts de données Analytics) s'affiche.

3. Pointez le pointeur de la souris sur la colonne Modifié du rapport à modifier. Une icône Modifier et une icône Supprimer s'affichent.

4. modifier ou supprimer le datastore ;

5. Si vous avez modifié le datastore, sélectionnez Tester la connexion pour vous assurer que les identifiants peuvent être utilisés pour accéder au datastore.

   Si le test réussit, vous pouvez afficher les exemples de données dans votre dépôt de données.

   Si le test échoue, corrigez les éventuels problèmes et réessayez.

6. Une fois le test de connexion réussi, mettez à jour le datastore.

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 datastore
• 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 dépôt 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 d'un environnement de test dans 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 requêtes d'exportation de données 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"
  }