API Metadata: guia do desenvolvedor

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 à API Analytics incluindo uma chave de API em cada solicitação.

Como receber e usar uma chave de API

Para adquirir uma chave de API:

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

      Observação:como essa API não tem nenhum método que exija autorização do OAuth 2.0, talvez seja necessário conseguir chaves de API, que sã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 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 diversos tipos de restrições em chaves de API. Se a chave de API de que você precisa ainda não existe, crie uma no Console clicando 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 proteger as chaves de API, siga as práticas recomendadas para usar as chaves de API com segurança.

Depois que você tiver uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=yourAPIKey a todos os URLs de solicitação.

A chave de API é segura para ser incorporada a URLs sem precisar 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 API Metadata inclui uma propriedade attributeNames que lista todos os atributos de colunas válidos. Cada coluna tem uma propriedade attributes que inclui um subconjunto de atributos aplicáveis à 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 uma coluna (ou seja, uma dimensão ou métrica) tiver sido descontinuada, seu atributo status será definido como DEPRECATED.

O snippet a seguir mostra como usar o atributo status para verificar se uma coluna foi descontinuada:

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

Se uma coluna for renomeada/removida, o atributo status vai ser definido como DEPRECATED e pode ter um atributo replacedBy definido como Id da coluna substituta.

O snippet a seguir mostra como usar o atributo replacedBy para conseguir o ID da coluna substituta:

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

Nomes de colunas

O atributo uiName é o nome da métrica ou dimensão usado 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 modelos terá atributos minTemplateIndex e maxTemplateIndex que definem o intervalo 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

O atributo allowedInSegments permite 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;
}

Adição à versão da API

Use o atributo addedInApiVersion para verificar se uma coluna pode ser usada em uma API de relatórios de uma versão especificada. Por exemplo, chame a seguinte função para verificar se a coluna pode ser usada na API Core Reporting 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ê quiser recuperar apenas o valor da ETag da API de metadados, defina o parâmetro de consulta fields como etag ao fazer uma solicitação. Veja um exemplo.

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

Se você tiver uma versão em cache de uma coleção de colunas, será possível incluir o valor da ETag em uma solicitação da API Metadata configurando o campo de cabeçalho HTTP If-None-Match. A API Metadata verificará o valor da ETag e responderá com uma versão atualizada do recurso e um status HTTP 200 OK ou uma resposta vazia com um status 304 Not Modified se a versão em cache estiver atual.