Genel bakış

Google Analytics Data API v1, pivot tablolar oluşturmanıza olanak tanır. Pivot Yükseltici tabloları yeniden düzenleyerek verileri görselleştiren bir veri özetleme aracıdır. verilerinizi bir veya daha çok grup üzerinde özetleyerek (döndürerek) tablodaki bilgileri seçin.

Örnek olarak aşağıdaki ham veri tablosunu ele alalım:

Ham veri tablosu

Bu verileri kullanarak bir pivot tablo oluşturmak mümkündür. tarayıcı bazında oturum verileri (ülke ve dil boyutları şu şekilde seçilmiştir: yeni bir grafik ekleyeceksiniz.

Özetlenmiş veri tablosu

Temel Raporlarda Paylaşılan Özellikler

Pivot raporlama istekleri, birçok ortak özellik. Örneğin, sayfalara ayırma, Boyut Filtreleri ve Kullanıcı Mülkler için Pivot Raporlar'da Temel Raporlar ile aynı şekilde davranın. Bu kılavuzu, pivot raporlama özelliklerine odaklanmaktadır. Çekirdek bölümü hakkında bilgi edinmek için Data API v1'in raporlama işlevi. Raporlamayla ilgili temel bilgiler kılavuzunu okuyun. ve ileri düzey kullanım alanları rehberini inceleyin.

Özet raporlama yöntemleri

Data API v1, aşağıdaki raporlama yöntemlerinde pivot işlevini destekler:

  • runPivotReport Bu yöntem Google Analytics etkinlik verilerinizin özelleştirilmiş bir pivot raporunu döndürür. Her biri Pivot, rapor yanıtındaki görünür boyut sütunlarını ve satırları açıklar.

  • batchRunPivotReports Bu runPivotReport yönteminin, veri oluşturmaya izin veren ve tek bir API çağrısı kullanarak birden fazla rapor oluşturabilirsiniz.

Rapor Eden Tüzel Kişi Seçme

Data API v1'in tüm yöntemleri için Google Analytics mülk tanımlayıcısı gerekir. properties/GA_PROPERTY_ID, örneğin:

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

Elde edilen rapor, Google Analytics etkinlik verilerini temel alarak oluşturulur toplanan verileri içerebilir.

Data API istemci kitaplıklarından birini kullanıyorsanız istek URL'sinin yolunu manuel olarak değiştirmeye gerek yoktur. Çoğu API istemcisi şu biçimde bir dize bekleyen bir property parametresi sağlayın: properties/GA_PROPERTY_ID. Hızlı başlangıç kılavuzunu inceleyin. istemci kitaplıklarını kullanıma ilişkin örneklere göz atın.

Özet Rapor İsteği

Pivot tabloyla istek oluşturmak için runPivotReport veya batchRunPivotReports yöntemidir.

Özetlenmiş veriler istemek için bir RunPivotReportRequest oluşturabilirsiniz nesnesini tanımlayın. Şu istek parametreleriyle başlamanızı öneririz:

  • dateRanges alanında geçerli bir giriş.
  • Boyutlar alanında en az bir geçerli giriş olmalıdır.
  • metrics alanında en az bir geçerli giriş olmalıdır.
  • Özetler alanında en az iki geçerli pivot girişi girişi olmalıdır.

Önerilen alanları içeren örnek bir isteği aşağıda bulabilirsiniz:

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

Pivotlar

İsteğin pivot alanında Pivot nesnelerini kullanın gövde için kullanabilirsiniz. Her Pivot, görünür boyutu açıklar sütun ve satırlar bulunur.

Data API v1, sınırın çarpımı olduğu sürece birden çok pivot işlemini destekler parametresinin değeri 100.000'i aşmamalıdır.

Aşağıda, rapor oluşturmak için pivots kullanımını gösteren bir snippet verilmiştir browser boyutu temel alınarak özetlenmiştir. sorgu işlemi için orderBys alanını sıralama, sınır ve Sayfalara ayırma işlemini uygulamak için offset alanlarını kullanın.

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

Boyutlar

Boyutlar, size ait etkinlik verilerini açıklar ve gruplandırır. web sitesi veya uygulama. Örneğin city boyutu, şehri ("Paris" olarak) belirtir. veya "New York") gösterilir. Rapor isteğinde şunları yapabilirsiniz: sıfır veya daha fazla boyut belirtin.

Boyutlar, reklamın boyutlar alanına girmelisiniz. Bu boyutların bir raporda görünür olması için ayrıca fieldNames alanında listelenmelidir Pivot nesnesinin alanı. Herhangi bir raporda kullanılmayan boyutlar raporda görünmez özetlemek için kullanılabilir. Bir pivot tabloda her boyutun mevcut olması gerekmez fieldNames Boyutlar yalnızca filtrelerde kullanılabilir, Herhangi bir özetin fieldNames.

