Analizza i contenuti dei messaggi dell'API utilizzando dati e analisi personalizzati

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

L'analisi delle API Edge raccoglie e analizza un'ampia gamma di informazioni statistiche da ogni richiesta e risposta dell'API. Queste informazioni vengono raccolte automaticamente e possono essere visualizzate nell'interfaccia utente Edge o utilizzando l'API delle metriche. Per ulteriori informazioni su queste statistiche, consulta metrics e Dimensioni.

Potresti anche voler raccogliere dati di analisi personalizzati specifici per proxy API, app, prodotti o sviluppatori. Ad esempio, potresti voler raccogliere dati da parametri di query, intestazioni delle richieste, corpi di richieste e risposte o variabili che definisci nelle API.

Questo argomento illustra come utilizzare il criterio StatisticsCollector per estrarre dati di analisi personalizzati da una richiesta o risposta dell'API e inviarli ad Analytics API Edge. Quindi, mostra come visualizzare i dati di analisi in un report nell'interfaccia utente Edge o utilizzando l'API Edge.

Informazioni sull'API Google Book

Questo argomento descrive come acquisire i dati di analisi personalizzati dalle richieste proxy API all'API Google Books. L'API Google Books consente di cercare libri per titolo, argomento, autore e altre caratteristiche.

Ad esempio, invia richieste all'endpoint /volumes per eseguire una ricerca in base al titolo del libro. Passa un singolo parametro di query all'API Books che contiene il titolo del libro:

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

La chiamata restituisce un array JSON di elementi trovati che corrispondono ai criteri di ricerca. Di seguito è mostrato il primo elemento array nella risposta (tieni presente che alcuni contenuti sono stati omessi per semplicità):

{
 "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"
    },
...
   }
  }

Nota che sono state evidenziate diverse aree della risposta:

  • Numero di risultati di ricerca
  • Valutazione media del libro
  • Numero di valutazioni
  • Disponibilità delle versioni PDF del libro

Le seguenti sezioni descrivono come raccogliere statistiche per queste aree della risposta e anche per il parametro di ricerca q contenente i criteri di ricerca.

Crea un proxy API per l'API Google Book

Prima di poter raccogliere statistiche per l'API Google Book, devi creare un proxy API Edge che la chiami. Quindi richiamerai quel proxy API per effettuare le richieste all'API Google Book.

Passaggio 2: crea un proxy API del tutorial per la creazione di un proxy API, descrive come creare un proxy che chiama l'API https://mocktarget.apigee.net. Tieni presente che il proxy descritto in quel tutorial non richiede una chiave API per chiamarlo.

Utilizza la stessa procedura per creare un proxy API per l'endpoint /volumes dell'API Google Book. Nel passaggio 5 della procedura, quando crei il proxy API, imposta le seguenti proprietà per fare riferimento all'API Google Books:

  • Nome proxy: "mybooksearch"
  • Percorso di base del proxy: "/mybooksearch"
  • API esistente: "https://www.googleapis.com/books/v1/volumes"

Dopo aver creato ed eseguito il deployment del proxy, dovresti essere in grado di chiamarlo utilizzando un comando curl nel formato:

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

dove org_name e env_name specificano l'organizzazione e l'ambiente in cui hai eseguito il deployment del proxy. Ad esempio:

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

Raccogliere dati di analisi personalizzati

La raccolta dei dati di analisi da una richiesta API è una procedura in due passaggi:

  1. Estrai i dati di interesse e scrivili in una variabile.

    Tutti i dati passati ad Analisi dell'API Edge provengono da valori memorizzati nelle variabili. Alcuni dati vengono archiviati automaticamente in variabili flow Edge predefinite, ad esempio i valori dei parametri di query passati al proxy API. Consulta la panoramica delle variabili di flusso per ulteriori informazioni sulle variabili di flusso predefinite.

    Utilizza il criterio Estrai variabili per estrarre contenuti personalizzati da una richiesta o risposta e scrivere i dati in una variabile.

  2. Scrivi i dati da una variabile all'analisi dell'API Edge.

    Utilizza il criterio Raccoglitore statistiche per scrivere dati da una variabile nell'analisi dell'API Edge. I dati possono provenire da variabili di flusso Edge predefinite o da variabili create dal criterio Estrai variabili.

