Présentation

La version 1 de l'API Google Analytics Data vous permet de générer des tableaux croisés dynamiques. Tableau croisé dynamique tableaux sont un outil de synthèse des données qui visualise les données en réorganisant les les informations du tableau en croisant les données sur un ou plusieurs .

Prenons l'exemple de la table de données brutes suivante:

Table de données brutes

À l'aide de ces données, il est possible de créer un tableau croisé dynamique, en décomposant les les données de sessions par navigateur, avec les dimensions de pays et de langue sélectionnées en tant que pivots supplémentaires.

Tableau de données croisé dynamique

Fonctionnalités partagées avec les rapports principaux

Les demandes de rapports croisés dynamiques ont la même sémantique que les demandes de rapport principales pour de nombreuses fonctionnalités partagées. Exemples : "pagination", "Filtres de dimensions" et "Utilisateurs" Les propriétés se comportent de la même manière dans les rapports croisés que les rapports principaux. Ce se concentre sur les fonctionnalités de création de rapports croisés dynamiques. Pour vous familiariser avec le Noyau la fonctionnalité de création de rapports de l'API Data v1, consultez le guide de base sur la création de rapports ; ainsi que les cas d'utilisation avancés.

Méthodes de reporting croisés

Data API v1 prend en charge les fonctionnalités de tableau croisé dynamique dans les méthodes de création de rapports suivantes:

  • runPivotReport. Cette méthode renvoie un rapport croisé personnalisé contenant vos données d'événement Google Analytics. Chaque Le tableau croisé dynamique décrit les colonnes et les lignes des dimensions visibles dans la réponse du rapport.

  • batchRunPivotReports : est une version traitement par lot de la méthode runPivotReport qui permet de générer plusieurs rapports à l'aide d'un seul appel d'API.

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

Toutes les méthodes de la version 1 de l'API Data nécessitent l'identifiant de propriété Google Analytics. dans un chemin de requête d'URL sous la forme suivante : properties/GA_PROPERTY_ID, par exemple:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport

Le rapport obtenu sera généré en fonction des données d'événement Google Analytics collectées dans la propriété Google Analytics spécifiée.

Si vous utilisez l'une des bibliothèques clientes de l'API Data, 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 le guide de démarrage rapide. pour obtenir des exemples d'utilisation des bibliothèques clientes.

Demande de rapport croisé dynamique

Pour élaborer une demande à partir d'un tableau croisé dynamique, utilisez l'une des méthodes runPivotReport ou batchRunPivotReports .

Pour demander des données croisées dynamiques, vous pouvez créer une RunPivotReportRequest. . Nous vous recommandons de commencer par les paramètres de requête suivants:

  • Une entrée valide dans le champ dateRanges.
  • Au moins une entrée valide dans le champ dimensions.
  • Au moins une entrée valide dans le champ metrics.
  • Au moins deux entrées de tableaux croisés dynamiques valides dans le champ pivots

Voici un exemple de requête avec les champs recommandés:

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
  {
    "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
    "dimensions": [
        { "name": "browser" },
        { "name": "country" },
        { "name": "language" }
      ],
    "metrics": [{ "name": "sessions" }],
    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 15
      }
    ]
  }

Pivots

Utiliser des objets Pivot dans le champ pivot de la requête pour définir des rapports croisés. Chaque Pivot décrit la dimension visible de colonnes et de lignes dans la réponse du rapport.

La version 1 de l'API Data permet d'utiliser plusieurs tableaux croisés dynamiques si le produit de la limite de chaque tableau croisé dynamique ne dépasse pas 100 000.

Vous trouverez ci-dessous un extrait illustrant l'utilisation de pivots pour créer un rapport sur le nombre de sessions par pays, en fonction de la dimension browser. Notez que utilise le champ orderBys pour tri, et les limites et Champs offset pour implémenter la pagination.

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

Dimensions

Les dimensions décrivent et regroupent les données d'événement pour vos de votre site Web ou application. Par exemple, la dimension city indique la ville ("Paris" ou "New York") d'où provient l'événement. Dans une demande de rapport, vous pouvez spécifiez zéro, une ou plusieurs dimensions.

Les dimensions doivent être définies à l'intérieur des dimensions du corps d'une requête. Pour être visibles dans un rapport, ces dimensions doivent également être répertoriés dans le champ fieldNames ; d'un objet Pivot. Une dimension ne sera pas visible dans un rapport si elle n'est utilisée dans aucune le tableau croisé dynamique d'une requête de tableau croisé dynamique. Toutes les dimensions ne doivent pas être présentes dans le tableau croisé dynamique fieldNames Les dimensions ne peuvent être utilisées que dans les filtres et non dans les fieldNames de n'importe quel tableau croisé dynamique.

Vous trouverez ci-dessous un extrait illustrant l'utilisation des champs dimension et fieldNames Pour un tableau avec des tableaux croisés dynamiques browser, country et language:

    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 10
      }
    ],

Métriques

