API de gerenciamento - guia do desenvolvedor de dimensões e métricas personalizadas

Este documento descreve como usar a API de gerenciamento para gerenciar dimensões e métricas personalizadas do Google Analytics para um usuário autorizado.

Introdução

Dimensões e métricas personalizadas na API de gerenciamento permitem que você crie, recupere, liste, atualize e corrija em dimensões e métricas personalizadas para uma propriedade do Google Analytics. Para saber mais sobre como dimensões e métricas personalizadas funcionam, consulte a referência dos recursos de dimensões e métricas personalizadas.

Os dois recursos a seguir na API de gerenciamento permitem automatizar o gerenciamento de dimensões e métricas personalizadas:

  1. O recurso de dimensões personalizadas, que representa todas as propriedades e configurações disponíveis para uma dimensão personalizada no Google Analytics.
  2. O recurso de métricas personalizadas, que representa todas as propriedades e configurações disponíveis para uma métrica personalizada no Google Analytics.

Pré-requisitos

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

  • 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 API de gerenciamento. Para criar o objeto de serviço:

  1. Registre seu aplicativo no Google Developers Console.
  2. Autorize o acesso aos dados do Google Analytics.
  3. Crie um objeto de serviço "Analytics".

Se você não tiver concluído essas etapas, pare e leia o Tutorial de apresentação da Google Analytics API. Esse guia orienta você nas etapas iniciais da criação de um aplicativo da Google Analytics API. Depois de concluí-lo, você saberá como acessar Google Analytics APIs para realizar tarefas reais.

Alterações de escopo e inconsistências de dados

Para saber mais, consulte a seção Considerações sobre a implementação da referência do recurso de dimensões e métricas personalizadas.

Casos de uso

As dimensões e métricas personalizadas na API de gerenciamento podem ser usadas para automatizar as tarefas a seguir.

Listagem de dimensões e métricas personalizadas para uma propriedade

Para listar todas as dimensões e métricas personalizadas para uma propriedade:

  1. Use a API de gerenciamento ou a interface do Explorador de contas para recuperar o ID da conta e o ID da propriedade.
  2. Execute o método list dos recursos de dimensão personalizada ou métrica personalizada.

Consulte a referência da API para ver detalhes sobre o método list dos recursos de dimensão personalizada e métrica personalizada.

Criação de dimensões e métricas personalizadas novas para uma propriedade

Para criar uma nova dimensão ou métrica personalizada para uma propriedade:

  1. Use a API de gerenciamento ou a interface do Explorador de contas para recuperar o ID da conta e o ID da propriedade.
  2. Para dimensões e métricas personalizados, você precisa fornecer name e scope. Para métricas personalizadas, você também precisa escolher a métrica type.
  3. Execute o método insert dos recursos de dimensão personalizada ou métrica personalizadas.

Consulte a referência da API para ver detalhes sobre o método insert dos recursos Dimensão personalizada e Métrica personalizada.

Atualização de dimensões e métricas personalizadas existentes para uma propriedade

Também é possível alterar a finalidade de uma dimensão ou métrica personalizada atualizando o nome, escopo ou tipo dela. No entanto, recomendamos que você primeiro avalie o efeito das alterações nas dimensões e métricas antes de fazer isso.

Para atualizar dimensão e métrica personalizadas existentes para uma propriedade:

  1. Use a API de gerenciamento ou a interface do Explorador de contas para recuperar o ID da conta e o ID da propriedade.
  2. Para dimensões e métricas personalizados, você precisa fornecer name e scope. Para métricas personalizadas, você também precisa definir a métrica type.
  3. Execute o método update dos recursos de dimensão personalizada ou métrica personalizada.

Se você tentar usar a API de gerenciamento para atualizar uma dimensão ou métrica personalizada que está sendo usada por um conjunto de dados / origem de dados personalizada, a operação não será bem-sucedida e retornará um erro. Esse comportamento destina-se a evitar alterações acidentais de escopo a dimensões ou métricas, que podem levar a inconsistências de dados. Para substituir esse comportamento e ignorar os avisos, você pode definir o parâmetro ignoreCustomDataSourceLinks como true ao executar uma operação de atualização.

Exemplos de códigos

Com os recursos de dimensão personalizada e de métrica personalizada, um usuário autorizado pode listar, recuperar, atualizar, corrigir e inserir dimensões e métricas personalizadas. Para usar qualquer um desses métodos, você primeiro precisa criar um objeto de serviço "Analytics", conforme descrito na seção Pré-requisitos.

Para ver exemplos de código que mostram como trabalhar com recursos de dimensão personalizada e métrica personalizada, acesse as referências de método a seguir:

Gerenciamento de dimensões personalizadas

  • list: lista dimensões personalizadas à quais o usuário tem acesso.
  • get: recupera uma dimensão personalizada à qual o usuário tem acesso.
  • insert: cria uma nova dimensão personalizada.
  • patch: corrige uma dimensão personalizada existente.
  • update: atualiza uma dimensão personalizada existente.

Gerenciamento de métricas personalizadas

  • list: lista métricas personalizadas às quais o usuário tem acesso.
  • get: recupera uma métrica personalizada à qual o usuário tem acesso.
  • insert: cria uma nova métrica personalizada.
  • patch: corrige uma métrica personalizada existente.
  • update: atualiza uma métrica personalizada existente.