Bu belgede, Çok Kanallı Dönüşüm Hunileri Raporlama API'si ile ilgili hem sorgu hem de yanıt için eksiksiz referans sağlanmaktadır.
Giriş
Çok Kanallı Dönüşüm Hunileri Raporlama API'si, Google Analytics Çok Kanallı Dönüşüm Hunileri rapor verilerini istemenize olanak tanır. Her rapor, izleme kodunun Analytics'e geri gönderdiği verilerden türetilen, boyutlar ve metrikler şeklinde düzenlenmiş istatistiklerden oluşur. Kendi boyut ve metrik kombinasyonlarınızı seçerek kendi spesifikasyonlarınıza göre özelleştirilmiş raporlar oluşturmak için Reporting API'yi kullanabilirsiniz.
API, rapor verilerini isteyen tek bir yöntem içerir: report.get. Bu yöntemle, verilerini almak istediğiniz görünüme (profile) karşılık gelen tablo kimliğini sağlarsınız. Ayrıca aşağıdakileri de belirtirsiniz:
- Boyutlar ve metriklerin bir kombinasyonu.
- Bir tarih aralığı.
- Döndürülen verileri kontrol eden bir dizi seçenek parametresi
API, report.get yöntemini bir REST uç noktasında kullanılabilir hale getirir: https://www.googleapis.com/analytics/v3/data/mcf. Aşağıdaki bölümde örnek bir istek görüntülenmiş ve parametrelerin her biri açıklanmıştır.
İstek
API, veri istemek için tek bir yöntem sağlar:
analytics.data.mcf.get()
API, REST uç noktası olarak da sorgulanabilir:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Her bir URL sorgu parametresi, URL kodlamalı olması gereken bir API sorgu parametresi belirtir.
Çok Kanallı Dönüşüm Hunileri Reporting API'ye gönderilen tüm İstekler, tercihen OAuth 2.0 aracılığıyla yetkilendirilmelidir.
Sorgu Parametrelerinin Özeti
Aşağıdaki tabloda, Çok Kanallı Dönüşüm Hunileri Raporlama API'si tarafından kabul edilen tüm sorgu parametreleri özetlenmektedir. Ayrıntılı bir açıklama için her bir parametre adını tıklayın.
| Ad | Değer | Gerekli | Özet |
|---|---|---|---|
ids |
string |
evet | ga:XXXX formunun benzersiz tablo kimliği. Burada XXXX, sorgunun verileri alacağı Analytics görünüm (profil) kimliğidir. |
start-date |
string |
evet |
Analytics verilerini getirmenin başlangıç tarihi. İstekler, YYYY-MM-DD olarak biçimlendirilmiş bir başlangıç tarihi veya göreli bir tarih (ör. today, yesterday veya NdaysAgo; burada N pozitif bir tam sayıdır).
|
end-date |
string |
evet |
Analytics verilerinin getirilmesi için bitiş tarihi. İstek, YYYY-MM-DD olarak biçimlendirilmiş bir bitiş tarihi veya göreli bir tarih (ör.
today, yesterday veya NdaysAgo; burada N pozitif bir tam sayıdır).
|
metrics |
string |
evet | mcf:totalConversions,mcf:totalConversionValue gibi virgülle ayrılmış metriklerin listesi.
Geçerli bir sorguda en az bir metrik belirtilmelidir. |
dimensions |
string |
no | Çok Kanallı Dönüşüm Hunisi raporunuz için mcf:source,mcf:keyword gibi virgülle ayrılmış boyutların bir listesi. |
sort |
string |
no | Döndürülen verilerin sıralama düzenini ve sıralama yönünü belirten, virgülle ayrılmış boyut ve metrikler listesi. |
filters |
string |
no | İsteğiniz için döndürülen verileri kısıtlayan boyut veya metrik filtreleri. |
samplingLevel |
string |
no | İstenen örnekleme düzeyi. İzin Verilen Değerler:
|
start-index |
integer |
no | Alınacak ilk veri satırı; 1'den başlar.
Bu parametreyi, max-results parametresiyle birlikte sayfalara ayırma mekanizması olarak kullanın. |
max-results |
integer |
no | Yanıta dahil edilecek maksimum satır sayısı. |
Sorgu Parametresi Ayrıntıları
ids
ids=ga:12345
ga: ad alanının raporun görünüm (profil) kimliğiyle birleştirilmesidir. Raporunuzun görünüm (profil) kimliğini,
Google Analytics Management API'deki Görünüm (Profil) kaynağında id sağlayan analytics.management.profiles.list yöntemini kullanarak alabilirsiniz.
başlangıç-tarihi
start-date=2011-10-01
start-date ve end-date parametrelerini dahil etmezseniz sunucu bir hata döndürür.
Tarih değerleri, YYYY-MM-DD kalıbı kullanılarak belirli bir tarih ya da today, yesterday veya NdaysAgo kalıbı kullanılarak göreli olabilir.
Değerler [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) ile eşleşmelidir.
start-date, 2011-01-01.
start-date için üst sınır kısıtlaması yoktur.Göreli tarihler kullanılarak son 7 gün (dünden başlayarak) için örnek tarih aralığı:
&start-date=7daysAgo &end-date=yesterday
bitiş tarihi
end-date=2011-10-31
start-date ve end-date parametrelerini dahil etmezseniz sunucu bir hata döndürür.
Tarih değerleri, YYYY-MM-DD kalıbı kullanılarak belirli bir tarih ya da today, yesterday veya NdaysAgo kalıbı kullanılarak göreli olabilir.
Değerler [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) ile eşleşmelidir.
end-date, 2005-01-01. end-date için üst sınır kısıtlaması yoktur. Göreli tarihler kullanılarak son 10 gün için (bugünden başlamak üzere) örnek tarih aralığı:
&start-date=9daysAgo &end-date=today
boyutlar
dimensions=mcf:source,mcf:keyword
Boyutlar parametresi, Çok Kanallı Dönüşüm Hunileri raporunuz için mcf:source veya mcf:medium gibi birincil veri anahtarlarını tanımlar.
Dönüşüm metriklerinizi segmentlere ayırmak için boyutları kullanın. Örneğin, sitenize gelen toplam dönüşüm sayısını sorarken, aracıya göre segmentlere ayrılmış dönüşüm sayısını sormak daha ilginç olabilir.
Bu durumda, organik, yönlendirme, e-posta ve benzerlerinden gelen dönüşümlerin sayısını görürsünüz.
Bir veri isteğinde dimensions kullanırken aşağıdaki kısıtlamaları göz önünde bulundurun:
- Herhangi bir sorguda en fazla 7 boyut sağlayabilirsiniz.
- Yalnızca boyutlardan oluşan bir sorgu gönderemezsiniz: İstenen tüm boyutları en az bir metrikle birleştirmeniz gerekir.
Kullanılamayan Değerler
Boyutun değeri belirlenemediğinde Analytics, özel dizeyi (not set) kullanır.
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
Toplam dönüşüm sayısı veya toplam dönüşüm değeri gibi sitenizdeki kullanıcı etkinliğiyle ilgili toplu istatistikler.
Bir sorguda dimensions parametresi yoksa döndürülen metrikler, istenen tarih aralığı için genel toplam dönüşüm değeri gibi toplam değerler sağlar. Ancak boyutlar istendiğinde, değerler boyut değerine göre segmentlere ayrılır.
Örneğin, mcf:source ile istenen mcf:totalConversions, kaynak başına toplam dönüşüm sayısını döndürür.
Metrik isterken aşağıdakileri aklınızda bulundurun:
- Tüm istekler en az bir metrik sağlamalıdır. Bir istek yalnızca boyutlardan oluşamaz.
- Herhangi bir sorgu için en fazla 10 metrik sağlayabilirsiniz.
sıralama
sort=mcf:source,mcf:medium
Döndürülen veriler için sıralama düzenini ve sıralama yönünü belirten metrik ve boyutların listesi.
- Sıralama sıralaması, listelenen metrik ve boyutların soldan sağa doğru sıralanmasıyla belirtilir.
- direction sıralama varsayılan olarak artan şeklinde yapılır ve istenen alanda eksi işareti (
-) ön eki kullanılarak azalan olarak değiştirilebilir.
Sorgu sonuçlarını sıralayarak verilerinizle ilgili farklı sorular sorabilirsiniz. Örneğin, "En iyi dönüşüm kaynaklarım hangileri ve hangi aracılar üzerinden yapılıyor?" sorusunu ele almak için
aşağıdaki parametreyle bir sorgu oluşturabilirsiniz. Önce mcf:source, ardından mcf:medium ölçütüne göre (her ikisi de artan düzende) sıralanır:
sort=mcf:source,mcf:medium
"En iyi dönüşüm ortamlarım hangileri ve hangi kaynaklardan yapılıyor?" sorusunu yanıtlamak için aşağıdaki parametreyle sorgu oluşturabilirsiniz. Önce mcf:medium, ardından mcf:source ölçütüne göre, her ikisi de artan düzende sıralanır:
sort=mcf:medium,mcf:source
sort parametresini kullanırken aşağıdakileri göz önünde bulundurun:
- Yalnızca
dimensionsveyametricsparametrelerinde kullandığınız boyutlara ya da metrik değerlerine göre sıralayın. İsteğiniz, boyutlar veya metrikler parametresinde belirtilmeyen bir alana göre sıralanıyorsa hata mesajı alırsınız. - Varsayılan olarak dizeler, en-US yerel ayarında artan alfabetik düzende sıralanır.
- Sayılar varsayılan olarak artan sayısal düzende sıralanır.
- Tarihler varsayılan olarak tarihe göre artan düzende sıralanır.
filtreler
filters=mcf:medium%3D%3Dreferral
filters sorgu dizesi parametresi, isteğinizden döndürülen verileri kısıtlar. filters parametresini kullanmak için filtrenin uygulanacağı boyut veya metriği, ardından filtre ifadesini girin. Örneğin, aşağıdaki sorgu, 12134 görünümü (profil) için mcf:totalConversions ve mcf:source isteğinde bulunur. Burada mcf:medium boyutu, referral dizesidir:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Ayrıntılar için Temel Raporlama API'si Referansı'nı okuyun.
samplingLevel
samplingLevel=DEFAULT
DEFAULT: Hız ve doğruluğu dengeleyen bir örnek boyutuyla yanıtı döndürür.FASTER: Daha küçük örnek boyutuyla hızlı bir yanıt döndürür.HIGHER_PRECISION: Büyük bir örnek boyutu kullanarak daha doğru bir yanıt döndürür ancak bu, yanıtın daha yavaş olmasına neden olabilir.
DEFAULT örnekleme düzeyi kullanılır.max-results
max-results=100
Bu yanıta dahil edilecek maksimum satır sayısı. Öğelerin bir alt kümesini almak için bunu start-index ile birlikte kullanabilir veya döndürülen öğelerin sayısını ilkinden başlayarak sınırlandırmak için tek başına kullanabilirsiniz.
max-results belirtilmezse sorgu, varsayılan maksimum 1.000 satırlık sınırı döndürür.
Çok Kanallı Dönüşüm Hunileri Raporlama API'si, kaç tane istediğinize bakılmaksızın istek başına maksimum 10.000 satır döndürür. Ayrıca, beklediğiniz kadar çok boyut segmenti yoksa istenenden daha az satır döndürebilir. Örneğin, mcf:medium için 300'den az olası değer vardır. Bu nedenle, yalnızca aracıya göre segmentlere ayırma işlemi yaparken max-results öğesini daha yüksek bir değere ayarlasanız bile 300'den fazla satır alamazsınız.
Yanıt
Başarılı olursa bu istek, aşağıda tanımlanan JSON yapısına sahip bir yanıt gövdesi döndürür.
Not: "results" terimi, sorguyla eşleşen tüm satır grubunu, "yanıt" ise geçerli sonuç sayfasında döndürülen satır grubunu ifade eder. itemsPerPage bölümünde açıklandığı gibi, toplam sonuç sayısı geçerli yanıtın sayfa boyutundan büyükse sonuçlar farklı olabilir.
Yanıt Biçimi
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
Yanıt Alanları
Yanıt gövde yapısının özellikleri aşağıdaki gibi tanımlanır:
| Mülk Adı | Değer | Açıklama |
|---|---|---|
kind |
string |
Kaynak türü. Değer "analytics#mcfData"dır. |
id |
string |
Bu veri yanıtı için bir kimlik. |
query |
object |
Bu nesne, sorguya parametre olarak iletilen tüm değerleri içerir. Her alanın anlamı, karşılık gelen sorgu parametresinin açıklamasında açıklanmıştır. |
query.start-date |
string |
Başlangıç tarihi. |
query.end-date |
string |
Bitiş tarihi. |
query.ids |
string |
Benzersiz tablo kimliği. |
query.dimensions[] |
list |
Analiz boyutlarının listesi. |
query.metrics[] |
list |
Analiz metriklerinin listesi. |
query.sort[] |
list |
Verilerin sıralandığı metriklerin veya boyutların listesi. |
query.filters |
string |
Metrik veya boyut filtrelerinin virgülle ayrılmış listesi. |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
Satırların başlangıç dizini. Varsayılan değer 1'dir. |
query.max-results |
integer |
Sayfa başına maksimum sonuç sayısı. |
startIndex |
integer |
start-index sorgu parametresi tarafından belirtilen satırların başlangıç dizini. Varsayılan değer 1'dir. |
itemsPerPage |
integer |
Döndürülen gerçek satır sayısından bağımsız olarak yanıtın içerebileceği maksimum satır sayısı. max-results sorgu parametresi belirtilirse itemsPerPage değeri, max-results veya 10.000 değerinden daha küçüktür. itemsPerPage öğesinin varsayılan değeri 1.000'dir.
|
totalResults |
integer |
Yanıtta döndürülen satır sayısından bağımsız olarak, sorgu sonucundaki toplam satır sayısı. Çok sayıda satırla sonuçlanan sorgular için totalResults, itemsPerPage değerinden büyük olabilir.
Büyük sorgular için totalResults ve itemsPerPage ile ilgili daha fazla açıklama için Sayfalama bölümüne bakın.
|
selfLink |
string |
Bu veri sorgusu için bu sonuç sayfasının bağlantısı. |
previousLink |
string |
Bu veri sorgusu için önceki sonuç sayfasının bağlantısı. |
nextLink |
string |
Bu veri sorgusu için sonraki sonuç sayfasının bağlantısı. |
profileInfo |
object |
Verilerinin istendiği görünüm (profil) hakkında bilgi. Görünüm (Profil) verileri, Google Analytics Management API aracılığıyla kullanılabilir. |
profileInfo.profileId |
string |
Görünüm (Profil) kimliği (ör. 1174). |
profileInfo.accountId |
string |
Bu görünümün (profilin) ait olduğu hesap kimliği (ör. 30481). |
profileInfo.webPropertyId |
string |
Bu görünümün (profilin) ait olduğu Web Mülkü Kimliği. Örneğin, UA-30481-1. |
profileInfo.internalWebPropertyId |
string |
Bu görünümün (profilin) ait olduğu web mülkünün UA-30481-1 gibi dahili kimliği. |
profileInfo.profileName |
string |
Görünümün (profil) adı. |
profileInfo.tableId |
string |
Görünüm (profil) için "ga:" ve ardından görünüm (profil) kimliğinden oluşan tablo kimliği. |
containsSampledData |
boolean |
Yanıt, örneklenmiş veriler içeriyorsa doğru değerini alır. |
sampleSize |
string |
Örneklenmiş verileri hesaplamak için kullanılan örnek sayısı. |
sampleSpace |
string |
Toplam örnekleme alanı boyutu. Örneklerin seçildiği toplam kullanılabilir örnek alanı boyutunu gösterir. |
columnHeaders[] |
list |
Boyut adlarını ve ardından metrik adlarını listeleyen sütun başlıkları. Boyut ve metriklerin sırası, istekte metrics ve dimensions parametreleri aracılığıyla belirtilenlerle aynıdır. Başlık sayısı, boyut sayısı + metrik sayısıdır. |
columnHeaders[].name |
string |
Boyut veya metriğin adı. |
columnHeaders[].columnType |
string |
Sütun türü. "DIMENSION" veya "METRIC". |
columnHeaders[].dataType |
string |
Veri türü. Boyut sütunu başlıklarında veri türü olarak yalnızca "STRING" veya "MCF_SEQUENCE" vardır.
Metrik sütunu başlıkları "INTEGER", "DOUBLE", "CURRENCY" gibi metrik değerleri için veri türleri içerir. |
totalsForAllResults |
object |
Metrik adları ve değerlerinden oluşan anahtar/değer çiftleri olarak, istenen metriklerin toplam değerleri. Metrik toplamlarının sırası, istekte belirtilen metrik sırası ile aynıdır. |
rows[] |
list |
Her satırda bir Bir
{
"primitiveValue": "2183"
}
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Hata Kodları
Çok Kanallı Dönüşüm Hunileri Reporting API, bir istek başarılı olursa bir 200 HTTP durum kodu döndürür. Sorgu işlenirken hata oluşursa API bir hata kodu ve açıklama döndürür.
Analytics API'yi kullanan her uygulamanın, doğru hata işleme mantığını uygulaması gerekir. Hata kodları ve bunların nasıl ele alınacağıyla ilgili ayrıntılar için
Hata Yanıtları başvuru kılavuzunu okuyun.
Deneyin.
Canlı verilerde bu yöntemi çağırmak ve yanıtı görmek için aşağıdaki API Gezgini'ni kullanın.
Örneklendirme
Google Analytics, belirli boyut ve metrik kombinasyonlarını anında hesaplar. Google Analytics, verileri makul bir sürede döndürmek için yalnızca verilerin bir örneğini işleyebilir.
samplingLevel parametresini ayarlayarak bir istek için kullanılacak örnekleme düzeyini belirtebilirsiniz.
Bir MCF Reporting API yanıtı örneklenmiş veri içeriyorsa containsSampledData yanıt alanı true olur.
Ayrıca 2 özellik, sorgunun örnekleme düzeyi hakkında bilgi sağlar: sampleSize ve sampleSpace.
Bu 2 değer ile sorgu için kullanılan oturumların yüzdesini hesaplayabilirsiniz. Örneğin, sampleSize değeri 201,000,sampleSpace değeri 220,000 ise rapor temel olarak (201.000 / 220.000) x 100 = % 91,36 oturuma dayanır.
Örneklemenin genel bir açıklaması ve Google Analytics'te nasıl kullanıldığı için Örnekleme bölümüne bakın.
Büyük Veri Sonuçlarını İşleme
Sorgunuzun büyük bir sonuç kümesi döndürmesini bekliyorsanız API sorgunuzu optimize etmenize, hatalardan kaçınmanıza ve kota aşımlarını en aza indirmenize yardımcı olacak aşağıdaki yönergeleri kullanın. Herhangi bir API isteğinde maksimum 7 boyuta ve 10 metriğe izin vererek performans temeli oluşturduğumuzu unutmayın. Çok sayıda metrik ve boyut belirten bazı sorguların işlenmesi diğerlerinden daha uzun sürebilir. Ancak, istenen metrik sayısının sınırlanması sorgu performansını iyileştirmek için yeterli olmayabilir. Bunun yerine, en iyi performans sonuçları için aşağıdaki teknikleri kullanabilirsiniz.
Sorgu Başına Boyutları Azaltma
API, herhangi bir istekte en fazla 7 boyutun belirtilmesine olanak tanır. Çoğu zaman, Google Analytics bu karmaşık sorguların sonuçlarını anında hesaplamak zorundadır. Bu işlem, özellikle sonuçta elde edilen satır sayısı yüksekse çok zaman alabilir. Örneğin, şehir bazında anahtar kelime sorguları milyonlarca veri satırıyla eşleşebilir. Sorgunuzdaki boyutların sayısını sınırlandırıp Google Analytics'in işlemesi gereken satır sayısını azaltarak performansı artırabilirsiniz.
Sorguyu Tarih Aralığına Göre Bölme
Tek bir uzun tarih aralığının tarih içeren veya tarih içeren sonuçlarına göz atmak yerine, aynı anda bir hafta, hatta bir gün için ayrı sorgular oluşturmayı deneyin. Elbette, büyük bir veri kümesinde tek bir güne ait verilerle ilgili bir istek bile max-results değerinden daha fazla sonuç döndürebilir. Bu durumda sayfalamadan kaçınılamaz. Ancak sorgunuzla eşleşen satırların sayısı max-results değerinden büyükse tarih aralığının ayrılması, sonuçların alınması için gereken toplam süreyi azaltabilir. Bu yaklaşım, hem tek iş parçacıklı hem de paralel sorgularda performansı artırabilir.
Sayfalama
Sonuçlara göz atmak, büyük sonuç kümelerini yönetilebilir parçalara bölmek için faydalı bir yol olabilir. totalResults alanı, kaç eşleşen satır olduğunu bildirir ve itemsPerPage, sonuçta döndürülebilecek maksimum satır sayısını verir.
totalResults/itemsPerPage oranı yüksekse tek tek sorgular gereğinden uzun sürebilir. Görüntüleme amaçları gibi yalnızca sınırlı sayıda satıra ihtiyacınız varsa max-results parametresi aracılığıyla yanıt boyutu için açık bir sınır belirlemek uygun olabilir. Bununla birlikte, uygulamanızın büyük bir sonuç grubunu bütünüyle işlemesi gerekiyorsa izin verilen maksimum satır sayısını istemek daha verimli olabilir.
gzip'i kullanma
Her bir istek için gereken bant genişliğini azaltmanın kolay ve rahat bir yolu gzip sıkıştırmasını etkinleştirmektir. Sıkıştırılmış sonuçların açılması için ek CPU süresi gerekse de, ağ maliyetlerinin dengelenmesi genellikle çok değerlidir. gzip kodlamalı bir yanıt almak için iki şey yapmanız gerekir: Bir Accept-Encoding üst bilgisi ayarlayın ve kullanıcı aracınızı gzip dizesini içerecek şekilde değiştirin.
Burada, gzip sıkıştırmasını etkinleştirmek için düzgün şekilde oluşturulmuş bir HTTP üst bilgisi örneği verilmiştir:
Accept-Encoding: gzip User-Agent: my program (gzip)