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

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Edge API Analytics collecte et analyse une grande variété d'informations statistiques provenant de chaque requête et réponse de l'API. Ces informations sont collectées automatiquement et peuvent ensuite être affichées dans le Edge ou à l'aide de l'API de métriques. 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 stratégie StatisticsCollector . pour extraire des données d'analyse personnalisées d'une demande/réponse API et les transmettre à Edge API Analytics. Ensuite, il montre comment afficher vos données d'analyse dans un rapport de l'interface utilisateur 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 Books. 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. Vous appelez ensuite ce proxy d'API pour envoyer vos requêtes à l'API Google Book.

L'é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 la même procédure pour créer un proxy d'API pour le point de terminaison /volumes du 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 pertinentes et écrivez-les dans une variable.

    Toutes les données transmises à Edge API Analytics proviennent des 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 de l'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 ExtractVariables pour extraire le contenu personnalisé d'une requête ou d'une réponse, et écrire ces données dans une variable.

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

    Utiliser la stratégie du collecteur de statistiques pour écrire les données d'une variable dans Edge API Analytics. Elles peuvent provenir d'entrées prédéfinies Variables de flux Edge ou les variables créées par la stratégie Extraire les variables.

Une fois les données statistiques collectées, vous pouvez utiliser l'interface utilisateur ou l'API de gestion 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

Les données d'analyse doivent être extraites et stockées dans une variable, soit une variable de flux prédéfinie par Variables de périphérie ou personnalisées que vous définissez, avant qu'elles puissent être transmises à API Analytics. 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 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 stratégie à votre proxy d'API dans l'interface utilisateur 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 stratégie du collecteur de statistiques pour écrire des données dans le service d'analyse

Utiliser la stratégie du collecteur de statistiques pour écrire les données d'une variable dans Edge API Analytics. La stratégie de collecte de statistiques a la forme suivante:

<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 d'analyse à collecter. Cette variable peut être intégrée dans Edge ou il peut s'agir d'une variable personnalisée créée par la règle Extract Variables.

  • dataType spécifie le type de données des données enregistrées sous forme de chaîne, d'entier, de float, long, double ou booléen.

    Pour les données de type chaîne, vous référencez les données statistiques en tant que dimension. dans un rapport personnalisé. Pour les types de données numériques (entier/flottant/long/double), vous référencez le les données statistiques sous forme de dimension ou une métrique dans un rapport personnalisé.

  • defValue permet éventuellement de définir 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 stratégie du collecteur de statistiques pour collecter des données pour les variables créées par la règle Extract Variables. Vous collectez aussi la valeur du paramètre de requête transmis à chaque appel d'API. Vous pouvez référencer des paramètres de requête à l'aide du modèle variable de flux:

request.queryparam.queryParamName

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

request.queryparam.q

Ajoutez cette stratégie à votre proxy d'API dans l'interface utilisateur Edge ou, si vous construisez le proxy d'API en XML, Sous /apiproxy/policies, ajoutez un fichier nommé AnalyzeBookResults.xml, 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 stratégies doivent s'exécuter après la réception de la réponse de l'API Google Book. et avant d'envoyer 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 propose deux façons d'afficher vos données d'analyse personnalisées:

  • L'interface utilisateur Edge prend en charge les rapports personnalisés qui vous permettent d'afficher vos données dans un graphique.
  • L'API de métriques vous permet de récupérer des données d'analyse en effectuant des appels REST vers la 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'interface utilisateur 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 n'importe quelle métrique. et les 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ération d'un rapport personnalisé à l'aide de l'interface utilisateur 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'interface utilisateur Edge:

    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'interface utilisateur Classic Edge:

    1. Connectez-vous à http://ms-ip:9000, où ms-ip est le Adresse IP ou nom DNS du nœud du serveur de gestion.

    2. Sélectionnez Données analytiques > "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

Utiliser l'API de métriques Edge aux statistiques de vos données d'analyse 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 de métriques Edge offre 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

Solution Builder vous permet de créer des variables d'analyse personnalisées à l'aide d'un outil de gestion de l'UI.

Nous vous invitons à lire la section précédente Collecter des données d'analyse personnalisées. qui explique le fonctionnement des stratégies Extract Variables and Statistics Collector main dans la main 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 stratégies extraient variables d'intérêt des requêtes ou des réponses et transmettre les variables extraites à 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 Présentation de votre proxy dans l'interface utilisateur 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 joindre le des stratégies à une étape du flux où les variables piégées entrent dans le champ d'application (renseignée).
  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.