Esportare i dati di Analytics

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

Configura le autorizzazioni per gli agenti di servizio assegnati

Per configurare le autorizzazioni per gli agenti di servizio assegnati, in preparazione alle modifiche descritte in precedenza, svolgi i passaggi che seguono.

  1. Trova il nome dell'agente di servizio Google Cloud inserendo questo comando: 
    curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/ORG" \
  -u email:password \
  | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

    dove ORG è la tua organizzazione. Vengono restituiti il nome e il valore dell'agente di servizio, come mostrato di seguito:

    "property" : [
  {
   "name" : "serviceAgent.analytics",
   "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
   },
  2. Apri la dashboard IAM nella console Google Cloud.
  3. Selezionare il tuo progetto Google Cloud.
  4. Fai clic su Aggiungi nella parte superiore del riquadro IAM.
  5. Nel campo Nuove entità, inserisci l'agente di servizio value restituito nel passaggio 1. Ad esempio, il valore value mostrato nel passaggio 1 è service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
  6. Fai clic sul pulsante +Aggiungi un altro ruolo e aggiungi i seguenti ruoli:
    • Utente BigQuery
    • Amministratore Storage
  7. Fai clic su Salva.

Dati di analisi Apigee

Apigee Analytics raccoglie e analizza un ampio spettro di dati che passano attraverso le tue API e fornisce strumenti di visualizzazione, tra cui dashboard interattive, report personalizzati e altri strumenti che identificano le tendenze delle prestazioni dei proxy API. Ora puoi usufruire di queste informazioni aggiuntive esportando i dati di analisi da Apigee Analytics nel tuo repository di dati, ad esempio Google Cloud Storage o Google BigQuery. Potrai quindi sfruttare le potenti funzionalità di query e machine learning offerte da Google BigQuery e TensorFlow per eseguire l'analisi dei tuoi dati. Puoi anche combinare i dati di analisi esportati con altri dati, ad esempio i log web, per ottenere nuovi insight su utenti, API e applicazioni.

Formato dei dati di esportazione

Esporta i dati di analisi in uno dei seguenti formati:

  • Valori separati da virgola (CSV)

    Il delimitatore predefinito è una virgola (,). I caratteri di delimitazione supportati includono la virgola (,), la barra verticale (|) e la tabulazione (\t). Configura il valore utilizzando la proprietà csvDelimiter, come descritto in Riferimento proprietà per la richiesta di esportazione .

  • JSON (delimitato da nuova riga)

    Consente di utilizzare il carattere della nuova riga come delimitatore.

I dati esportati includono tutte le metriche e le dimensioni di analisi integrate in Edge e tutti i dati di analisi personalizzati che aggiungi. Per una descrizione dei dati esportati, consulta la sezione Metriche, dimensioni e filtri di Analytics.

Puoi esportare i dati di analisi nei seguenti repository di dati:

Panoramica del processo di esportazione

I passaggi seguenti riepilogano la procedura utilizzata per esportare i dati di analisi:

  1. Configura il tuo repository di dati (Cloud Storage o BigQuery) per l'esportazione dei dati. Devi assicurarti che il repository di dati sia stato configurato correttamente e che l'account di servizio utilizzato per scrivere dati nel repository disponga delle autorizzazioni corrette.

  2. Crea un datastore che definisca le proprietà del repository dei dati (Cloud Storage o BigQuery) in cui esporti i dati, incluse le credenziali utilizzate per accedere al repository dei dati.

    Quando crei un datastore, carichi le credenziali del repository di dati in Edge Credentials Vault per archiviarle in modo sicuro. Il meccanismo di esportazione dei dati utilizza quindi queste credenziali per scrivere dati nel repository dei dati.

  3. Utilizza l'API di esportazione dei dati per avviare l'esportazione dei dati. L'esportazione dei dati viene eseguita in modo asincrono in background.

  4. Utilizza l'API di esportazione dei dati per determinare il completamento dell'esportazione.

  5. Al termine dell'esportazione, accedi ai dati esportati nel tuo repository di dati.

Questi passaggi vengono descritti in modo più dettagliato nelle sezioni seguenti.

Configura il repository di dati

Il meccanismo di esportazione dei dati di analisi scrive i dati in Cloud Storage o BigQuery. Affinché la scrittura avvenga, devi:

  • Creare un account di servizio per la piattaforma Google Cloud.
  • Imposta il ruolo dell'account di servizio in modo che possa accedere a Cloud Storage o BigQuery.

Crea un account di servizio per Cloud Storage o BigQuery

Un account di servizio è un tipo di Account Google che appartiene alla tua applicazione anziché a un singolo utente. L'applicazione utilizza quindi l'account di servizio per accedere a un servizio.

Un account di servizio ha una chiave dell'account di servizio rappresentata da una stringa JSON. Quando crei il datastore perimetrale che definisce la connessione al tuo repository di dati, passi questa chiave. Il meccanismo di esportazione dei dati utilizza quindi la chiave per accedere al repository dei dati.

L'account di servizio associato alla chiave deve essere un proprietario del progetto Google Cloud Platform e disporre dell'accesso in scrittura al bucket Google Cloud Storage. Per creare una chiave di servizio e scaricare il payload richiesto, consulta la sezione Creazione e gestione delle chiavi degli account di servizio nella documentazione della piattaforma Google Cloud.

Ad esempio, la prima volta che scarichi la chiave, questa verrà formattata come oggetto JSON: 

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Configura Google Cloud Storage

Per esportare i dati in Google Cloud Storage:

  • Assicurati che le API BigQuery e Cloud Resource Manager siano abilitate nel tuo progetto Google Cloud Platform. Per le istruzioni, consulta Abilitazione delle API. Apigee utilizza l'API BigQuery per sfruttare le funzionalità di esportazione di BigQuery durante l'esportazione in Cloud Storage e l'API Cloud Resource Manager per verificare l'autorizzazione prima di ogni esportazione.

  • Assicurati che l'account di servizio sia assegnato ai seguenti ruoli:

    • Utente job BigQuery
    • Creatore oggetti Storage
    • Amministratore archiviazione (obbligatorio solo per testare il datastore come descritto in Testare la configurazione di un datastore. Se questo ruolo è troppo ampio, puoi aggiungere l'autorizzazione storage.buckets.get a un ruolo esistente.

    In alternativa, se vuoi modificare un ruolo esistente o crearne uno personalizzato, aggiungi le seguenti autorizzazioni al ruolo:

Configura Google BigQuery

Per esportare i dati in Google BigQuery:

  • Assicurati che le API BigQuery e Cloud Resource Manager siano abilitate nel tuo progetto Google Cloud Platform. Per le istruzioni, consulta Abilitazione delle API. Apigee utilizza l'API Cloud Resource Manager per verificare l'autorizzazione prima di ogni esportazione.
  • Assicurati che l'API BigQuery sia attivata nel tuo progetto Google Cloud. Per le istruzioni, consulta Attivazione e disattivazione delle API.

  • Assicurati che l'account di servizio sia assegnato ai seguenti ruoli:

    • Utente job BigQuery
    • Editor dati BigQuery

    Se vuoi modificare un ruolo esistente o crearne uno personalizzato, aggiungi le seguenti autorizzazioni al ruolo:

    • bigquery.datasets.create
    • bigquery.datasets.get
    • bigquery.jobs.create
    • bigquery.tables.create
    • bigquery.tables.get
    • bigquery.tables.updateData

Crea un datastore

Il datastore definisce la connessione al repository dei dati di esportazione (Cloud Storage, BigQuery), incluse le credenziali utilizzate per accedere al repository.

Informazioni su Edge Credentials Vault

Edge utilizza l'Archivio protetto delle credenziali per archiviare in modo sicuro le credenziali utilizzate per accedere al repository dei dati di esportazione. Affinché un servizio possa accedere alle credenziali in Vault per le credenziali Edge, devi definire un consumer delle credenziali.

Quando crei un datastore utilizzando la UI Edge, come descritto di seguito, Edge crea automaticamente il consumer utilizzato per accedere alle credenziali.

Testare la configurazione di un datastore

Quando crei il datastore, Edge non verifica né convalida che le credenziali e la configurazione del repository di dati siano valide. Ciò significa che puoi creare il datastore e non rilevare eventuali errori finché non esegui la prima esportazione dei dati.

In alternativa, testa la configurazione del datastore prima di crearla. Il test è utile perché l'esecuzione di un processo di esportazione dei dati di grandi dimensioni può richiedere molto tempo. Testando le credenziali e la configurazione del datastore prima di iniziare a scaricare grandi quantità di dati, puoi risolvere rapidamente eventuali problemi relativi alle impostazioni.

Se il test ha esito positivo, crea il datastore. Se il test ha esito negativo, correggi gli errori e ripeti il test della configurazione. Il datastore viene creato solo dopo che i test hanno avuto esito positivo.

Per attivare la funzionalità di test, devi:

Crea un datastore

Per creare un datastore nella UI:

  1. Accedi ad https://apigee.com/edge come amministratore dell'organizzazione e seleziona la tua organizzazione.

    NOTA: per poter creare un datastore, devi essere un amministratore dell'organizzazione Edge.

  2. Seleziona Amministrazione > Datastore di Analytics dalla barra di navigazione a sinistra. Viene visualizzata la pagina Datastore di Analytics.

  3. Seleziona il pulsante + Aggiungi Datastore. Ti viene chiesto di selezionare il tipo di datastore:

  4. Scegli un tipo di target dei dati di esportazione:

    • Google Cloud Storage
    • Google BigQuery

    Viene visualizzata la pagina di configurazione:

  5. Inserisci il Nome del datastore.

  6. Seleziona una credenziale utilizzata per accedere al repository di dati. Viene visualizzato un elenco a discesa delle credenziali disponibili.

    Le credenziali sono specifiche per un tipo di repository di dati. Per ulteriori informazioni, vedi Creare un account di servizio per Cloud Storage o BigQuery.

    • Se hai già caricato le credenziali, selezionale dall'elenco a discesa. Assicurati di selezionare le credenziali appropriate per il tipo di repository di dati.

    • Se stai aggiungendo nuove credenziali al datastore, seleziona Aggiungi nuovo. Nella finestra di dialogo, inserisci:

      1. Il Nome delle credenziali.
      2. Il contenuto delle credenziali è la chiave dell'account di servizio JSON specifica per il repository di dati, come definita in Creare un account di servizio per Cloud Storage o BigQuery.
      3. Seleziona Crea.

  7. Inserisci le proprietà specifiche per il tipo di repository di dati:

    • Per Google Cloud Storage:
      Proprietà Descrizione Campo obbligatorio?
      ID progetto ID progetto della piattaforma Google Cloud.

      Per creare un progetto della piattaforma Google Cloud, consulta la sezione Creazione e gestione di progetti nella documentazione della piattaforma Google Cloud.

      		Sì
      Nome bucket Nome del bucket in Cloud Storage in cui vuoi esportare i dati di analisi. Il bucket deve esistere prima di eseguire un'esportazione dei dati.

      Per creare un bucket Cloud Storage, consulta la sezione Creazione di bucket di archiviazione nella documentazione della piattaforma Google Cloud.

      		Sì
      Percorso Directory in cui archiviare i dati di analisi nel bucket Cloud Storage. Sì
    • Per BigQuery:
      Proprietà Descrizione Campo obbligatorio?
      ID progetto ID progetto della piattaforma Google Cloud.

      Per creare un progetto della piattaforma Google Cloud, consulta la sezione Creazione e gestione di progetti nella documentazione della piattaforma Google Cloud.

      		 Sì
      Nome set di dati Nome del set di dati BigQuery in cui vuoi esportare i dati di analisi. Assicurati che il set di dati venga creato prima di richiedere l'esportazione dei dati.

      Per creare un set di dati BigQuery, consulta la sezione Creazione e utilizzo di set di dati nella documentazione della piattaforma Google Cloud.

      		 Sì
      Prefisso tabella Il prefisso per i nomi delle tabelle create per i dati di analisi nel set di dati BigQuery. Sì

  8. Seleziona Verifica connessione per assicurarti che le credenziali possano essere utilizzate per accedere al repository di dati.

    Se il test ha esito positivo, salva il datastore.

    Se il test non va a buon fine, risolvi gli eventuali problemi e riprova. Sposta il mouse sopra il messaggio di errore nell'interfaccia utente per visualizzare ulteriori informazioni in una descrizione comando.

  9. Una volta superato il test della connessione, salva il datastore.

Modifica un datastore

Per modificare un datastore:

  1. Accedi ad https://apigee.com/edge come amministratore dell'organizzazione e seleziona la tua organizzazione.

  2. Seleziona Amministrazione > Datastore di Analytics dalla barra di navigazione a sinistra. Viene visualizzata la pagina Datastore di Analytics.

  3. Sposta il puntatore del mouse sulla colonna Modificato del report da modificare. Viene visualizzata l'icona di modifica ed eliminazione.

  4. Modifica o elimina il datastore.

  5. Se hai modificato il datastore, seleziona Verifica connessione per assicurarti che le credenziali possano essere utilizzate per accedere al datastore.

    Se il test ha esito positivo, puoi visualizzare i dati di esempio nel tuo repository di dati.

    Se il test non va a buon fine, risolvi gli eventuali problemi e riprova.

  6. Una volta superato il test della connessione, aggiorna il datastore.

Esporta dati di analisi

Per esportare i dati di analisi, invia una richiesta POST all'API /analytics/exports. Trasmetti le seguenti informazioni nel corpo della richiesta:

  • Nome e descrizione della richiesta di esportazione
  • Intervallo di date dei dati esportati (il valore può includere un solo giorno)
  • Formato dei dati esportati
  • Nome datastore
  • Se la monetizzazione è attivata nell'organizzazione

Di seguito sono riportati alcuni esempi di richieste di esportazione. Per una descrizione completa delle proprietà del corpo della richiesta, consulta la sezione Riferimento proprietà della richiesta di esportazione.

La risposta al POST è nel formato:

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

Tieni presente che la proprietà state nella risposta è impostata su enqueued. La richiesta POST funziona in modo asincrono. Ciò significa che continua a essere eseguita in background dopo che la richiesta restituisce una risposta. I valori possibili per state includono: enqueued, running, completed, failed.

Utilizza l'URL restituito nella proprietà self per visualizzare lo stato della richiesta di esportazione dei dati, come descritto in Visualizzare lo stato di una richiesta di esportazione di Analytics. Al completamento della richiesta, il valore della proprietà state nella risposta viene impostato su completed. Potrai quindi accedere ai dati di analisi nel tuo repository di dati.

Esempio 1: esportare i dati in Cloud Storage

La seguente richiesta esporta un set completo di dati non elaborati delle ultime 24 ore dall'ambiente test nell'organizzazione myorg. I contenuti vengono esportati in Cloud Storage in formato JSON:

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

Utilizza l'URI specificato dalla proprietà self per monitorare lo stato del job come descritto in Visualizzazione dello stato di una richiesta di esportazione di Analytics.

Esempio 2: esportare i dati in BigQuery

La seguente richiesta esporta un file CSV delimitato da virgole in BigQuery:

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

Nota:il file CSV esportato crea una tabella BigQuery con il seguente prefisso:

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

Utilizza l'URI specificato dalla proprietà self per monitorare lo stato del job come descritto in Visualizzare lo stato di una richiesta di esportazione di Analytics.

Esempio 3: esportare i dati sulla monetizzazione

Se la monetizzazione è abilitata in un ambiente dell'organizzazione, puoi eseguire due tipi di esportazioni di dati:

  • Esportazione dei dati standard come mostrato nei due esempi precedenti.
  • Esportazione dei dati sulla monetizzazione per esportare dati specifici per la monetizzazione.

Per eseguire un'esportazione dei dati di monetizzazione, specifica "dataset":"mint" nel payload della richiesta. L'organizzazione e l'ambiente devono supportare la monetizzazione per poter impostare questa opzione, altrimenti ometti la proprietà dataset dal payload:

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

Informazioni sulle quote API di esportazione

Per evitare un uso eccessivo di chiamate API di esportazione dei dati costose, Edge applica una quota alle chiamate all'API /analytics/exports:

  • Per le organizzazioni e gli ambienti in cui non è abilitata la monetizzazione, la quota è:

    • 70 chiamate al mese per organizzazione/ambiente.

    Ad esempio, se nella tua organizzazione sono presenti due ambienti, prod e test, puoi effettuare 70 chiamate API al mese per ogni ambiente.

  • Per le organizzazioni e gli ambienti in cui la monetizzazione è abilitata, la quota è:

    • 70 chiamate al mese per ogni organizzazione e ambiente per i dati standard.
    • 70 chiamate al mese per ogni organizzazione e ambiente per i dati sulla monetizzazione.

    Ad esempio, se abiliti la monetizzazione sulla tua organizzazione prod, puoi effettuare 70 chiamate API per i dati standard e 70 chiamate API aggiuntive per i dati di monetizzazione.

Se superi la quota di chiamate, l'API restituisce una risposta HTTP 429.

Visualizzazione dello stato di tutte le richieste di esportazione delle analisi

Per visualizzare lo stato di tutte le richieste di esportazione di Analytics, invia una richiesta GET a /analytics/exports.

Ad esempio, la seguente richiesta restituisce lo stato di tutte le richieste di esportazione di dati e analisi per l'ambiente test nell'organizzazione myorg:

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

Di seguito è riportato un esempio della risposta in cui sono elencate due richieste di esportazione, una accoda (creata e in coda) e una completata:

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

Visualizzazione dello stato di una richiesta di esportazione dei dati e delle analisi

Per visualizzare lo stato di una richiesta di esportazione di dati e analisi specifica, invia una richiesta GET a /analytics/exports/{exportId}, dove {exportId} è l'ID associato alla richiesta di esportazione di dati e analisi.

Ad esempio, la seguente richiesta restituisce lo stato della richiesta di esportazione di Analytics con ID 4d6d94ad-a33b-4572-8dba-8677c9c4bd98.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

Di seguito è riportato un esempio della risposta:

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Se l'esportazione di dati e analisi non restituisce dati di analisi, executionTime è impostato su "0 secondi".

Riferimento proprietà della richiesta di esportazione

La tabella seguente descrive le proprietà che puoi trasmettere nel corpo della richiesta in formato JSON durante l'esportazione dei dati di analisi.

Proprietà Descrizione Campo obbligatorio?
description Descrizione della richiesta di esportazione. No
name Nome della richiesta di esportazione. Sì
dateRange

Specifica la data start e end dei dati da esportare nel formato yyyy-mm-dd. Ad esempio:

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

Il valore dateRange può includere un solo giorno. L'intervallo di date inizia alle 00:00:00 UTC della data del giorno start e termina alle 00:00:00 UTC della data del giorno end.

NOTA: per assicurarti che tutti i dati vengano acquisiti dal giorno precedente, potrebbe essere necessario ritardare l'ora di inizio della richiesta di esportazione, ad esempio 00:05:00 UTC.

Sì
outputFormat Specifica come json o csv. Sì
csvDelimiter

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

 No
datastoreName Il nome del datastore contenente la definizione del tuo datastore. Sì

Ad esempio:

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }