Panoramica

L'API Google Analytics Data v1 consente di generare tabelle pivot. Le tabelle pivot sono uno strumento di riepilogo dei dati che visualizza i dati riorganizzando le informazioni nella tabella ruotando i dati in una o più dimensioni.

Ad esempio, considera la seguente tabella di dati non elaborati:

Utilizzando questi dati, è possibile creare una tabella pivot, suddividendo i dati delle sessioni per browser, con le dimensioni paese e lingua selezionate come pivot aggiuntivi.

Funzionalità condivise con i report principali

Le richieste di report pivot hanno la stessa semantica delle richieste di report principali per molte funzionalità condivise. Ad esempio, l'impaginazione, i filtri delle dimensioni e le proprietà utente si comportano allo stesso modo nei report pivot e nei report principali. Questa guida si concentra sulle funzionalità di report pivot. Per familiarizzare con la funzionalità di report principali dell'API di dati v1, leggi la guida alle nozioni di base sui report, e la guida ai casi d'uso avanzati.

Metodi di report pivot

L'API di dati v1 supporta la funzionalità pivot nei seguenti metodi di report:

• runPivotReport Questo metodo restituisce un report pivot personalizzato contenente i dati sugli eventi di Google Analytics. Ogni pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.

• batchRunPivotReports Questa è una versione batch del metodo runPivotReport che consente di generare più report utilizzando una singola chiamata API.

Selezionare un'entità di report

Tutti i metodi dell'API di dati v1 richiedono che l' identificatore della proprietà Google Analytics sia specificato all'interno di un percorso della richiesta URL nel formato properties/GA_PROPERTY_ID, ad esempio:

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

Il report risultante verrà generato in base ai dati sugli eventi di Google Analytics raccolti nella proprietà Google Analytics specificata.

Se utilizzi una delle librerie client dell'API di dati, non è necessario manipolare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API fornisce un parametro property che prevede una stringa nel formato properties/GA_PROPERTY_ID. Per esempi di utilizzo delle librerie client, consulta la guida rapida.

Richiesta di report pivot

Per creare una richiesta con una tabella pivot, utilizza il metodo runPivotReport o il metodo batchRunPivotReports.

Per richiedere i dati pivot, puoi creare un oggetto RunPivotReportRequest. Ti consigliamo di iniziare con questi parametri della richiesta:

• Una voce valida nel campo dateRanges.
• Almeno una voce valida nel campo dimensions.
• Almeno una voce valida nel campo metrics.
• Almeno due voci pivot valide nel campo pivots.

Ecco una richiesta di esempio con i campi consigliati:

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

Pivot

Utilizza gli oggetti Pivot nel campo pivot del corpo della richiesta per definire i pivot dei report. Ogni Pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.

L'API di dati v1 supporta più pivot a condizione che il prodotto del parametro limit per ogni pivot non superi 100.000.

Il seguente snippet mostra l'utilizzo di pivots per creare un report dei conteggi delle sessioni per paese, con pivot in base alla dimensione browser. Tieni presente che la query utilizza il campo orderBys per l'ordinamento e i campi limit e offset per implementare l'impaginazione.

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

Dimensioni

Le dimensioni descrivono e raggruppano i dati sugli eventi per il tuo sito web o la tua app. La dimensione city, ad esempio, indica la città ("Parigi" o "New York") da cui ha avuto origine ogni evento. In una richiesta di report, puoi specificare zero o più dimensioni.

Le dimensioni devono essere definite all'interno del campo dimensions del corpo di una richiesta. Per essere visibili in un report, queste dimensioni devono anche essere elencate nel campo fieldNames di un oggetto Pivot. Una dimensione non sarà visibile in un report se non viene utilizzata in alcun pivot di una query pivot. Non tutte le dimensioni devono essere presenti in fieldNames di un pivot. Le dimensioni possono essere utilizzate esclusivamente nei filtri e non in fieldNames di alcun pivot.

Il seguente snippet mostra l'utilizzo dei campi dimension e fieldNames per una tabella con pivot browser, country e language:

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

Metriche

Le metriche sono misurazioni quantitative dei dati sugli eventi per il tuo sito web o la tua app. In una richiesta di report, puoi specificare una o più metriche. Per un elenco completo dei nomi delle metriche API che possono essere specificati nelle richieste, consulta Metriche API.

Nelle richieste di report pivot, le metriche vengono definite utilizzando il campo metrics del corpo della richiesta, in modo simile ai metodi di report principali.

