API de informes de embudos multicanal: guía para desarrolladores

En este documento se explica cómo usar la API de informes de embudos multicanal para acceder a los datos de los embudos multicanal.

Introducción

La API de informes de embudos multicanal proporciona acceso a los datos tabulares en los informes estándar y personalizados de los embudos multicanal. Para acceder a los datos, debes crear una consulta que especifique: la vista (perfil), las fechas de inicio y finalización, y las dimensiones y las métricas que componen los encabezados de columna de la tabla. Esta consulta se envía a la API de informes de embudos multicanal, que devuelve todos los datos con formato tabular.

Si es la primera vez que usas la API, consulta en Descripción general de la API de informes de embudos multicanal una introducción a la finalidad de la API y los datos que proporciona.

Antes de empezar

En esta guía se usa la biblioteca de cliente Java para acceder a la API de informes de embudos multicanal. Cada biblioteca de cliente proporciona un solo objeto de servicio de Analytics para llamar a la API de informes multicanal con el fin de obtener los datos. Si no utilizas una biblioteca de cliente para acceder a la API, consulta la Guía de referencia de la API de informes de embudos multicanal.

Para crear el objeto de servicio de Analytics:

  1. Registra la aplicación en la consola de la API de Google.
  2. Autoriza el acceso a los datos de Google Analytics.
  3. Escribir el código para crear el objeto de servicio de Analytics.

Si no has completado estos pasos, no continúes y lee Tutorial: Hello Analytics API, en el que se te guiará por los pasos para compilar aplicación de la API de Google Analytics. Después de completar el tutorial, sigue leyendo la siguiente guía.

Por ejemplo, el código siguiente crea un objeto de servicio de Analytics autorizado:

Java

Analytics analytics = initializeAnalytics();

Utiliza el objeto de servicio analytics para llamar a la API de informes de embudos multicanal.

Descripción general

Para usar la API de informes de embudos multicanal a fin de recuperar los datos, escribe una aplicación para:

  1. Consultar la API de informes de embudos multicanal.
  2. Trabajar con los resultados devueltos de la API.

Consultar la API de informes de embudos multicanal

Para solicitar datos de la API de informes de embudos multicanal, realiza las siguientes acciones:

  1. Crear un objeto de consulta de la API de informes de embudos multicanal.
  2. Utilizar el objeto de consulta para solicitar datos a los servidores de embudos multicanal.

Crear una consulta de la API de informes de embudos multicanal

Para crear un objeto de consulta de la API de informes de embudos multicanal, llama a este método:

analytics.data.mcf.get()    // analytics is the Analytics service object

El primer parámetro suministrado al método es un ID de tabla único con el formato ga:XXXX, donde XXXX es el ID de una vista (perfil) de Analytics que contiene los datos solicitados. Utilice el objeto de consulta para especificar los parámetros de consulta (por ejemplo, setDimensions). Por ejemplo:

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);

En Resumen de parámetros de consulta encontrará una lista de todos los parámetros de consulta. Los parámetros de dimensiones y métricas te permiten especificar qué datos se recuperarán de los embudos multicanal. En la Referencia de dimensiones y métricas encontrarás una lista de todas las dimensiones y métricas.

Crear una solicitud de datos de la API de informes de embudos multicanal

Después de crear el objeto de consulta, llama al método execute en el objeto para solicitar datos a los servidores de embudos multicanal. Por ejemplo:

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();
}

Si prefieres acceder a la respuesta de la API sin procesar, llama al método executeUnparsed() en el objeto de consulta.

HttpResponse response = apiQuery.executeUnparsed();

Si la consulta se realiza correctamente, devuelve los datos solicitados. Si se produce un error, el método execute genera una excepción que contiene un código de estado correspondiente al error y una descripción del mismo. La aplicación debe interceptar y gestionar la excepción.

Trabajar con los resultados de la API

Si la consulta de la API de informes de embudos multicanal se realiza correctamente, devuelve los datos de informe y la información sobre los datos.

Datos de los informes de los embudos multicanal

