Utiliser l'API de rapports personnalisés asynchrones

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

Edge Analytics fournit un ensemble complet de tableaux de bord interactifs, de générateurs de rapports personnalisés et de fonctionnalités associées. Toutefois, ces fonctionnalités sont conçues pour être interactives : vous envoyez une requête d'API ou d'interface utilisateur, laquelle est bloquée jusqu'à ce que le serveur d'analyse fournisse une réponse.

Toutefois, les requêtes d'analyse peuvent expirer si leur traitement prend trop de temps. Si une requête doit traiter une grande quantité de données (par exemple, des centaines de Go), elle peut échouer à cause d'un délai avant expiration.

Le traitement des requêtes asynchrones vous permet de lancer des requêtes sur des ensembles de données très volumineux et de récupérer les résultats ultérieurement. Vous pouvez envisager d'utiliser une requête hors connexion lorsque vous constatez que vos requêtes interactives ont expiré. Le traitement des requêtes asynchrones peut constituer une bonne alternative dans certains cas, par exemple :

• Analyse et création de rapports couvrant de grands intervalles de temps
• Analyse des données avec diverses dimensions de regroupement et d'autres contraintes qui ajoutent de la complexité à la requête
• Gestion des requêtes lorsque vous constatez que les volumes de données ont considérablement augmenté pour certains utilisateurs ou organisations

Ce document explique comment lancer des requêtes asynchrones à l'aide de l'API. Vous pouvez également utiliser l'interface utilisateur, comme décrit dans la section Exécuter un rapport personnalisé.

Comparer l'API de création de rapports à l'interface utilisateur

La page Créer et gérer des rapports personnalisés décrit comment utiliser l'interface utilisateur Edge pour créer et exécuter des rapports personnalisés. Vous pouvez exécuter ces rapports de manière synchrone ou asynchrone.

La plupart des concepts liés à la génération de rapports personnalisés avec l'interface utilisateur s'appliquent à l'utilisation de l'API. Autrement dit, lorsque vous créez des rapports personnalisés avec l'API, vous spécifiez des métriques, des dimensions et des filtres intégrés à Edge, ainsi que toute métrique personnalisée que vous avez créée à l'aide de la règle StatisticsCollector.

La principale différence entre les rapports générés dans l'interface utilisateur et dans l'API est qu'ils sont écrits sous la forme de fichiers CSV ou JSON (délimités par un retour à la ligne) dans l'API, tandis qu'ils sont affichés sous la forme d'un rapport visuel dans l'UI.

Limites dans Apigee hybrid

Apigee hybrid applique une limite de taille de 30 Mo à l'ensemble de données obtenu.

Créer une requête d'analyse asynchrone

Vous effectuez des requêtes d'analyse asynchrones en trois étapes :

1. Envoyez la requête.

2. Obtenez l'état de la requête.

3. Récupérez les résultats de la requête.

Étape 1 : Envoyer la requête

Vous devez envoyer une requête POST à l'API /queries. Cette API demande à Edge de traiter votre demande en arrière-plan. Si la soumission de la requête aboutit, l'API renvoie un état 201 et un ID que vous utiliserez pour faire référence à la requête dans les étapes suivantes.

Exemple :

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

Le corps de la requête est une description JSON de la requête. Dans le corps JSON, spécifiez les métriques, les dimensions et les filtres qui définissent le rapport.

Vous trouverez ci-dessous un exemple de fichier json-query-file :

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

Pour obtenir une description complète de la syntaxe du corps de la requête, consultez la section À propos du corps de la requête ci-dessous.

Exemple de réponse :

Notez que l'ID de requête 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd est inclus dans la réponse. En plus de l'état HTTP 201, le paramètre state ayant la valeur enqueued signifie que la requête a abouti.

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

Étape 2 : Obtenir l'état de la requête

Effectuez un appel GET pour demander l'état de la requête. Vous fournissez l'ID de requête renvoyé par l'appel POST. Exemple :

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

Exemples de réponses :

Si la requête est toujours en cours, vous obtenez une réponse de ce type, où le paramètre state a la valeur running :

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

Une fois que la requête a abouti, vous verrez une réponse de ce type, où le paramètre state est défini sur completed :

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

Étape 3 : Récupérer les résultats de la requête

Lorsque l'état de la requête est completed, vous pouvez utiliser l'API get results pour récupérer les résultats, où l'ID de la requête est à nouveau 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

