Questo documento spiega come utilizzare l'API di reporting Canalizzazioni multicanale per accedere ai dati delle canalizzazioni multicanale.
Introduzione
L'API di reporting delle canalizzazioni multicanale consente di accedere ai dati tabulari nei report standard e personalizzati di Canalizzazioni multicanale. Per accedere ai dati, crea una query che specifichi: la vista (profilo), le date di inizio e di fine, nonché le dimensioni e le metriche che costituiscono le intestazioni di colonna nella tabella. Questa query viene inviata all'API di reporting Canalizzazioni multicanale e l'API di reporting delle canalizzazioni multicanale restituisce tutti i dati sotto forma di tabella.
Se non hai mai utilizzato l'API, leggi la Panoramica dell'API Multi-Channel Canal Reporting API per saperne di più sullo scopo dell'API di reporting Canalizzazioni multicanale e sui dati che fornisce.
Prima di iniziare
Questa guida utilizza la libreria client Java per accedere all'API di reporting Canalizzazioni multicanale. Ogni libreria client fornisce un singolo oggetto di servizio Analytics per chiamare l'API Multi-ChannelFunnel Reporting per ottenere i dati. Se non utilizzi una libreria client per accedere all'API, consulta la Guida di riferimento API di reporting Canalizzazioni multicanale.
Per creare l'oggetto di servizio Analytics:
- Registra la tua applicazione nella console API di Google.
- Autorizza l'accesso ai dati di Google Analytics.
- Scrivi il codice per creare l'oggetto di servizio Analytics.
Se non hai completato questi passaggi, interrompi e leggi il tutorial sull'API Hello Analytics, che illustra i passaggi iniziali per la creazione di un'applicazione API di Google Analytics. Dopo aver completato il tutorial, continua a leggere la guida che segue.
Ad esempio, il seguente codice crea un oggetto di servizio Analytics autorizzato:
Java
Analytics analytics = initializeAnalytics();
Utilizza l'oggetto di servizio Analytics analytics
per chiamare
l'API di reporting Canalizzazioni multicanale.
Panoramica
Per utilizzare l'API di reporting Canalizzazioni multicanale per recuperare i dati, scrivi un'applicazione in:
- Esegui una query sull'API Multi-ChannelFunnel Reporting.
- Lavora con i risultati restituiti dall'API.
Esegui una query sull'API Multi-ChannelFunnel Reporting
Per richiedere i dati dall'API Multi-ChannelFunnel Reporting:
- Creare un oggetto query dell'API multicanale per i report sulle canalizzazioni.
- Utilizza l'oggetto query per richiedere i dati dai server Canalizzazioni multicanale.
Creare una query API multicanale per i report sulle canalizzazioni
Per creare un oggetto di query dell'API multicanale per i report sulle canalizzazioni multicanale, chiama questo metodo:
analytics.data.mcf.get() // analytics is the Analytics service object
Il primo parametro fornito al metodo è un ID tabella univoco
sotto forma di ga:XXXX
, dove XXXX
è
l'ID di una vista (profilo) Analytics contenente i dati richiesti.
Utilizza l'oggetto query per specificare
i parametri di query (ad es. setDimensions
). Ad esempio:
Java
Get apiQuery = analytics.data().mcf() .get(tableId, "2012-01-01", // Start date "2012-03-31", // End date "mcf:totalConversions") // Metrics .setDimensions("mcf:sourcePath") .setSort("-mcf:totalConversions") .setMaxResults(25);
Per un elenco di tutti i parametri di query, consulta il riepilogo dei parametri di query. I parametri delle metriche e delle dimensioni consentono di specificare quali dati delle Canalizzazioni multicanale recuperare. Per un elenco di tutte le dimensioni e metriche, consulta la pagina Riferimento per dimensioni e metriche.
Esecuzione di una richiesta di dati dell'API Multi-Channel Canal Reporting API
Dopo aver creato l'oggetto query, chiama il metodo execute
sull'oggetto per richiedere dati ai server delle canalizzazioni multicanale. Ad esempio:
Java
try { apiQuery.execute(); // Success. Do something cool! } catch (GoogleJsonResponseException e) { // Catch API specific errors. handleApiError(e); } catch (IOException e) { // Catch general parsing network errors. e.printStackTrace(); }
Se preferisci accedere alla risposta dell'API non elaborata, chiama il metodo executeUnparsed()
nell'oggetto query:
HttpResponse response = apiQuery.executeUnparsed();
Se la query ha esito positivo, restituisce i dati richiesti. Se si verifica un errore, il metodo execute
genera un'eccezione contenente un codice di stato e una descrizione dell'errore. L'applicazione deve rilevare e gestire l'eccezione.
Utilizzo dei risultati dell'API
Se la query API Multi-ChannelFunnel Reporting ha esito positivo, restituisce i dati dei report e le informazioni sui dati.
Dati dei report Canalizzazioni multicanale
La query restituisce i seguenti dati dei report tabulari:
- Dati dell'intestazione di colonna
- Dati riga
Dati dell'intestazione di colonna
La risposta alla query contiene un campo di intestazione di colonna contenente le informazioni di intestazione della tabella. Il campo è un elenco (o un array) di oggetti ColumnHeaders
, ognuno dei quali contiene nome, tipo di colonna e tipo di dati della colonna. L'ordine delle colonne corrisponde alle colonne delle dimensioni seguite dalle colonne delle metriche nello stesso ordine specificato nella query originale. Ad esempio, il seguente metodo stampa le intestazioni di colonna:
Java
private static void printColumnHeaders(McfData mcfData) { System.out.println("Column Headers:"); for (ColumnHeaders header : mcfData.getColumnHeaders()) { System.out.println("Column Name: " + header.getName()); System.out.println("Column Type: " + header.getColumnType()); System.out.println("Column Data Type: " + header.getDataType()); } }
Dati riga
I dati principali restituiti dall'API vengono restituiti come un List
bidimensionale di McfData.Rows
. Ogni McfData.Rows
rappresenta una singola cella che è un valore primitivo di tipo String
o un valore del percorso di conversione di tipo McfData.Rows.ConversionPathValue
. L'ordine delle celle in una riga è lo stesso dei campi nell'oggetto intestazione di colonna descritto sopra.
Poiché i dati di ogni cella vengono restituiti come stringa o come un tipo di sequenza di Canalizzazioni multicanale, il campo DataType
in ogni oggetto di intestazione di colonna è particolarmente utile per analizzare i valori nei tipi appropriati.
Consulta la
guida di riferimento per tutti i possibili tipi di dati.
Ad esempio, il seguente metodo stampa le intestazioni e le righe della tabella:
Java
private static void printDataTable(McfData mcfData) { System.out.println("Data Table:"); if (mcfData.getTotalResults() > 0) { // Print the column names. List<ColumnHeaders> headers = mcfData.getColumnHeaders(); for (ColumnHeaders header : headers) { System.out.print(header.getName()); } System.out.println(); // Print the rows of data. for (List<McfData.Rows> row : mcfData.getRows()) { for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) { ColumnHeaders header = headers.get(columnIndex); McfData.Rows cell = row.get(columnIndex); if (header.getDataType().equals("MCF_SEQUENCE")) { System.out.print(getStringFromMcfSequence(cell.getConversionPathValue())); } else { System.out.print(cell.getPrimitiveValue()); } } System.out.println(); } } else { System.out.println("No rows found"); } }
L'esempio seguente mostra come analizzare un oggetto di tipo di sequenza Canalizzazioni multicanale e convertirlo in una stringa:
Java
private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) { StringBuilder stringBuilder = new StringBuilder(); for (McfData.Rows.ConversionPathValue pathElement : path) { if (stringBuilder.length() > 0) stringBuilder.append(" > "); stringBuilder.append(pathElement.getNodeValue()); } return stringBuilder.toString(); }
Informazioni sulla segnalazione
Oltre ai dati dei report, la query restituisce informazioni (ad es. ID report) sui dati. Ad esempio, il seguente metodo stampa le informazioni del report:
Java
private static void printReportInfo(McfData mcfData) { System.out.println("Report Info:"); System.out.println("ID:" + mcfData.getId()); System.out.println("Self link: " + mcfData.getSelfLink()); System.out.println("Kind: " + mcfData.getKind()); System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData()); }
Il campo containsSampledData
indica se la risposta alla query è stata campionata.
Poiché il campionamento può influire sui risultati della query, i valori campionati restituiti dalla query (API) non corrispondono a quelli mostrati nell'interfaccia web. Per ulteriori dettagli, consulta la sezione Campionamento.
Visualizzare le informazioni (profilo)
La risposta alla query include l'ID proprietà web, il nome e l'ID della vista (profilo) e l'ID dell'account Analytics contenente la vista (profilo). Ad esempio, il seguente metodo le stampa sul terminale (output standard):
Java
private static void printProfileInfo(McfData mcfData) { ProfileInfo profileInfo = mcfData.getProfileInfo(); System.out.println("View (Profile) Info:"); System.out.println("Account ID: " + profileInfo.getAccountId()); System.out.println("Web Property ID: " + profileInfo.getWebPropertyId()); System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId()); System.out.println("View (Profile) ID: " + profileInfo.getProfileId()); System.out.println("View (Profile) Name: " + profileInfo.getProfileName()); System.out.println("Table ID: " + profileInfo.getTableId()); }
Informazioni sulla query
La risposta alla query include un oggetto Query
che contiene i valori di tutti i parametri di query della richiesta di dati. Ad esempio, il seguente metodo stampa i valori di questi parametri:
Java
private static void printQueryInfo(McfData mcfData) { Query query = mcfData.getQuery(); System.out.println("Query Info:"); System.out.println("Ids: " + query.getIds()); System.out.println("Start Date: " + query.getStartDate()); System.out.println("End Date: " + query.getEndDate()); System.out.println("Metrics: " + query.getMetrics()); // List of Analytics metrics System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions System.out.println("Sort: " + query.getSort()); // List of sorte metrics or dimensions System.out.println("Segment: " + query.getSegment()); System.out.println("Filters: " + query.getFilters()); System.out.println("Start Index: " + query.getStartIndex()); System.out.println("Max Results: " + query.getMaxResults()); }
I metodi diversi da query.getMetrics()
,
query.getDimensions()
e query.getSort()
restituiscono un valore String
. Ad esempio, query.getStartDate()
restituisce la data di inizio (a String
) del report.
Informazioni sull'impaginazione
Qualsiasi richiesta all'API di reporting sulle canalizzazioni multicanale potrebbe corrispondere a centinaia di migliaia di righe di dati delle canalizzazioni multicanale. L'API Multi-ChannelFunnel Reporting restituisce in un determinato momento solo un sottoinsieme, denominato una singola pagina di dati. Per recuperare tutte le pagine di dati, utilizza il campo impaginazione. Il seguente metodo stampa le informazioni sull'impaginazione:
Java
private static void printPaginationInfo(McfData mcfData) { System.out.println("Pagination Info:"); System.out.println("Previous Link: " + mcfData.getPreviousLink()); System.out.println("Next Link: " + mcfData.getNextLink()); System.out.println("Items Per Page: " + mcfData.getItemsPerPage()); System.out.println("Total Results: " + mcfData.getTotalResults()); }
La chiamata al metodo mcfData.getTotalResults()
restituisce il numero totale di righe per la query, che può essere maggiore del numero totale di righe restituite dalla query. E la chiamata al metodo mcfData.getItemsPerPage()
restituisce il numero massimo di righe che la risposta alla query può contenere.
La chiamata di metodo mcfData.getPreviousLink()
restituisce il link alla
pagina precedente e mcfData.getNextLink()
restituisce il
link alla pagina successiva.
Totali per tutti i risultati
Per ottenere i valori totali delle metriche richieste su tutti i risultati, non solo su quelli restituiti nella risposta alla query, chiama il metodo getTotalsForAllResults()
nella risposta alla query, un oggetto McfData
. Usa i valori totali per calcolare
le medie.
Java
private static void printTotalsForAllResults(McfData mcfData) { System.out.println("Metric totals over all results:"); Map<String, String> totalsMap = mcfData.getTotalsForAllResults(); for (Map.Entry<String, String> entry : totalsMap.entrySet()) { System.out.println(entry.getKey() + " : " + entry.getValue()); } }
Esempio funzionante
Java
Libreria client Java dell'API di Google Esempio di API di reporting delle canalizzazioni multicanale