Google Analytics API İsteklerini Toplu İşlem

Toplu işlemeye yönelik belirli bir yaklaşım olan Global HTTP Batch uç noktası (www.googleapis.com/batch), 12 Ağustos 2020'de Google Developers blogunda duyurulduğu üzere kullanımdan kaldırılmıştır. Bu sayfanın geri kalanında belirtildiği gibi, toplu işlemeye yönelik diğer yaklaşımlar da çalışmaya devam eder. Kodunuzda Global HTTP Batch uç noktası kullanılıyorsa API'ye özel HTTP toplu uç noktaları (www.googleapis.com/batch/API/VERSION) gibi diğer yaklaşımları kullanmaya geçişle ilgili talimatlar için blog yayınına bakın.

Bu dokümanda, istemcinizin kurması gereken HTTP bağlantılarının sayısını azaltmak için API çağrılarını bir araya nasıl getirebileceğiniz gösterilmektedir.

Bu belge, özellikle HTTP isteği göndererek toplu istek göndermeyle ilgilidir. Bunun yerine toplu istek yapmak için bir Google istemci kitaplığı kullanıyorsanız istemci kitaplığı dokümanlarına bakın.

Genel bakış

İstemcinizin yaptığı her HTTP bağlantısı belirli bir ek yükü beraberinde getirir. Google Analytics API, istemcinizin tek bir HTTP isteğine birden fazla API çağrısı yapmasını sağlamak için toplu işlemleri destekler.

Gruplandırma kullanmak isteyebileceğiniz durumlara örnekler:

  • Kullanıcı izinleri güncelleniyor. Kullanıcı izinlerini güncellerken toplu istekte bulunduğunuzda elde edilen belirli performans kazanımları ve kota teşvikleri vardır. Ayrıntılı bilgi için Kullanıcı İzinleri geliştirici kılavuzuna bakın.
  • Mobil raporlama uygulamanız çevrimdışı olabilir ve uygulama tekrar çevrimiçi olduğunda bir grup veri isteğinde bulunmanız gerekir.
  • Düzenli olarak birden fazla rapor oluşturması gereken bir hizmet hesabı uygulamanız var.
  • Bir dizi özel boyut veya özel metrik oluşturmanız gerekir ve yalnızca bir HTTP isteği oluşturmayı tercih edersiniz.

Her durumda, her aramayı ayrı ayrı göndermek yerine tek bir HTTP isteği altında gruplandırabilirsiniz. Dahili isteklerin tümü aynı Google API'ye gitmelidir.

Tek bir toplu istekte 1.000 aramayla sınırlısınız. Bundan daha fazla arama yapmanız gerekiyorsa birden fazla toplu istek kullanın.

Not: Google Analytics API için toplu sistem, OData toplu işleme sistemiyle aynı söz dizimini kullanır ancak anlamsal anlamlar farklıdır.

Toplu işlem ayrıntıları

Toplu istek, tek bir HTTP isteğinde birleştirilmiş birden fazla API çağrısından oluşur. Bu istekler, API keşif dokümanında belirtilen batchPath öğesine gönderilebilir. Varsayılan yol /batch/api_name/api_version şeklindedir. Bu bölümde, toplu söz dizimi ayrıntılı bir şekilde açıklanmaktadır; daha sonra bir örnek verilmiştir.

Not: Bir araya getirilmiş n istek grubu, tek bir istek olarak değil n istek olarak kullanım sınırınıza dahil edilir. Toplu istek, işlenmeden önce bir dizi istek için ayrılır.

Toplu isteğin biçimi

Toplu istek, birden fazla Google Analytics API çağrısı içeren ve multipart/mixed içerik türünü kullanan standart bir HTTP isteğidir. Bu ana HTTP isteğinde, parçaların her biri iç içe yerleştirilmiş bir HTTP isteği içerir.

Her bölüm kendi Content-Type: application/http HTTP üst bilgisi ile başlar. Ayrıca isteğe bağlı bir Content-ID üstbilgisi de olabilir. Bununla birlikte, parça başlıkları parçanın başlangıcını işaretlemek için kullanılır ve iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteği sarmalayarak ayrı isteklere getirdikten sonra, bölüm başlıkları yoksayılır.