Pour récupérer le fichier téléchargé, vous devez configurer l'outil que vous utilisez afin qu'il enregistre un fichier téléchargé sur votre système. Exemple :

• Si vous utilisez cURL, vous pouvez utiliser les options -O -J, comme indiqué ci-dessus.

• Si vous utilisez Postman, vous devez sélectionner le bouton Enregistrer et télécharger. Dans ce cas, un fichier ZIP appelé response est téléchargé.

• Si vous utilisez le navigateur Chrome, le téléchargement est accepté automatiquement.

Si la requête aboutit et qu'il existe un ensemble de résultats non nul, le résultat est téléchargé vers le client sous la forme d'un fichier JSON compressé (délimité par un retour à la ligne). Le nom du fichier téléchargé sera le suivant :

OfflineQueryResult-<query-id>.zip

Exemple :

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

Le fichier ZIP contient un fichier d'archive .gz des résultats JSON. Pour accéder au fichier JSON, décompressez le fichier téléchargé, puis exécutez la commande gzip pour extraire le fichier JSON :

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

À propos du corps de la requête

Cette section décrit chacun des paramètres que vous pouvez utiliser dans le corps d'une requête JSON. Pour plus de détails sur les métriques et les dimensions que vous pouvez utiliser dans votre requête, consultez la documentation de référence d'Analytics.

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

Syntaxe des expressions de filtre

Cette section de référence décrit les jetons que vous pouvez utiliser pour créer des expressions de filtre dans le corps de la requête. Par exemple, l'expression suivante utilise le jeton "ge" (supérieur ou égal à) :

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

Contraintes et valeurs par défaut

Vous trouverez ci-dessous la liste des contraintes et des valeurs par défaut pour la fonctionnalité de traitement des requêtes asynchrones.

À propos des résultats de la requête

Vous trouverez ci-dessous un exemple de résultat au format JSON. La sortie comprend des lignes JSON séparées par un nouveau délimiteur de ligne :

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

Vous pouvez extraire les résultats de l'URL jusqu'à l'expiration des données dans le dépôt. Consultez la section Contraintes et valeurs par défaut.

Exemples

Exemple 1 : Somme des messages

Requête portant sur la somme des messages au cours des 60 dernières minutes.

Requête

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Corps de la requête de last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

Exemple 2 : Période personnalisée

Requête utilisant une période personnalisée.

Requête

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Corps de la requête de last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Exemple 3 : Transactions par minute

Requête sur la métrique pour les transactions par minute (tpm).

Requête

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

Corps de la requête de tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

Exemple de résultat

Extrait du fichier de résultats :

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

Exemple 4 : Utiliser une expression de filtre

Requête avec une expression de filtre utilisant un opérateur booléen.

Requête

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

Corps de la requête de filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Exemple 5 : Transmettre une expression dans le paramètre "metrics"

Requête avec une expression transmise dans le cadre du paramètre "metrics". Vous ne pouvez utiliser que des expressions simples à un opérateur.

Requête

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

Corps de la requête de metricsExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

Créer une requête de rapport de monétisation asynchrone

Vous pouvez capturer toutes les transactions de monétisation réussies dans une période donnée pour un ensemble de critères spécifique en suivant les étapes décrites dans cette section.

Comme pour les requêtes d'analyse asynchrones, vous effectuez des requêtes de rapport de monétisation asynchrones en trois étapes : (1) envoyez la requête, (2) obtenez l'état de la requête et (3) récupérez les résultats.

L'étape 1, qui consiste à envoyer la requête, est décrite ci-dessous.

Les étapes 2 et 3 sont exactement les mêmes que pour les requêtes d'analyse asynchrones. Pour plus d'informations, consultez la section Créer une requête d'analyse asynchrone.

Pour envoyer une requête concernant un rapport de monétisation asynchrone, envoyez une requête POST à /mint/organizations/org_id/async-reports.

Vous pouvez également spécifier l'environnement en transmettant le paramètre de requête environment. S'il n'est pas spécifié, le paramètre de requête est défini par défaut sur prod. Exemple :

/mint/organizations/org_id/async-reports?environment=prod

Dans le corps de la requête, spécifiez les critères de recherche suivants.

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

Par exemple, la requête suivante génère un rapport de monétisation asynchrone pour le mois de juin 2017 pour le produit d'API et l'ID de développeur spécifiés. Les valeurs fromDate et toDate du rapport sont exprimées en temps UTC/GMT et peuvent inclure des heures.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password