Rapor Oluşturma

Bu, Analytics Reporting API v4 için 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övdesinin yapısı ve batchGet kaynağındaki yanıt gövdesinin yapısı açıklanmaktadır.

İstek Metni

Analytics Reporting API v4'ü veri isteğinde bulunmak amacıyla kullanmak için aşağıdaki minimum gereksinimlere sahip bir ReportRequest nesnesi oluşturmanız gerekir:

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

Bir görünüm kimliğini bulmak için hesap özetleri yöntemini sorgulayın veya Hesap Gezgini'ni kullanın. Tarih aralığı belirtilmemişse varsayılan tarih aralığı şu şekilde olur: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Aşağıda, gerekli minimum alanların yer aldığı örnek bir 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 nesnesi kabul eder. Tüm istekler aynı dateRange, viewId, segments, samplingLevel ve cohortGroup özelliklerine sahip olmalıdır.

Yanıt Metni

API isteğinin yanıt gövdesi, bir Rapor nesneleri dizisidir. Rapor yapısı, rapordaki boyutları, metrikleri ve bunların veri türlerini açıklayan ColumnHeader nesnesinde tanımlanır. Boyut ve metriklerin değerleri data (veriler) alanında belirtilir.

Aşağıda, yukarıdaki örnek istek için örnek bir yanıt verilmiştir:

{
    "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 için en az bir Metrik nesnesi gerekir.

Aşağıdaki örnekte, belirtilen tarih aralığındaki toplam oturum sayısını almak için batchGet yöntemine Sessions metriği sağlanmıştı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 metrik gezginini veya Metadata API'sini kullanabilirsiniz.

Filtreleme

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

  • metricName
  • not
  • operator
  • comparisonValue

Metriği {metricName}, {operator} operator ve {comparisonValue} comparisonValue temsil etsin. Bu durumda filtre şu şekilde çalışır:

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

not için true değerini 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 metrikler üzerinde tanımladığınız matematiksel bir ifadedir. 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:

  • Adını veya takma adını fieldName alanından sağlayın.
  • sortOrder alanı aracılığıyla sıralama düzenini (ASCENDING veya DESCENDING) belirtin.

Aşağıdaki örnekte batchGet, önce oturum sayısına, ardından sayfa görüntüleme sayısına göre büyükten küçüğe sıralanan metrikleri 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 oluştuğu şehri ("Paris" veya "New York") belirtir. Bir 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

Bir 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 DimensionsFilterClauses öğesini belirtin ve her bir DimensionsFilterClause öğesinde bir veya daha fazla DimensionsFilters tanımlayın. Her bir DimensionsFilters içinde aşağıdakilerin değerlerini belirtin:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

{dimensionName} boyutu, {operator} operator ve {expressions} expressions temsil ediyor olsun. Bu durumda filtre şu şekilde çalışır:

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

not için true değerini 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ülemelerini ve oturumları 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ı boyut değerine göre sıralamak için:

  • Dosyanın adını fieldName alanından sağlayın.
  • sortOrder alanından sıralama düzenini (ASCENDING veya DESCENDING) belirtin.

Örneğin, aşağıdaki batchGet, boyutları ülkeye ve ardından tarayıcıya göre sıralanmış şekilde 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ın değerlerini aralıklar halinde gruplandırarak özelliklerini anlamak daha kolaydır. Sonuçta elde edilen paketlerde aralıkları 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 çok tarih aralığındaki verileri almanıza olanak tanır. İsteğiniz ister bir ister iki tarih aralığı belirtsin, 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ğerleri isteğinde bulunurken sonuçları, tarih aralıklarındaki metriğin 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 saatle ilgili bir boyut isteğinde bulunursanız DateRangeValue nesnesi, yalnızca ilgili aralıklarda yer alan tarihlere ait değerleri içerir. Belirtilen tarih aralıklarında olmayan diğer tüm değerler 0 olur.

Örneğin, ga:date boyutu ve ga:sessions metriği için Ocak ve Şubat olmak üzere iki tarih aralığındaki bir isteği ele alalım. Ocak ayındaki istenen verilerin yanıtında, Şubat ayındaki değerler 0; Şubat ayındaki istenen verilerin yanıtında ise Ocak ayındaki 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, bir segmentte belirli bir ülkeden veya şehirden kullanıcıları, başka bir segmentte ise sitenizin belirli bir bölümünü ziyaret eden kullanıcıları tanımlayabilirsiniz. Filtreler yalnızca bir koşulu karşılayan satırları döndürürken segmentler, segmentleri içeren koşulları karşılayan kullanıcıların, oturumların veya etkinliklerin alt kümelerini döndürür.

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

  • Bir batchGet yöntemindeki her ReportRequest, aynı segment tanımları 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"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

Segment içeren daha fazla örnek istek için Örnekler bölümüne bakın.

Segment kimliği

Segment istemek için segmentId alanını kullanın. Segment isteğinde bulunmak 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"}]
    }
  ]
}

Örneklendirme

Ö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 için değeri SMALL olarak ayarlayın.
  • daha doğru ancak daha yavaş bir yanıt için değeri LARGE olarak ayarlayın.
  • Hızı ve 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 örneklenmemişse bu alanlar tanımlanmaz.

Aşağıda, iki tarih aralığına sahip bir istekten örneklenmiş veriler içeren bir yanıt örneği verilmiştir. Sonuçlar, yaklaşık 15 milyon oturum büyüklüğündeki bir örnekleme alanının yaklaşık 500 bin örneğinden hesaplanmıştır:

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

Sayfalara ayırma

Analytics Reporting API v4, birden fazla sayfaya yayılan yanıt sonuçlarını sayfalara ayırmak için pageToken ve pageSize alanlarını kullanır. reports.batchGet isteğine verilen yanıtta nextPageToken parametresinden pageToken elde edersiniz:

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 öğrendiğinize göre, API v4'ün gelişmiş özelliklerine göz atabilirsiniz.