Les métriques sont des mesures quantitatives des données d'événements pour votre site Web ou votre application. Dans une demande de rapport, vous pouvez spécifier une ou plusieurs métriques. Consultez la page Métriques d'API pour obtenir la liste complète des noms de métriques d'API. pouvant être spécifiées dans les requêtes.

Dans les demandes de rapport de tableau croisé dynamique, les métriques sont définies à l'aide du champ metrics du corps de la requête. Il est semblable aux méthodes principales de création de rapports.

L'exemple ci-dessous indique le nombre de sessions à utiliser comme valeur de métrique dans un rapport:

    "metrics": [
      {
        "name": "sessions"
      }
    ],

Agrégations de métriques

Utiliser metricAggregations champ d'un objet Pivot pour calculer la métrique agrégée pour chaque tableau croisé dynamique.

Les agrégations ne seront calculées que si metricAggregations est spécifié dans une requête.

Vous trouverez ci-dessous un extrait d'une requête demandant les totaux pour browser dimension de tableau croisé dynamique:

"pivots": [
  {
    "fieldNames": [
      "browser"
    ],
    "limit": 10,
    "metricAggregations": [
      "TOTAL",
    ]
  },
  ...

Les métriques calculées sont renvoyées sous forme d'agrégations. de RunPivotReportResponse . Pour les lignes de métriques agrégées, le champ dimensionValues contient une valeur spéciale de RESERVED_TOTAL, RESERVED_MAX ou RESERVED_MIN.

  "aggregates": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6"
        }
      ]
    },
  ....

  }

Pagination

Tout comme les méthodes principales de création de rapports, les demandes de tableau croisé dynamique vous permettent pour spécifier la limite et offset dans le Pivot pour implémenter la pagination Les paramètres de pagination sont appliqués individuellement à chaque tableau croisé dynamique. Le champ limit est obligatoire pour chaque objet Pivot afin de limiter le la cardinalité des rapports.

La version 1 de l'API Data permet d'utiliser plusieurs tableaux croisés dynamiques si le produit de la limit de chaque tableau croisé dynamique ne dépasse pas 100 000.

Vous trouverez ci-dessous un extrait illustrant l'utilisation des champs offset et limit pour Récupérez les cinq dimensions language suivantes avec un décalage de 10:

      {
        "fieldNames": [
          "language"
        ],
        "offset": 10,
        "limit": 5
      }

Filtrage

À l'instar de la fonctionnalité principale de création de rapports, filtre de dimension avec portée de la requête doit être utilisé si vous souhaitez filtrer les dimensions dans un rapport croisé dynamique requête.

Tri

L'ordre des requêtes de rapport de tableau croisé dynamique peut être contrôlé pour chaque tableau croisé dynamique individuellement à l'aide de la commande orderBys d'un objet Pivot, qui contient une liste de OrderBy.

Chaque OrderBy peut contenir l'un des éléments suivants:

Cet exemple montre l'extrait d'une définition de tableau croisé dynamique utilisant le rapport sous forme de tableau croisé dynamique la dimension browser, en triant les résultats en fonction de la métrique sessions dans ordre décroissant.

      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }

Signaler la réponse

Réponse au rapport croisé dynamique d'un tableau croisé dynamique la requête API report est principalement un en-tête et des lignes.

En-têtes de réponse

L'en-tête d'un rapport croisé se compose des éléments PivotHeaders, DimensionHeaders et MetricHeaders, qui répertorient les colonnes des sous forme de tableau croisé dynamique.

Par exemple, un rapport avec les dimensions de tableau croisé dynamique browser, country et language et la métrique sessions générera des en-têtes comme ceux-ci:

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Chrome"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Firefox"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Canada"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "English"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "French"
            }
          ]
        },
        ...

      ],
      ...
    }
  ],
  "dimensionHeaders": [
    {
      "name": "browser"
    },
    {
      "name": "country"
    },
    {
      "name": "language"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  ...

}

Le graphique ci-dessous illustre le rôle de chaque composant du rapport croisé dynamique. Réponse lors de l'affichage du rapport croisé dynamique:

Table de données brutes

Lignes de réponse

Réponse de runPivotReport au rapport de tableau croisé dynamique et batchRunPivotReports diffère de la réponse obtenue pour les méthodes de création de rapports principales comme runReport et batchRunReports car chaque ligne de réponse d'un rapport croisé représente une seule cellule de la de données, alors que dans un rapport standard, une seule ligne de réponse représente ligne de tableau.

Vous trouverez ci-dessous un fragment de réponse à un rapport de tableau croisé dynamique pour une requête avec les dimensions de tableau croisé dynamique browser, country et language, et la Métrique sessions. Chaque cellule du rapport croisé est renvoyée individuellement:

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "United States"
        },
        {
          "value": "English"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "Canada"
        },
        {
          "value": "French"
        }
      ],
      "metricValues": [
        {
          "value": "3"
        }
      ]
    },
    ...

  ]

