Tworzenie raportu

To jest przewodnik dla programistów po interfejsie Analytics Reporting API w wersji 4. Więcej informacji o tym interfejsie API znajdziesz w jego dokumentacji.

Raporty

Interfejs Analytics Reporting API w wersji 4 udostępnia metodę batchGet, która umożliwia dostęp do zasobów Raporty. W kolejnych sekcjach opisano strukturę treści żądania batchGet oraz strukturę treści odpowiedzi z batchGet.

Treść żądania

Aby używać interfejsu Analytics Reporting API w wersji 4 do wysyłania żądań danych, musisz utworzyć obiekt ReportRequest, który spełnia te minimalne wymagania:

  • Prawidłowy identyfikator widoku dla pola viewId.
  • Co najmniej jeden prawidłowy wpis w polu dateRanges.
  • Co najmniej jeden prawidłowy wpis w polu metrics.

Aby znaleźć identyfikator widoku danych, wyślij zapytanie za pomocą metody podsumowań kont lub użyj eksploratora kont. Jeśli zakres dat nie jest podany, domyślny zakres dat to: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Oto przykładowe żądanie z minimalną liczbą wymaganych pól:

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

Metoda batchGet akceptuje maksymalnie 5 obiektów ReportRequest. Wszystkie żądania powinny mieć te same właściwości dateRange, viewId, segments, samplingLevel i cohortGroup.

Treść odpowiedzi

Treść odpowiedzi żądania do interfejsu API to tablica obiektów Report. Struktura raportu jest definiowana w obiekcie ColumnHeader, który opisuje wymiary i dane oraz ich typy danych w raporcie. Wartości wymiarów i danych są określone w polu dane.

Oto przykładowa odpowiedź na to przykładowe żądanie:

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

Wskaźniki

Dane to ilościowe pomiary. Każde żądanie wymaga co najmniej 1 obiektu Metric.

W tym przykładzie dane Sessions są dostarczane do metody batchGet, aby uzyskać łączną liczbę sesji w wybranym zakresie dat:

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

Aby uzyskać listę dostępnych wymiarów i danych, możesz użyć eksploratora wymiarów i danych lub interfejsu Metadata API.

Filtrowanie

Przesyłając żądanie batchGet, możesz poprosić o zwrócenie tylko tych danych, które spełniają określone kryteria. Aby filtrować wskaźniki, w treści żądania określ co najmniej 1 MetricFilterClauses, a w każdym elemencie MetricFilterClause zdefiniuj co najmniej 1 MetricFilters. W elemencie MetricFilter określ wartości tych parametrów:

  • metricName
  • not
  • operator
  • comparisonValue

Niech {metricName} reprezentuje dane, {operator} – operator, a {comparisonValue} – comparisonValue. Następnie filtr działa w następujący sposób:

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

Jeśli podasz true dla parametru not, filtr będzie działać w ten sposób:

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

W tym przykładzie funkcja batchGet zwraca tylko odsłony, których wartość jest większa niż 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"
          }]
      }]
  }]
}

Wyrażenia

Wyrażenie danych to wyrażenie matematyczne zdefiniowane przez Ciebie na podstawie istniejących danych. Działa ono jak dynamiczne obliczane dane. Możesz zdefiniować alias reprezentujący wyrażenie danych, na przykład:

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

Kolejność

Aby posortować wyniki według wartości danych:

  • Podaj jego nazwę lub alias w polu fieldName.
  • Określ kolejność sortowania (ASCENDING lub DESCENDING) w polu sortOrder.

W tym przykładzie funkcja batchGet zwraca dane posortowane najpierw według sesji, a potem według odsłon w kolejności malejącej:

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

Wymiary

Wymiary charakteryzują użytkowników oraz ich sesje i działania. Na przykład wymiar Miasto opisuje cechę sesji i wskazuje miasto („Paryż” lub „Nowy Jork”), z którego pochodzi każda sesja. W żądaniu batchGet możesz określić zero lub więcej obiektów wymiarów, np.:

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

Filtrowanie

Przesyłając żądanie batchGet, możesz poprosić o zwrócenie tylko tych wymiarów, które spełniają określone kryteria. Aby filtrować wymiary, w treści żądania określ co najmniej 1 DimensionsFilterClauses (klasyfikacji wymiarów), a w każdym elemencie DimensionsFilterClause zdefiniuj co najmniej 1 DimensionsFilters. W elemencie DimensionsFilters określ wartości tych parametrów:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Niech {dimensionName} reprezentuje wymiar, {operator} – operator, a {expressions} – expressions. Następnie filtr działa w następujący sposób:

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

