Panoramica

La versione 1 dell'API di dati di Google Analytics consente di generare tabelle pivot. Pivot sono uno strumento di riepilogo dei dati che visualizzano i dati riorganizzando informazioni nella tabella ruotando i dati su uno o più dimensioni.

Considera ad esempio la seguente tabella di dati non elaborati:

Tabella di dati non elaborati

Usando questi dati è possibile creare una tabella pivot, suddividendo dati sulle sessioni per browser, con le dimensioni Paese e Lingua selezionate pivot aggiuntivi.

Tabella di dati pivot

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, impaginazione, filtri delle dimensioni e Le proprietà funzionano allo stesso modo dei report principali nei report pivot. Questo è incentrata sulle funzionalità di reporting pivot. Per acquisire familiarità con il Core Funzionalità di generazione di report dell'API di dati v1, leggi la guida alle nozioni di base sui report, nonché una guida ai casi d'uso avanzati.

Metodi di reporting pivot

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

  • runPivotReport Questo metodo restituisce un report pivot personalizzato dei dati sugli eventi di Google Analytics. Ciascuna la funzione pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.

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

Selezione di un'entità segnalante

Tutti i metodi dell'API di dati v1 richiedono l'identificatore proprietà Google Analytics all'interno di un percorso di richiesta dell'URL sotto forma di 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, è possibile non occorre manipolare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API fornisci un parametro property che prevede una stringa sotto forma di properties/GA_PROPERTY_ID. Consulta la Guida rapida per esempi di utilizzo delle librerie client.

Richiesta report pivot

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

Per richiedere dati sottoposti a pivot, puoi creare una richiesta RunPivotReportRequest . Ti consigliamo di iniziare con questi parametri di richiesta:

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

Ecco un esempio di richiesta con i campi consigliati:

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

Pivot

Utilizza gli oggetti Pivot nel campo pivot della richiesta per definire i pivot del report. Ogni Pivot descrive la dimensione visibile e righe e colonne nella risposta del report.

L'API di dati v1 supporta più pivot a condizione che il prodotto dell'attributo limit per ogni pivot non sia maggiore di 100.000.

Di seguito è riportato uno snippet che mostra l'utilizzo di pivots per creare un report di numero di sessioni per paese, in base alla dimensione browser. Nota come utilizza il campo orderBys per ordinamento, il limite e Campi offset per implementare la paginazione.

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

Dimensioni

Dimensioni che descrivono e raggruppano i dati sugli eventi per sito web o 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: non devono specificare più dimensioni.

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

Di seguito è riportato uno snippet che 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 sul tuo sito web o sulla tua app. In una richiesta di report, puoi specificare una o più metriche. Consulta la pagina Metriche API per un elenco completo dei nomi delle metriche API. che possono essere specificate nelle richieste.

Nelle richieste di report pivot, le metriche vengono definite utilizzando il campo metrics dell' corpo della richiesta, che è simile ai metodi di reporting principali.

Un esempio riportato di seguito specifica il conteggio delle sessioni da utilizzare come valore della metrica in una report:

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

Aggregazioni di metriche

Utilizzare metricAggregations campo di un oggetto Pivot per calcolare la metrica aggregata per ogni pivot.

Le aggregazioni verranno calcolate solo se la metrica metricAggregations viene specificato in una richiesta.

Di seguito è riportato uno snippet di una query che richiede i totali per browser dimensione pivot:

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

Le metriche calcolate vengono restituite nei aggregati. nel campo 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 principali per la generazione di report, le richieste pivot consentono per specificare il limite e offset nel Oggetto Pivot per implementare l'impaginazione. Le impostazioni di impaginazione vengono applicate singolarmente a ogni pivot. Il campo limit è obbligatorio per ogni oggetto Pivot al fine di limitare le segnala la cardinalità.

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

Di seguito è riportato uno snippet che mostra l'utilizzo dei campi offset e limit per recupera le successive cinque dimensioni language con un offset pari a 10:

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

Filtri

In modo simile alla funzionalità di reporting principale, una filtro dimensione con ambito a livello di richiesta deve essere utilizzato se si desidera applicare il filtro delle dimensioni in un report pivot richiesta.

Ordinamento

Il comportamento di ordinamento delle query dei report pivot può essere controllato per ogni pivot singolarmente utilizzando il comando orderBys campo di un oggetto Pivot, che contiene un elenco di 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 in pivot query e ordina i risultati in base ai valori di una metrica in un gruppo di colonne pivot.

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

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

Segnala risposta

La risposta al report pivot di un pivot è principalmente un'intestazione e delle righe.

Intestazioni della risposta

L'intestazione del report pivot è composta da PivotHeaders, DimensionHeaders e MetricHeaders che elencano le colonne in un report pivot.

Ad esempio, un report con dimensioni pivot browser, country e language e la metrica sessions restituirà intestazioni come queste:

{
  "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 grafico seguente illustra il ruolo di ogni componente del report pivot. Risposta nel rendering del report pivot:

Tabella di dati non elaborati

Righe di risposta

La risposta del report pivot di runPivotReport e batchRunPivotReports è diverso dalla risposta dei metodi principali di reporting come runReport e batchRunReports in quanto ogni riga di risposta del report pivot rappresenta una singola cella , mentre in un normale report una singola riga di risposta rappresenta una risposta dalla riga della tabella.

Di seguito è riportato un frammento di una risposta a un report pivot relativo a query con le dimensioni pivot browser, country e language e 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:

Tabella di dati non elaborati

Librerie client

Consulta la Guida rapida per una spiegazione delle come installare e configurare le librerie client.

I seguenti esempi utilizzano la libreria client per eseguire una query pivot al fine di creare un report sul conteggio delle sessioni per paese, in base alla dimensione browser.

PHP

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

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

  // 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

Applicazione demo

Vedi la demo del report pivot v1 dell'API Google Analytics applicazione per un esempio di come creare e visualizzare un report pivot utilizzando JavaScript.