La API de Google Analytics Admin v1 te permite generar informes de acceso a los datos
con el método
runAccessReport
. El informe proporciona registros de cada vez que un usuario lee datos de informes de Google Analytics. Los registros de acceso se conservan por 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.
Cómo crear un informe de acceso a los datos
Los informes de acceso a los datos se proporcionan con el método runAccessReport.
Funciones compartidas con informes principales
Las solicitudes de informes de acceso a los datos tienen la misma semántica con las solicitudes de informes principales para muchas funciones compartidas. Por ejemplo, las especificaciones de Paginación, Filtros de dimensiones y Rangos de fechas se comportan de la misma manera en los informes de acceso a los datos que en los informes principales.
Familiarízate con la descripción general de la funcionalidad de informes principales de la versión 1 de la API de datos, ya que el resto de este documento se enfocará en las funciones específicas de las solicitudes de informes de acceso a los datos.
Selección de una entidad denunciante
Al igual que con la funcionalidad principal de informes
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 la propiedad Google Analytics 4
en una ruta de solicitud de URL en forma de
properties/GA4_PROPERTY_ID
, como en los siguientes ejemplos:
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
El informe de acceso a los datos resultante se generará en función de los registros de acceso a los datos de Google Analytics para la propiedad Google Analytics 4 especificada.
Si utilizas una de las bibliotecas cliente de la API de Admin, no es necesario manipular manualmente la ruta de URL de la solicitud. La mayoría de los clientes de la API proporcionan un parámetro property
que espera una cadena en forma de properties/GA4_PROPERTY_ID
. Consulta el fragmento de código al final de esta guía para ver un ejemplo del uso de las bibliotecas cliente.
Dimensiones y métricas
En Dimensiones, se 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 dimensiones en las respuestas del informe 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.
Solicitud de informe de acceso a los datos
Para solicitar informes de acceso a los datos, crea un objeto RunAccessReportRequest. Recomendamos comenzar 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
, debes tener al menos una entrada válida en el campo metrics para recibir datos cuantitativos de 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 correos electrónicos del usuario, la hora más reciente en la que accedió a la propiedad especificada durante el rango de los últimos 7 días y el recuento de acceso correspondiente.
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 respuesta
Conceptualmente, similar a la funcionalidad principal de informes de la versión 1 de la API de datos, la respuesta del informe de acceso a los datos de la solicitud del informe de acceso 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 todas las filas.
A continuación, se incluye una respuesta de muestra para la solicitud de muestra 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
}
Cómo filtrar los registros de acceso
Utiliza 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 y se filtran 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 del usuario y la dirección IP.
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"
}
}
}
}
De manera similar, el campo metricFilter
del objeto RunAccessReportRequest
se puede usar para restringir la respuesta del informe a valores de métrica 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 accesos de todos los usuarios que accedieron a la propiedad especificada más de 100 veces.
HTTP
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "userEmail"
}
],
"metricFilter": {
"accessFilter": {
"numericFilter": {
"operation": "GREATER_THAN",
"value": {
"int64Value": 100
}
},
"fieldName": "accessCount"
}
},
"metrics": [
{
"metricName": "accessCount"
}
]
}
Informes de ejemplo
Estos son algunos informes de muestra que puedes probar.
Informe del acceso más reciente por usuario
El siguiente informe de acceso de muestra que se puede crear con runAccessReport
:
Micros de tiempo del período de acceso más reciente | Correo electrónico del usuario | Recuento de accesos |
---|---|---|
1525220215025371 | Bola@example.net | 5 |
1525220215028361 | Alex@example.net | 36 |
1525220215027671 | Charlie@example.net | 1153 |
1525220215027341 | Mahan@example.net | 1 |
Este informe se puede generar consultando las dimensiones
mostRecentAccessEpochTimeMicros
, 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 el ciclo de entrenamiento) de cada fila.
Informe de desglose de acceso de los usuarios
Otro ejemplo de informe útil es un desglose de los accesos de usuario por mecanismo de acceso (p. ej., la interfaz de usuario de Google Analytics, la API, etc.).
Micros de tiempo del período de acceso más reciente | Correo electrónico del usuario | Mecanismo de acceso | Recuento de accesos |
---|---|---|---|
1525220215028367 | Alex@example.net | Firebase | 31 |
1525220215555778 | Alex@example.net | Interfaz de usuario de Google Analytics | 1 |
1525220215022378 | Bola@example.net | Interfaz de usuario de Google Analytics | 65 |
1525220215026389 | Bola@example.net | API de Google Analytics | 894 |
1525220215025631 | Charlie@example.net | API de Google Analytics | 67 |
1525220215068325 | Mahan@example.net | Google Ads | 3 |
Este informe se puede generar consultando las dimensiones
mostRecentAccessEpochTimeMicros
, userEmail
, accessMechanism
y la métrica accessCount
.
El informe contiene una fila por cada combinación de mecanismo de acceso y usuario. La dimensión mostRecentAccessEpochTimeMicros
contiene la última vez que un usuario accedió a la propiedad con el mecanismo de acceso especificado.
Informe de descripción general de acceso a la propiedad
Es posible generar un informe para una propiedad sin desglosar los usuarios individuales. Por ejemplo, el siguiente informe indica la frecuencia con la que se accede a una propiedad a través de diferentes mecanismos de acceso:
ID de la propiedad a la que se accedió | Nombre de la propiedad a la que se accedió | Mecanismo de acceso | Recuento de accesos |
---|---|---|---|
12345678 | DemoApp | Firebase | 31 |
12345678 | DemoApp | Interfaz de usuario de Google Analytics | 624 |
12345678 | DemoApp | Google Ads | 83 |
12345678 | DemoApp | API de Google Analytics | 1744 |
Este informe se puede generar consultando las dimensiones accessedPropertyId
, accessedPropertyName
, accessMechanism
y la métrica accessCount
.
El informe contiene una fila por cada combinación de ID de propiedad y mecanismo de acceso.
Informe de accesos a datos individuales
Para generar un informe en el que cada fila se base en un registro de acceso a datos individual, omite la dimensión mostRecentAccessEpochTimeMicros
de una consulta y 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.
Tiempo de época en micrómetros | Correo electrónico del usuario | ID de la propiedad a la que se accedió | Nombre de la propiedad a la que se accedió | IP del usuario | Mecanismo de acceso | Datos de costos mostrados | Datos de ingresos devueltos |
---|---|---|---|---|---|---|---|
1525220215025371 | Bola@example.net | 12345678 | DemoApp | 1.2.3.1 | Interfaz de usuario de Google Analytics | verdadero | verdadero |
1525220645645645 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Interfaz de usuario de Google Analytics | false | false |
1525220211312322 | Bola@example.net | 12345678 | DemoApp | 11.22.33.11 | Google Ads | verdadero | 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 | verdadero | verdadero |
1525220423423452 | Charlie@example.net | 12345678 | DemoApp | 1.2.3.3 | API de Google Analytics | verdadero | false |
1525220132312333 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Google Ads | verdadero | verdadero |
Este informe se puede generar consultando las dimensiones
epochTimeMicros
, userEmail
, accessedPropertyId
, accessedPropertyName
, userIP
, accessMechanism
, costDataReturned
y revenueDataReturned
.
Bibliotecas cliente
Consulta la Guía de inicio rápido para obtener una explicación sobre cómo instalar y configurar bibliotecas cliente.
A continuación, se muestra 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.
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}")