Informações gerais

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}")