Esportare i dati di Analytics

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

Configurare le autorizzazioni per gli agenti di servizio assegnati

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

1. Trova il nome dell'agente di servizio Google Cloud inserendo il seguente comando:

   curl -X GET \
     "https://api.enterprise.apigee.com/v1/organizations/ORG" \
     -u email:password \
     | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

   ORG è la tua organizzazione. Verranno 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 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 archiviazione
7. Fai clic su Salva.

Dati di Apigee Analytics

Formato di esportazione dei dati

Esportare i dati di analisi in uno dei seguenti formati:

• Valori separati da virgole (CSV)

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

• JSON (delimitato da nuova riga)

  Consente di utilizzare il carattere di a capo come delimitatore.

I dati esportati includono tutte le metriche e le dimensioni di analisi integrate in Edge e qualsiasi dato di analisi personalizzato che aggiungi. Per una descrizione dei dati esportati, consulta Riferimento per metriche, dimensioni e filtri di analisi.

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

• Google Cloud Storage
• Google BigQuery

Panoramica della procedura di esportazione

I passaggi riportati di seguito riassumono 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 dei dati sia stato configurato correttamente e che il service account utilizzato per scrivere dati nel repository dei dati disponga delle autorizzazioni corrette.

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

   Quando crei un data store, carichi le credenziali del repository di dati in Edge Credentials Vault per archiviarle in modo sicuro. Il meccanismo di esportazione dei dati utilizza poi queste credenziali per scrivere i dati nel tuo repository di 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 quando viene completata l'esportazione.

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

Le sezioni seguenti descrivono questi passaggi in modo più dettagliato.

Configura il repository di dati

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

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

Creare un account di servizio per Cloud Storage o BigQuery

Un account di servizio è un tipo di Account Google che appartiene all'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 l'archivio dati Edge che definisce la connessione al tuo repository di dati, devi passare questa chiave. Il meccanismo di esportazione dei dati utilizza quindi la chiave per accedere al tuo repository di dati.

L'account di servizio associato alla chiave deve essere un proprietario del progetto Google Cloud e avere accesso in scrittura al bucket Google Cloud Storage. Per creare una chiave di servizio e scaricare il payload richiesto, consulta Creare e gestire le chiavi dell'account di servizio nella documentazione della piattaforma Google Cloud.

Ad esempio, la prima volta che scarichi la chiave, questa sarà 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" 
}

Configurare Google Cloud Storage

Prima di poter esportare i dati in Google Cloud Storage:

• Assicurati che le API BigQuery e Cloud Resource Manager siano attive nel tuo progetto Google Cloud. Per le istruzioni, consulta Abilitare le 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 controllare l'autorizzazione prima di ogni esportazione.

