Com a API Admin do Google Analytics v1, é possível gerar relatórios de acesso a dados usando o método runAccessReport
. O relatório fornece registros de cada vez que um usuário lê dados de relatório do Google Analytics. Os registros de acesso são mantidos por até dois anos.
Os relatórios de acesso a dados estão disponíveis apenas para usuários com função de administrador.
Como criar um relatório de acesso a dados
O relatório de acesso a dados é fornecido pelo método runAccessReport.
Recursos compartilhados com os relatórios principais
As solicitações de relatórios de acesso aos dados têm a mesma semântica das Solicitações de relatórios principais para muitos recursos compartilhados. Por exemplo, Paginação, Filtros de dimensão e Períodos se comportam da mesma maneira nos relatórios de acesso a dados e nos relatórios principais.
Conheça a visão geral da funcionalidade de relatórios principais da API Data v1, porque o restante deste documento se concentrará nos recursos específicos das solicitações de relatório de acesso a dados.
Como selecionar uma entidade denunciante
Semelhante à Principal funcionalidade de relatórios da API Data v1, o método runAccessReport da API Admin do Google Analytics v1 exige que o identificador de propriedade do Google Analytics 4 seja especificado em um caminho de solicitação de URL no formato properties/GA4_PROPERTY_ID
, como:
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
O relatório de acesso a dados resultante é gerado com base nos registros de acesso a dados do Google Analytics da propriedade especificada do GA4.
Se você estiver usando uma das bibliotecas de cliente da API Admin, não será necessário manipular manualmente o caminho do URL da solicitação. A maioria dos clientes de API fornece um parâmetro property
que deve ser preenchido com uma string no formato properties/GA4_PROPERTY_ID
. Consulte o snippet de código no fim deste guia para conferir um exemplo de como usar as bibliotecas de cliente.
Dimensões e métricas
As dimensões descrevem e agrupam dados de acesso à sua propriedade. Por exemplo, a dimensão
userEmail
indica o e-mail do usuário que acessou os dados do relatório.
Os valores de dimensão nas respostas do relatório são strings.
As métricas representam as medições quantitativas de um relatório. A métrica accessCount
retorna o número total de registros de acesso a dados.
Consulte o Esquema de acesso a dados para ver uma lista completa dos nomes de dimensões e métricas disponíveis nas solicitações de relatórios de acesso aos dados.
Solicitação de relatório de acesso a dados
Para solicitar relatórios de acesso a dados, crie um objeto RunAccessReportRequest. Recomendamos começar com estes parâmetros de solicitação:
- Pelo menos uma entrada válida no campo de períodos.
- Pelo menos uma entrada válida no campo dimensions.
- Se a dimensão
epochTimeMicros
não for usada, pelo menos uma entrada válida no campo metrics para receber dados quantitativos para cada combinação de valores de dimensão em um relatório.
Veja a seguir um exemplo de solicitação com os campos recomendados. Essa consulta vai gerar uma lista de e-mails dos usuários, a hora mais recente em que eles acessaram a propriedade especificada durante o intervalo dos últimos sete dias e a contagem de acesso correspondente.
HTTP
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "mostRecentAccessEpochTimeMicros"
},
{
"dimensionName": "userEmail"
}
],
"metrics": [
{
"metricName": "accessCount"
}
]
}
Denunciar resposta
Conceitualmente semelhante à Principal funcionalidade de relatórios da API Data v1, a Resposta do relatório de acesso a dados da solicitação de relatório de acesso é basicamente um cabeçalho e linhas. O cabeçalho consiste em
AccessDimensionHeaders
e
AccessMetricHeaders
,
que listam as colunas no relatório.
Cada linha do relatório de acesso consiste em AccessDimensionValues
e AccessMetricValues
para as colunas do relatório. A ordem das colunas é consistente
na solicitação, no cabeçalho e em cada linha.
Veja a seguir um exemplo de resposta para a solicitação de amostra anterior:
{
"dimensionHeaders": [
{
"dimensionName": "mostRecentAccessEpochTimeMicros"
},
{
"dimensionName": "userEmail"
}
],
"metricHeaders": [
{
"metricName": "accessCount"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "1667591408427733"
},
{
"value": "Bola@example.net"
}
],
"metricValues": [
{
"value": "1238"
}
]
},
{
"dimensionValues": [
{
"value": "1667710959827161"
},
{
"value": "Alex@example.net"
}
],
"metricValues": [
{
"value": "475"
}
]
},
{
"dimensionValues": [
{
"value": "1667868650762743"
},
{
"value": "Mahan@example.net"
}
],
"metricValues": [
{
"value": "96"
}
]
}
],
"rowCount": 3
}
Como filtrar registros de acesso
Use o campo dimensionFilter do objeto RunAccessReportRequest para restringir a resposta do relatório a valores de dimensão específicos que correspondem ao filtro.
O exemplo a seguir gera um relatório com base em registros de acesso a dados individuais, filtrando os registros de acesso de um único usuário com o e-mail Alex@example.net
. O relatório contém o horário de cada registro de acesso, o e-mail
e o endereço IP do usuário.
HTTP
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "epochTimeMicros"
},
{
"dimensionName": "userEmail"
},
{
"dimensionName": "userIP"
}
],
"dimensionFilter": {
"accessFilter": {
"fieldName": "userEmail",
"stringFilter": {
"matchType": "EXACT",
"value": "Alex@example.net"
}
}
}
}
Da mesma forma, o campo
metricFilter
do objeto
RunAccessReportRequest
pode ser usado para restringir a resposta do relatório a valores de métricas específicos que
correspondem ao filtro.
O exemplo a seguir gera um relatório com e-mails e contagens de acesso de todos os usuários que acessaram a propriedade especificada mais de 100 vezes.
HTTP
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "userEmail"
}
],
"metricFilter": {
"accessFilter": {
"numericFilter": {
"operation": "GREATER_THAN",
"value": {
"int64Value": 100
}
},
"fieldName": "accessCount"
}
},
"metrics": [
{
"metricName": "accessCount"
}
]
}
Relatórios de exemplo
Confira alguns exemplos de relatórios.
Relatório de acesso mais recente por usuário
Confira a seguir um exemplo de relatório de acesso que pode ser
criado usando runAccessReport
:
Micros de tempo de época de acesso mais recente | E-mail do usuário | Contagem de acessos |
---|---|---|
1525220215025371 | Bola@example.net | 5 |
1525220215028361 | Alex@example.net | 36 |
1525220215027671 | Charlie@example.net | 1153 |
1525220215027341 | Mahan@example.net | 1 |
Esse relatório pode ser gerado consultando as dimensões
mostRecentAccessEpochTimeMicros
, userEmail
e
a métrica accessCount
. O relatório contém uma linha por usuário: a dimensão mostRecentAccessEpochTimeMicros
agrega registros de acesso a dados para cada usuário que acessa a propriedade e retorna o último horário de acesso (em microssegundos Unix desde a época) para cada linha.
Relatório detalhado de acesso do usuário
Outro exemplo de relatório útil é um detalhamento dos acessos do usuário por mecanismo de acesso (por exemplo, interface do usuário do Google Analytics, API etc).
Micros de tempo de época de acesso mais recente | E-mail do usuário | Mecanismo de acesso | Contagem de acessos |
---|---|---|---|
1525220215028367 | Alex@example.net | Firebase | 31 |
1525220215555778 | Alex@example.net | Interface do usuário do Google Analytics | 1 |
1525220215022378 | Bola@example.net | Interface do usuário do Google Analytics | 65 |
1525220215026389 | Bola@example.net | Google Analytics API | 894 |
1525220215025631 | Charlie@example.net | Google Analytics API | 67 |
1525220215068325 | Mahan@example.net | Google Ads | 3 |
Esse relatório pode ser gerado consultando as dimensões
mostRecentAccessEpochTimeMicros
, userEmail
, accessMechanism
e
a métrica accessCount
.
O relatório contém uma linha para cada combinação de usuário/mecanismo de acesso. A dimensão mostRecentAccessEpochTimeMicros
contém a última vez que um usuário acessou a propriedade usando o Mecanismo de acesso especificado.
Relatório de visão geral do acesso à propriedade
É possível gerar um relatório para uma propriedade sem detalhar os usuários individuais. Por exemplo, o relatório a seguir indica com que frequência uma propriedade é acessada usando diferentes mecanismos de acesso:
ID da propriedade acessada | Nome da propriedade acessada | Mecanismo de acesso | Contagem de acessos |
---|---|---|---|
12345678 | DemoApp | Firebase | 31 |
12345678 | DemoApp | Interface do usuário do Google Analytics | 624 |
12345678 | DemoApp | Google Ads | 83 |
12345678 | DemoApp | Google Analytics API | 1744 |
Esse relatório pode ser gerado consultando as
dimensões accessedPropertyId
,
accessedPropertyName
, accessMechanism
e a
métrica accessCount
.
O relatório contém uma linha para cada combinação de ID da propriedade/mecanismo de acesso.
Relatório de acessos a dados individuais
Para gerar um relatório em que cada linha é baseada em um registro de acesso a dados
individuais, omita a dimensão mostRecentAccessEpochTimeMicros
de uma consulta e
use a dimensão epochTimeMicros
. Não é necessário consultar a métrica accessCount
, porque cada linha do relatório contém informações sobre uma única ocorrência de acesso a dados.
O relatório a seguir contém informações detalhadas sobre cada vez que um usuário acessou a propriedade especificada.
Micros de tempo de época | E-mail do usuário | ID da propriedade acessada | Nome da propriedade acessada | IP do usuário | Mecanismo de acesso | Dados de custo retornados | Dados de receita retornados |
---|---|---|---|---|---|---|---|
1525220215025371 | Bola@example.net | 12345678 | DemoApp | 1.2.3.1 | Interface do usuário do Google Analytics | verdadeiro | verdadeiro |
1525220645645645 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Interface do usuário do Google Analytics | false | false |
1525220211312322 | Bola@example.net | 12345678 | DemoApp | 11.22.33.11 | Google Ads | verdadeiro | false |
1525220210234221 | Alex@example.net | 12345678 | DemoApp | 11.22.33.22 | Firebase | false | false |
1525220215028368 | Alex@example.net | 12345678 | DemoApp | 1.2.3.2 | Google Ads | false | false |
1525220214234231 | Mahan@example.net | 12345678 | DemoApp | 11.22.33.55 | Google Ads | verdadeiro | verdadeiro |
1525220423423452 | Charlie@example.net | 12345678 | DemoApp | 1.2.3.3 | Google Analytics API | verdadeiro | false |
1525220132312333 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Google Ads | verdadeiro | verdadeiro |
Esse relatório pode ser gerado consultando as dimensões
epochTimeMicros
, userEmail
, accessedPropertyId
, accessedPropertyName
,
userIP
, accessMechanism
, costDataReturned
e revenueDataReturned
.
Bibliotecas de cliente
Consulte o Guia de início rápido para uma explicação sobre como instalar e configurar bibliotecas de cliente.
Este é um exemplo usando a biblioteca de cliente Python que executa uma consulta de acesso a dados e imprime a resposta.
Python
from datetime import datetime from google.analytics.admin import AnalyticsAdminServiceClient from google.analytics.admin_v1alpha.types import ( AccessDateRange, AccessDimension, AccessMetric, RunAccessReportRequest, ) 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" run_access_report(property_id) def run_access_report(property_id: str, transport: str = None): """ Runs an access report for a Google Analytics property. The report will aggregate over dimensions `userEmail`, `accessedPropertyId`, `reportType`, `revenueDataReturned`, `costDataReturned`, `userIP`, and return the access count, as well as the most recent access time for each combination. See https://developers.google.com/analytics/devguides/config/admin/v1/access-api-schema for the description of each field used in a data access report query. 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) request = RunAccessReportRequest( entity=f"properties/{property_id}", dimensions=[ AccessDimension(dimension_name="userEmail"), AccessDimension(dimension_name="accessedPropertyId"), AccessDimension(dimension_name="reportType"), AccessDimension(dimension_name="revenueDataReturned"), AccessDimension(dimension_name="costDataReturned"), AccessDimension(dimension_name="userIP"), AccessDimension(dimension_name="mostRecentAccessEpochTimeMicros"), ], metrics=[AccessMetric(metric_name="accessCount")], date_ranges=[AccessDateRange(start_date="yesterday", end_date="today")], ) access_report = client.run_access_report(request) print("Result:") print_access_report(access_report) def print_access_report(response): """Prints the access report.""" print(f"{response.row_count} rows received") for dimensionHeader in response.dimension_headers: print(f"Dimension header name: {dimensionHeader.dimension_name}") for metricHeader in response.metric_headers: print(f"Metric header name: {metricHeader.metric_name})") for rowIdx, row in enumerate(response.rows): print(f"\nRow {rowIdx}") for i, dimension_value in enumerate(row.dimension_values): dimension_name = response.dimension_headers[i].dimension_name if dimension_name.endswith("Micros"): # Convert microseconds since Unix Epoch to datetime object. dimension_value_formatted = datetime.utcfromtimestamp( int(dimension_value.value) / 1000000 ) else: dimension_value_formatted = dimension_value.value print(f"{dimension_name}: {dimension_value_formatted}") for i, metric_value in enumerate(row.metric_values): metric_name = response.metric_headers[i].metric_name print(f"{metric_name}: {metric_value.value}")