Informes de acceso a los datos

Puedes crear informes de acceso a los datos con el método runAccessReport de la API de Admin v1. Este informe te muestra cada vez que un usuario lee datos de Google Analytics. Los registros de acceso a los datos se retienen durante un máximo de 2 años. Los informes de acceso a los datos solo están disponibles para los usuarios con el rol de Administrador.

Solicita un informe de acceso a los datos con la biblioteca cliente

La forma más rápida de comenzar a usar los informes de acceso a los datos es usar las bibliotecas cliente.

Consulta la guía de inicio rápido para obtener una explicación sobre cómo instalar y configurar las bibliotecas cliente de Google Analytics.

Este es un ejemplo en el que se usa la biblioteca cliente de Python que ejecuta una consulta de acceso a los datos y, luego, imprime la respuesta.

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

Funciones compartidas con los informes principales

Las solicitudes de informes de acceso a los datos tienen la misma semántica que las solicitudes de informes principales para muchas funciones comunes. Por ejemplo, la Paginación, los Filtros de dimensión y los Períodos se comportan de la misma manera en ambos tipos de informes.

Familiarízate con la descripción general de los informes principales en la API de datos v1 y, luego, vuelve a esta página para obtener más información sobre los informes de acceso a los datos.

Crea un informe de acceso a los datos

Usa el método runAccessReport para solicitar un informe de acceso a los datos.

Selecciona una entidad de informes

Al igual que la funcionalidad de informes principales de la API de datos v1, el método runAccessReport de la API de Google Analytics Admin v1 requiere que se especifique el identificador de propiedad de Google Analytics dentro de una ruta de solicitud de URL en forma de properties/GA_PROPERTY_ID, como la siguiente:

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

El informe de acceso a los datos resultante se genera en función de los registros de acceso a los datos de Google Analytics de la propiedad de Google Analytics especificada.

Si usas una de las bibliotecas cliente de la API de Admin, no es necesario manipular la ruta de acceso de la URL de la solicitud de forma manual. La mayoría de los clientes de la API proporcionan un parámetro property que espera una cadena en forma de properties/GA_PROPERTY_ID. Consulta el fragmento de código al comienzo de esta página para ver un ejemplo del uso de las bibliotecas cliente.

Elige dimensiones y métricas

Las dimensiones describen y agrupan los datos de acceso de tu propiedad. Por ejemplo, la dimensión userEmail indica el correo electrónico del usuario que accedió a los datos de informes. Los valores de dimensión en las respuestas de los informes son cadenas.

Las métricas representan las mediciones cuantitativas de un informe. La métrica accessCount muestra la cantidad total de registros de acceso a los datos.

Consulta el esquema de acceso a los datos para obtener una lista completa de los nombres de dimensiones y métricas disponibles en las solicitudes de informes de acceso a los datos.

Solicita el informe

Para solicitar informes de acceso a los datos, crea un objeto RunAccessReportRequest. Te recomendamos que comiences con estos parámetros de solicitud:

• Al menos una entrada válida en el campo períodos
• Al menos una entrada válida en el campo dimensions
• Si no usas la dimensión epochTimeMicros, al menos una entrada válida en el campo métricas para recibir datos cuantitativos para cada combinación de valores de dimensión en un informe

A continuación, se muestra una solicitud de ejemplo con los campos recomendados. Esta consulta generará una lista de los correos electrónicos de los usuarios, la última vez que accedieron a la propiedad especificada durante el período de los últimos 7 días y el recuento de accesos correspondiente.

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

Lee la respuesta

La respuesta del informe de acceso a los datos es principalmente un encabezado y filas. El encabezado consta de AccessDimensionHeaders y AccessMetricHeaders, que enumeran las columnas del informe.

Cada fila del informe de acceso consta de AccessDimensionValues y AccessMetricValues para las columnas del informe. El orden de las columnas es coherente en la solicitud, el encabezado y cada fila.

Esta es una respuesta de ejemplo para la solicitud de ejemplo 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
}

Filtra los registros de acceso

Usa el campo dimensionFilter del objeto RunAccessReportRequest para restringir la respuesta del informe a valores de dimensión específicos que coincidan con el filtro.

En el siguiente ejemplo, se genera un informe basado en registros de acceso a datos individuales, que filtra los registros de acceso de un solo usuario con el correo electrónico Alex@example.net. El informe contiene la hora de cada registro de acceso, el correo electrónico y la dirección IP del usuario.

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

Del mismo modo, el campo metricFilter del objeto RunAccessReportRequest se puede usar para restringir la respuesta del informe a valores de métricas específicos que coincidan con el filtro.

En el siguiente ejemplo, se genera un informe que contiene los correos electrónicos y los recuentos de acceso de todos los usuarios que accedieron a la propiedad especificada más de 100 veces.

{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "userEmail"
    }
  ],
  "metricFilter": {
    "accessFilter": {
      "numericFilter": {
        "operation": "GREATER_THAN",
        "value": {
          "int64Value": 100
        }
      },
      "fieldName": "accessCount"
    }
  },
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

Ejemplos de informes

Estos son algunos informes de muestra que puedes probar.

Acceso más reciente

El siguiente es un informe de acceso de muestra que se puede crear con runAccessReport:

Para generar este informe, consulta las dimensiones mostRecentAccessEpochTimeMicros y userEmail, y la métrica accessCount. El informe contiene una fila por cada usuario: la dimensión mostRecentAccessEpochTimeMicros agrega los registros de acceso a los datos de cada usuario que accede a la propiedad y muestra la hora del último acceso (en microsegundos Unix desde la época) para cada fila.

Desglose del acceso de los usuarios

Otro ejemplo de un informe útil es un desglose de los accesos de los usuarios por mecanismo de acceso (p.ej., interfaz de usuario de Google Analytics, API, etcétera).

Para generar este informe, consulta las dimensiones mostRecentAccessEpochTimeMicros, userEmail, accessMechanism y la métrica accessCount.

El informe contiene una fila por cada combinación de usuario o mecanismo de acceso. La dimensión mostRecentAccessEpochTimeMicros contiene la última vez que un usuario accedió a la propiedad con el mecanismo de acceso especificado.

Descripción general del acceso a la propiedad

Es posible generar un informe para una propiedad sin desglosar los datos por usuarios individuales. Por ejemplo, el siguiente informe indica la frecuencia con la que se accede a una propiedad con diferentes mecanismos de acceso:

Para generar este informe, consulta las dimensiones accessedPropertyId, accessedPropertyName, accessMechanism y la métrica accessCount.

El informe contiene una fila por cada combinación de ID de propiedad o mecanismo de acceso.

Acceso a datos individuales

Para generar un informe en el que cada fila se base en un registro de acceso a los datos individual, omíte la dimensión mostRecentAccessEpochTimeMicros de una consulta y, en su lugar, usa la dimensión epochTimeMicros. No es necesario consultar la métrica accessCount, ya que cada fila del informe contiene información sobre un solo caso de acceso a los datos.

El siguiente informe contiene información detallada sobre cada vez que un usuario accedió a la propiedad especificada.

Para generar este informe, consulta las dimensiones epochTimeMicros, userEmail, accessedPropertyId, accessedPropertyName, userIP, accessMechanism, costDataReturned y revenueDataReturned.