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 à 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 apropriadas para o 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 métodos que exigem autorização do OAuth 2.0, talvez seja necessário conseguir somente as chaves de 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 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. É possível restringir a chave antes de usá-la na produção clicando em Restringir chave e selecionando 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.

Observação: se seu aplicativo já autenticou e autorizou um usuário (por exemplo, com o uso do OAuth 2.0), qualquer solicitação que você fizer à API Metadata usando um objeto de serviço "Analytics" autorizado identificará automaticamente seu aplicativo. Nesse caso, você não precisa definir a chave de API.

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 de metadados inclui uma propriedade attributeNames que lista todos os atributos de coluna válidos. Cada coluna tem uma propriedade attributes que inclui um subconjunto de atributos aplicáveis.

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

** O uso do atributo appUiName foi descontinuado. Remova qualquer código que use o atributo appUiName e use apenas o atributo uiName. Consulte a política de descontinuação de dados para mais detalhes sobre a remoção de atributos.

Casos de uso

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

• Colunas descontinuadas
• Nomes de colunas
• Colunas em modelos
• Colunas calculadas
• Colunas e segmentos
• Versões da API
• ETags (link em inglês)

Colunas suspensas

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

Observação: seu aplicativo deve procurar e parar de usar colunas DEPRECATED nas consultas da API Reporting. Se uma coluna substituta estiver disponível, ela deve ser usada como alternativa. As colunas DEPRECATED serão removidas das APIs Reporting e Metadata quando o período de descontinuação terminar, e as consultas dessas colunas retornarão um erro.

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

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

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

O snippet a seguir mostra como usar o atributo replacedBy para receber o ID da coluna de substituição:

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

Nomes de colunas

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

O atributo appUiName foi descontinuado. Remova qualquer código que use o atributo appUiName e use apenas o atributo uiName. Consulte a política de descontinuação de dados para mais detalhes sobre a remoção de atributos.

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 terá os 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 que você verifique 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 função a seguir 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 somente o valor da ETag da API de metadados, defina o parâmetro de consulta fields como etag ao fazer uma solicitação. Confira um exemplo.

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

Se você tiver uma versão em cache de um conjunto de colunas, poderá incluir o valor da ETag em uma solicitação da Metadata API definindo o campo de cabeçalho HTTP If-None-Match. A API Metadata vai 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 for atual.

Observação: a biblioteca de cliente que você usa para fazer solicitações à Metadata API pode reconhecer e usar uma ETag ou oferecer suporte para isso. Consulte a documentação da biblioteca para confirmar se o suporte a ela está disponível.