Relatórios de acesso a dados

É possível criar relatórios de acesso a dados usando o método runAccessReport da API Admin v1. Esse relatório mostra cada vez que um usuário lê dados do Google Analytics. Os registros de acesso aos dados são retidos por até 2 anos. Os relatórios de acesso aos dados só estão disponíveis para usuários com a função de Administrador.

Solicitar um relatório de acesso a dados usando a biblioteca de cliente

A maneira mais rápida de começar a usar os relatórios de acesso a dados é com as bibliotecas de cliente.

Consulte o Guia de início rápido para saber como instalar e configurar as bibliotecas de cliente do Google Analytics.

Veja um exemplo que usa a biblioteca de cliente do Python para executar uma consulta de acesso a dados e imprimir a resposta.

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

properties_run_access_report.py

Recursos compartilhados com relatórios principais

As solicitações de relatórios de acesso aos dados têm a mesma semântica que as solicitações de relatórios principais para muitos recursos comuns. Por exemplo, Paginação, Filtros de dimensão e Períodos se comportam da mesma forma nos dois tipos de relatório.

Familiarize-se com a visão geral dos relatórios principais na API Data v1 e volte a esta página para saber mais sobre os relatórios de acesso a dados.

Criar um relatório de acesso a dados

Use o método runAccessReport para solicitar um relatório de acesso aos dados.

Selecione uma entidade de relatório

Semelhante à funcionalidade de relatórios principais da API Data v1, o método runAccessReport da API Admin do Google Analytics v1 exige que o identificador da propriedade do Google Analytics seja especificado em um caminho de solicitação de URL no formato properties/GA_PROPERTY_ID, como:

  POST  https://analyticsadmin.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runAccessReport

O relatório de acesso aos dados resultante é gerado com base nos registros de acesso aos dados do Google Analytics para a propriedade do Google Analytics especificada.

Se você estiver usando uma das bibliotecas de cliente da API Admin, não será necessário manipular o caminho do URL da solicitação manualmente. A maioria dos clientes de API fornece um parâmetro property que deve ser preenchido com uma string no formato properties/GA_PROPERTY_ID. Consulte o snippet de código no início desta página para ver um exemplo de como usar as bibliotecas de cliente.

Escolher dimensões e métricas

As dimensões descrevem e agrupam os dados de acesso da 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 aos dados para ver uma lista completa de nomes de dimensões e métricas disponíveis nas solicitações de relatório de acesso aos dados.

Solicite o relatório

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 períodos.
• Pelo menos uma entrada válida no campo dimensions.
• Se você não usar a dimensão epochTimeMicros, pelo menos uma entrada válida no campo metrics para receber dados quantitativos de cada combinação de valores de dimensão em um relatório.

Confira um exemplo de solicitação com os campos recomendados. Essa consulta vai gerar uma lista de e-mails de usuários, o horário mais recente em que eles acessaram a propriedade especificada durante o período dos últimos 7 dias e a contagem de acessos correspondente.

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runAccessReport
{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "mostRecentAccessEpochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    }
  ],
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

Leia a resposta.

A resposta do relatório de acesso a dados é composta principalmente por 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 no relatório. A ordem das colunas é consistente na solicitação, no cabeçalho e em todas as linhas.

Veja um exemplo de resposta para o exemplo de solicitação 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
}

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 correspondam 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.

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_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.

{
  "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 que você pode testar.

Acesso mais recente

O exemplo de relatório de acesso a seguir pode ser criado usando runAccessReport:

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 dados agregados de acesso para cada usuário que acessa a propriedade e retorna o horário do último acesso (em microssegundos do Unix desde a época) para cada linha.

Detalhamento do acesso do usuário

Outro exemplo de relatório útil é um detalhamento dos acessos de usuários por mecanismo de acesso (por exemplo, interface do usuário do Google Analytics, API etc.).

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.

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:

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.

Acesso a dados individuais

Para gerar um relatório em que cada linha é baseada em um registro de acesso a dados individual, omita a dimensão mostRecentAccessEpochTimeMicros de uma consulta e use a dimensão epochTimeMicros. Não é necessário consultar a métrica accessCount, já que cada linha do relatório contém informações sobre uma única ocorrência de acesso aos dados.

O relatório a seguir contém informações detalhadas sobre cada vez que um usuário acessou a propriedade especificada.

Esse relatório pode ser gerado consultando as dimensões epochTimeMicros, userEmail, accessedPropertyId, accessedPropertyName, userIP, accessMechanism, costDataReturned, revenueDataReturned.