API de metadatos: guía para desarrolladores

En este documento, se explican conceptos importantes sobre el uso de la API de Metadata para acceder a la lista y los atributos de las columnas de Google Analytics.

Introducción

La API de metadatos muestra la lista de columnas (es decir, dimensiones y métricas) expuestas en las APIs de informes de Google Analytics y sus atributos. Si es la primera vez que usas la API, lee la Descripción general de la API de metadatos para obtener una introducción a la API de metadatos.

Antes de comenzar

Se accede a todas las APIs de Google Analytics de manera similar. Antes de comenzar con la API de metadatos, debes hacer lo siguiente:

  • Lee la página sobre bibliotecas cliente para obtener una lista completa de las bibliotecas cliente específicas de cada lenguaje de programación que funcionan con la API.
  • Lee la Guía de referencia para obtener más información sobre la interfaz de la API y el acceso a los datos sin una biblioteca cliente.

Cada biblioteca cliente proporciona un solo objeto de servicio de estadísticas para acceder a todos los datos de la API de Metadata. Por lo general, si quieres crear el objeto de servicio para usarlo con la API de metadatos, debes seguir estos pasos:

  1. Registra tu aplicación en la Consola de API de Google.
  2. Crea un objeto de servicio de Analytics y configura la clave de API.

Registro y clave de API

Tu aplicación necesita identificarse cada vez que envía una solicitud a la API de Analytics; para ello, debe incluir una clave de API en cada solicitud.

Adquiere y usa una clave de API

Para adquirir una clave de API, haz lo siguiente:

  1. Abre la página Credenciales en la Consola de APIs.
  2. En esta API, se admiten dos tipos de credenciales. Crea las credenciales apropiadas para tu proyecto:

    • OAuth 2.0: Siempre que se soliciten datos privados del usuario, mediante tu aplicación se debe enviar un token OAuth 2.0 junto con la solicitud. En primer lugar, se envía un ID de cliente y, posiblemente, un secreto de cliente para obtener un token a través de la aplicación. Puedes generar credenciales OAuth 2.0 para aplicaciones web, cuentas de servicio o aplicaciones instaladas.

      Nota: Dado que esta API no tiene ningún método que requiera autorización de OAuth 2.0, es posible que solo necesites obtener claves de API, las cuales se describen a continuación. Sin embargo, si tu aplicación llama a otras APIs que requieren la autorización del usuario, aún necesitarás credenciales de OAuth 2.0.

      Para obtener más información, consulta la documentación de OAuth 2.0.

    • Claves de API: Una solicitud que no proporcione un token de OAuth 2.0 debe enviar una clave de API. Con la clave de API, se identifica tu proyecto y se proporciona acceso a la API, la cuota y los informes.

      En la API, se admiten varios tipos de restricciones sobre las claves de API. Si aún no existe la clave de API que necesitas, crea una en la consola. Para ello, haz clic en Crear credenciales > Clave de API. Puedes restringir la clave antes de usarla en producción. Para ello, haz clic en Restringir clave y selecciona una de las Restricciones.

Para garantizar la seguridad de tus claves de API, sigue las prácticas recomendadas de uso seguro de las claves de API.

Una vez que tienes una clave de API, puedes usar tu aplicación para adjuntar el parámetro de consulta key=yourAPIKey a todas las URL de solicitud.

La clave de API en las URL se incorpora de manera segura, por lo que no necesita codificación.

En los siguientes fragmentos de código, se muestra cómo configurar la clave de API para varias bibliotecas cliente:

Java

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

Atributos de columna

La respuesta de la API de metadatos incluye una propiedad attributeNames que enumera todos los atributos de columna válidos. Cada columna tiene una propiedad attributes que incluye un subconjunto de atributos aplicables a la columna.

La siguiente tabla es la lista completa de atributos válidos:

Casos de uso

La API de metadatos se puede usar para resolver los siguientes casos de uso:

Columnas obsoletas

Si una columna (es decir, una dimensión o métrica) deja de estar disponible, su atributo status se establecerá como DEPRECATED.

En el siguiente fragmento, se muestra cómo usar el atributo status para verificar si una columna dejó de estar disponible:

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

Si se le cambia el nombre a una columna o se la quita, su atributo status se establecerá como DEPRECATED y puede tener un atributo replacedBy establecido en Id de la columna de reemplazo.

En el siguiente fragmento, se muestra cómo usar el atributo replacedBy para obtener el ID de la columna de reemplazo:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

Nombres de columna

El atributo uiName es el nombre de la dimensión o métrica que se usa en las interfaces de usuario de Google Analytics (p.ej., la interfaz web).

En el siguiente fragmento, se muestra cómo recuperar el nombre de la IU de una columna:

function getColumnName(column) {
  return column.attributes.uiName;
}

Columnas basadas en plantillas

Las columnas con plantillas incluyen dimensiones o métricas con un índice numérico. Por ejemplo, ga:goalXXStarts, ga:dimensionXX, ga:metricXX, etc. Una columna con plantillas tendrá atributos minTemplateIndex y maxTemplateIndex que definen el rango del índice.

En el siguiente fragmento, se muestra cómo verificar si una columna tiene plantillas:

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

En el siguiente fragmento, se muestra cómo recuperar una lista de ID válidos para una columna con plantillas:

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

Columnas calculadas

Una columna que se deriva de un cálculo de otras columnas tendrá un atributo calculation. P.ej., el cálculo de ga:percentNewSessions es ga:newSessions / ga:sessions.

En el siguiente ejemplo, se muestra cómo verificar si se calcula una columna y cómo recuperar el cálculo de una columna:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

Columnas y segmentos

El atributo allowedInSegments te permite verificar si una columna se puede usar en el parámetro de consulta del segmento.

En el siguiente ejemplo, se muestra cómo determinar si una columna se puede usar en los segmentos:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

Se agregó en la versión de API

Usa el atributo addedInApiVersion para verificar si una columna se puede usar en una API de informes de una versión especificada. Por ejemplo, llama a la siguiente función para verificar que la columna se pueda usar en la API de Core Reporting V3: 

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

Se incluye una ETag en cada respuesta de la API de metadatos. La ETag es un identificador que se puede usar para almacenar en caché y actualizar las respuestas de la API de metadatos. Esto es importante porque los datos de las columnas (es decir, las dimensiones y métricas) pueden permanecer sin cambios durante largos períodos y no es eficaz realizar solicitudes y actualizaciones innecesarias cuando se pueden usar los datos almacenados en caché.

Si almacenas la ETag de una colección de columnas, puedes usarla principalmente de 2 maneras: para verificar si una respuesta de la API de metadatos en caché está actualizada y para incluirla como parte de una solicitud a la API de metadatos.

Cómo verificar una respuesta en caché

Si comparas el valor de ETag que se muestra en una respuesta de la API de metadatos y es equivalente al ETag de un recurso almacenado en caché, entonces la versión almacenada en caché es la actual. Si las ETag no son equivalentes, actualiza tu aplicación y actualiza la caché con la respuesta más reciente.

Si solo deseas recuperar el valor de ETag de la API de metadatos, establece el parámetro de consulta de fields en etag cuando realices una solicitud. Mira un ejemplo.

Cómo usar una ETag con una solicitud a la API

Si tienes una versión almacenada en caché de una colección de columnas, puedes incluir su valor de ETag en una solicitud a la API de metadatos configurando el campo del encabezado HTTP If-None-Match. La API de Metadata verificará el valor de ETag y responderá con una versión actualizada del recurso y un estado HTTP 200 OK, o una respuesta vacía con un estado 304 Not Modified si la versión almacenada en caché es actual.