Creazione di un report

Questa è una guida per gli sviluppatori all'API Analytics Reporting v4. Per un riferimento dettagliato dell'API, consulta la documentazione di riferimento API.

Report

L'API Analytics Reporting v4 fornisce il metodo batchGet per accedere alla risorsa Reports. Le seguenti sezioni descrivono la struttura del corpo della richiesta per batchGet e la struttura del corpo della risposta da batchGet.

Corpo della richiesta

Per utilizzare l'API Analytics Reporting v4 per richiedere i dati, devi creare un oggetto ReportRequest, che abbia i seguenti requisiti minimi:

  • Un ID vista valido per il campo viewId.
  • Almeno una voce valida nel campo dateRanges.
  • Almeno una voce valida nel campo metrics.

Per trovare un ID vista, esegui una query sul metodo riepiloghi account o utilizza Esplora account. Se non viene specificato un intervallo di date, l'intervallo di date predefinito è: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Ecco un esempio di richiesta con i campi minimi obbligatori:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

Il metodo batchGet accetta un massimo di cinque oggetti ReportRequest. Tutte le richieste devono avere gli stessi valori di dateRange, viewId, segments, samplingLevel e cohortGroup.

Corpo della risposta

Il corpo della risposta della richiesta API è un array di oggetti Report. La struttura del report è definita nell'oggetto ColumnHeader che descrive le dimensioni, le metriche e i relativi tipi di dati nel report. I valori delle dimensioni e delle metriche sono specificati nel campo Dati.

Di seguito è riportato un esempio di risposta per la richiesta di esempio riportata sopra:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

Metriche

Le metriche sono misurazioni quantitative; ogni richiesta richiede almeno un oggetto Metric.

Nell'esempio seguente, la metrica Sessions viene fornita al metodo batchGet per ottenere il numero totale di sessioni nell'intervallo di date specificato:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

Puoi utilizzare Explorer dimensioni e metriche o l'API metadati per ottenere l'elenco delle dimensioni e delle metriche disponibili.

Applicazione dei filtri

Quando invii una richiesta batchGet, puoi chiedergli di restituire solo metriche che soddisfano criteri specifici. Per filtrare le metriche, nel corpo della richiesta specifica una o più MetricFilterClauses e in ogni MetricFilterClause definisci uno o più MetricFilters. In ogni MetricFilter, specifica i valori per gli elementi seguenti:

  • metricName
  • not
  • operator
  • comparisonValue

Consenti a {metricName} di rappresentare la metrica, {operator} di operator e {comparisonValue} di comparisonValue. A questo punto il filtro funziona nel seguente modo:

if {metricName} {operator} {comparisonValue}
   return the metric

Se specifichi true per not, il filtro funziona come segue:

if {metricName} {operator} {comparisonValue}
   do not return the metric

Nell'esempio seguente, batchGet restituisce solo le visualizzazioni di pagina il cui valore è maggiore di 2:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

Espressioni

Un'espressione di metrica è un'espressione matematica che definisci su metriche esistenti; funziona come metriche calcolate dinamiche. Puoi definire un alias per rappresentare l'espressione della metrica, ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

Ordine

Per ordinare i risultati in base a un valore di metrica:

  • Fornisci il nome o l'alias tramite il campo fieldName.
  • Specifica l'ordinamento (ASCENDING o DESCENDING) tramite il campo sortOrder.

Nell'esempio seguente, batchGet restituisce le metriche ordinate prima per sessioni e poi in base alle visualizzazioni di pagina in ordine decrescente:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

Dimensioni

Le dimensioni descrivono le caratteristiche degli utenti, delle sessioni e delle azioni eseguite. La dimensione Città, ad esempio, descrive una caratteristica delle sessioni e indica la città ("Parigi" o "New York") da cui ha avuto origine ogni sessione. In una richiesta batchGet, puoi specificare zero o più oggetti dimensione, ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

Applicazione dei filtri

Quando invii una richiesta batchGet, puoi chiederle di restituire solo le dimensioni che soddisfano criteri specifici. Per filtrare le dimensioni, nel corpo della richiesta, specifica una o più DimensionsFilterClauses e in ogni DimensionsFilterClause, definisci uno o più DimensionsFilters. In ogni DimensionsFilters, specifica i valori per gli elementi seguenti:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Consenti a {dimensionName} di rappresentare la dimensione, {operator} di operator e {expressions} di expressions. A questo punto il filtro funziona nel seguente modo:

