Utilizzare l'API asincrona per i report personalizzati

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

Edge Analytics fornisce un ampio insieme di dashboard interattive, generatori di report personalizzati e funzionalità correlate. Tuttavia, queste funzionalità sono pensate per essere interattive: invii una richiesta API o UI e la richiesta viene bloccata finché il server di analisi non fornisce una risposta.

Tuttavia, le richieste di analisi possono scadere se richiedono troppo tempo per essere completate. Se una richiesta di query deve elaborare una grande quantità di dati (ad esempio centinaia di GB), potrebbe non riuscire a causa di un timeout.

L'elaborazione asincrona delle query ti consente di eseguire query su set di dati molto grandi e di recuperare i risultati in un secondo momento. Ti consigliamo di utilizzare una query offline se noti che le query interattive scadono. Ecco alcune situazioni in cui l'elaborazione asincrona delle query potrebbe essere una buona alternativa:

• Analisi e creazione di report che coprono intervalli di tempo ampi.
• Analisi dei dati con una serie di dimensioni di raggruppamento e altri vincoli che aumentano la complessità della query.
• Gestire le query quando scopri che i volumi di dati sono aumentati in modo significativo per alcuni utenti o organizzazioni.

Questo documento descrive come avviare una query asincrona utilizzando l'API. Puoi anche utilizzare l'interfaccia utente, come descritto in Eseguire un report personalizzato.

Confronto dell'API di reporting con l'interfaccia utente

L'articolo Creare e gestire i report personalizzati descrive come utilizzare l'interfaccia utente di Edge per creare ed eseguire report personalizzati. Puoi eseguire questi report in modo sincrono o asincrono.

La maggior parte dei concetti per la generazione di report personalizzati con l'interfaccia utente si applica all'utilizzo dell'API. In altre parole, quando crei report personalizzati con l'API, specifichi le metriche, le dimensioni e i filtri integrati in Edge, nonché eventuali metriche personalizzate create utilizzando il policy StatisticsCollector.

Le principali differenze tra i report generati nell'interfaccia utente e nell'API sono che i report generati con l'API vengono scritti in file CSV o JSON (separati da riga nuova) anziché in un report visivo visualizzato nell'interfaccia utente.

Limiti in Apigee hybrid

Apigee hybrid applica un limite di dimensioni di 30 MB al set di dati dei risultati.

Come eseguire una query di analisi asincrona

Per eseguire query di analisi asincrone, segui tre passaggi:

1. Invia la query.

2. Ottieni lo stato della query.

3. Recupero i risultati della query.

Passaggio 1: Invia la query

Devi inviare una richiesta POST all'API /queries. Questa API indica a Edge di elaborare la richiesta in background. Se l'invio della query va a buon fine, l'API restituisce uno stato 201 e un ID che utilizzerai per fare riferimento alla query nei passaggi successivi.

Ad esempio:

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

Il corpo della richiesta è una descrizione JSON della query. Nel corpo JSON, specifica le metriche, le dimensioni e i filtri che definiscono il report.

Di seguito è riportato un esempio di file json-query-file:

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

Consulta la sezione Informazioni sul corpo della richiesta di seguito per una descrizione completa della sintassi del corpo della richiesta.

Risposta di esempio:

Tieni presente che l'ID query 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd è incluso nella risposta. Oltre allo stato HTTP 201, il valore state di enqueued indica che la richiesta è andata a buon fine.

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

Passaggio 2: Recupera lo stato della query

Esegui una chiamata GET per richiedere lo stato della query. Fornisci l'ID query restituito dalla chiamata POST. Ad esempio:

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

Risposte di esempio:

Se la query è ancora in corso, riceverai una risposta simile a questa, dove state è 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"
}

Una volta completata la query, viene visualizzata una risposta simile a questa, in cui state è impostato su 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"
}

Passaggio 3: Recupera i risultati della query

Quando lo stato della query è completed, puoi utilizzare l'API get results per recuperare i risultati, in cui l'ID query è di nuovo 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

Per recuperare il file scaricato, devi configurare lo strumento che utilizzi in modo che salvi un file scaricato nel tuo sistema. Ad esempio:

