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:
- O recurso de dimensões personalizadas, que representa todas as propriedades e configurações disponíveis para uma dimensão personalizada no Google Analytics.
- 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:
- Registre seu aplicativo no Google Developers Console.
- Autorize o acesso aos dados do Google Analytics.
- 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
- Criação de dimensões e métricas personalizadas novas para uma propriedade
- Atualização de dimensões e métricas personalizadas existentes para uma propriedade
Listagem de dimensões e métricas personalizadas para uma propriedade
Para listar todas as dimensões e métricas personalizadas para uma propriedade:
- Use a API de gerenciamento ou a interface do Explorador de contas para recuperar o ID da conta e o ID da propriedade.
- 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:
- Use a API de gerenciamento ou a interface do Explorador de contas para recuperar o ID da conta e o ID da propriedade.
- Para dimensões e métricas personalizados, você precisa fornecer
name
escope
. Para métricas personalizadas, você também precisa escolher a métricatype
. - 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:
- Use a API de gerenciamento ou a interface do Explorador de contas para recuperar o ID da conta e o ID da propriedade.
- Para dimensões e métricas personalizados, você precisa fornecer
name
escope
. Para métricas personalizadas, você também precisa definir a métricatype
. - Execute o método
update
dos recursos de dimensão personalizada ou métrica personalizada.
Como iIgnorar links de conjunto de dados / origem de dados 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.