Her bölümün gövdesi, kendi filiğini, URL'sini, üstbilgilerini ve gövdesini içeren tam bir HTTP isteğidir. HTTP isteği, URL'nin yalnızca yol kısmını içermelidir. Toplu isteklerde tam URL'lere izin verilmez.

Harici toplu isteğin HTTP üstbilgileri (Content-Type gibi Content- üstbilgileri hariç) gruptaki her istek için geçerlidir. Hem dış istekte hem de tek bir aramada belirli bir HTTP üstbilgisi belirtirseniz her bir bağımsız arama üstbilgisi değeri, harici toplu istek üstbilgisinin değerini geçersiz kılar. Tek bir aramanın üstbilgileri yalnızca söz konusu aramaya uygulanır.

Örneğin, belirli bir arama için Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi yalnızca söz konusu arama için geçerli olur. Harici istek için bir Yetkilendirme başlığı sağlarsanız bu başlık, kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece her bir çağrı için geçerli olur.

Sunucu toplu isteği aldığında, dış isteğin sorgu parametrelerini ve başlıklarını (uygun olduğu şekilde) her bir bölüme uygular ve daha sonra her bölümü ayrı bir HTTP isteğiymiş gibi işler.

Toplu isteğe yanıt verme

Sunucunun yanıtı, multipart/mixed içerik türüne sahip tek bir standart HTTP yanıtıdır. Her bölüm, isteklerle aynı sırada toplu istekteki isteklerden birine verilen yanıttır.

İstekteki parçalar gibi, her yanıt bölümü de durum kodu, üstbilgiler ve gövde dahil olmak üzere tam bir HTTP yanıtı içerir. İstekteki parçalarda olduğu gibi, her yanıt bölümünden önce parçanın başlangıcını belirten bir Content-Type başlığı bulunur.

İsteğin belirli bir bölümünde Content-ID üst bilgisi varsa, yanıtın ilgili bölümünde, aşağıdaki örnekte gösterildiği gibi, ilk olarak response- dizesinin önünde yer alan orijinal değerle eşleşen bir Content-ID üst bilgisi bulunur.

Not: Sunucu, çağrılarınızı istediğiniz sırayla gerçekleştirebilir. Belirttiğiniz sırayla bunların yürütülmesine güvenmeyin. Belirli bir sırada iki çağrının gerçekleşmesini sağlamak istiyorsanız bunları tek bir istekte gönderemezsiniz. Bunun yerine, ilk çağrıyı tek başına gönderebilir, ardından ikincisini göndermeden önce ilkinin yanıtını beklersiniz.

Örnek

Aşağıdaki örnekte, Google Analytics API ile gruplandırma özelliğinin kullanımı gösterilmektedir.

Örnek toplu istek

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

Örnek toplu yanıt

Bu, önceki bölümdeki örnek isteğin yanıtıdır.

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

İstemci kitaplıkları

Toplu işlemeyi kendi dilinizde nasıl uygulayacağınızı görmek için aşağıdaki istemci kitaplığı kılavuzlarını kullanın:

Toplu işlem ve Google Analytics kotası

Toplu işlem sizi, bir toplu istek içindeki her Google Analytics API isteği için çok sayıda HTTP isteği oluşturmanın ek yükünden kurtarır. Bu durum, günlük proje kotanızda hesaba katılır. Varsayılan olarak bir proje günde 50.000 isteğe kadar istekte bulunabilir. Toplu işlem,bu kotanın altında kalmanıza yardımcı olmaz.

Toplu Kullanıcı İzinleri yazma (silme, ekleme, güncelleme) istekleri hariç tüm hız sınırları geçerli olmaya devam eder. Örneğin, Core Reporting API görünüm başına 10 eşzamanlı istek (profil) ile sınırlıdır. Gruplandırma, bu sınırı aşmamanıza yardımcı olmaz.

Hesap Kimliği başına saniyede 1,5 sorgu (QPS) Management API Yazma İstekleri ve Temel Hazırlık API'si Yazma İstekleri için geçerlidir. Bu nedenle, söz konusu yazma isteklerini gruplandırmak performansı artırmayabilir.