API Metadata: guia do desenvolvedor

Este documento explica conceitos importantes sobre como usar a Metadata API para acessar a lista e os atributos das colunas do Google Analytics.

Introdução

A Metadata API retorna a lista e os atributos das colunas (ou seja, dimensões e métricas) expostos nas APIs de relatórios do Google Analytics. Se você está começando a usar a API, leia a Visão geral da Metadata API para uma introdução sobre a Metadata API.

Antes de começar

Todas as Google Analytics APIs são acessadas de maneira semelhante. Antes de começar a usar a Metadata API:

  • Leia a página Bibliotecas cliente para ver uma lista completa de bibliotecas cliente específicas de linguagens de programação que funcionam com a API.
  • Leia o Guia de referência para saber mais sobre a interface da API e sobre como acessar dados sem uma biblioteca cliente.

Cada biblioteca cliente fornece um único objeto de serviço "analytics" para acessar todos os dados da Metadata API. Para criar o objeto de serviço para uso com a API de metadados, geralmente é necessário seguir estas etapas:

  1. Registre seu aplicativo no console de APIs do Google.
  2. Crie um objeto de serviço "Analytics" e defina a Chave da API.

Registro e chave da API

Seu aplicativo precisa se identificar toda vez que enviar uma solicitação à Google Analytics API incluindo uma Chave da API em cada solicitação.

Aquisição e uso de uma chave de API

Para adquirir uma chave de API:

  1. Abra a página Credenciais no Console da API.
  2. Essa API suporta dois tipos de credenciais. Crie as credenciais apropriadas para seu projeto:
    • OAuth 2.0: sempre que seu aplicativo solicitar dados privados de usuários, ele precisar enviar um token OAuth 2.0 junto com a solicitação. Primeiro, seu aplicativo envia um Client-ID e, possivelmente, uma chave secreta do cliente para conseguir um token. É possível gerar credenciais do OAuth 2.0 para aplicativos da Web, contas de serviço ou aplicativos instalados.

      Observação: como essa API não tem métodos que exigem autorização do OAuth 2.0, serão necessárias somente as chaves da API, que estão descritas abaixo. No entanto, se seu aplicativo chamar outras APIs que exigem autorização de usuário, as credenciais do OAuth 2.0 serão necessárias.

      Para mais informações, leia a documentação do OAuth 2.0.

    • Chaves de API: uma solicitação que não fornece um token do OAuth 2.0 precisa enviar uma chave de API. A chave identifica seu projeto e fornece acesso à API, à cota e aos relatórios.

      A API é compatível com vários tipos de restrições de chaves de API. Se a chave de API de que você precisa ainda não existe, crie uma no Console. Para fazer isso, clique em Criar credenciais > Chave de API. Para restringir a chave antes de usá-la na produção, clique em Restringir chave e selecione uma das Restrições.

Para manter suas chaves de API seguras, siga as práticas recomendadas.

Depois que você está com uma chave de API, seu aplicativo pode adicionar o parâmetro da consulta key=yourAPIKey a todos os URLs das solicitações.

É seguro incorporar a chave de API em URLs sem a necessidade de codificação.

Os snippets de código a seguir ilustram como definir a chave da API para várias 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 das colunas

A resposta da Metadata API inclui uma propriedade attributeNames que lista todos os atributos de coluna válidos. Cada coluna possui uma propriedade attributes que inclui um subconjunto de atributos que se aplicam à coluna.

A tabela a seguir é a lista completa dos atributos válidos:

Casos de uso

A Metadata API pode ser usada para solucionar os casos de uso a seguir:

Colunas suspensas

Se o uso de uma coluna (ou seja, uma dimensão ou métrica) for suspenso, o atributo status dela será definido como DEPRECATED.

O snippet a seguir mostra como usar o atributo status para identificar se o uso de uma coluna está suspenso:

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

Se uma coluna for renomeada/removida, o atributo status dela será definido como DEPRECATED, e um atributo replacedBy poderá ser definido como o Id da coluna substituta.

O snippet a seguir mostra como usar o atributo replacedBy para encontrar o ID da coluna substitua:

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

Nomes de colunas

O atributo uiName é o nome da dimensão ou métrica usada nas interfaces do usuário do Google Analytics (por exemplo, interface da Web).

O snippet a seguir mostra como recuperar o nome da interface do usuário de uma coluna:

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

Colunas em modelos

As colunas de modelo incluem dimensões ou métricas com um índice numérico. Por exemplo, ga:goalXXStarts, ga:dimensionXX, ga:metricXX etc. Uma coluna de modelo tem os atributos minTemplateIndex e maxTemplateIndex que definem a variação do índice.

O snippet a seguir mostra como verificar se uma coluna é de modelo:

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

O snippet a seguir mostra como recuperar uma lista de IDs válidos para uma coluna de modelo:

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

Colunas calculadas

Uma coluna derivada do cálculo de outras colunas terá um atributo calculation. Por exemplo, o cálculo de ga:percentNewSessions é ga:newSessions / ga:sessions.

O exemplo a seguir mostra como verificar se uma coluna é calculada e como recuperar o cálculo dela:

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

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

Colunas e segmentos

Com o atributo allowedInSegments, você pode verificar se uma coluna pode ser usada no parâmetro de consulta do segmento.

O exemplo a seguir mostra como determinar se uma coluna pode ser usada em segmentos:

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

Adicionado na versão da API

Use o atributo addedInApiVersion para verificar se é possível usar uma coluna na API de relatórios de uma versão específica. Por exemplo, chame a função a seguir para confirmar que é possível usar a coluna na Core Reporting API V3:

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

ETag

Uma ETag é incluída em todas as respostas da Metadata API. A ETag é um identificador que pode ser usado para armazenar em cache e atualizar respostas da Metadata API. Isso é importante porque os dados das colunas (ou seja, dimensões e métricas) podem permanecer inalterados por períodos longos, e isso é ineficiente para fazer solicitações e atualizações desnecessárias quando dados armazenados em cache puderem ser usados.

Se você armazenar a ETag de um conjunto de colunas, ela pode ser usada principalmente de duas formas: para verificar se uma resposta da Metadata API armazenada em cache está atualizada e para inclui-lo como parte de uma solicitação da Metadata API.

Verificação de uma resposta armazenada em cache

Se você comparar o valor da ETag retornado em uma resposta da Metadata API e o valor equivalente à ETag de um recurso armazenado em cache, a versão armazenada em cache é a atual. Se as ETags não forem equivalentes, atualize seu aplicativo e o armazenamento em cache com a resposta mais recente.

Se você quer recuperar somente o valor da ETag da API de metadados, defina os campos parâmetro da consulta como etag ao fazer uma solicitação. Veja um exemplo.

Uso de uma ETag com uma solicitação da API

Se você tem uma versão em cache de um conjunto de colunas, pode incluir o valor da ETag dele em uma solicitação da Metadata API definindo o campo de cabeçalho HTTP If-None-Match. A Metadata API verificará o valor da ETag e responderá com uma versão atualizada do recurso e um status HTTP 200 OK ou enviará uma resposta vazia com um status 304 Not Modified, se sua versão em cache for atual.