Ces données correspondent aux deux cellules mises en surbrillance dans le tableau ci-dessous:

Table de données brutes

Bibliothèques clientes

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

Les exemples suivants utilisent la bibliothèque cliente pour exécuter une requête de tableau croisé dynamique afin de créer une rapport du nombre de sessions par pays, en fonction de la dimension "Navigateur".

PHP

<ph type="x-smartling-placeholder"></ph> google-analytics-data/src/run_pivot_report.php
<ph type="x-smartling-placeholder"></ph> Ouvrir dans Cloud Shell Afficher sur GitHub
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;

/**
 * Runs a pivot query to build a report of session counts by country,
 * pivoted by the browser dimension.
 * @param string $propertyId Your GA-4 Property ID
 */
function run_pivot_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new BetaAnalyticsDataClient();

    // Make an API call.
    $request = (new RunPivotReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([new DateRange([
            'start_date' => '2021-01-01',
            'end_date' => '2021-01-30',
            ]),
        ])
        ->setPivots([
            new Pivot([
                'field_names' => ['country'],
                'limit' => 250,
                'order_bys' => [new OrderBy([
                    'dimension' => new DimensionOrderBy([
                        'dimension_name' => 'country',
                    ]),
                ])],
            ]),
            new Pivot([
                'field_names' => ['browser'],
                'offset' => 3,
                'limit' => 3,
                'order_bys' => [new OrderBy([
                    'metric' => new MetricOrderBy([
                        'metric_name' => 'sessions',
                    ]),
                    'desc' => true,
                ])],
            ]),
        ])
        ->setMetrics([new Metric(['name' => 'sessions'])])
        ->setDimensions([
            new Dimension(['name' => 'country']),
            new Dimension(['name' => 'browser']),
        ]);
    $response = $client->runPivotReport($request);

    printPivotReportResponse($response);
}

/**
 * Print results of a runPivotReport call.
 * @param RunPivotReportResponse $response
 */
function printPivotReportResponse(RunPivotReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;

    foreach ($response->getRows() as $row) {
        printf(
            '%s %s' . PHP_EOL,
            $row->getDimensionValues()[0]->getValue(),
            $row->getMetricValues()[0]->getValue()
        );
    }
}

Python

<ph type="x-smartling-placeholder"></ph> google-analytics-data/run_pivot_report.py
<ph type="x-smartling-placeholder"></ph> Ouvrir dans Cloud Shell Afficher sur GitHub
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    OrderBy,
    Pivot,
    RunPivotReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_pivot_report(property_id)


def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a pivot query to build a report of session counts by country,
    pivoted by the browser dimension."""
    client = BetaAnalyticsDataClient()

    request = RunPivotReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
        pivots=[
            Pivot(
                field_names=["country"],
                limit=250,
                order_bys=[
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name="country")
                    )
                ],
            ),
            Pivot(
                field_names=["browser"],
                offset=3,
                limit=3,
                order_bys=[
                    OrderBy(
                        metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
                    )
                ],
            ),
        ],
        metrics=[Metric(name="sessions")],
        dimensions=[Dimension(name="country"), Dimension(name="browser")],
    )
    response = client.run_pivot_report(request)
    print_run_pivot_report_response(response)


def print_run_pivot_report_response(response):
    """Prints results of a runPivotReport call."""
    print("Report result:")
    for row in response.rows:
        for dimension_value in row.dimension_values:
            print(dimension_value.value)

        for metric_value in row.metric_values:
            print(metric_value.value)


Node.js

<ph type="x-smartling-placeholder"></ph> google-analytics-data/run_pivot_report.js
<ph type="x-smartling-placeholder"></ph> Ouvrir dans Cloud Shell Afficher sur GitHub
  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = Y'OUR-GA4-PROPERTY-ID;'

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require(@'google-analytics/data)';

  // Initialize client that will be used to send requests. This client only
  // needs to be created once, and can be reused for multiple requests.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
  async function runPivotReport() {
    const [response] = await analyticsDataClient.runPivotReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: 2'021-01-01,'
          endDate: 2'021-01-30,'
        },
      ],
      pivots: [
        {
          fieldNames: [c'ountry]',
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: c'ountry,'
              },
            },
          ],
        },
        {
          fieldNames: [b'rowser]',
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: s'essions,'
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: s'essions,'
        },
      ],
      dimensions: [
        {
          name: c'ountry,'
        },
        {
          name: b'rowser,'
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log(R'eport result:)';
    response.rows.forEach(row = >{
      row.dimensionValues.forEach(dimensionValue = >{
        console.log(dimensionValue.value);
      });

      row.metricValues.forEach(metricValue = >{
        console.log(metricValue.value);
      });
    });
  }r

Application de démonstration

Voir la démonstration du rapport "Tableau croisé dynamique" de l'API Google Analytics v1 l'application pour voir un exemple de création et d'affichage d'un rapport de tableau croisé dynamique en utilisant JavaScript.