API de metadatos: guía para desarrolladores

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

Introducción

La API de metadatos devuelve la lista de columnas (es decir, las dimensiones y las métricas) que se exponen en las API de informes de Google Analytics y sus atributos. Si es la primera vez que usas la API, consulta la descripción general de la API de metadatos para ver una presentación de dicha API.

Antes de empezar

A todas las API de Google Analytics se accede de un modo similar. Antes de empezar a usar la API de metadatos, debes realizar las siguientes acciones:

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

Cada biblioteca de cliente proporciona un solo objeto de servicio analytics para acceder a todos los datos de la API de metadatos. Por lo general, para crear el objeto de servicio para la API de metadatos tienes que realizar los pasos siguientes:

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

Registro y clave de la API

Tu aplicación necesita identificarse cada vez que envía una solicitud a la API de Analytics mediante la inclusión de una clave de la API con cada solicitud.

Adquirir y usar una clave de la API

Para obtener una clave de la API:

  1. Abre la página Credenciales en la consola de Cloud Platform.
  2. Esta API admite dos tipos de credenciales. Crea las que resulten adecuadas para tu proyecto:
    • OAuth 2.0: Siempre que tu aplicación solicite datos de usuario privados, debe enviar un token de OAuth 2.0 junto con la solicitud. La aplicación envía primero un ID de cliente y, posiblemente, un secreto de cliente para obtener un token. Puedes generar las credenciales de OAuth 2.0 para aplicaciones web, cuentas de servicio o aplicaciones descargadas.

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

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

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

      La API admite varios tipos de restricciones de claves de API. Si la clave de la API que necesitas todavía no existe, créala en la consola haciendo clic en Create credentials > API key (Crear credenciales > Clave de la API) y seleccionando el tipo adecuado. Puedes restringir la clave antes de utilizarla en producción haciendo clic en Restrict key (Restringir clave) y seleccionando una de las Restricciones.

Para proteger las claves de la API, sigue las prácticas recomendadas para usarlas de forma segura.

Una vez que dispongas de una clave de la API, tu aplicación puede adjuntar el parámetro de consulta key=yourAPIKey a todas las URL de solicitud.

La clave de la API se puede insertar en las URL; no es necesario codificarla.

En los siguientes fragmentos de código se ilustra el modo de configurar la clave de la API para diferentes bibliotecas de 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 la propiedad attributeNames que enumera todos los atributos de columna válidos. Cada columna tiene una propiedad attributes que incluye un subconjunto de atributos que se pueden aplicar a la columna.

En la siguiente tabla se ofrece una lista completa de los atributos válidos:

Casos de uso

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

Columnas retiradas

Si una columna (es decir, una dimensión o métrica) está retirada, su atributo status se establecerá con el valor DEPRECATED.

En el siguiente fragmento se muestra cómo usar el atributo status para comprobar si una columna está retirada:

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

Si se ha cambiado el nombre de columna o se ha quitado, su atributo status se configurará como DEPRECATED y puede tener el atributo replacedBy configurado como el valor de 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 (por ejemplo, la interfaz web).

En el siguiente fragmento se muestra cómo recupera el nombre de la interfaz de usuario de una columna:

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

Columnas de plantilla

En las columnas de plantilla se incluyen las dimensiones o las métricas con un índice numérico. Por ejemplo, ga:goalXXStarts, ga:dimensionXX, ga:metricXX, etc. Una columna de plantilla tendrá los atributos minTemplateIndex y maxTemplateIndex que definen el intervalo del índice.

En el siguiente fragmento se muestra cómo comprobar que una columna es de plantilla:

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 correspondientes a una columna de plantilla:

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 del cálculo de otras columnas tendrá el atributo calculation. Por ejemplo, el cálculo de ga:percentNewSessions es ga:newSessions / ga:sessions.

En el siguiente ejemplo se muestra cómo comprobar si una columna es calculada 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 permite comprobar si una columna se puede usar en el parámetro de consulta de segmento.

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

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

Agregada en la versión de la API

Usa el atributo addedInApiVersion para comprobar si una columna puede utilizarse en una versión concreta de una API de informes. Por ejemplo, llama a la función siguiente para comprobar que la columna puede usarse en la versión 3 de la API de informes centrales:

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

ETag

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

Si almacenas la etiqueta ETag de una colección de columnas, puedes usarla principalmente de dos formas: para comprobar que una respuesta de la API de metadatos en caché esté actualizada y para incluirla como parte de una solicitud de la API de metadatos.

Comprobar una respuesta en caché

Si comparas el valor de ETag devuelto en una respuesta de la API de metadatos y es equivalente a la ETag de un recurso en caché, la versión en caché es actual. Si las ETag no son equivalentes, actualiza la aplicación y la memoria caché con la respuesta más reciente.

Si solo quieres recuperar el valor de ETag de la API de metadatos, configura el parámetro de consulta fields como etag al realizar una solicitud. Consultar un ejemplo.

Usar una ETag con una solicitud de la API

Si tienes una versión en caché de una colección de columnas, puedes incluir un valor de ETag en una solicitud de la API de metadatos configurando el campo de encabezado de HTTP If-None-Match. La API de metadatos comprobará 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 en caché es la actual.