• Assicurati che all'account di servizio siano assegnati i seguenti ruoli:

  • Utente job BigQuery
  • Creatore oggetti Storage
  • Amministratore dello spazio di archiviazione (obbligatorio solo per testare lo spazio di archiviazione come descritto in Testare una configurazione dello spazio di archiviazione. 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:

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (obbligatorio solo per testare il datastore come descritto in Testare una configurazione del datastore)

Configurare Google BigQuery

Prima di poter esportare i dati in Google BigQuery:

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

• Assicurati che all'account di servizio siano assegnati i 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

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

Informazioni su Edge Credentials Vault

Edge utilizza Credentials Vault per archiviare in modo sicuro le credenziali utilizzate per accedere al repository dei dati di esportazione. Affinché un servizio possa accedere alle credenziali nella cassetta di sicurezza delle credenziali Edge, devi definire un consumatore delle credenziali.

Quando crei un data store utilizzando l'interfaccia utente di Edge, come descritto di seguito, Edge crea automaticamente il consumer utilizzato per accedere alle credenziali.

Testare una configurazione del datastore

Quando crei l'archivio dati, Edge non verifica la validità delle credenziali e della configurazione del repository di dati. Ciò significa che puoi creare il datastore e non rilevare errori finché non esegui la prima esportazione dei dati.

In alternativa, testa la configurazione del datastore prima di crearlo. I test sono utili perché l'esecuzione di un processo di esportazione di dati di grandi dimensioni può richiedere molto tempo. Se testi le credenziali e la configurazione dello spazio dati prima di iniziare a scaricare grandi quantità di dati, puoi risolvere rapidamente eventuali problemi con le impostazioni.

Se il test va a buon fine, crea il datastore. Se il test non va a buon fine, correggi gli errori e riprova a eseguire la configurazione. Crea il datastore solo dopo che i test sono stati superati.

Per attivare la funzionalità di test, devi:

• Assicurati che l'API Cloud Resource Manager sia attivata nel tuo progetto Google Cloud. Per le istruzioni, vedi Abilitazione e disattivazione delle API.

Crea un datastore

Per creare un datastore nell'interfaccia utente:

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

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

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

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

   

4. Scegli un tipo di destinazione 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 saperne di più, consulta 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 dati.

   • Se aggiungi nuove credenziali al datastore, seleziona Aggiungi nuova. Nella finestra di dialogo, inserisci:

     1. Il nome delle credenziali.
     2. Contenuti delle credenziali è la chiave dell'account di servizio JSON specifica per il tuo repository di dati, come definito 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	Obbligatorio?
     ID progetto	ID progetto della piattaforma Google Cloud. Per creare un progetto Google Cloud, consulta Creare e gestire i 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 Creare 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	Obbligatorio?
     ID progetto	ID progetto della piattaforma Google Cloud. Per creare un progetto Google Cloud, consulta Creare e gestire i 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 sia stato creato prima di richiedere l'esportazione dei dati. Per creare un set di dati BigQuery, consulta Creazione e utilizzo di set di dati nella documentazione della piattaforma Google Cloud.	Sì
     Prefisso tabella	Il prefisso dei nomi delle tabelle create per i dati di analisi nel set di dati BigQuery.	Sì

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

   Se il test va a buon fine, salva il tuo data store.

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

9. Dopo che il test di connessione è stato superato, salva il data store.

Modificare un datastore

Per modificare un datastore:

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

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

3. Posiziona il cursore del mouse sulla colonna Modificata del report da modificare. Vengono visualizzate le icone Modifica ed Elimina.

4. Modifica o elimina il datastore.

5. Se hai modificato il data store, seleziona Testa connessione per assicurarti che le credenziali possano essere utilizzate per accedere al data store.

   Se il test va a buon fine, puoi visualizzare i dati di esempio nel tuo repository di dati.

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

6. Dopo che il test di connessione è stato superato, Aggiorna l'archivio dati.

Esportare i dati di analisi

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

• Nome e descrizione della richiesta di esportazione
• Intervallo di date dei dati esportati (il valore può comprendere 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 Riferimento alle proprietà della richiesta di esportazione.

La risposta al POST è nel seguente 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 eseguito in background dopo che la richiesta ha restituito 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 Visualizzazione dello stato di una richiesta di esportazione di Analytics. Al termine della richiesta, il valore della proprietà state nella risposta viene impostato su completed. A questo punto puoi accedere ai dati di analisi nel tuo repository di dati.

Esempio 1: esportazione dei dati in Cloud Storage

La seguente richiesta esporta un insieme completo di dati non elaborati per le ultime 24 ore dall'ambiente di 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 Visualizzare lo stato di una richiesta di esportazione di dati di analisi.

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 dati di analisi.

Esempio 3: esportare i dati di monetizzazione

Se la monetizzazione è attivata 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 di monetizzazione per esportare i dati specifici relativi alla 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 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 dell'API Export

Per evitare un utilizzo 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 la monetizzazione non è attivata, la quota è:

  • 70 chiamate al mese per organizzazione/ambiente.

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

• Per le organizzazioni e gli ambienti con la monetizzazione attivata, 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 di monetizzazione.

  Ad esempio, se attivi la monetizzazione nella tua organizzazione prod, puoi effettuare 70 chiamate API per i dati standard e altre 70 chiamate API 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 di dati di analisi

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

Ad esempio, la seguente richiesta restituisce lo stato di tutte le richieste di esportazione di dati di 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 di risposta che elenca due richieste di esportazione, una in coda (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",
    ... 
  }
]

Visualizzare lo stato di una richiesta di esportazione di dati di analisi

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

Ad esempio, la seguente richiesta restituisce lo stato della richiesta di esportazione di Analytics con l'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 di 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 dei dati di analisi non restituisce dati di analisi, executionTime viene impostato su "0 secondi".

Riferimento alla proprietà della richiesta di esportazione

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

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

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