if {dimensionName} {operator} {expressions}
    return the dimension

Se specifichi true per not, il filtro funziona come segue:

if {dimensionName} {operator} {expressions}
    do not return the dimension

Nell'esempio seguente, batchGet restituisce visualizzazioni di pagina e sessioni in un browser Chrome:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

Ordine

Per ordinare i risultati in base a un valore di dimensione:

  • Fornisci il nome tramite il campo fieldName.
  • Specifica l'ordinamento (ASCENDING o DESCENDING) mediante il campo sortOrder.

Ad esempio, batchGet restituisce le dimensioni ordinate per paese e poi per browser:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

Bucket a istogrammi

Per le dimensioni con valori interi, è più facile comprenderne le caratteristiche raggruppando i valori in intervalli. Utilizza il campo histogramBuckets per definire gli intervalli per i bucket risultanti e specificare HISTOGRAM_BUCKET come tipo di ordine, ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

Più intervalli di date

La versione 4 dell'API di reporting di Google Analytics ti consente di ottenere dati relativi a più intervalli di date in una singola richiesta. Indipendentemente dal fatto che la richiesta specifichi uno o due intervalli di date, i dati vengono restituiti nell'oggetto dateRangeValue, ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

Ordinazione delta

Se richiedi valori delle metriche in due intervalli di date, puoi ordinare i risultati in base alla differenza tra i valori della metrica negli intervalli di date, ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

Comportamento della dimensione Data

Se richiedi una dimensione relativa alla data o all'ora, l'oggetto DateRangeValue conserverà solo i valori per le date che rientrano nei rispettivi intervalli; tutti gli altri valori non compresi negli intervalli di date specificati saranno 0.

Ad esempio, considera una richiesta per la dimensione ga:date e la metrica ga:sessions in due intervalli di date: gennaio e febbraio. Nella risposta per i dati richiesti di gennaio, i valori di febbraio saranno 0; nella risposta per i dati richiesti di febbraio, i valori di gennaio saranno 0.

Report di gennaio

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

Report di febbraio

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

Segmenti

Per richiedere un sottoinsieme di dati di Analytics, utilizza i segmenti. Ad esempio, puoi definire gli utenti di un determinato paese o città in un segmento e gli utenti che visitano una parte specifica del tuo sito in un altro. I filtri restituiscono solo le righe che soddisfano una condizione, mentre i segmenti restituiscono un sottoinsieme di utenti, sessioni o eventi che soddisfano le condizioni contenenti i segmenti.

Quando effettui una richiesta con segmenti, assicurati che:

  • Ogni ReportRequest all'interno di un metodo batchGet deve contenere definizioni di segmenti identiche.
  • Aggiungi ga:segment all'elenco delle dimensioni.

Ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

Consulta Esempi per altri esempi di richieste con segmenti.

ID segmento

Utilizza il campo segmentId per richiedere segmenti. Non puoi utilizzare sia un segmentId che un dynamicSegment per richiedere segmenti.

Ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

Campionamento

Il campionamento può influire sui risultati dei dati ed è un motivo comune per cui i valori restituiti dall'API non corrispondono all'interfaccia web. Utilizza il campo samplingLevel per impostare la dimensione del campione desiderata.

  • Imposta il valore su SMALL per una risposta rapida con una dimensione di campionamento più piccola.
  • imposta il valore su LARGE per una risposta più precisa ma più lenta.
  • imposta il valore su DEFAULT per una risposta che bilancia velocità e precisione.

Ad esempio:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

Se un report contiene dati campionati, l'API Analytics Reporting v4 restituisce i campi samplesReadCounts e samplingSpaceSizes. Se i risultati non vengono campionati, questi campi non verranno definiti.

Di seguito è riportato un esempio di risposta contenente dati campionati di una richiesta con due intervalli di date. I risultati sono stati calcolati su quasi 500.000 campioni di una dimensione dello spazio di campionamento di circa 15 milioni di sessioni:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Impaginazione

L'API Analytics Reporting v4 utilizza i campi pageToken e pageSize per eseguire l'impaginazione dei risultati delle risposte su più pagine. Ricevi pageToken dal parametro nextPageToken nella risposta alla richiesta reports.batchGet:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

Passaggio successivo

Ora che hai esaminato le nozioni di base per la creazione di un report, dai un'occhiata alle funzionalità avanzate di API v4.