L'esempio seguente specifica il conteggio delle sessioni da utilizzare come valore della metrica in un report:

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

Aggregazioni di metriche

Utilizza il campo metricAggregations di un oggetto Pivot per calcolare i valori delle metriche aggregate per ogni pivot.

Le aggregazioni verranno calcolate solo se il campo metricAggregations è specificato in una richiesta.

L'esempio seguente è uno snippet di una query che richiede i totali per la dimensione pivot browser:

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

Le metriche calcolate vengono restituite nel campo aggregates dell'oggetto RunPivotReportResponse. Per le righe delle metriche aggregate, il campo dimensionValues contiene un valore speciale di RESERVED_TOTAL, RESERVED_MAX o 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"
        }
      ]
    },
  ....

  }

Impaginazione

Analogamente ai metodi di report principali, le richieste pivot consentono di specificare i campi limit e offset nell'oggetto Pivot per implementare l'impaginazione. Le impostazioni di impaginazione vengono applicate a ogni pivot singolarmente. Il campo limit è obbligatorio per ogni oggetto Pivot per limitare la cardinalità del report.

L'API di dati v1 supporta più pivot a condizione che il prodotto del parametro limit per ogni pivot non superi 100.000.

Il seguente snippet mostra l'utilizzo dei campi offset e limit per recuperare le cinque dimensioni language successive con un offset di 10:

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

Filtri

Analogamente alla funzionalità di report principali, se vuoi filtrare le dimensioni in una richiesta di report pivot, devi utilizzare un filtro delle dimensioni con ambito di richiesta.

Ordinamento

Il comportamento di ordinamento delle query di report pivot può essere controllato per ogni pivot singolarmente utilizzando il campo orderBys di un oggetto Pivot, che contiene un elenco di oggetti OrderBy.

Ogni OrderBy può contenere uno dei seguenti elementi:

• DimensionOrderBy, ordina i risultati in base ai valori di una dimensione.
• MetricOrderBy, ordina i risultati in base ai valori di una metrica.
• PivotOrderBy, utilizzato nelle query pivot e ordina i risultati in base ai valori di una metrica all'interno di un gruppo di colonne pivot.

Questo esempio mostra uno snippet per una definizione pivot che ruota il report sulla dimensione browser, ordinando i risultati in base alla metrica sessions in ordine decrescente.

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

Risposta del report

La risposta del report pivot di una richiesta API di report pivot è costituita principalmente da un'intestazione e da righe.

Intestazioni della risposta

L'intestazione del report pivot è costituita da PivotHeaders, DimensionHeaders e MetricHeaders che elencano le colonne nel report pivot.

Ad esempio, un report con le dimensioni pivot browser, country e language e la metrica sessions genererà intestazioni come le seguenti:

{
  "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"
    }
  ],
  ...

}

Il seguente grafico illustra il ruolo di ogni componente della risposta del report pivot nel rendering del report pivot:

Righe della risposta

La risposta del report pivot dei metodi runPivotReport e batchRunPivotReports differisce da una risposta per i metodi di report principali come runReport e batchRunReports in quanto ogni riga di risposta del report pivot rappresenta una singola cella della tabella, mentre in un report normale una singola riga di risposta rappresenta una riga completa della tabella.

L'esempio seguente mostra un frammento di una risposta del report pivot per una query con le dimensioni pivot browser, country e language e la metrica sessions. Ogni cella del report pivot viene restituita singolarmente:

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

  ]

Questi dati corrispondono alle due celle evidenziate nella tabella seguente:

Librerie client

Per una spiegazione su come installare e configurare le librerie client, consulta la guida rapida.

Gli esempi seguenti utilizzano la libreria client per eseguire una query pivot per creare un report dei conteggi delle sessioni per paese, con pivot in base alla dimensione browser.

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()
        );
    }
}
run_pivot_report.php

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)

run_pivot_report.py

  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = 'YOUR-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: '2021-01-01',
          endDate: '2021-01-30',
        },
      ],
      pivots: [
        {
          fieldNames: ['country'],
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: 'country',
              },
            },
          ],
        },
        {
          fieldNames: ['browser'],
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: 'sessions',
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: 'sessions',
        },
      ],
      dimensions: [
        {
          name: 'country',
        },
        {
          name: 'browser',
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

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

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

Applicazione demo

Per un esempio di come creare e visualizzare un report pivot utilizzando JavaScript, consulta l'applicazione demo del report pivot dell'API di Google Analytics v1.