Analyser le contenu du message de l'API à l'aide de données analytiques personnalisées

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

Edge API Analytics collecte et analyse une grande variété d'informations statistiques provenant de chaque requête et réponse d'API. Ces informations sont automatiquement recueillies et peuvent ensuite être affichées dans l'UI Edge ou à l'aide de l'API Metrics. Pour en savoir plus sur ces statistiques, consultez les sections Métriques et Dimensions.

Vous pouvez également recueillir des données analytiques personnalisées spécifiques à vos proxys d'API, vos applications, vos produits ou vos développeurs. Par exemple, vous souhaiterez peut-être recueillir des données à partir des paramètres de requête, des en-têtes de requête, des corps de requête et de réponse ou des variables que vous définissez dans vos API.

Cette rubrique explique comment utiliser la règle StatisticsCollector pour extraire des données analytiques personnalisées à partir d'une requête/réponse d'API et transmettre ces données à Edge API Analytics. Elle explique également comment afficher vos données analytiques dans un rapport dans l'UI Edge ou à l'aide de l'API Edge.

À propos de l'API Google Book

Cette rubrique explique comment capturer des données analytiques personnalisées provenant de requêtes de proxy d'API dans l' API Google Livres. L'API Google Books vous permet de rechercher des livres par titre, sujet, auteur, etc.

Par exemple, envoyez des requêtes au point de terminaison /volumes pour effectuer une recherche par titre de livre. Transmettez à l'API Books un seul paramètre de requête contenant le titre du livre :

curl https://www.googleapis.com/books/v1/volumes?q=davinci%20code

L'appel renvoie un tableau JSON d'éléments correspondant aux critères de recherche. Vous trouverez ci-dessous le premier élément de tableau de la réponse (notez que certains contenus ont été omis pour des raisons de simplicité) :

