Guía para desarrolladores: API de informes de embudos multicanales

Este documento explica cómo utilizar la API de informes de embudos multicanales para acceder a los datos de los embudos multicanales.

Introducción

La API de informes de embudos multicanales proporciona acceso a los datos tabulares en los informes personalizados y estándar de los embudos multicanales. 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 métricas que conforman los encabezados de columna en la tabla. Esta consulta se envía a la API de informes de embudos multicanales y la API de informes de embudos multicanales muestra todos los datos en forma de tabla.

Si eres nuevo en la API, lee la Descripción general de la API de informes de embudos multicanales para obtener una introducción del propósito de la API de informes de embudos multicanales y los datos que proporciona.

Antes de comenzar

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

Para crear el objeto de servicio de Analytics, siga estos pasos:

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

Si todavía no completaste estos pasos, detente y lee el Instructivo de la API de Hello Analytics, en el que se explican los pasos iniciales para compilar una aplicación de la API de Google Analytics. Después de completar el instructivo, continúa leyendo la siguiente guía.

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

Java

Analytics analytics = initializeAnalytics();

Usa el objeto de servicio de Analytics analytics para llamar a la API de informes de embudos multicanales.

Descripción general

Si desea utilizar la API de informes de embudos multicanales para recuperar datos, escriba una aplicación en:

  1. Consulte la API de informes de embudos multicanales.
  2. Trabaja con los resultados que muestra la API.

Cómo consultar la API de informes de embudos multicanales

Para solicitar datos de la API de informes de embudos multicanales:

  1. Cree un objeto de consulta de la API de informes de embudos multicanales.
  2. Usa el objeto de consulta para solicitar los datos de los servidores de embudos multicanales.

Cree una consulta a la API de informes de embudos multicanales

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

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

El primer parámetro proporcionado al método es un ID de tabla único con el formato ga:XXXX, en el que XXXX es el ID de una vista de Analytics (perfil) que contiene los datos solicitados. Usa el objeto de consulta para especificar parámetros de consulta (es decir, 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);

Para obtener una lista de todos los parámetros de consulta, visita Resumen de parámetros de consulta. Los parámetros de métricas y dimensiones te permiten especificar qué datos de los embudos multicanal recuperar. Para obtener una lista de todas las dimensiones y métricas, consulta la Referencia de métricas y dimensiones.

Cómo realizar una solicitud de datos de la API de informes de embudos multicanales

Después de crear el objeto de consulta, llama al método execute en el objeto para solicitar datos de los servidores de embudos multicanales. 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, se mostrarán los datos solicitados. Si se produce un error, el método execute muestra una excepción que contiene un código de estado y una descripción. La aplicación debería detectar y manejar la excepción.

Trabaje con los resultados de la API

Si la consulta de la API de informes de embudos multicanal es exitosa, mostrará los datos de informes y la información sobre ellos.

Datos de informes de Embudos multicanales

La consulta muestra los siguientes datos de informes tabulares:

  • Datos del encabezado de columna
  • Datos de la fila

Datos del encabezado de columna

La respuesta de la consulta tiene un campo de encabezado de columna que contiene la información del encabezado de la tabla. El campo es una lista (o arreglo) de objetos ColumnHeaders, cada uno de los cuales contiene un nombre de columna, un tipo de columna y un tipo de datos de columna. El orden de las columnas son columnas de dimensiones seguidas de columnas de métricas en el mismo orden que se especifica 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 la fila

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

Dado que los datos en cada celda se muestran como una string o como un tipo de secuencia de embudos multicanales, el campo DataType en cada objeto de encabezado de columna es particularmente útil para analizar valores en tipos adecuados. Consulta la guía de referencia para conocer todos los tipos de datos posibles.

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

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 multicanales y convertirlo en una string:

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

Información del informe

Además de los datos de informes, la consulta muestra información (ID de informe, por ejemplo) 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 indica si se realizó un muestreo de la respuesta a la consulta. Debido a que el muestreo puede afectar los resultados de la consulta, los valores de muestra que muestra la consulta (API) no coinciden con los que se muestran en la interfaz web. Consulta Muestreo para obtener más detalles.

Ver información (perfil)

La respuesta a la consulta incluye el ID de propiedad web, el nombre y el ID de la vista (perfil), y el ID de la cuenta de Analytics que contiene la vista (perfil). Por ejemplo, el siguiente método los imprime en la 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

La respuesta a la consulta 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 esos 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 que no sean query.getMetrics(), query.getDimensions() y query.getSort() muestran un String. Por ejemplo, query.getStartDate() muestra la fecha de inicio (una String) del informe.

Información de paginación

Cualquier solicitud a la API de informes de embudos multicanales puede coincidir con cientos de miles de filas de datos de embudos multicanales. La API de informes de embudos multicanales mostrará solo un subconjunto, denominado página única de los datos, en un momento determinado. Para recuperar todas las páginas de datos, usa 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 al método mcfData.getTotalResults() muestra la cantidad total de filas que se muestran para la consulta, que puede ser mayor que la cantidad total de filas que muestra la consulta. Y la llamada al método mcfData.getItemsPerPage() muestra la cantidad máxima de filas que puede contener la respuesta a la consulta.

La llamada de método mcfData.getPreviousLink() muestra el vínculo a la página anterior y mcfData.getNextLink() muestra el vínculo a la página siguiente.

Totales de todos los resultados

Para obtener los valores totales de las métricas solicitadas de todos los resultados, no solo los resultados que se muestran en la respuesta a la consulta, llama al método getTotalsForAllResults() en la respuesta de la consulta, un objeto McfData. Usa los valores totales para calcular los promedios.

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 de trabajo

Java

Biblioteca cliente de las API de Google para Java: API de informes de embudos multicanales