Aşağıda, dimension ve fieldNames alanlarının kullanımını gösteren bir snippet bulunmaktadır. browser, country ve language pivotları içeren bir tablo için:

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

Metrikler

Metrikler, kullanıcılara ait etkinlik verilerinin nicel ölçümleridir. web siteniz veya uygulamanız. Bir rapor isteğinde, bir veya daha fazla metrik belirtebilirsiniz. API metrik adlarının tam listesi için API Metrikleri'ne bakın. belirli bir süre boyunca kullanılabilir.

Pivot rapor isteklerinde metrikler, metrics istek gövdesini ayarlayabilirsiniz. Bu yöntem, Temel Raporlama yöntemlerine benzer.

Aşağıdaki örnek, rapor:

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

Metrik toplamaları

metricAggregations yöntemini kullanma Toplam metriği hesaplamak için bir Pivot nesnesinin alanı değerlerini daha iyi anlayabilir.

Toplamalar yalnızca metricAggregations verisinin alanı bir istekte belirtilir.

Aşağıda, browser pivot boyutu:

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

Hesaplanan metrikler toplularda döndürülür RunPivotReportResponse'un nesnesini tanımlayın. Birleştirilmiş metrik satırları için dimensionValues alanı RESERVED_TOTAL, RESERVED_MAX veya RESERVED_MIN özel bir değerini içerir.

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

  }

Sayfalara ayırma

Temel Raporlama yöntemlerine benzer şekilde, pivot istekleri şunları yapmanıza olanak tanır: (sınırı belirtmek için) ve offset alanlarını kullanarak Sayfalara ayırma uygulamak için Pivot nesnesini seçin. Sayfalandırma ayarları her özete ayrı ayrı uygulanır. limitPivot rapor kardinalitesi:

Data API v1, limit ürününün ürünü olduğu sürece birden çok özeti destekler. parametresinin değeri 100.000'i aşmamalıdır.

Aşağıda, offset ve limit alanlarının aşağıdaki amaçlarla kullanımını gösteren bir snippet bulunmaktadır: sonraki beş language boyutunu 10 ofsetle alın:

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

Filtreleme

Temel Raporlama işlevine benzer şekilde istek kapsamlı boyut filtresi Pivot raporlamada boyut filtrelemesi isteniyorsa kullanılmalıdır. isteğinde bulunabilirsiniz.

Sıralama

Pivot rapor sorgularının sıralama davranışı, her pivot için kontrol edilebilir orderBys kullanılarak tek tek Pivot nesnesinin alanına ait OrderBy nesnelerinde geçerlidir.

Her OrderBy aşağıdakilerden birini içerebilir:

Bu örnekte, raporu özetleyen bir pivot tanım için bir snippet gösterilmektedir sonuçları sessions metriğine göre sıralayarak browser boyutunu azalan sırada.

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

Yanıtı Bildir

Bir özetin Pivot rapor Yanıtı rapor API isteği, birincil olarak bir başlık ve satırlardan oluşur.

Yanıt Başlıkları

Pivot rapor başlığı PivotHeaders'dan oluşur. DimensionHeaders ve MetricHeaders pivot raporumuz.

Örneğin browser, country ve language pivot boyutlarına sahip bir rapor ve sessions metriği şuna benzer başlıklar verir:

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

}

Aşağıdaki grafikte Pivot rapordaki her bileşenin rolü gösterilmektedir Pivot raporu oluşturma ile ilgili yanıt:

Ham veri tablosu

Yanıt Satırları

runPivotReport'un pivot rapor yanıtı ve batchRunPivotReports yöntemleri, Temel Raporlama yöntemlerine ilişkin bir yanıttan farklı runReport gibi ve batchRunReports Her bir pivot rapor yanıt satırı, özet akışına ait tek bir hücreyi tablosunda ise, normal raporlarda tek bir yanıt satırı tam bir yanıtı temsil eder. girin.

Aşağıda, browser, country ve language pivot boyutlarını ve sessions metriği. Pivot raporun her bir hücresi tek tek döndürülür:

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

  ]

Bu veriler, aşağıdaki tabloda vurgulanan iki hücreye karşılık gelir:

Ham veri tablosu

İstemci kitaplıkları

Bir açıklama için Hızlı başlangıç kılavuzuna bakın istemci kitaplıklarının nasıl yükleneceği ve yapılandırılacağı.

Aşağıdaki örneklerde bir pivot sorgu çalıştırmak için istemci kitaplığı kullanılmaktadır tarayıcı boyutuna göre özetlenen, ülkeye göre oturum sayıları raporu.

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

Demo uygulama

Google Analytics API v1 Özet Rapor Demosunu inceleyin uygulama .