{
 "kind": "books#volumes",
 "totalItems": 1799,
 "items": [
  {
   "kind": "books#volume",
   "id": "ohZ1wcYifLsC",
   "etag": "4rzIsMdBMYM",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/ohZ1wcYifLsC",
   "volumeInfo": {
    "title": "The Da Vinci Code",
    "subtitle": "Featuring Robert Langdon",
    "authors": [
     "Dan Brown"
    ],
    "publisher": "Anchor",
    "publishedDate": "2003-03-18",
    "description": "MORE THAN 80 MILLION COPIES SOLD ....",
    "industryIdentifiers": [
     {
      "type": "ISBN_10",
      "identifier": "0385504217"
     },
     {
      "type": "ISBN_13",
      "identifier": "9780385504218"
     }
    ],
    "readingModes": {
     "text": true,
     "image": true
    },
    "pageCount": 400,
    "printType": "BOOK",
    "categories": [
     "Fiction"
    ],
    "averageRating": 4.0,
    "ratingsCount": 710,
    "maturityRating": "NOT_MATURE",
    "allowAnonLogging": true,
    "contentVersion": "0.18.13.0.preview.3",
    "panelizationSummary": {
     "containsEpubBubbles": false,
     "containsImageBubbles": false
    },
...
   "accessInfo": {
    "country": "US",
    "viewability": "PARTIAL",
    "embeddable": true,
    "publicDomain": false,
    "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
    "epub": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
    "pdf": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
...
   }
  }

Notez que plusieurs parties de la réponse ont été mises en surbrillance :

  • Nombre de résultats de recherche
  • Note moyenne du livre
  • Nombre de notes
  • Disponibilité du livre en versions PDF

Les sections suivantes décrivent comment recueillir des statistiques pour ces parties de la réponse et pour le paramètre de requête, q, contenant les critères de recherche.

Créer un proxy d'API pour l'API Google Book

Avant de pouvoir collecter des statistiques pour l'API Google Book, vous devez créer un proxy d'API Edge qui l'appelle. Ensuite, vous devez appeler ce proxy d'API pour envoyer vos requêtes à l'API Google Book.

Étape 2 : Créer un proxy d'API du tutoriel concernant la création d'un proxy d'API décrit comment créer un proxy qui appelle l' API https://mocktarget.apigee.net. Notez que le proxy décrit dans ce tutoriel ne nécessite pas de clé API pour l'appeler.

Utilisez cette même procédure pour créer un proxy d'API pour le point de terminaison /volumes de l'API Google Book. À l'étape 5 de la procédure, lorsque vous créez le proxy d'API, définissez les propriétés suivantes pour référencer l'API Google Books :

  • Nom du proxy : "mybooksearch"
  • Chemin de base du proxy : "/mybooksearch"
  • API existante : "https://www.googleapis.com/books/v1/volumes"

Après avoir créé et déployé le proxy, vous devriez pouvoir l'appeler à l'aide d'une commande curl au format suivant :

curl http://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

où org_name et env_name spécifient l'organisation et l'environnement dans lesquels vous avez déployé le proxy. Exemple : 

curl http://myorg-test.apigee.net/mybooksearch?q=davinci%20code

Collecter des données analytiques personnalisées

La collecte de données analytiques à partir d'une requête API s'effectue en deux étapes :

  1. Extrayez les données qui vous intéressent et écrivez-les dans une variable.

    Toutes les données transmises à Edge API Analytics proviennent de valeurs stockées dans des variables. Certaines données sont automatiquement stockées dans des variables de flux Edge prédéfinies, telles que les valeurs des paramètres de requête transmis au proxy d'API. Pour en savoir plus sur les variables de flux prédéfinies, consultez la page Présentation des variables de flux.

    Utilisez la règle Extract Variables pour extraire le contenu personnalisé d'une requête ou d'une réponse, et écrire ces données dans une variable.

  2. Écrivez les données d'une variable dans Edge API Analytics.

    Utilisez la règle Statistics Collector pour écrire les données d'une variable dans Edge API Analytics. Les données peuvent provenir de variables de flux Edge prédéfinies ou de variables créées par la règle ExtractVariables, .

Après avoir recueilli les données statistiques, vous pouvez utiliser l'UI de gestion ou l'API Edge pour récupérer et filtrer les statistiques. Par exemple, vous pouvez générer un rapport personnalisé indiquant la note moyenne de chaque titre de livre, le titre du livre correspondant à la valeur du paramètre de requête transmis à l'API.

Utiliser la règle ExtractVariables pour extraire des données analytiques

Avant de pouvoir être transmises à l'API Analytics, les données analytiques doivent être extraites et stockées dans une variable, soit une variable de flux prédéfinie par Edge, soit des variables personnalisées que vous définissez. Pour écrire des données dans une variable, vous devez utiliser la règle ExtractVariables.

La règle ExtractVariables peut analyser les charges utiles de messages avec des expressions JSONPath ou XPath. Pour extraire les informations des résultats de recherche JSON de l'API Google Book, utilisez une expression JSONPath. Par exemple, pour extraire la valeur du averageRating du premier élément du tableau de résultats JSON, l'expression JSONPath est la suivante :

$.items[0].volumeInfo.averageRating

Une fois l'expression JSONPath évaluée, la règle ExtractVariables écrit la valeur extraite dans une variable.

Dans cet exemple, vous utilisez la règle ExtractVariables pour créer quatre variables :

  • responsejson.totalitems
  • responsejson.ratingscount
  • responsejson.avgrating
  • responsejson.pdf

Pour ces variables, responsejson est le préfixe de la variable, et totalitems, ratingscount, avgrating et pdf sont les noms des variables.

La règle ExtractVariables ci-dessous montre comment extraire des données de la réponse JSON et les écrire dans des variables personnalisées. Chaque élément <Variable> utilise l'attribut name qui spécifie le nom des variables personnalisées et l'expression JSONPath associée. L'élément <VariablePrefix> spécifie le préfixe de la variable.

Ajoutez cette règle à votre proxy d'API dans l'UI Edge. Si vous créez le proxy d'API au format XML, ajoutez la règle dans un fichier nommé ExtractVars.xml, sous /apiproxy/policies :

<ExtractVariables name="ExtractVars">
    <Source>response</Source>
    <JSONPayload>
        <Variable name="totalitems">
            <JSONPath>$.totalItems</JSONPath>
        </Variable>
        <Variable name="ratingscount">
            <JSONPath>$.items[0].volumeInfo.ratingsCount</JSONPath>
        </Variable>
        <Variable name="avgrating">
            <JSONPath>$.items[0].volumeInfo.averageRating</JSONPath>
        </Variable>
        <Variable name="pdf">
            <JSONPath>$.items[0].accessInfo.pdf.isAvailable</JSONPath>
        </Variable>
    </JSONPayload>
    <VariablePrefix>responsejson</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Utiliser la règle StatisticsCollector pour écrire des données dans le service Analytics

Utilisez la règle Statistics Collector pour écrire les données d'une variable dans Edge API Analytics. La règle StatisticsCollector se présente comme suit :

<StatisticsCollector>
<DisplayName>Statistics Collector-1</DisplayName>
    <Statistics>
        <Statistic name="statName" ref="varName" type="dataType">defVal</Statistic>
       …
    </Statistics>
</StatisticsCollector>

où :

  • statName spécifie le nom que vous utilisez pour référencer les données statistiques dans un rapport personnalisé.
  • varName spécifie le nom de la variable contenant les données analytiques à collecter. Cette variable peut être intégrée à Edge ou être une variable personnalisée créée par la règle ExtractVariables.

  • dataType spécifie le type de données enregistrées (chaîne, entier, flottant, long, double ou booléen).

    Pour les données de type chaîne, référencez les données statistiques en tant que dimension dans un rapport personnalisé. Pour les données numériques (nombre entier/à virgule flottante/long/double), référencez les données statistiques en tant que dimension ou une métrique dans un rapport personnalisé.

  • defValue fournit éventuellement une valeur par défaut pour une variable personnalisée, qui est envoyée à API Analytics si les variables ne peuvent pas être résolues ou si la variable n'est pas définie.

Dans l'exemple ci-dessous, vous utilisez la règle StatisticsCollector pour collecter des données pour les variables créées par la règle ExtractVariables. Vous collectez également la valeur du paramètre de requête transmis à chaque appel d'API. Référencez les paramètres de requête à l'aide de la variable de flux prédéfinie :

request.queryparam.queryParamName

Pour le paramètre de requête nommé "q", référencez-le comme suit :

request.queryparam.q

Ajoutez cette règle à votre proxy d'API dans l'UI Edge ou, si vous créez le proxy d'API au format XML, ajoutez un fichier nommé AnalyzeBookResults.xml, sous /apiproxy/policies, avec le contenu suivant :

<StatisticsCollector name="AnalyzeBookResults">
 <Statistics>
        <Statistic name="totalitems" ref="responsejson.totalitems" type="integer">0</Statistic>
        <Statistic name="ratingscount" ref="responsejson.ratingscount" type="integer">0</Statistic>
        <Statistic name="avgrating" ref="responsejson.avgrating" type="float">0.0</Statistic>
        <Statistic name="pdf" ref="responsejson.pdf" type="boolean">true</Statistic>
        <Statistic name="booktitle" ref="request.queryparam.q" type="string">none</Statistic>
 </Statistics>
</StatisticsCollector>

Associer des règles au flux de réponse ProxyEndpoint

Pour un bon fonctionnement, les règles doivent être associées au flux du proxy d'API à l'emplacement approprié. Dans ce cas d'utilisation, les règles doivent s'exécuter après la réception de la réponse de l'API Google Book et avant l'envoi de la réponse au client demandeur. Par conséquent, associez les règles au paramètre Preflow de la réponse ProxyEndpoint.

L'exemple de configuration ProxyEndpoint ci-dessous exécute d'abord la règle appelée ExtractVars pour analyser le message de réponse. La règle appelée AnalyzeBookResults transmet ensuite ces valeurs à l'API Analytics :

<ProxyEndpoint name="default">
    ><PreFlow name="PreFlow">
        <Request/>
        <Response>
            <Step>
                <Name>Extract-Vars</Name>
            </Step>
            <Step>
                <Name>AnalyzeBookResults</Name>
            </Step>
        </Response>
    </PreFlow>
 <HTTPProxyConnection>
  <!-- Base path used to route inbound requests to this API proxy -->
  <BasePath>/mybooksearch</BasePath>
  <!-- The named virtual host that defines the base URL for requests to this proxy -->
  <VirtualHost>default</VirtualHost>
 </HTTPProxyConnection>
 <RouteRule name="default">
 <!-- Connects the proxy to the target defined under /targets -->
  <TargetEndpoint>default</TargetEndpoint>
 </RouteRule>
</ProxyEndpoint>

Déployer le proxy d'API

Après avoir apporté ces modifications, vous devez déployer le proxy d'API que vous avez configuré.

Renseigner les données analytiques

Après avoir déployé votre proxy d'API, appelez-le pour renseigner les données dans l'API Analytics. Pour ce faire, exécutez les commandes suivantes, chacune incluant un titre de livre différent :

Moby Dick :

curl https://org_name-env_name.apigee.net/mybooksearch?q=mobey%20dick

Da Vinci Code :

curl https://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

Gone Girl :

curl https://org_name-env_name.apigee.net/mybooksearch?q=gone%20girl

Game of Thrones :

curl https://org_name-env_name.apigee.net/mybooksearch?q=game%20of%20thrones

Afficher les données d'analyse

Edge offre deux façons d'afficher vos données analytiques personnalisées :

  • L'UI Edge accepte les rapports personnalisés vous permettant d'afficher vos données dans un graphique.
  • L'API Metrics vous permet de récupérer des données d'analyse en effectuant des appels REST vers l' API Edge. Vous pouvez utiliser l'API pour créer vos propres visualisations sous la forme de widgets personnalisés que vous pouvez intégrer à des portails ou à des applications personnalisées.

Générer un rapport de statistiques à l'aide de l'UI Edge

Les rapports personnalisés vous permettent d'explorer des statistiques d'API spécifiques et d'afficher les données exactes que vous souhaitez voir. Vous pouvez créer un rapport personnalisé à l'aide de l'une des métriques et dimensions intégrées à Edge. En outre, vous pouvez utiliser n'importe quelle donnée analytique que vous avez extraite à l'aide de la règle StatisticsCollector.

Lorsque vous créez une règle StatisticsCollector, vous spécifiez le type de données collectées. Pour les données de type chaîne, référencez les données statistiques en tant que dimension dans un rapport personnalisé. Pour les données de type numérique (nombre entier/à virgule flottante/long/double), référencez la date statistique dans un rapport personnalisé en tant que dimension ou métrique. Pour en savoir plus, consultez la page Gérer des rapports personnalisés.

Générer un rapport personnalisé à l'aide de l'UI Edge :

  1. Accédez à la page "Rapports personnalisés", comme décrit ci-dessous.

    Edge

    Pour accéder à la page "Rapports personnalisés" à l'aide de l'UI Edge, procédez comme suit :

    1. Connectez-vous à apigee.com/edge.
    2. Sélectionnez Analyser > Rapports personnalisés > Rapports dans la barre de navigation de gauche.

    Classic Edge (Cloud privé)

    Pour accéder à la page "Rapports personnalisés" à l'aide de l'UI Classic Edge, procédez comme suit :

    1. Connectez-vous à http://ms-ip:9000, où ms-ip correspond à l'adresse IP ou au nom DNS du nœud du serveur de gestion.

    2. Sélectionnez Analyse > Rapports dans la barre de navigation supérieure.

  2. Sur la page "Rapports personnalisés", cliquez sur + Nouveau rapport personnalisé.
  3. Spécifiez un nom de rapport, tel que mybookreport.

  4. Sélectionnez une métrique intégrée, telle que Trafic, et une fonction d'agrégation, telle que Somme.

    Vous pouvez également sélectionner l'une des statistiques de données numériques que vous avez créées à l'aide de la règle StatisticsCollector. Par exemple, sélectionnez ratingscount (Nombre de notes) et la fonction d'agrégation Somme.

  5. Sélectionnez une dimension intégrée, telle qu'un proxy d'API, ou l'une des statistiques de type chaîne ou numérique que vous avez créées à l'aide de la règle StatisticsCollector.

    Par exemple, sélectionnez booktitle (Titre de livre). Votre rapport affiche alors la somme des ratingscount par titre de livre :

    Rapport personnalisé sur les livres
  6. Sélectionnez Enregistrer. Le rapport apparaît dans la liste de tous les rapports personnalisés.

  7. Pour générer le rapport, sélectionnez son nom. Par défaut, le rapport affiche les données de la dernière heure.

  8. Pour définir une période, sélectionnez la période affichée dans l'angle supérieur droit afin d'ouvrir la fenêtre pop-up Sélecteur de date.

  9. Sélectionnez l'option Les 7 derniers jours. Le rapport se met à jour pour afficher la somme des notes par titre de livre :

    Graphique du rapport sur les livres

Obtenir des statistiques à l'aide de l'API Edge

Utilisez l'API Metrics d'Edge pour obtenir des statistiques sur vos données analytiques personnalisées. Dans l'exemple de requête ci-dessous :

  • La ressource vers l'URL après /stats spécifie la dimension souhaitée. Dans cet exemple, vous obtenez des données pour la dimension booktitle.
  • Le paramètre de requête select spécifie les métriques à récupérer. Cette requête renvoie des données analytiques concernant la somme des ratingscount.

  • Le paramètre timeRange spécifie l'intervalle de temps pour les données renvoyées. La période est au format suivant :

    MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

L'appel d'API complet ressemble à ceci :

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00" /
-u email:password

Vous devriez obtenir une réponse au format suivant :

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "5352.0"
              ]
            }
          ],
          "name": "gone girl"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "4260.0"
              ]
            }
          ],
          "name": "davinci code"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1836.0"
              ]
            }
          ],
          "name": "game of thrones"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1812.0"
              ]
            }
          ],
          "name": "mobey dick"
        }
      ],
      "name": "prod"
    }
  ],
  "metaData": {
    "errors": [],
    "notices": [
      "query served by:9b372dd0-ed30-4502-8753-73a6b09cc028",
      "Table used: uap-prod-gcp-us-west1.edge.edge_api_raxgroup021_fact",
      "Source:Big Query"
    ]
  }
}