La consulta devuelve los siguientes datos de informes tabulares:

  • Datos de encabezado de columna
  • Datos de filas

Datos de encabezado de columna

La respuesta de consulta tiene un campo de encabezado de columna que contiene la información de encabezado de tabla. El campo es una lista (o una matriz) de objetos ColumnHeaders, cada uno de los cuales contiene el nombre, el tipo y el tipo de datos de la columna. El orden de las columnas es el de columnas de dimensiones seguidas de las columnas de métricas en el mismo orden especificado en la consulta original. Por ejemplo, el siguiente método imprime los encabezados de las columnas:

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());
  }
}

Datos de filas

Los datos principales que devuelve la API se incluyen en un objeto List bidimensional de McfData.Rows. Cada objeto McfData.Rows representa una sola celda que es un valor primitivo del tipo String o un valor de ruta de conversión de tipo McfData.Rows.ConversionPathValue. El orden de las celdas de una fila es el mismo que los campos en el objeto de encabezado de columna descrito anteriormente.

Debido a que los datos de cada celda se devuelven como una cadena o como un tipo de secuencia de embudos multicanal, el campo DataType de cada objeto de encabezado de columna resulta muy útil para analizar los valores en sus tipos adecuados. Consulta en la guía de referencia todos los posibles tipos de datos.

Por ejemplo, el siguiente método imprime los encabezados de tabla y las filas:

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

En el siguiente ejemplo se muestra cómo analizar un objeto de tipo de secuencia de embudos multicanal y convertirlo en una cadena.

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();
}

Datos del informe

Además de los datos de informes, la consulta devuelve información (por ejemplo, el ID de informe) sobre los datos. Por ejemplo, el siguiente método imprime la información del informe:

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());
}

El campo containsSampledData te indica si se ha muestreado la respuesta de la consulta. Como el muestreo puede afectar a los resultados de la consulta, los valores muestreados devueltos desde la consulta (API) no coinciden con los mostrados en la interfaz web. Consulta Muestreo para obtener más información.

Información de vista (perfil)

En la respuesta de consulta se incluyen el ID de propiedad web, el nombre e ID de vista (perfil), y el ID de la cuenta de Analytics que contiene la vista (perfil). Por ejemplo, el siguiente método los imprime en el terminal (salida estándar):

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());
}

Información de consulta

En la respuesta de consulta se incluye un objeto Query que contiene los valores de todos los parámetros de consulta de solicitud de datos. Por ejemplo, el siguiente método imprime los valores de dichos parámetros:

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());
}

Los métodos distintos de query.getMetrics(), query.getDimensions() y query.getSort() devuelve un valor de tipo String. Por ejemplo, query.getStartDate() devuelve la fecha de inicio (un valor de tipo String) del informe.

Información de paginación

Cualquier solicitud de la API de informes de embudos multicanal puede coincidir con centenares de miles de filas de los datos de los embudos multicanal. La API de informes de embudos multicanal solo devolverá un subconjunto, que se denomina como una sola página de los datos en un momento dado. Para recuperar todas las páginas de datos, utilice el campo de paginación. El siguiente método imprime la información de paginación:

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 llamada de método mcfData.getTotalResults() devuelve el número total de filas de la consulta, que puede ser mayor que el número total de las filas que devuelve la consulta. Y la llamada de método mcfData.getItemsPerPage() devuelve el número máximo de filas que puede contener la respuesta de consulta.

La llamada de método mcfData.getPreviousLink() devuelve el enlace a la página anterior y mcfData.getNextLink() devuelve el enlace a la página siguiente.

Totales de todos los resultados

Para obtener los valores totales de las métricas solicitadas sobre todos los resultados, no solo los devueltos en la respuesta de consulta, llama al método getTotalsForAllResults() en dicha respuesta, un objeto McfData. Utiliza los valores totales para calcular las medias.

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());
  }
}

Muestra funcional

Java

Biblioteca de cliente Java de la API de Google: muestra de la API de informes de embudos multicanal.