Rapor Oluşturma

Bu makale, Analytics Reporting API v4'e yönelik bir geliştirici kılavuzudur. API'nin ayrıntılı referansı için API Referansı'na bakın.

Raporlar

Analytics Reporting API v4, Raporlar kaynağına erişmek için batchGet yöntemini sağlar. Aşağıdaki bölümlerde batchGet için istek gövdesi'nin yapısı ve batchGet'den yanıt gövdesi'nin yapısı açıklanmaktadır.

İstek Metni

Veri isteğinde bulunmak için Analytics Reporting API v4'ü kullanmak istiyorsanız aşağıdaki minimum gereksinimleri karşılayan bir ReportRequest nesnesi oluşturmanız gerekir:

  • viewId alanı için geçerli bir görünüm kimliği.
  • dateRanges alanında en az bir geçerli giriş olmalıdır.
  • Metrikler alanında en az bir geçerli giriş olmalıdır.

Görünüm kimliğini bulmak için hesap özetleri yöntemini sorgulayın veya Hesap Gezgini'ni kullanın. Tarih aralığı sağlanmazsa varsayılan tarih aralığı: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Aşağıda, gerekli minimum alanların bulunduğu bir örnek istek verilmiştir:

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

batchGet yöntemi en fazla beş ReportRequest nesnesini kabul eder. Tüm istekler aynı dateRange, viewId, segments, samplingLevel ve ve cohortGroup değerine sahip olmalıdır.

Yanıt Metni

API isteğinin yanıt gövdesi, Report nesnelerinden oluşan bir dizidir. Rapor yapısı, rapordaki boyutları, metrikleri ve veri türlerini açıklayan ColumnHeader nesnesinde tanımlanır. Boyutların ve metriklerin değerleri data alanında belirtilir.

Yukarıdaki örnek istek için örnek bir yanıtı aşağıda bulabilirsiniz:

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

Metrikler

Metrikler nicel ölçümlerdir; her istek en az bir Metrik nesnesi gerektirir.

Aşağıdaki örnekte, belirtilen tarih aralığındaki toplam oturum sayısını elde etmek için batchGet yöntemine Sessions metriği sağlanır:

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

Kullanılabilir boyutların ve metriklerin listesini almak için boyutlar ve metrikler gezginini veya Meta Veri API'sini kullanabilirsiniz.

Filtreleme

batchGet isteği gönderirken yalnızca belirli ölçütleri karşılayan metriklerin döndürülmesini isteyebilirsiniz. Metrikleri filtrelemek için istek gövdesinde bir veya daha fazla MetricFiltreClauses belirtin ve her MetricFilterClause içinde bir veya daha fazla MetrikFiltre tanımlayın. Her MetricFilter için aşağıdakilerin değerlerini belirtin:

  • metricName
  • not
  • operator
  • comparisonValue

{metricName} metriğin {operator}, operator ve {comparisonValue} comparisonValue değerini temsil etmesini sağlayın. Filtre şu şekilde çalışır:

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

not için true etiketini belirtirseniz filtre şu şekilde çalışır:

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

Aşağıdaki örnekte batchGet yalnızca değeri 2'den büyük olan sayfa görüntülemelerini döndürür:

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

İfadeler

Metrik ifadesi, mevcut metriklerde tanımladığınız matematiksel ifadedir ve dinamik hesaplanmış metrikler gibi çalışır. Metrik ifadesini temsil edecek bir takma ad tanımlayabilirsiniz. Örneğin:

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

Sıralama

Sonuçları bir metrik değerine göre sıralamak için:

  • fieldName alanını kullanarak adını veya takma adını girin.
  • sortOrder alanını kullanarak sıralama ölçütünü (ASCENDING veya DESCENDING) belirtin.

Aşağıdaki örnekte batchGet, metrikleri önce oturumlara, sonra da azalan düzende sıralanmış olarak döndürür:

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

Boyutlar