Dopo aver raccolto i dati statistici, puoi utilizzare l'API o l'interfaccia utente di gestione perimetrale per recuperare e filtrare le statistiche. Ad esempio, potresti generare un report personalizzato che mostri la valutazione media di ogni titolo del libro, dove il titolo del libro corrisponde al valore del parametro di ricerca trasmesso all'API.

Usa il criterio Estrai variabili per estrarre dati analitici

Prima di poter essere trasferiti ad API Analytics, i dati di Analytics devono essere estratti e archiviati in una variabile di flusso predefinita da Edge oppure di variabili personalizzate da te definite. Per scrivere dati in una variabile, puoi utilizzare il criterio Estrai variabili.

Il criterio per l'estrazione delle variabili può analizzare i payload dei messaggi con espressioni JSONPath o XPath. Per estrarre le informazioni dai risultati di ricerca JSON della Google Book API, utilizza un'espressione JSONPath. Ad esempio, per estrarre il valore di averageRating dal primo elemento nell'array dei risultati JSON, l'espressione JSONPath è:

$.items[0].volumeInfo.averageRating

Una volta valutato il JSONPath, il criterio Estrai variabili scrive il valore estratto in una variabile.

In questo esempio, utilizzerai il criterio Estrai variabili per creare quattro variabili:

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

Per queste variabili, responsejson è la variabile prefix, mentre totalitems, ratingscount, avgrating e pdf sono i nomi delle variabili.

Il criterio Estrai variabili di seguito mostra come estrarre i dati dalla risposta JSON e scriverli nelle variabili personalizzate. Ogni elemento <Variable> utilizza l'attributo name, che specifica il nome delle variabili personalizzate e l'espressione JSONPath associata. L'elemento <VariablePrefix> specifica che il prefisso della variabile.

Aggiungi questo criterio al proxy API nella UI perimetrale. Se crei il proxy API in XML, aggiungi il criterio a un file in /apiproxy/policies denominato ExtractVars.xml:

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

Utilizzare il criterio del raccoglitore di statistiche per scrivere dati nel servizio Analytics

Utilizza il criterio Raccoglitore statistiche per scrivere dati da una variabile in Analisi dell'API Edge. Le norme relative alla raccolta di statistiche hanno il seguente formato:

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

dove:

  • statName specifica il nome utilizzato per fare riferimento ai dati statistici in un report personalizzato.
  • varName specifica il nome della variabile contenente i dati di analisi da raccogliere. Questa variabile può essere incorporata in Edge oppure può essere una variabile personalizzata creata dal criterio Estrai variabili.
  • dataType specifica il tipo di dati dei dati registrati come stringa, numero intero, numero in virgola mobile, lungo, doppio o booleano.

    Per i dati di tipo stringa, fai riferimento ai dati statistici come una dimensione in un report personalizzato. Per i tipi di dati numerici (numero intero/in virgola mobile/lungo/doppio), in un report personalizzato devi fare riferimento ai dati statistici come dimensione o metrica.

  • defValue fornisce facoltativamente un valore predefinito per una variabile personalizzata, che viene inviato ad Analisi delle API se le variabili non possono essere risolte o se non sono definite.

Nell'esempio riportato di seguito, il criterio del raccoglitore di statistiche viene utilizzato per raccogliere dati per le variabili create dal criterio Estrai variabili. Puoi anche raccogliere il valore del parametro di query passato a ogni chiamata API. Fai riferimento ai parametri di query utilizzando la variabile di flusso predefinita:

request.queryparam.queryParamName

Fai riferimento al parametro di query "q" come segue:

request.queryparam.q

Aggiungi questo criterio al proxy API nella UI di Edge oppure, se lo crei in XML, aggiungi un file in /apiproxy/policies denominato AnalyzeBookResults.xml, con i seguenti contenuti:

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

Collega criteri al flusso di risposta di ProxyEndpoint

Per un corretto funzionamento, i criteri devono essere collegati al flusso proxy API nella posizione appropriata. In questo caso d'uso, i criteri devono essere eseguiti dopo che la risposta è stata ricevuta dall'API Google Book e prima che la risposta venga inviata al client richiedente. Di conseguenza, collega i criteri al PreFlow di risposta ProxyEndpoint.