Jeśli podasz true dla parametru not, filtr będzie działać w ten sposób:

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

W tym przykładzie batchGet zwraca wyświetlenia stron i sesje w przeglądarce 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"]
            }
          ]
        }
      ]
    }
  ]
}

Kolejność

Aby posortować wyniki według wartości wymiaru:

  • Podaj jego nazwę w polu fieldName.
  • W polu sortOrder określ kolejność sortowania (ASCENDING lub DESCENDING).

Na przykład funkcja batchGet zwraca wymiary posortowane według kraju, a następnie według przeglądarki:

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

Zasobniki histogramu

W przypadku wymiarów z wartościami całkowitymi łatwiej jest zrozumieć ich cechy, grupując wartości w zakresy. Użyj pola histogramBuckets, aby zdefiniować zakresy dla wynikowych zasobników i określ HISTOGRAM_BUCKET jako typ kolejności, np.:

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

Wiele zakresów dat

Interfejs Google Analytics Reporting API w wersji 4 umożliwia uzyskiwanie danych z wielu zakresów dat w jednym żądaniu. Niezależnie od tego, czy w żądaniu określono 1 czy 2 zakresy dat, dane są zwracane w obiekcie dateRangeValue, np.:

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

Kolejność delta

Gdy żądasz wartości danych w 2 zakresach dat, możesz posortować wyniki według różnicy między wartościami danych w zakresach dat, np.:

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

Zachowanie wymiaru daty

Jeśli poprosisz o wymiar związany z datą lub godziną, obiekt DateRangeValue będzie zawierał tylko wartości z dat należących do odpowiednich zakresów. Pozostałe wartości spoza określonych zakresów dat to 0.

Weźmy np. żądanie wymiaru ga:date i danych ga:sessions w 2 zakresach dat: w styczniu i lutym. W odpowiedzi na żądania danych w styczniu wartością z lutego będzie 0, a w odpowiedzi na dane z lutego – w styczniu – 0.

Raport za styczeń

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

Raport za luty

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

Segmenty

Aby poprosić o podzbiór danych Analytics, użyj segmentów. Możesz np. zdefiniować w jednym segmencie użytkowników z określonego kraju lub miasta, a użytkowników z określonej części Twojej witryny – w innym. Filtry zwracają tylko te wiersze, które spełniają warunek, a segmenty zwracają podzbiory użytkowników, sesji lub zdarzeń, które spełniają warunki zawierające te segmenty.

Jeśli wysyłasz żądanie obejmujące segmenty, upewnij się, że:

  • Każdy element ReportRequest w metodzie batchGet musi zawierać identyczne definicje segmentów.
  • Dodajesz do listy wymiarów wymiar ga:segment.

Na przykład:

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

Więcej przykładowych żądań z segmentami znajdziesz w sekcji Przykłady.

Identyfikator segmentu

Aby poprosić o segmenty, użyj pola segmentId. Do wysyłania żądań segmentów nie możesz używać jednocześnie protokołu segmentId i dynamicSegment.

Na przykład:

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

Próbkowanie

Próbkowanie może wpływać na wyniki danych i jest częstą przyczyną niezgodności wartości zwracanych przez interfejs API z interfejsem internetowym. W polu samplingLevel ustaw odpowiedni rozmiar próbki.

  • Aby uzyskać szybką odpowiedź z mniejszą próbką, ustaw wartość na SMALL.
  • ustaw wartość LARGE na uzyskanie dokładniejszej, ale wolniejszej odpowiedzi.
  • ustaw wartość DEFAULT, aby uzyskać odpowiedź równoważącą szybkość i dokładność.

Na przykład:

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

jeśli raport zawiera spróbkowane dane, interfejs Analytics Reporting API w wersji 4 zwraca pola samplesReadCounts i samplingSpaceSizes. Jeśli wyniki nie są spróbkowane, pola nie zostaną zdefiniowane.

Poniżej znajdziesz przykładową odpowiedź, która zawiera próbkowane dane z żądania z 2 zakresami dat. Wyniki zostały obliczone na podstawie prawie 500 tys. próbek z przestrzeni próbek o rozmiarze około 15 milionów sesji:

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

Podział na strony

Interfejs Analytics Reporting API w wersji 4 używa pól pageToken i pageSize do podziału na strony wyników odpowiedzi, które obejmują wiele stron. Otrzymasz pageToken z parametru nextPageToken w odpowiedzi na żądanie reports.batchGet:

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

Następny krok

Skoro znasz już podstawy tworzenia raportu, przyjrzyj się zaawansowanym funkcjom interfejsu API w wersji 4.