L'API Metrics d'Edge dispose de nombreuses options. Par exemple, vous pouvez trier les résultats par ordre croissant ou décroissant. Dans l'exemple suivant, vous utiliserez l'ordre croissant :

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&sort=ASC" /
-u email:password

Les résultats peuvent également être filtrés en spécifiant les valeurs des dimensions qui vous intéressent. Dans l'exemple ci-dessous, le rapport est filtré par résultats pour "Gone Girl" et "The Da Vinci Code" :

$ curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&filter=(booktitle%20in%20'gone%20girl'%2C%20'davinci%20code')" /
-u email:password

Créer des variables de données analytiques personnalisées avec le générateur de solutions

Le générateur de solutions vous permet de créer des variables de données analytiques personnalisées via une boîte de dialogue conviviale de l'UI de gestion.

Vous pouvez consulter la section précédente Collecter des données analytiques personnalisées, qui explique comment les règles ExtractVariables et StatisticsCollector fonctionnent ensemble pour transmettre des variables personnalisées à Edge API Analytics. Comme vous pouvez le voir, l'UI suit le même schéma, mais fournit un moyen pratique d'effectuer entièrement vos configurations. Si vous le souhaitez, essayez l'exemple de l'API Google Books en utilisant l'UI au lieu de modifier et d'associer des règles manuellement.