• Se utilizzi cURL, puoi utilizzare le opzioni -O -J, come mostrato sopra.

• Se utilizzi Postman, devi selezionare il pulsante Salva e scarica. In questo caso, viene scaricato un file ZIP denominato response.

• Se utilizzi il browser Chrome, il download viene accettato automaticamente.

Se la richiesta ha esito positivo ed è presente un insieme di risultati diverso da zero, il risultato viene scaricato sul client come file JSON compresso (delimitato da una nuova riga). Il nome del file scaricato sarà:

OfflineQueryResult-<query-id>.zip

Ad esempio:

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

Il file ZIP contiene un file archivio .gz dei risultati JSON. Per accedere al file JSON, decomprimere il file scaricato e utilizzare il comando gzip per estrarlo:

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

Informazioni sul corpo della richiesta

Questa sezione descrive ciascuno dei parametri che puoi utilizzare nel corpo della richiesta JSON per una query. Per informazioni dettagliate sulle metriche e sulle dimensioni che puoi utilizzare nella query, consulta la documentazione di riferimento di 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"
}

Sintassi dell'espressione di filtro

Questa sezione di riferimento descrive i token che puoi utilizzare per creare espressioni di filtro nel corpo della richiesta. Ad esempio, la seguente espressione utilizza il token "ge" (maggiore o uguale a):

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

Vincoli e valori predefiniti

Di seguito è riportato un elenco di vincoli e valori predefiniti per la funzionalità di elaborazione delle query asincrone.

Informazioni sui risultati della query

Di seguito è riportato un esempio di risultato in formato JSON. L'output è costituito da righe JSON separate da un delimitatore di nuova riga:

{"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"}    
…

Puoi recuperare i risultati dall'URL fino alla scadenza dei dati nel repository. Consulta Vincoli e valori predefiniti.

Esempi

Esempio 1: somma dei conteggi dei messaggi

Esegui una query per la somma del numero di messaggi negli ultimi 60 minuti.

Query

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

Corpo della richiesta da last60minutes.json

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

Esempio 2: intervallo di tempo personalizzato

Esegui una query utilizzando un intervallo di tempo personalizzato.

Query

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

Corpo della richiesta da 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"
   }
}

Esempio 3: transazioni al minuto

Esegui una query sulla metrica delle transazioni al minuto (tpm).

Query

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

Corpo della richiesta da tpm.json

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

Risultato di esempio

Estratto dal file dei risultati:

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

Esempio 4: utilizzo di un'espressione di filtro

Esegui una query con un'espressione di filtro che utilizza un operatore booleano.

Query

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

Corpo della richiesta da 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"
   }
}

Esempio 5: passaggio dell'espressione nel parametro delle metriche

Esegui una query con un'espressione passata come parte del parametro delle metriche. Puoi utilizzare solo espressioni semplici con un solo operatore.

Query

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

Corpo della richiesta da metricsExpression.json

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

Come eseguire una query asincrona sui report sulla monetizzazione

Puoi acquisire tutte le transazioni di monetizzazione andate a buon fine in un determinato intervallo di tempo per un insieme specifico di criteri seguendo i passaggi descritti in questa sezione.

Come per le query di analisi asincrone, puoi eseguire query sui report sulla monetizzazione asincroni in tre passaggi: (1) invia la query, (2) ottieni lo stato della query e (3) recupera i risultati della query.

Il passaggio 1, l'invio della query, è descritto di seguito.

I passaggi 2 e 3 sono esattamente gli stessi delle query di analisi asincrone. Per ulteriori informazioni, consulta Come eseguire una query di analisi asincrona.

Per inviare una query per un report sulla monetizzazione asincrona, invia una richiesta POST a /mint/organizations/org_id/async-reports.

Facoltativamente, puoi specificare l'ambiente passando il parametro di query environment. Se non specificato, il valore predefinito del parametro di query è prod. Ad esempio:

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

Nel corpo della richiesta, specifica i seguenti criteri di ricerca.

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

Ad esempio, la seguente richiesta genera un report sulla monetizzazione asincrono per il mese di giugno 2017 per il prodotto API e l'ID sviluppatore specificati. Le date e le ore dei report fromDate e toDate sono in UTC/GMT e possono includere le ore.

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