La configurazione ProxyEndpoint di esempio riportata di seguito esegue prima il criterio denominato ExtractVars per analizzare il messaggio di risposta. Successivamente, il criterio denominato AnalyzeBookResults inoltra questi valori ad analisi delle API:

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

Deployment del proxy API

Dopo aver apportato queste modifiche, devi eseguire il deployment del proxy API che hai configurato.

Completare i dati di analisi

Dopo aver implementato il proxy API, chiamalo per completare i dati in API Analytics. A tale scopo, esegui i comandi seguenti, ognuno dei quali utilizza un titolo del libro diverso:

Mobey Dick:

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

Il codice da Vinci:

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

L'amore bugiardo:

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

Il Trono di Spade:

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

Visualizza dati di analisi

Edge offre due modi per visualizzare i dati di analisi personalizzati:

  • L'interfaccia utente Edge supporta i report personalizzati che ti consentono di visualizzare i dati in un grafico grafico.
  • L'API delle metriche consente di recuperare i dati di analisi effettuando chiamate REST all'API Edge. Puoi utilizzare l'API per creare le tue visualizzazioni sotto forma di widget personalizzati che puoi incorporare in portali o app personalizzate.

Generare un report di statistiche utilizzando l'interfaccia utente Edge

I report personalizzati ti consentono di visualizzare in dettaglio le statistiche dell'API specifiche per individuare i dati esatti che vuoi consultare. Puoi creare un report personalizzato utilizzando qualsiasi delle metrics e delle dimensioni incorporate in Edge. Inoltre, puoi utilizzare qualsiasi dato di analisi che hai estratto utilizzando il criterio StatisticsCollector.

Quando crei un criterio per la raccolta delle statistiche, devi specificare il tipo di dati raccolti. Per il tipo di dati stringa, fai riferimento ai dati statistici come dimensione in un report personalizzato. Per i tipi di dati numerici (numero intero/in virgola mobile/lungo/doppio), fai riferimento alla data statistica in un report personalizzato come dimensione o metrica. Per ulteriori informazioni, consulta Gestire i report personalizzati.

Generazione di un report personalizzato utilizzando l'interfaccia utente Edge:

  1. Accedere alla pagina Report personalizzati, come descritto di seguito.

    Perimetrale

    Per accedere alla pagina Report personalizzati utilizzando l'interfaccia utente Edge:

    1. Accedi ad apigee.com/edge.
    2. Seleziona Analizza > Report personalizzati > Report nella barra di navigazione a sinistra.

    Classic Edge (private cloud)

    Per accedere alla pagina Report personalizzati utilizzando l'interfaccia utente Edge classico:

    1. Accedi a http://ms-ip:9000, dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.
    2. Seleziona Analisi > Report nella barra di navigazione in alto.

  2. Nella pagina Report personalizzati, fai clic su +Report personalizzato.
  3. Specifica un Nome report, ad esempio mybookreport.
  4. Seleziona una Metrica integrata, ad esempio Traffico, e una Funzione aggregata, ad esempio Somma.

    In alternativa, seleziona una delle statistiche di dati numeriche create utilizzando il criterio StatisticsCollector. Ad esempio, seleziona ratingscount e una Funzione aggregata di Somma.

  5. Seleziona una dimensione integrata, ad esempio un proxy API, o una qualsiasi stringa o statistiche numeriche che hai creato utilizzando il criterio StatisticsCollector.

    Ad esempio, seleziona booktitle. Il report mostrerà ora la somma di ratingscount per booktitle:

    report sui libri personalizzato
  6. Seleziona Salva. Il report viene visualizzato nell'elenco di tutti i report personalizzati.
  7. Per eseguire il report, seleziona il nome del report. Per impostazione predefinita, il report mostra i dati dell'ultima ora.

  8. Per impostare l'intervallo di tempo, seleziona la visualizzazione della data nell'angolo in alto a destra per aprire il popup del selettore di date.
  9. Seleziona Ultimi 7 giorni. Il report viene aggiornato mostrando la somma delle valutazioni per titolo del libro:

    Grafico del report sui libri

Ricevi statistiche con l'API Edge

