Utilizzare l'API asincrona per i report personalizzati

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

Edge Analytics fornisce un'ampia gamma 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 consente di eseguire query su set di dati di grandi dimensioni e di recuperare i risultati in un secondo momento. Potresti prendere in considerazione l'uso di una query offline quando ti rendi conto che le query interattive sono scadute. 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 varietà di dimensioni di raggruppamento e altri vincoli che aggiungono complessità alla query.
  • Gestione delle query quando noti che i volumi di dati sono aumentati in modo significativo per alcuni utenti o organizzazioni.

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

Confrontare l'API Reports con l'interfaccia utente

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

La maggior parte dei concetti relativi alla generazione di report personalizzati con l'interfaccia utente riguarda l'uso dell'API. In altre parole, quando crei report personalizzati con l'API, specifichi metrics, dimensioni e filtri integrati in Edge, oltre alle metriche personalizzate che hai creato utilizzando il criterio 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 (delimitato da una nuova riga) anziché in un report visivo visualizzato nell'interfaccia utente.

Limiti in Apigee hybrid

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

Come eseguire una query di analisi asincrona

Puoi eseguire query di analisi asincrone in tre passaggi:

  1. Invia la query.

  2. Recupera lo stato della query.

  3. Recupera 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 tua richiesta in background. Se l'invio della query ha esito positivo, l'API restituisce lo 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 metrics, 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.

Esempio di risposta:

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

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: Recuperare lo stato della query

Effettua una chiamata GET per richiedere lo stato della query. Devi fornire 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 alla seguente, 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 correttamente la query, verrà visualizzata una risposta come la seguente, 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: Recuperare i risultati della query

Una volta che lo stato della query è completed, puoi utilizzare l'API get results per recuperare i risultati, dove l'ID query è ancora 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 il file scaricato sul sistema. Ad esempio:

  • Se utilizzi cURL, puoi usare 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 set di risultati diverso da zero, il risultato viene scaricato sul client come file JSON compresso (delimitato da 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 di archivio .gz con i risultati JSON. Per accedere al file JSON, decomprimi il file di download, quindi usa il comando gzip per estrarre il file JSON:

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 per 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"
}
Proprietà Descrizione Campo obbligatorio?
metrics

Array di metriche. Puoi specificare una o più metriche per una query in cui ciascuna metrica include. È obbligatorio solo il nome della metrica:

  • name: (obbligatorio) il nome della metrica come definito dalla tabella metrics.
  • function: (facoltativo) la funzione di aggregazione come avg, min, max o sum.

    Non tutte le metriche supportano tutte le funzioni di aggregazione. La documentazione sulle metrics contiene una tabella che specifica il nome della metrica e la funzione (avg, min, max,sum) supportata dalla metrica.

  • alias: (facoltativo) il nome della proprietà che contiene i dati della metrica nell'output. Se omesso, viene utilizzato per impostazione predefinita il nome della metrica combinato con il nome della funzione di aggregazione.
  • operator: (facoltativo) un'operazione da eseguire sulla metrica dopo il calcolo del relativo valore. Compatibile con la proprietà value. Le operazioni supportate includono: + - / % *.
  • value: (facoltativo) il valore applicato alla metrica calcolata dall'elemento operator specificato.

Le proprietà operator e value definiscono un'operazione di post-elaborazione eseguita sulla metrica. Ad esempio, se specifichi la metrica response_processing_latency, quest'ultima restituisce la latenza media di elaborazione delle risposte con un'unità di millisecondi. Per convertire le unità in secondi, imposta operator su "/" e value su ”1000.0“:

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

Per saperne di più, consulta l'articolo Riferimento per metriche, dimensioni e filtri di Analytics.

No
dimensions Array di dimensioni per raggruppare le metriche. Per ulteriori informazioni, consulta l'elenco delle dimensioni supportate. Puoi specificare più dimensioni. No
timeRange Intervallo di tempo della query.

Puoi utilizzare le seguenti stringhe predefinite per specificare l'intervallo di tempo:

  • last60minutes
  • last24hours
  • last7days

In alternativa, puoi specificare timeRange come una struttura che descrive i timestamp di inizio e fine nel formato ISO: yyyy-mm-ddThh:mm:ssZ. Ad esempio:

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}
limit Numero massimo di righe che possono essere restituite nel risultato. No
filter Espressione booleana che può essere utilizzata per filtrare i dati. Le espressioni di filtro possono essere combinate utilizzando termini AND/OR e devono essere incluse tra parentesi per evitare ambiguità. Per ulteriori informazioni sui campi disponibili in base ai quali applicare i filtri, consulta le informazioni di riferimento sulle metriche, sulle dimensioni e sui filtri di Analytics. Per ulteriori informazioni sui token da utilizzare per creare le espressioni di filtro, consulta Sintassi delle espressioni di filtro. No
groupByTimeUnit Unità di tempo utilizzata per raggruppare il set di risultati. I valori validi sono: second, minute, hour, day, week o month.

Se una query include groupByTimeUnit, il risultato è un'aggregazione basata sull'unità di tempo specificata e il timestamp risultante non include la precisione in millisecondi. Se una query omette groupByTimeUnit, il timestamp risultante include la precisione in millisecondi.

No
outputFormat Formato di output. I valori validi sono: csv o json. Il valore predefinito è json, che corrisponde a un JSON delimitato da una nuova riga.

Nota: configura il delimitatore per l'output CSV utilizzando la proprietà csvDelimiter.

