Présentation

L'API Google Analytics Admin version 1 vous permet d'accéder aux rapports à l'aide de le runAccessReport . Le rapport fournit un enregistrement chaque fois qu'un utilisateur consulte Google Analytics. des données de rapport. Les enregistrements d'accès sont conservés pendant deux ans maximum. Accès aux données Ils ne sont disponibles que pour les utilisateurs dotés du rôle Administrateur.

Créer un rapport sur l'accès aux données

Les rapports sur l'accès aux données sont fournis par runAccessReport.

Fonctionnalités partagées avec les rapports principaux

Les demandes de rapport sur l'accès aux données ont la même sémantique que celles du rapport principal de requête, pour de nombreuses fonctionnalités partagées. Exemple : La pagination, les filtres de dimension et la spécification des plages de dates se comportent de la même manière. dans les rapports sur l'accès aux données en tant que rapports principaux.

Familiarisez-vous avec la présentation des principales fonctionnalités de création de rapports Data API v1, comme le reste de ce document sur les fonctionnalités spécifiques aux demandes de rapport sur l'accès aux données.

Sélection d'une entité à l'origine du signalement

Semblable à l'atelier Création de rapports les fonctionnalités Data API v1, runAccessReport de l'API Google Analytics Admin version 1 nécessite l'API Google Analytics identifiant de propriété à spécifier à l'intérieur un chemin de requête d'URL au format properties/GA_PROPERTY_ID, tel que:

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

Le rapport obtenu sur l'accès aux données sera généré sur la base de l'API Google Analytics pour la propriété Google Analytics spécifiée.

Si vous utilisez l'une des bibliothèques clientes de l'API Admin, il n'est pas nécessaire de manipuler manuellement le chemin de l'URL de la requête. La plupart des clients API fournissez un paramètre property qui attend une chaîne au format suivant : properties/GA_PROPERTY_ID Consultez l'extrait de code à la page à la fin de ce guide pour obtenir un exemple d'utilisation des bibliothèques clientes.

Dimensions et statistiques

Dimensions décrire et regrouper les données d'accès à votre propriété. Par exemple, la dimension userEmail indique l'adresse e-mail de l'utilisateur qui a accédé aux données de rapport. Les valeurs des dimensions dans les réponses au rapport sont des chaînes.

Métriques représentent les mesures quantitatives d'un rapport. La métrique accessCount renvoie le nombre total d'enregistrements d'accès aux données.

Reportez-vous au schéma d'accès aux données pour obtenir la liste complète des dimensions et noms des métriques disponibles dans les demandes de rapport sur l'accès aux données.

Demande de rapport sur l'accès aux données

Pour demander des rapports sur l'accès aux données, créez un objet RunAccessReportRequest. Mer nous vous recommandons de commencer par les paramètres de requête suivants:

• Au moins une entrée valide pour la date plages .
• Au moins une entrée valide dans le champ dimensions .
• Si vous n'utilisez pas la dimension epochTimeMicros, au moins une entrée valide dans la métriques pour recevoir des données quantitatives pour chaque combinaison de valeurs de dimension dans un rapport.

Voici un exemple de requête avec les champs recommandés. Cette requête génère une Liste des adresses e-mail des utilisateurs, la date de leur dernier accès à la propriété spécifiée au cours des sept derniers jours, et le nombre d'accès correspondant.

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

Signaler la réponse

Semblable à l'argumentaire principal sur le plan conceptuel de Google de l'API Data v1, le rapport sur l'accès aux données Réponse de la demande de rapport d'accès est principalement un en-tête et des lignes. L'en-tête se compose de AccessDimensionHeaders et AccessMetricHeaders qui listent les colonnes du rapport.

Chaque accès au rapport ligne se compose des éléments suivants : AccessDimensionValues et AccessMetricValues pour les colonnes du rapport. L'ordre des colonnes est cohérent dans la requête, l'en-tête et chaque ligne.

Voici un exemple de réponse à l'exemple de requête précédent:

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

Filtrer sur les enregistrements d'accès

Utilisez les dimensionFilter du RunAccessReportRequest pour limiter la réponse du rapport à des valeurs de dimension spécifiques qui correspondent aux filtre.

L'exemple suivant génère un rapport basé sur l'accès individuel à des données les enregistrements d'accès d'un seul utilisateur avec une adresse e-mail Alex@example.net Le rapport indique l'heure de chaque enregistrement d'accès, l'heure l'adresse e-mail et l'adresse IP.

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

De même, le metricFilter du RunAccessReportRequest peut être utilisé pour limiter la réponse du rapport à des valeurs de métriques spécifiques, correspondent au filtre.

L'exemple suivant génère un rapport contenant les adresses e-mail et le nombre d'accès tous les utilisateurs ayant accédé à la propriété spécifiée plus de 100 fois.

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

Exemples de rapports

Voici quelques exemples de rapports que vous pouvez essayer.

Rapport sur les accès les plus récents par utilisateur

L'exemple de rapport d'accès suivant, qui peut être créé à l'aide de runAccessReport:

Ce rapport peut être généré en interrogeant dimensions mostRecentAccessEpochTimeMicros, userEmail et la métrique accessCount. La Le rapport contient une ligne par utilisateur: mostRecentAccessEpochTimeMicros. La dimension regroupe les enregistrements d'accès aux données pour chaque utilisateur accédant à la propriété et renvoie la date et l'heure du dernier accès (en microsecondes Unix depuis le epoch) pour chaque ligne.

Rapport de répartition des accès utilisateur

Autre exemple de rapport utile : la répartition des accès utilisateur par type d'accès Mécanisme (par exemple, interface utilisateur Google Analytics, API, etc.)

Ce rapport peut être généré en interrogeant dimensions mostRecentAccessEpochTimeMicros, userEmail, accessMechanism et le accessCount métrique.

Le rapport comporte une ligne pour chaque combinaison utilisateur/mécanisme d'accès. La La dimension mostRecentAccessEpochTimeMicros indique la dernière fois qu'un utilisateur a accédé à la propriété à l'aide du mécanisme d'accès spécifié.

Rapport "Vue d'ensemble des accès à la propriété"

Il est possible de générer un rapport pour une propriété sans détailler des utilisateurs individuels. Par exemple, le rapport suivant indique la fréquence à laquelle une propriété est accessible à l'aide de différents mécanismes d'accès:

Ce rapport peut être généré en interrogeant dimensions accessedPropertyId, accessedPropertyName, accessMechanism et le accessCount métrique.

Le rapport contient une ligne pour chaque combinaison ID de propriété/mécanisme d'accès.

Rapport sur les accès aux données individuelles

À générer un rapport dans lequel chaque ligne est basée sur un accès individuel aux données , omettez la dimension mostRecentAccessEpochTimeMicros d'une requête et utilisez plutôt la dimension epochTimeMicros. Il n'est pas nécessaire d'interroger accessCount, car chaque ligne du rapport contient des informations sur un une seule occurrence d'accès aux données.

Le rapport suivant contient des informations détaillées sur chaque fois qu'un utilisateur a accédé à la propriété spécifiée.

Ce rapport peut être généré en interrogeant dimensions epochTimeMicros, userEmail, accessedPropertyId, accessedPropertyName, userIP, accessMechanism costDataReturned et revenueDataReturned.

Bibliothèques clientes

Consultez le guide de démarrage rapide pour en savoir plus sur comment installer et configurer des bibliothèques clientes.

Voici un exemple utilisant la bibliothèque cliente Python qui exécute une requête d'accès aux données et affiche la réponse.

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