Boyutlar kullanıcılarınızın özelliklerini, oturumlarını ve işlemlerini tanımlar. Örneğin, Şehir boyutu oturumların özelliğini tanımlar ve her bir oturumun çıkışlandığı şehri (''Paris' veya 'New York') belirtir. batchGet isteğinde, sıfır veya daha fazla boyut nesnesi belirtebilirsiniz. Örneğin:

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

Filtreleme

batchGet isteği gönderirken yalnızca belirli ölçütleri karşılayan boyutları döndürmesini isteyebilirsiniz. Boyutları filtrelemek için istek gövdesinde bir veya daha fazla BoyutlarFiltre Filtresi belirtin ve her DimensionsFilterClause için bir veya daha fazla BoyutlarFiltresi tanımlayın. Her DimensionsFilters için aşağıdakilerin değerlerini belirtin:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

{dimensionName} boyutunu, {operator} operator ve {expressions}, expressions değerini temsil edelim. Filtre şu şekilde çalışır:

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

not için true etiketini belirtirseniz filtre şu şekilde çalışır:

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

Aşağıdaki örnekte batchGet, Chrome tarayıcıda sayfa görüntüleme ve oturum sayısını döndürür:

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

Sıralama

Sonuçları bir boyut değerine göre sıralamak için:

  • Parametre adını fieldName alanı aracılığıyla girin.
  • sortOrder alanını kullanarak sıralama ölçütünü (ASCENDING veya DESCENDING) belirtin.

Örneğin aşağıdaki batchGet, ülkeye ve ardından tarayıcıya göre boyutları döndürür:

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

Histogram paketleri

Tam sayı değerlerine sahip boyutlar için değerlerini aralıklara ayırarak özelliklerini anlamak daha kolaydır. Sonuçta oluşan paketlerin aralıklarını tanımlamak için histogramBuckets alanını kullanın ve sipariş türü olarak HISTOGRAM_BUCKET değerini belirtin. Örneğin:

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

Birden Fazla Tarih Aralığı

Google Analytics Reporting API v4, tek bir istekte birden fazla tarih aralığındaki verileri almanıza olanak tanır. İsteğiniz bir veya iki tarih aralığı belirtirse veriler dateRangeValue nesnesinde döndürülür. Örneğin:

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

Delta siparişi

İki tarih aralığında metrik değeri isteğinde bulunurken sonuçları tarih aralıklarındaki metrik değerleri arasındaki farka göre sıralayabilirsiniz. Örneğin:

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

Tarih boyutu davranışı

Tarih veya saat ile ilgili bir boyut isterseniz DateRangeValue nesnesi yalnızca ilgili aralıklara denk gelen tarihlere ait değerleri içerir. Belirtilen tarih aralıklarında olmayan diğer tüm değerler 0 olur.

Örneğin, iki boyut aralığında ga:date boyutu ve ga:sessions metriği için bir istek düşünün: Ocak ve Şubat. Ocak ayında istenen verilere verilen yanıtta, Şubat ayında değerler 0 olacak ve Şubat ayında istenen verilere verilen yanıtta Ocak ayında değerler 0 olacaktır.

Ocak raporu

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

Şubat raporu

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

Segmentler

Analytics verilerinizin bir alt kümesini istemek için segmentleri kullanın. Örneğin, belirli bir ülkedeki veya şehirdeki kullanıcıları bir segmentte, sitenizin belirli bir bölümünü başka bir bölümde ziyaret eden kullanıcıları tanımlayabilirsiniz. Filtreler yalnızca bir koşulu karşılayan satırları döndürür. Segmentler ise segmentleri içeren koşulları karşılayan kullanıcıların, oturumların veya etkinliklerin bir alt kümesini döndürür.

Segmentlerle istekte bulunurken aşağıdakilerden emin olun:

  • Bir batchGet yöntemindeki her ReportRequest, aynı segment tanımlarını içermelidir.
  • Boyut listesine ga:segment eklersiniz.

Örneğin:

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

Segmentlerle daha fazla örnek istek için Örnekler konusuna bakın.

Segment kimliği

Segment istemek için segmentId alanını kullanın. Segment istemek için hem segmentId hem de dynamicSegment kullanamazsınız.

Örneğin:

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

Örnekleme

Örnekleme, verilerinizin sonuçlarını etkileyebilir ve API'den döndürülen değerlerin web arayüzüyle eşleşmemesinin yaygın bir nedenidir. İstediğiniz örnek boyutunu ayarlamak için samplingLevel alanını kullanın.

  • Daha küçük bir örnekleme boyutuyla hızlı yanıt almak için değeri SMALL olarak ayarlayın.
  • Daha doğru ancak daha yavaş yanıt için değeri LARGE olarak ayarlayın.
  • Hız ile doğruluğu dengeleyen bir yanıt için değeri DEFAULT olarak ayarlayın.

Örneğin:

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

Bir rapor, örneklenmiş veriler içeriyorsa Analytics Reporting API v4, samplesReadCounts ve samplingSpaceSizes alanlarını döndürür. Sonuçlar örneklenmezse bu alanlar tanımlanmaz.

Aşağıda, iki tarih aralığı içeren bir istekten örneklenmiş verilerin yer aldığı bir örnek yanıt verilmiştir. Sonuçlar, yaklaşık 15 milyon oturumdan oluşan örnekleme alan boyutunun neredeyse 500 bin örneğinden hesaplandı:

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

Sayfalara ayırma

Analytics Reporting API v4, birden fazla sayfayı kapsayan yanıt sonuçları sayfalara ayırmak için pageToken ve pageSize alanlarını kullanır. reports.batchGet isteğine verilen yanıtta nextPageToken parametresinden pageToken alırsınız:

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

Sonraki adım

Rapor oluşturmayla ilgili temel bilgileri edindiğinize göre API v4's gelişmiş özelliklerine göz atın.