La boîte de dialogue du générateur de solutions vous permet de configurer des variables de données analytiques directement dans l'UI. Cet outil génère les règles et les associe au proxy d'API pour vous. Les règles extraient les variables d'intérêt des requêtes ou des réponses et les transmettent à Edge API Analytics.

Le générateur de solutions crée de nouvelles règles ExtractVariables et StatisticsCollector, et leur attribue des noms uniques. Il ne vous permet pas de revenir en arrière et de modifier ces règles une fois qu'elles ont été créées dans une révision de proxy donnée. Pour apporter des modifications, modifiez les règles générées directement dans l'éditeur de règle.

  1. Accédez à la page "Vue d'ensemble" de votre proxy dans l'UI Edge.
  2. Cliquez sur Développer.
  3. Sur la page "Développer", sélectionnez Collecte de données analytiques personnalisées dans le menu "Outils". La boîte de dialogue du générateur de solutions s'affiche.
  4. Dans cette boîte de dialogue, vous configurez d'abord deux règles : ExtractVariables et StatisticsCollector. Vous configurez ensuite l'emplacement où ces règles doivent être associées.
  5. Spécifiez les données que vous souhaitez extraire :
    • Location Type (Type d'emplacement) : sélectionnez le type de données que vous souhaitez collecter et où les collecter. Vous pouvez sélectionner des données du côté requête ou réponse. Par exemple, "Request: Query Parameter" (Requête : paramètre de requête ou "Response: XML Body." (Réponse : corps du fichier XML).
    • Location Source (Source de l'emplacement) : identifiez les données que vous souhaitez collecter. Par exemple, le nom du paramètre de requête ou l'expression XPath pour les données XML dans le corps de la réponse.
  6. Spécifiez un nom de variable (et un type) que la règle StatisticsCollector utilisera pour identifier les données extraites. Consultez les restrictions en termes de dénomination dans cette rubrique.

    Le nom que vous utilisez apparaîtra dans le menu déroulant Dimensions ou Métriques dans l'UI de l'Outil de création de rapports personnalisés.
  7. Choisissez où, dans le flux de proxy d'API, vous souhaitez associer les règles ExtractVariables et StatisticsCollector générées. Pour obtenir des instructions, consultez la section Associer des règles au flux de réponse ProxyEndpoint. Pour un bon fonctionnement, les règles doivent être associées au flux du proxy d'API à l'emplacement approprié. Vous devez associer les règles à l'étape du flux où les variables souhaitées sont couvertes (renseignées).
  8. Cliquez sur + Collector (Nouvelle collecte) pour ajouter d'autres variables personnalisées.

  9. Lorsque vous avez terminé, cliquez sur Build Solution (Générer la solution).

  10. Enregistrez et déployez le proxy.

Vous pouvez maintenant générer un rapport personnalisé pour les données, comme décrit ci-dessus.