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 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 API de informes de Google Analytics y sus atributos. Si eres nuevo en 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 API de Google Analytics de manera similar. Antes de comenzar a usar la API de metadatos, debes realizar los siguientes pasos:

  • Lee la página sobre las bibliotecas cliente para obtener una lista completa de las bibliotecas cliente específicas de los lenguajes de programación que funcionan con la API.
  • Lee la Guía de referencia para obtener información sobre la interfaz de API y cómo acceder 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 metadatos. Para crear el objeto de servicio a fin de usarlo con la API de metadatos, por lo general, debes realizar los siguientes 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 debe identificarse cada vez que envía una solicitud a la API de Analytics; para ello, incluye una clave de API con 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 API.
  2. En esta API, se admiten dos tipos de credenciales. Crea las credenciales adecuadas 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 debas obtener claves de API, que se describen a continuación. Sin embargo, si tu aplicación llama a otras API que requieren autorización del usuario, igualmente 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 proporciona 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 la clave de API que necesitas aún no existe, crea una clave de API en Console; para ello, haz clic en Crear credenciales > Clave de API. Puedes restringir la clave antes de utilizarla en producción si haces clic en Restringir clave y seleccionas 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 ilustra 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 prácticos:

Columnas obsoletas

Si una columna (es decir, una dimensión o métrica) es obsoleta, su atributo status se establecerá en DEPRECATED.

En el siguiente fragmento, se muestra cómo usar el atributo status para verificar si una columna está obsoleta:

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

Si se cambia el nombre o se quita una columna, su atributo status se establecerá en 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 la 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 templadas

Las columnas templadas 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 de índice.

En el siguiente fragmento, se muestra cómo verificar si una columna está cubierta:

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 derivada 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 una columna se calculó 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 se puede usar una columna en el parámetro de búsqueda de segmentos.

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

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

Se agregó en la versión de la 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 informes principal 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 las métricas) pueden permanecer sin cambios durante períodos prolongados y es ineficiente la realización de solicitudes y actualizaciones innecesarias cuando se pueden usar datos almacenados en caché.

Si almacenas la ETag de una recopilación de columnas, se puede usar principalmente de 2 maneras: verificar si una respuesta de la API de metadatos en caché está actualizada y, también, incluirla como parte de una solicitud a la API de metadatos.

Verifica una respuesta almacenada en caché

Si comparas el valor de ETag que muestra una respuesta de la API de metadatos y es equivalente a la ETag para un recurso almacenado en caché, la versión almacenada en caché es actual. Si los ETag no son equivalentes, actualiza tu aplicación y actualiza la caché con la última respuesta.

Si deseas recuperar solo el valor ETag de la API de metadatos, configura el parámetro de búsqueda de fields como etag cuando realices una solicitud. Consulta un ejemplo.

Cómo usar una ETag con una solicitud de API

Si tienes una versión almacenada en caché de una colección de columnas, puedes incluir su valor ETag en una solicitud a la API de metadatos si configuras el campo del encabezado HTTP If-None-Match. La API de metadatos 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 tu versión almacenada en caché es actual.