Utilizza l'API Edge Metrics per le statistiche sui dati di analisi personalizzati. Nella richiesta di esempio riportata di seguito:

  • La risorsa all'URL dopo /stats specifica la dimensione desiderata. In questo esempio, ottieni i dati per la dimensione booktitle.
  • Il parametro di query select per specificare le metrics da recuperare. Questa richiesta restituisce dati e analisi basati sulla somma dei ratingscount.
  • Il parametro timeRange specifica l'intervallo di tempo per i dati restituiti. L'intervallo di tempo ha il seguente formato:

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

La chiamata API completa è:

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

Dovresti vedere una risposta nel modulo:

{
  "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 Edge Metrics ha molte opzioni. Ad esempio, puoi ordinare i risultati in ordine crescente o decrescente. Nell'esempio seguente, utilizza l'ordine crescente:

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

I risultati possono anche essere filtrati specificando i valori delle dimensioni di interesse. Nell'esempio riportato di seguito, il report viene filtrato in base ai risultati relativi a "Gone Girl" e "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

Creazione di variabili di analisi personalizzate con lo Strumento per la creazione di soluzioni

Solution Builder consente di creare variabili di analisi personalizzate tramite una finestra di dialogo dell'interfaccia utente di gestione di facile utilizzo.

Ti consigliamo di leggere la sezione precedente Raccogliere dati di analisi personalizzati, in cui viene spiegato in che modo i criteri Estrai variabili e raccoglitore statistiche funzionano in sinergia per fornire variabili personalizzate ad Analytics dell'API Edge. Come vedrai, l'interfaccia utente segue questo stesso schema, ma offre un modo comodo per configurare le impostazioni completamente attraverso l'interfaccia utente. Se vuoi, prova l'esempio dell'API Google Books utilizzando l'interfaccia utente anziché modificare e allegare manualmente i criteri.

La finestra di dialogo Solution Builder consente di configurare le variabili di analisi direttamente nell'interfaccia utente. Questo strumento genera automaticamente i criteri e li collega al proxy API. I criteri estraggono le variabili di interesse dalle richieste o dalle risposte e le passano all'analisi dell'API Edge.

Lo strumento per la creazione di soluzioni crea nuovi criteri per il raccoglitore di statistiche e di estrazione delle variabili e assegna loro nomi univoci. Solution Builder non consente di tornare indietro e modificare questi criteri una volta creati in una determinata revisione del proxy. Per apportare modifiche, modifica i criteri generati direttamente nell'editor dei criteri.

  1. Vai alla pagina Panoramica del proxy nell'interfaccia utente Edge.
  2. Fai clic su Sviluppa.
  3. Nella pagina Sviluppo, seleziona Raccolta personalizzata di Analytics dal menu Strumenti. Viene visualizzata la finestra di dialogo Solution Builder.
  4. Nella finestra di dialogo Solution Builder, devi prima configurare due criteri: estrazione variabili e raccoglitore statistiche. Quindi, configurerai dove collegare questi criteri.
  5. Specifica i dati che vuoi estrarre:
    • Tipo di posizione: seleziona il tipo di dati che vuoi raccogliere e da dove raccoglierli. Puoi selezionare i dati dal lato della richiesta o della risposta. Ad esempio, Richiesta: parametro di ricerca o risposta: corpo XML.
    • Fonte delle informazioni sulla posizione: identifica i dati che vuoi raccogliere. Ad esempio, il nome del parametro di ricerca o il nome XPath per i dati XML nel corpo della risposta.
  6. Specifica un nome (e un tipo) di variabile che il criterio del raccoglitore di statistiche utilizzerà per identificare i dati estratti. Consulta le limitazioni di denominazione in questo argomento.

    Il nome utilizzato verrà visualizzato nel menu a discesa Dimensioni o Metriche nell'interfaccia utente di Report Builder personalizzato.
  7. Scegli dove nel flusso proxy API vuoi collegare i criteri generati Estrazione di variabili e raccoglitore di statistiche. Per indicazioni, consulta "Collegare i criteri al flusso di risposta di ProxyEndpoint". Per un corretto funzionamento, i criteri devono essere collegati al flusso proxy API nella posizione appropriata. Devi collegare i criteri nella fase del flusso in cui le variabili che stai bloccando rientrano nell'ambito (compilate).
  8. Fai clic su +Raccoglitore per aggiungere altre variabili personalizzate.
  9. Al termine, fai clic su Crea soluzione.

  10. Salva ed esegui il deployment del proxy.

Ora puoi generare un report personalizzato per i dati come descritto sopra.