Bu belge, Çok Kanallı Dönüşüm Hunileri Raporlama API'si için hem sorgu hem de yanıtın tam referansını sağlar.
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 gönderdiği verilerden türetilen ancak boyutlar ve metrikler şeklinde düzenlenmiş istatistiklerden oluşur. Kendi boyut ve metrik kombinasyonlarınızı seçerek Reporting API'yi kullanarak kendi spesifikasyonlarınıza göre özelleştirilmiş raporlar oluşturabilirsiniz.
API, rapor verileri isteyen tek bir yöntem içerir: report.get. Bu yöntemle, veri almak istediğiniz görünüme (profil) karşılık gelen tablo kimliğini sağlarsınız. Ayrıca, aşağıdakileri belirtirsiniz:
- Boyut ve metrik kombinasyonu.
- Bir tarih aralığı.
- Hangi verilerin döndürüldüğünü kontrol eden bir grup 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 bir örnek istek gösterilmektedir ve her bir parametre 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 URL sorgu parametresi, URL kodlamalı olması gereken bir API sorgu parametresi belirtir.
Çok Kanallı Dönüşüm Hunileri Raporlama API'sine gönderilen tüm İstekler, tercihen OAuth 2.0 üzerinden yetkilendirilmelidir.
Sorgu Parametreleri Özeti
Aşağıdaki tabloda, Çok Kanallı Dönüşüm Hunileri Raporlama API'si tarafından kabul edilen tüm sorgu parametreleri özetlenmiştir. Ayrıntılı bir açıklama için ilgili parametre adını tıklayın.
Ad | Değer | Zorunlu | Özet |
---|---|---|---|
ids |
string |
evet | ga:XXXX biçimindeki benzersiz tablo kimliği. XXXX, sorgudaki verileri alacağı Analytics görünümü (profil) kimliğidir. |
start-date |
string |
evet |
Analytics verilerinin getirilmesi için başlangıç tarihi. İstekler YYYY-MM-DD olarak biçimlendirilmiş bir başlangıç tarihi veya göreli bir tarih (ör. N , pozitif bir tam sayı olduğunda today , yesterday veya NdaysAgo ).
|
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 sorgu en az bir metrik belirtmelidir. |
dimensions |
string |
hayır | Çok Kanallı Dönüşüm Hunileri raporunuz için mcf:source,mcf:keyword gibi boyutların virgülle ayrılmış listesi. |
sort |
string |
hayır | Döndürülen verilerin sıralama sırasını ve sıralama yönünü belirten virgülle ayrılmış boyut ve metriklerin listesi. |
filters |
string |
hayır | İsteğiniz için döndürülen verileri kısıtlayan boyut veya metrik filtreleri. |
samplingLevel |
string |
hayır | İstenen örnekleme düzeyi. İzin Verilen Değerler:
|
start-index |
integer |
hayır | Alınacak ilk veri satırı 1'den başlar.
Bu parametreyi, max-results parametresiyle birlikte bir sayfalara ayırma mekanizması olarak kullanın. |
max-results |
integer |
hayır | Yanıta dahil edilecek maksimum satır sayısı. |
Sorgu Parametresi Ayrıntıları
kimlikler
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'sindeki 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ını veya today
, yesterday
ya da NdaysAgo
kalıbını kullanarak göreli olarak belirli bir tarih için 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 tarihleri kullanarak son 7 güne (dünden başlayan) ö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ını veya today
, yesterday
ya da NdaysAgo
kalıbını kullanarak göreli olarak belirli bir tarih için 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 tarihleri kullanarak son 10 güne ait (bugünden itibaren) ö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ı öğrenmek isteseniz de aracıya göre segmentlere ayrılmış dönüşüm sayısını istemek daha ilginç olabilir.
Bu durumda, organik, yönlendirme, e-posta ve benzeri kaynaklardan gelen dönüşümlerin sayısını görürsünüz.
Bir veri isteğinde dimensions
kullanırken aşağıdaki kısıtlamalara dikkat edin:
- Herhangi bir sorgu için en fazla 7 boyut girebilirsiniz.
- 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 (ayarlanmadı) 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ği için toplu istatistikler.
Bir sorguda dimensions
parametresi yoksa döndürülen metrikler, istenen tarih aralığı için toplam toplam dönüşüm değeri gibi toplu 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 şunları unutmayın:
- Her istek en az bir metrik sağlamalıdır. İstek yalnızca boyutlardan oluşturulamaz.
- Herhangi bir sorgu için en fazla 10 metrik girebilirsiniz.
sıralama
sort=mcf:source,mcf:medium
Döndürülen verilerin sıralama düzenini ve sıralama yönünü belirten metriklerin ve boyutların listesi.
- Sıralama sıralaması, listelenen metriklerin ve boyutların soldan sağa sıralamasıyla belirlenir.
- Sıralama yön varsayılan olarak artan düzendedir ve istenen alanda bir eksi işareti (
-
) ön eki kullanılarak azalan olarak değiştirilebilir.
Bir sorgunun sonuçlarını sıralamanız, verilerinizle ilgili farklı sorular sormanıza olanak tanır. Örneğin, "En iyi dönüşüm kaynaklarım hangileri" ve "Hangi aracılar" yoluyla
aşağıdaki parametreyle bir sorgu yapabilirsiniz. Önce her birine (mcf:source
) ve ardından mcf:medium
ölçütüne göre artan düzende sıralanır:
sort=mcf:source,mcf:medium
İlgili "En iyi dönüşüm ortamlarım hangileri?" ve "Hangi kaynaklardan?" sorusunu yanıtlamak için aşağıdaki parametreyle bir sorgu yapabilirsiniz. Önce her birine (mcf:medium
) ve ardından mcf:source
ölçütüne göre artan düzende sıralanır:
sort=mcf:medium,mcf:source
sort
parametresini kullanırken aşağıdakileri unutmayın:
- Yalnızca
dimensions
veyametrics
parametrelerinde kullandığınız boyutlara veya metrik değerlerine göre sıralama yapın. İsteğiniz, boyutlar veya metrikler parametresinde belirtilmeyen bir alanda sıralanırsa bir hata mesajı alırsınız. - Dizeler varsayılan olarak en-US yerel ayarında, artan düzeyde 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 filtre uygulanacak bir boyut veya metrik ve ardından filtre ifadesini sağlayın. Ö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 Reporting API Referansı'nı okuyun.
örnekleme düzeyi
samplingLevel=DEFAULT
DEFAULT
: Hızı ve doğruluğu dengeleyen bir örnek boyutuyla yanıtı döndürür.FASTER
: Daha küçük örnek boyutuna sahip bir hızlı 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.maks. sonuç
max-results=100
Bu yanıta dahil edilecek maksimum satır sayısı. Bunu, bir öğe alt kümesini almak için start-index
ile birlikte veya ilk adımdan başlayarak, döndürülen öğelerin sayısını kısıtlamak için kullanabilirsiniz.
max-results
belirtilmezse sorgu, varsayılan maksimum 1.000 satır döndürür.
Çok Kanallı Dönüşüm Hunileri Raporlama API'sı, kaç istek istediğinize bakılmaksızın istek başına maksimum 10.000 satır döndürür. Beklediğiniz kadar çok boyut segmenti yoksa istenenden daha az satır da 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ırdığınızda max-results
değerini 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ıyla bir yanıt gövdesi döndürür.
Not: "Sonuçlar" terimi, sorguyla eşleşen tüm satır kümesini, "yanıt" ise mevcut sonuçlar sayfasında döndürülen satır grubunu ifade eder. Toplam öğe sonuçları, mevcut yanıtın sayfa boyutundan büyükse itemsPerPage bölümünde açıklandığı gibi farklı olabilirler.
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 şu şekilde tanımlanır:
Mülk Adı | Değer | Açıklama |
---|---|---|
kind |
string |
Kaynak türü. Değer "analytics#mcfData" |
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'den küçük olur. Varsayılan itemsPerPage 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, totalResults değerini 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ünü inceleyin.
|
selfLink |
string |
Bu veri sorgusu için bu sonuçlar sayfasının bağlantısı. |
previousLink |
string |
Bu veri sorgusu için önceki sonuçlar sayfasının bağlantısı. |
nextLink |
string |
Bu veri sorgusu için sonraki sonuçlar sayfasının bağlantısı. |
profileInfo |
object |
Verilerin istendiği görünüm (profil) ile ilgili bilgiler. Görünüm (Profil) verileri Google Analytics Management API üzerinden 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 (ör. UA-30481-1 ). |
profileInfo.internalWebPropertyId |
string |
Bu görünümün (profilin) ait olduğu web mülkünün dahili kimliği (ör. UA-30481-1 ). |
profileInfo.profileName |
string |
Görünümün adı (profili). |
profileInfo.tableId |
string |
Görünüm (profil) için &&t;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 örneklerin sayısı. |
sampleSpace |
string |
Toplam örnekleme alanı boyutu. Bu, örneklerin seçili olduğu kullanılabilir toplam örnek alan boyutunu belirtir. |
columnHeaders[] |
list |
Boyut adlarının ve ardından metrik adlarının listelendiği sütun başlıkları. Boyutların ve metriklerin sırası, istekte metrics ve dimensions parametreleri aracılığıyla belirtilenlerle aynıdır. Başlık sayısı, boyut sayısı ile metrik
sayısını ifade eder. |
columnHeaders[].name |
string |
Boyut veya metriğin adı. |
columnHeaders[].columnType |
string |
Sütun türü. "BOYUT" veya "METRİK". |
columnHeaders[].dataType |
string |
Veri türü. Boyut sütunu başlıkları veri türü olarak yalnızca "STRING" veya "MCF_SEQUENCE" içerir.
Metrik sütunu başlıklarında "INTEGER" , "DOUBLE" , "CURRENCY" gibi metrik değerleri için veri türleri bulunur. |
totalsForAllResults |
object |
İstenen metriklerin toplam değeri, metrik adı ve değerinden oluşan anahtar/değer çiftleridir. Metrik toplamlarının sırası, istekte belirtilen metrik sıralamasıyla aynıdır. |
rows[] |
list |
Her bir satırın
{ "primitiveValue": "2183" }
{ "conversionPathValue": [ { "interactionType" : "CLICK", "nodeValue" : "google" }, { "interactionType" : "CLICK", "nodeValue" : "google" } ] } |
Hata Kodları
Çok Kanallı Dönüşüm Hunileri Raporlama API'si, bir istek başarılı olursa 200
HTTP durum kodu döndürür. Sorgunun işlenmesi sırasında bir hata oluşursa API bir hata kodu ve açıklaması 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 işleneceğiyle ilgili ayrıntılar için Hata Yanıtları referans kılavuzunu inceleyin.
Deneyin.
Canlı verilerde bu yöntemi çağırmak ve yanıtı görmek için aşağıdaki API Gezgini'ni kullanın.
Örnekleme
Google Analytics, belirli boyut ve metrik kombinasyonlarını anında hesaplar. Google Analytics, verileri makul bir sürede iade etmek için verilerin yalnızca bir örneğini işleyebilir.
Bir istek için kullanılacak örnekleme düzeyini, samplingLevel parametresini ayarlayarak belirtebilirsiniz.
Bir MCF Reporting API yanıtı, örneklenmiş veriler içeriyorsa containsSampledData
yanıt alanı true
olur.
Ayrıca 2 mülk, sorgu için örnekleme düzeyiyle ilgili bilgi sağlar: sampleSize
ve sampleSpace
.
Bu 2 değerle, sorgu için kullanılan oturumların yüzdesini hesaplayabilirsiniz. Örneğin, sampleSize
201,000
ve sampleSpace
220,000
ise rapor (201.000 / 220.000) x 100 = %91,36 oturuma dayanır.
Örneklemenin genel açıklaması ve Google Analytics'te nasıl kullanıldığı hakkında bilgi edinmek için Örnekleme konusuna bakın.
Büyük Veri Sonuçlarını Kullanma
Sorgunuzun büyük bir sonuç grubu döndürmesini bekliyorsanız API sorgunuzu optimize etmenize, hatalardan kaçınmanıza ve kota taşmalarını en aza indirmenize yardımcı olacak aşağıdaki yönergeleri kullanın. Herhangi bir API isteğinde en fazla 7 boyuta ve 10 metriğe izin vererek bir performans tabanı belirleriz. Çok sayıda metrik ve boyut belirten bazı sorguların işlenmesi diğerlerinden daha uzun sürebilir ancak istenen metriklerin sayısının sınırlandırılması sorgu performansını iyileştirmek için yeterli olmayabilir. Bunun yerine, en iyi performans sonuçlarını elde etmek için aşağıdaki teknikleri kullanabilirsiniz.
Sorgu başına boyutları azaltma
API, herhangi bir istekte en fazla 7 boyut belirtmeye olanak tanır. Çoğu zaman, Google Analytics'in bu karmaşık sorguların sonuçlarını anında hesaplaması gerekir. Bu, özellikle elde edilen satır sayısı yüksekse çok zaman alabilir. Örneğin, anahtar kelimeleri şehir bazında saat bazında sorgulamak, milyonlarca satır veriyle eşleşebilir. Sorgunuzdaki boyut sayısını sınırlandırarak Google Analytics'in işlemesi gereken satır sayısını azaltarak performansı artırabilirsiniz.
Sorguyu Tarih Aralığına Bölme
Uzun bir tarih aralığına ait tarih içeren sonuçlara göz atmak yerine, aynı anda bir hafta, hatta bir gün için ayrı sorgular oluşturabilirsiniz. Elbette büyük bir veri kümesinde, tek bir güne ait veriler için gönderilen istek bile max-results
üzerinde değer döndürebilir. Bu durumda, sayfalandırmadan kaçınılamaz. Ancak her durumda, sorgunuzla eşleşen satırların sayısı max-results
değerinden yüksekse tarih aralığını ayırmak sonuçları almak için toplam süreyi azaltabilir. Bu yaklaşım, hem tek ileti dizileri hem de paralel sorgularda performansı artırabilir.
Sayfalandırma
Sonuçlar arasında gezinmek, büyük sonuç kümelerini yönetilebilir parçalara ayırmak için yararlı bir yol olabilir. totalResults
alanı, eşleşen satır sayısını belirtir. itemsPerPage
, sonuçta döndürülebilecek maksimum satır sayısını verir.
Yüksek bir totalResults
oranı varsa itemsPerPage
tek tek gerekenden daha uzun sürebilir. Yalnızca sınırlı sayıda satıra ihtiyacınız varsa (örneğin, görüntüleme amacıyla) max-results
parametresi aracılığıyla yanıt boyutu için açık bir sınır belirleyebilirsiniz. Ancak, uygulamanızın çok sayıda sonucu eksiksiz olarak işlemesi gerekiyorsa izin verilen maksimum satır sayısını istemek daha verimli olabilir.
Gzip'i kullanma
Her istek için gereken bant genişliğini azaltmanın kolay ve kolay yolu gzip sıkıştırmayı etkinleştirmektir. Bu işlem, sonuçların sıkıştırmasını açmak için ek CPU süresi gerektirse de ağ maliyetlerinin dengelenmesi genellikle çok değerlidir. gzip kodlu bir yanıt almak için iki şey yapmanız gerekir: Bir Accept-Encoding
başlığı ayarlayın ve kullanıcı aracısını gzip
dizesini içerecek şekilde değiştirin.
Aşağıda, gzip sıkıştırmasını etkinleştirmek için düzgün şekilde oluşturulmuş HTTP başlıkları örneği verilmiştir:
Accept-Encoding: gzip User-Agent: my program (gzip)