API Multi-ChannelFunnel Reporting - Guida per gli sviluppatori

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:

  1. Registra la tua applicazione nella console API di Google.
  2. Autorizza l'accesso ai dati di Google Analytics.
  3. 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:

  1. Esegui una query sull'API Multi-ChannelFunnel Reporting.
  2. Lavora con i risultati restituiti dall'API.

Esegui una query sull'API Multi-ChannelFunnel Reporting

Per richiedere i dati dall'API Multi-ChannelFunnel Reporting:

  1. Creare un oggetto query dell'API multicanale per i report sulle canalizzazioni.
  2. 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