No
csvDelimiter Delimitatore utilizzato nel file CSV, se outputFormat è impostato su csv. Il valore predefinito è , (virgola). I caratteri di delimitazione supportati includono virgola (,), barra verticale (|) e tabulazione (\t). No

Sintassi delle espressioni 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)"
Token Descrizione Esempi
in Includi nell'elenco
(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

Nota : le stringhe devono essere racchiuse tra virgolette.

notin Escludi dall'elenco
(response_status_code notin 400,401,500,501)
eq Uguale a (==))
(response_status_code eq 504)

(apiproxy eq 'non-prod')
ne Non uguali a (!=)
(response_status_code ne 500)

(apiproxy ne 'non-prod')
gt Maggiore di (>))
(response_status_code gt 500)
lt Minore di (<))
(response_status_code lt 500)
ge Maggiore di o uguale a (>=)
(target_response_code ge 400)
le Minore o uguale a (<=)
(target_response_code le 300)
like Restituisce true se il pattern stringa corrisponde a quello fornito.

L'esempio a destra corrisponde come segue:

- qualsiasi valore che contenga la parola "acquista"

- qualsiasi valore che termina con "item"

- Qualsiasi valore che inizia con "Prod"

- Qualsiasi valore che inizia con 4; tieni presente che il codice di stato della risposta è numerico

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')
not like Restituisce false se il pattern di stringa corrisponde al pattern fornito.
(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')
and Consente di utilizzare la logica "and" per includere più di un'espressione di filtro. Il filtro include i dati che soddisfano tutte le condizioni.
(target_response_code gt 399) and (response_status_code ge 400)
or Consente di utilizzare la logica "or" per valutare diverse espressioni di filtro possibili. Il filtro include i dati che soddisfano almeno una delle condizioni.
(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 asincrona.

Vincolo Predefinito Descrizione
Limite chiamate query Vedi descrizione Puoi effettuare fino a sette chiamate all'ora all'API di gestione /queries per avviare un report asincrono. Se superi la quota di chiamate, l'API restituisce una risposta HTTP 429.
Limite di query attive 10 Puoi avere fino a 10 query attive per un'organizzazione o un ambiente.
Soglia di tempo di esecuzione della query 6 ore Le query che richiedono più di 6 ore verranno terminate.
Intervallo di tempo della query Vedi descrizione L'intervallo di tempo massimo consentito per una query è 365 giorni.
Limite di dimensioni e metriche 25 Il numero massimo di dimensioni e metriche che puoi specificare nel payload della query.

Informazioni sui risultati della query

Di seguito è riportato un risultato di esempio in formato JSON. L'output è costituito da righe JSON separate da un nuovo delimitatore di 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 la sezione Vincoli e valori predefiniti.

Esempi

Esempio 1: somma dei conteggi dei messaggi

Query per la somma dei conteggi dei 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

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

Query sulla metrica per le 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 a 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

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

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 report sulla monetizzazione asincrona

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

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

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

I passaggi 2 e 3 sono esattamente gli stessi delle query di analisi asincrone. Per saperne di più, 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 parametro di ricerca è prod per impostazione predefinita. Ad esempio:

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

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

Nome Descrizione Predefinita Obbligatorio?
appCriteria ID e organizzazione di una specifica applicazione da includere nel report. Se questa proprietà non viene specificata, nel report vengono incluse tutte le applicazioni. N/A No
billingMonth Mese di fatturazione del report, ad esempio LUGLIO. N/A
billingYear Anno di fatturazione del report, ad esempio 2015. N/A
currencyOption Valuta del report. I valori validi includono:
  • LOCAL: ogni riga del report viene visualizzata utilizzando il piano tariffario applicabile. Ciò significa che un report potrebbe includere più valute, se gli sviluppatori hanno piani che utilizzano valute diverse.
  • EUR: le transazioni in valuta locale vengono convertite e visualizzate in euro.
  • GPB: le transazioni in valuta locale vengono convertite e visualizzate in sterline britanniche.
  • USD: le transazioni in valuta locale vengono convertite e visualizzate in dollari statunitensi.

Se selezioni EUR, GBP o USD, il report visualizza tutte le transazioni che utilizzano la singola valuta in base al tasso di cambio in vigore alla data della transazione.

N/A No
devCriteria

L'ID o l'indirizzo email dello sviluppatore e il nome dell'organizzazione di uno sviluppatore specifico da includere nel report. Se questa proprietà non viene specificata, nel report vengono inclusi tutti gli sviluppatori.

Ad esempio:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
N/A No
fromDate Data di inizio del report in UTC. N/A
monetizationPakageIds ID di uno o più pacchetti API da includere nel report. Se questa proprietà non viene specificata, nel report vengono inclusi tutti i pacchetti API. N/A No
productIds ID di uno o più prodotti API da includere nel report. Se questa proprietà non viene specificata, nel report vengono inclusi tutti i prodotti API. N/A No
ratePlanLevels

Tipo di piano tariffario da includere nel report. I valori validi includono:

  • DEVELOPER: piano tariffario per sviluppatori.
  • STANDARD: piano tariffario standard.

Se questa proprietà non viene specificata, nel report sono inclusi i piani tariffari standard e specifici per sviluppatori.

N/A No
toDate Data di fine del report in UTC. N/A

Ad esempio, la seguente richiesta genera un report sulla monetizzazione asincrona relativo al mese di giugno 2017 per il prodotto API e l'ID sviluppatore specificati. Le date e gli orari dei report fromDate e toDate sono espressi in UTC/GMT e possono includere 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