Os canais Alfa e Beta da API ainda têm suporte. O canal Beta contém um subconjunto dos recursos disponíveis na versão Alfa, que são considerados estáveis e não vão passar por uma mudança significativa no futuro. Novos recursos serão adicionados à versão Beta assim que estiverem consolidados.
Neste documento, mostramos como migrar o código existente da API Google Analytics Management v3 para a API Google Analytics Admin v1 e apresentamos uma visão geral das principais diferenças entre as duas APIs.
Por que preciso migrar?
Se for necessário criar ou configurar uma propriedade do Google Analytics 4 para seu aplicativo, você precisará usar a API Admin v1. A API Management v3 só funciona com as propriedades do Universal Analytics, e a API Admin v1, com as propriedades do Google Analytics 4.
Pré-requisitos
Para conhecer os princípios básicos da API Admin v1, leia o guia de início rápido.
Primeiros passos
Para começar, crie uma propriedade do Google Analytics 4, ative a API Admin v1 e configure uma biblioteca de cliente da API adequada para sua plataforma.
Criar uma propriedade do Google Analytics 4
Antes de migrar o código para que ele seja compatível com a API Admin v1, é necessário migrar seu site para usar uma propriedade do Google Analytics 4.
Ativar a API
Clique nesse botão para ativar automaticamente a API Admin v1 no projeto do Google Cloud selecionado.
Ativar a API Admin do Google AnalyticsUsar uma biblioteca de cliente
Instalar uma biblioteca de cliente
Se você usar uma biblioteca de cliente, precisará instalar a biblioteca da API Admin v1 para sua linguagem de programação.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/admin/v1alpha
Inicializar uma biblioteca de cliente
As bibliotecas de cliente da API Admin v1 ajudam você a começar rapidamente. Por padrão, elas tentam encontrar de forma automática as credenciais da sua conta de serviço.
Uma maneira fácil de recuperar as credenciais é definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. O cliente da API usará o valor dessa variável para encontrar o arquivo JSON da chave da conta de serviço.
Por exemplo, é possível definir essas credenciais executando o comando abaixo e usando o caminho para o arquivo JSON da conta de serviço:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Veja a seguir os snippets de código normalmente usados para inicializar as bibliotecas de cliente da API Admin v1.
Java
try (AnalyticsAdminServiceClient analyticsAdmin = AnalyticsAdminServiceClient.create()) {
Python
client = AlphaAnalyticsAdminClient()
.NET
AlphaAnalyticsAdminClient client = AlphaAnalyticsAdminClient.Create();
PHP
$client = new AlphaAnalyticsAdminClient();
Node.js
// Imports the Google Analytics Data API client library.
const {AlphaAnalyticsAdminClient} = require('@google-analytics/admin');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsAdminClient = new AlphaAnalyticsAdminClient();
Em vez de usar uma variável de ambiente, também é possível enviar as informações de credenciais para uma instância do cliente da API de forma explícita durante a inicialização.
Se você não usa uma biblioteca de cliente
Se você usa a API Management v3 sem uma biblioteca de cliente e quer fazer o mesmo com a API Admin v1, pode continuar utilizando suas credenciais.
É preciso usar o novo endpoint HTTP e o documento de descoberta que acompanham a API Admin:
Se o código usa um documento de descoberta, é necessário atualizá-lo para referenciar o documento da API Admin v1:
Depois de atualizar o endpoint, familiarize-se com a nova estrutura de solicitação e os conceitos da API Admin para atualizar sua consulta JSON.
Tarefas comuns
Gerenciar contas
A API Admin v1 oferece um conjunto de métodos de gerenciamento de contas e propriedades do Google Analytics semelhantes aos da API Management v3. Além disso, ela dispõe de novas funcionalidades para provisionar, excluir e atualizar contas do Google Analytics.
Os métodos de gerenciamento de propriedades da API Admin v1 só são compatíveis com propriedades do Google Analytics 4.
A noção de vistas (perfis) não existe na API Admin v1.
Como os fluxos de dados foram inseridos no Google Analytics 4, algumas informações não estão mais presentes no nível da propriedade. Por exemplo, o campo
websiteUrlagora está localizado na entidadeDataStreame não mais no objeto de propriedade.
Exibir resumos da conta
O método accountSummaries da API Admin retorna resumos de todas as contas acessíveis pelo autor da chamada, semelhante ao método accountSummaries da API Management v3.
Uma diferença importante é que a API Admin v1 retorna apenas informações sobre as propriedades do Google Analytics 4, enquanto as respostas da API Management v3 contêm dados sobre propriedades criadas com o Universal Analytics. Não é possível recuperar informações sobre os dois tipos de propriedade usando uma única chamada.
Como não há vistas (perfis) no Google Analytics 4, os resumos da conta retornados pela API Admin não contêm informações correspondentes.
Os dados de resumo da conta do Google Analytics 4 são limitados ao recurso e exibem os nomes das contas/propriedades disponíveis para o usuário atual.
Use os nomes de recursos retornados nos campos account e property da resposta de resumos para recuperar os dados de configuração completos chamando os métodos account.get e property.get.
Solicitação da API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries?key=[YOUR_API_KEY]
Resposta da API Admin v1
{
"accountSummaries": [
{
"name": "accountSummaries/XXXXXX",
"account": "accounts/XXXXXX",
"displayName": "Test",
"propertySummaries": [
{
"property": "properties/XXXXXX",
"displayName": "Test App"
}
]
},
...
}
Solicitação da API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accountSummaries?key=[YOUR_API_KEY]
Resposta da API Management v3
{
"kind": "analytics#accountSummaries",
"username": "XXXXXX",
"totalResults": 9,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX",
"kind": "analytics#accountSummary",
"name": "Test Account",
"webProperties": [
{
"kind": "analytics#webPropertySummary",
"id": "UA-XXXXXX",
"name": "Test Property",
"internalWebPropertyId": "XXXXXX",
"level": "STANDARD",
"websiteUrl": "XXXXXX",
"profiles": [
{
"kind": "analytics#profileSummary",
"id": "XXXXXX",
"name": "Test Profile",
"type": "WEB"
}
]
},
...
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
def list_account_summaries(transport: str = None) -> None:
"""
Prints summaries of all accounts accessible by the caller.
Args:
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_account_summaries()
print("Result:")
for account_summary in results:
print("-- Account --")
print(f"Resource name: {account_summary.name}")
print(f"Account name: {account_summary.account}")
print(f"Display name: {account_summary.display_name}")
print()
for property_summary in account_summary.property_summaries:
print("-- Property --")
print(f"Property resource name: {property_summary.property}")
print(f"Property display name: {property_summary.display_name}")
print()
Exibir contas
O método accounts.list da API Admin v1 retorna todas as contas acessíveis pelo autor da chamada, semelhante ao método accounts.list da API Management v3.
Solicitação da API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/accounts?key=[YOUR_API_KEY]
Resposta da API Admin v1
{
"accounts": [
{
"name": "accounts/XXXXXX",
"createTime": "2020-02-21T00:17:33.282Z",
"updateTime": "2021-01-07T02:47:57.386Z",
"displayName": "Test Account",
"regionCode": "US"
},
...
}
Solicitação da API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts?key=[YOUR_API_KEY]
Resposta da API Management v3
{
"kind": "analytics#accounts",
"username": "XXXXXX",
"totalResults": 9,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX",
"kind": "analytics#account",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "Test Account",
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"READ_AND_ANALYZE"
]
},
"created": "2020-02-21T00:17:33.282Z",
"updated": "2021-01-07T02:47:57.386Z",
"childLink": {
"type": "analytics#webproperties",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties"
}
},
...
}
A resposta da API Admin v1 não inclui informações sobre permissões efetivas do usuário nem o campo childLink que estava presente na API Management v3.
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from accounts_get import print_account
def list_accounts(transport: str = None):
"""
Lists the Google Analytics accounts available to the current user.
Args:
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_accounts()
print("Result:")
for account in results:
print_account(account)
Gerenciar propriedades
Exibir propriedades
O método properties.list da API Admin v1 retorna todas as propriedades do Google Analytics 4 acessíveis pelo autor da chamada, semelhantes ao método webproperties.list da API Management v3, que retorna todas as propriedades do Universal Analytics acessíveis.
Como o campo websiteUrl não está mais presente no nível da propriedade no Google Analytics 4, use properties.dataStreams/list para listar todos os fluxos de dados associados à propriedade e procure o campo defaultUri para recuperar o URL do site associado a um fluxo.
Observe o parâmetro filter no URL da solicitação properties.list. O valor do parâmetro contém uma expressão para filtrar os resultados da solicitação e pode ser usado para listar as propriedades associadas ao ID da conta do Google Analytics fornecido ou ao projeto vinculado do Firebase.
Solicitação da API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/properties?filter=parent:accounts/XXXXXX&key=[YOUR_API_KEY]
Resposta da API Admin v1
{
"properties": [
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2020-10-29T04:02:49.124Z",
"updateTime": "2020-10-29T04:02:49.124Z",
"displayName": "Test Property",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
},
...
}
Solicitação da API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]
Resposta da API Management v3
{
"kind": "analytics#webproperties",
"username": "XXXXXX",
"totalResults": 33,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "UA-XXXXXX-1",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test Account",
"websiteUrl": "XXXXXX",
"level": "PREMIUM",
"profileCount": 4,
"industryVertical": "HEALTH",
"defaultProfileId": "XXXXXX",
"dataRetentionTtl": "INDEFINITE",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"READ_AND_ANALYZE"
]
},
"created": "2020-02-21T00:28:47.287Z",
"updated": "2021-01-27T21:39:22.704Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/profiles"
}
},
...
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import ListPropertiesRequest
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
list_properties(account_id)
def list_properties(account_id: str, transport: str = None):
"""
Lists Google Analytics 4 properties under the specified parent account
that are available to the current user.
Args:
account_id(str): The Google Analytics account ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_properties(
ListPropertiesRequest(filter=f"parent:accounts/{account_id}", show_deleted=True)
)
print("Result:")
for property_ in results:
print(property_)
print()
Ver informações da propriedade
O método properties.get da API Admin v1 retorna as informações sobre uma propriedade do Google Analytics 4, semelhante ao método webproperties.get da API Management v3.
O método properties.get da API Admin é compatível apenas com propriedades do Google Analytics 4.
Solicitação da API Admin v1
GET https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?key=[YOUR_API_KEY]
Resposta da API Admin v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-04-30T21:32:49.804Z",
"updateTime": "2021-04-30T21:32:49.804Z",
"displayName": "Test Property",
"industryCategory": "FINANCE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Solicitação da API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]
Resposta da API Management v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test 2",
"websiteUrl": "YOUR-WEBSITE-URL",
"level": "STANDARD",
"profileCount": 0,
"industryVertical": "FINANCE",
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:41:39.219Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import IndustryCategory
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID (e.g. "123456") before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
get_property(property_id)
def get_property(property_id: str, transport: str = None):
"""
Retrieves the Google Analytics 4 property details.
Args:
property_id(str): The Google Analytics Property ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
property_ = client.get_property(name=f"properties/{property_id}")
print("Result:")
print_property(property_)
def print_property(property):
"""Prints the Google Analytics 4 property details."""
print(f"Resource name: {property.name}")
print(f"Parent: {property.parent}")
print(f"Display name: {property.display_name}")
print(f"Create time: {property.create_time}")
print(f"Update time: {property.update_time}")
# print(f"Delete time: {property.delete_time}")
# print(f"Expire time: {property.expire_time}")
if property.industry_category:
print(f"Industry category: {IndustryCategory(property.industry_category).name}")
print(f"Time zone: {property.time_zone}")
print(f"Currency code: {property.currency_code}")
Criar propriedade
O método properties.create da API Admin v1 cria uma nova propriedade do Google Analytics 4, semelhante ao método webproperties.insert da API Management v3.
Solicitação da API Admin v1
POST https://analyticsadmin.googleapis.com/v1beta/properties?key=[YOUR_API_KEY]
{
"displayName": "Test Property",
"industryCategory": "AUTOMOTIVE",
"currencyCode": "USD",
"timeZone": "America/Los_Angeles",
"parent": "accounts/XXXXXX"
}
Resposta da API Admin v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-05-20T09:16:08.458Z",
"updateTime": "2021-05-20T09:16:08.458Z",
"displayName": "Test Property",
"industryCategory": "AUTOMOTIVE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Solicitação da API Management v3
POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties?key=[YOUR_API_KEY]
{
"name": "Test",
"websiteUrl": "YOUR-WEBSITE-URL"
}
Resposta da API Management v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "Test",
"websiteUrl": "YOUR-WEBSITE-URL",
"level": "STANDARD",
"profileCount": 0,
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:35:51.985Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import Property
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
create_property(account_id)
def create_property(account_id: str, transport: str = None):
"""
Creates a Google Analytics 4 property.
Args:
account_id(str): The Google Analytics Account ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
property_ = client.create_property(
property=Property(
parent=f"accounts/{account_id}",
currency_code="USD",
display_name="Test property",
industry_category="OTHER",
time_zone="America/Los_Angeles",
)
)
print("Result:")
print(property_)
Atualizar/corrigir uma propriedade
O método properties.patch da API Admin v1 atualiza a configuração de uma propriedade do Google Analytics 4, semelhante ao método webproperties.patch da API Management v3.
Observe o parâmetro updateMask no URL da solicitação que contém a lista de campos separada por vírgulas a ser atualizada. Os campos que não estão nessa lista não serão atualizados. Se você usar uma biblioteca de cliente, o parâmetro update_mask estará disponível como parte da assinatura do método.
Solicitação da API Admin v1
PATCH https://analyticsadmin.googleapis.com/v1beta/properties/XXXXXX?updateMask=displayName,industryCategory&key=[YOUR_API_KEY]
{
"displayName": "New Property Name",
"industryCategory": "FINANCE"
}
Resposta da API Admin v1
{
"name": "properties/XXXXXX",
"parent": "accounts/XXXXXX",
"createTime": "2021-04-30T21:32:49.804Z",
"updateTime": "2021-05-20T09:25:14.810Z",
"displayName": "New Property Name",
"industryCategory": "FINANCE",
"timeZone": "America/Los_Angeles",
"currencyCode": "USD"
}
Solicitação da API Management v3
PATCH https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3?key=[YOUR_API_KEY]
{
"name": "New Property Name",
"industryVertical": "FINANCE"
}
Resposta da API Management v3
{
"id": "UA-XXXXXX-3",
"kind": "analytics#webproperty",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3",
"accountId": "XXXXXX",
"internalWebPropertyId": "XXXXXX",
"name": "New Property Name",
"websiteUrl": "XXXXXX",
"level": "STANDARD",
"profileCount": 0,
"industryVertical": "FINANCE",
"dataRetentionTtl": "MONTHS_26",
"dataRetentionResetOnNewActivity": true,
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
]
},
"created": "2021-05-20T05:35:51.985Z",
"updated": "2021-05-20T05:41:39.219Z",
"parentLink": {
"type": "analytics#account",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX"
},
"childLink": {
"type": "analytics#profiles",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-3/profiles"
}
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import Property
from google.protobuf.field_mask_pb2 import FieldMask
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics property ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID (e.g. "123456") before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
update_property(property_id)
def update_property(property_id: str, transport: str = None):
"""
Updates the Google Analytics 4 property.
Args:
property_id(str): The Google Analytics Property ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
# This call updates the display name, industry category and time zone of the
# property, as indicated by the value of the `update_mask` field.
# The property to update is specified in the `name` field of the `Property`
# instance.
property_ = client.update_property(
property=Property(
name=f"properties/{property_id}",
display_name="This is an updated test property",
industry_category="GAMES",
time_zone="America/New_York",
),
update_mask=FieldMask(paths=["display_name", "time_zone", "industry_category"]),
)
print("Result:")
print(property_)
Gerenciar usuários
No momento, a API Admin do Google Analytics implementa um modelo de permissões do usuário semelhante à API Management v3, mas com algumas diferenças.
- Você gerencia as permissões do usuário com a API Admin do Google Analytics usando os recursos da conta
AccessBindinge da propriedadeAccessBindingem vez dos recursosAccountUserLink,WebPropertyUserLinkeProfileUserLinkna API Management v3. - As vinculações de acesso à propriedade na API Admin do Google Analytics não incluem permissões implícitas ou herdadas de vinculações de acesso à conta. Na API Management v3, cada link do usuário continha uma coleção
permissions.effectiveque incluía permissões implícitas e herdadas.
Uma entidade AccessBinding contém um usuário (endereço de e-mail) e uma lista de papéis
concedidos a ele. Uma entidade AccessBinding pode ser criada, atualizada ou
excluída.
O mapeamento entre os nomes dos papéis da API Admin v1 e os nomes das permissões da API Management v3 é o seguinte:
| Papel da API Admin v1 | Nome da permissão da API Management v3 |
|---|---|
| DefaultRoles/viewer | READ_AND_ANALYZE |
| predictedRoles/analista | COLLABORATE |
| predefinidoPapéis/editor | EDITAR |
| predefinidoRoles/administrador | MANAGE_USERS |
Os papéis predefinedRoles/no-cost-data e predefinedRoles/no-revenue-data foram introduzidos na API Admin v1 e não têm mapeamento correspondente na API Management v3.
Este guia demonstra como gerenciar vinculações de acesso no nível da conta. Para gerenciar
vinculações de acesso no nível da propriedade, siga o mesmo processo, mas use os recursos e
métodos da propriedade
AccessBinding em vez do AccessBinding
da conta.
Listar vinculações de acesso à conta
O método accounts.accessBindings.list da API Admin v1 lista todas as vinculações de acesso em uma conta, semelhante ao método accountUserLinks.list da API Management v3.
Solicitação da API Admin v1
GET https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX
Resposta da API Admin v1
{
"accessBindings": [
{
"name": "accounts/XXXXXX/accessBindings/XXXXXX",
"user": "XXXXXX",
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
]
}
Solicitação da API Management v3
GET https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]
Resposta da API Management v3
{
"kind": "analytics#entityUserLinks",
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1000,
"items": [
{
"id": "XXXXXX:XXXXXX",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:XXXXXX",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "XXXXXX",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
]
}
Exemplo de código para chamar a API Admin usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
list_account_access_bindings(account_id)
def list_account_access_bindings(account_id: str, transport: str = None):
"""
Lists access bindings under the specified parent account.
Args:
account_id(str): The id of the account.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
results = client.list_access_bindings(parent=f"accounts/{account_id}")
print("Result:")
for access_binding in results:
print(access_binding)
print()
Atualizar as vinculações de acesso à conta
O método accounts.accessBindings.patch da API Admin v1 atualiza uma vinculação de acesso de uma conta, de maneira semelhante ao método accountUserLinks.update da API Management v3.
Solicitação da API Admin v1
PATCH https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings/XXXXXXXX
{
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Resposta da API Admin v1
{
"name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
"user": "USER-EMAIL",
"directRoles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Solicitação da API Management v3
PUT https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX%3A104236685715552897132?key=[YOUR_API_KEY]
{
"entity": {
"accountRef": {
"id": "XXXXXX"
}
},
"userRef": {
"email": "XXXXXX"
},
"permissions": {
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Resposta da API Management v3
{
"id": "XXXXXX:104236685715552897132",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:104236685715552897132",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "104236685715552897132",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import AccessBinding
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics property ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with your Google Analytics
# account access binding ID (e.g. "123456") before running the sample.
account_access_binding_id = "YOUR-ACCOUNT-ACCESS-BINDING-ID"
update_account_access_binding(account_id, account_access_binding_id)
def update_account_access_binding(
account_id: str, account_access_binding_id: str, transport: str = None
):
"""
Updates the account access binding.
Args:
account_id(str): The Google Analytics Account ID.
account_access_binding_id(str): Google Analytics account access binding ID.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
# This call updates the roles of the access binding. The access binding to
# update is specified in the `name` field of the `AccessBinding` instance.
access_binding = client.update_access_binding(
access_binding=AccessBinding(
name=f"accounts/{account_id}/accessBindings/{account_access_binding_id}",
roles=["predefinedRoles/collaborate"],
),
)
print("Result:")
print(access_binding)
Criar vinculações de acesso à conta
O método accounts.accessBindings.create da API Admin v1 cria uma vinculação de acesso em uma conta, semelhante ao método accountUserLinks.insert da API Management v3.
Solicitação da API Admin v1
POST https://analyticsadmin.googleapis.com/v1alpha/accounts/XXXXXX/accessBindings
{
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
],
"user": "USER-EMAIL"
}
Resposta da API Admin v1
{
"name": "accounts/XXXXXX/accessBindings/XXXXXXXX",
"user": "USER-EMAIL",
"roles": [
"predefinedRoles/editor",
"predefinedRoles/admin"
]
}
Solicitação da API Management v3
POST https://analytics.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks?key=[YOUR_API_KEY]
{
"entity": {
"accountRef": {
"id": "XXXXXX"
}
},
"userRef": {
"email": "XXXXXX"
},
"permissions": {
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Resposta da API Management v3
{
"id": "XXXXXX:114236685715552897132",
"kind": "analytics#entityUserLink",
"selfLink": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/entityUserLinks/XXXXXX:114236685715552897132",
"entity": {
"accountRef": {
"id": "XXXXXX",
"kind": "analytics#accountRef",
"href": "https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX",
"name": "This is a test account"
}
},
"userRef": {
"kind": "analytics#userRef",
"id": "114236685715552897132",
"email": "XXXXXX"
},
"permissions": {
"effective": [
"COLLABORATE",
"EDIT",
"MANAGE_USERS",
"READ_AND_ANALYZE"
],
"local": [
"EDIT",
"MANAGE_USERS"
]
}
}
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
AccessBinding,
CreateAccessBindingRequest,
)
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with an email address of the user to
# link. This user will be given access to your account after running the
# sample.
email_address = "TEST-EMAIL-ADDRESS"
create_account_access_binding(account_id, email_address)
def create_account_access_binding(
account_id: str, email_address: str, transport: str = None
):
"""
Creates a access binding for the account.
Args:
account_id(str): The Google Analytics Account ID.
email_address(str): Email address of the access binding user.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
access_binding = client.create_access_binding(
CreateAccessBindingRequest(
parent=f"accounts/{account_id}",
access_binding=AccessBinding(
user=email_address, roles=["predefinedRoles/read"]
),
)
)
print("Result:")
print(access_binding)
Agrupar chamadas
A API Admin v1 não aceita o agrupamento de várias chamadas da API Google Analytics que usam o tipo de conteúdo de várias partes/misto, ao contrário da API Management v3.
No entanto, o agrupamento é compatível de forma explícita no nível da API. Os seguintes métodos da API Admin v1 são compatíveis com a funcionalidade de lote:
Exemplo de código para chamar a API Admin v1 usando bibliotecas de cliente:
Python
from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
AccessBinding,
BatchCreateAccessBindingsRequest,
CreateAccessBindingRequest,
)
def run_sample():
"""Runs the sample."""
# !!! ATTENTION !!!
# Running this sample may change/delete your Google Analytics account
# configuration. Make sure to not use the Google Analytics account ID from
# your production environment below.
# TODO(developer): Replace this variable with your Google Analytics
# account ID (e.g. "123456") before running the sample.
account_id = "YOUR-GA-ACCOUNT-ID"
# TODO(developer): Replace this variable with an email address of the user to
# link. This user will be given access to your account after running the
# sample.
email_address = "TEST-EMAIL-ADDRESS"
batch_create_account_access_binding(account_id, email_address)
def batch_create_account_access_binding(
account_id: str, email_address: str, transport: str = None
):
"""
Creates a access binding for the account using a batch call.
Args:
account_id(str): The Google Analytics Account ID.
email_address(str): Email address of the access binding user.
transport(str): The transport to use. For example, "grpc"
or "rest". If set to None, a transport is chosen automatically.
"""
client = AnalyticsAdminServiceClient(transport=transport)
response = client.batch_create_access_bindings(
BatchCreateAccessBindingsRequest(
parent=f"accounts/{account_id}",
requests=[
CreateAccessBindingRequest(
access_binding=AccessBinding(
user=email_address,
roles=["predefinedRoles/read"],
)
)
],
)
)
print("Result:")
for access_binding in response.access_bindings:
print(access_binding)
print()
Mudanças na cota da API
A API Admin v1 aplica cotas menos restritivas do que a API Management v3.
- Por padrão, o número de solicitações para a API Admin v1 é limitado a 600 solicitações por minuto no caso de um projeto do GCP.
- No momento, não há um limite de cota diária para a quantidade de chamadas da API Admin v1 por projeto do GCP. Em teoria, o número máximo de solicitações por dia ainda é restrito à cota de solicitações por minuto.
- Removemos o limite separado para o número de operações de gravação por dia.