Exporter des données depuis Analytics

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Configurer les autorisations pour les agents de service attribués

Pour configurer les autorisations des agents de service attribués en prévision 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 correspond à 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 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 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 dans Edge, ainsi que toutes les données d'analyse personnalisées 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 référentiel de données a été correctement configuré et que le compte de service utilisé pour écrire des données dans le référentiel de données dispose des autorisations appropriées.

2. Créez un data store qui définit les propriétés du dépôt de données (Cloud Storage ou BigQuery) dans lequel vous exportez vos données, y compris les identifiants permettant d'y accéder.

   Lorsque vous créez un data store, 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 des 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 dépôt de données.

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

Configurer votre référentiel 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, procédez comme suit:

• 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 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 des 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 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 la page 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 votre clé pour la première fois, celle-ci 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 de BigQuery Export 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 de l'espace de stockage (obligatoire uniquement pour tester le datastore, comme décrit dans la section 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 data store, comme décrit dans la section Tester une configuration de data store)

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. Consultez la section Activer et désactiver des API pour obtenir des instructions.

• 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 data store

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

À propos du coffre des informations d'identification Edge

Edge utilise le coffre-fort des identifiants 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 data store

Lorsque vous créez le data store, Edge ne teste pas et ne valide pas 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 data store 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 data store avant de le créer. Les tests sont utiles, car l'exécution d'un processus d'exportation de données volumineuses peut prendre beaucoup de temps. En testant vos identifiants et la configuration du data store 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 data store. Si le test échoue, corrigez les erreurs, puis testez de nouveau la configuration. Vous ne créez le data store qu'une fois les tests réussis.

Pour activer la fonctionnalité de test:

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

Créer un data store

Pour créer un data store dans l'interface utilisateur:

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

   REMARQUE: Vous devez être un administrateur de l'organisation Edge pour pouvoir créer un data store.

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

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

   

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 data store.

6. Sélectionnez un identifiant pour accéder au référentiel de données. Une liste déroulante des identifiants disponibles s'affiche.

   Les identifiants sont spécifiques à un type de référentiel de données. Pour en savoir plus, consultez la section 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. Veillez à sélectionner des identifiants adaptés au type de référentiel de données.

   • Si vous ajoutez de nouveaux identifiants au data store, 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 la section 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 référentiel de données:

   • Google Cloud Storage :

     Propriété	Description	nécessaire
     ID du projet	ID du projet Google Cloud Platform. Pour créer un projet Google Cloud Platform, consultez la section Créer et gérer des projets dans la documentation de 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 la section Créer des buckets de stockage dans la documentation Google Cloud Platform.	Oui
     Chemin d'accès	Répertoire dans lequel stocker les données d'analyse dans le bucket Cloud Storage.	Oui

   • BigQuery :

     Propriété	Description	nécessaire
     ID du projet	ID du projet Google Cloud Platform. Pour créer un projet Google Cloud Platform, consultez la section Créer et gérer des projets dans la documentation de 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 la section Créer et utiliser des ensembles de données dans la documentation Google Cloud Platform.	Oui
     Préfixe de table	Préfixe des noms des tables créées pour les données d'analyse dans le jeu 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 référentiel de données.

   Si le test réussit, enregistrez votre data store.

   Si le test échoue, corrigez les problèmes et relancez le test. Passez 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 data store.

Modifier un data store

Pour modifier un data store:

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

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

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

4. Modifiez ou supprimez le data store.

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

   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 test.

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

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 délimité 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 le statut du travail, comme décrit dans Affichage du statut d'une demande d'exportation 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 une utilisation excessive des appels d'API d'exportation de données coûteux, Edge applique un quota sur les 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 demande d'exportation d'analyse spécifique, envoyez une requête GET à /analytics/exports/{exportId}, où {exportId} est l'ID associé à la demande d'exportation 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"
  }