Bu dokümanda, uygulamanızın performansını artırmak için kullanabileceğiniz bazı teknikler açıklanmaktadır. Bazı durumlarda, sunulan fikirleri göstermek için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak, Blogger API'leri için aynı kavramlar geçerlidir.
gzip kullanarak sıkıştırma
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ı ortaya çıkarmak 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 uygun şekilde biçimlendirilmiş HTTP üstbilgileri örneği verilmiştir:
Accept-Encoding: gzip User-Agent: my program (gzip)
Kısmi kaynaklarla çalışma
API çağrılarınızın performansını iyileştirmenin bir başka yolu, verilerin yalnızca ilgilendiğiniz bölümünü göndermek ve almaktır. Bu yaklaşım, uygulamanızın gereksiz alanları aktarmasını, ayrıştırmasını ve depolamasını önler. Böylece ağ, CPU ve bellek gibi kaynakları daha verimli bir şekilde kullanabilir.
İki tür kısmi istek vardır:
- Kısmi yanıt: Yanıta hangi alanların dahil edileceğini belirttiğiniz bir istek (
fields
istek parametresini kullanın). - Patch: Yalnızca değiştirmek istediğiniz alanları gönderdiğiniz güncelleme isteği (
PATCH
HTTP fiilini kullanın).
Kısmi istek oluşturmayla ilgili daha ayrıntılı bilgiyi aşağıdaki bölümlerde bulabilirsiniz.
Kısmi yanıt
Varsayılan olarak sunucu, istekleri işleme aldıktan sonra bir kaynağın tam temsilini geri gönderir. Daha iyi performans için sunucudan yalnızca gerçekten ihtiyacınız olan alanları göndermesini isteyebilir ve bunun yerine kısmi bir yanıt alabilirsiniz.
Kısmi yanıt istemek için fields
istek parametresini kullanarak döndürülmesini istediğiniz alanları belirtin. Bu parametreyi, yanıt verileri döndüren tüm isteklerle kullanabilirsiniz.
fields
parametresinin yalnızca yanıt verilerini etkilediğini unutmayın. Varsa göndermeniz gereken veriler bu durumdan etkilenmez. Kaynakları değiştirirken gönderdiğiniz veri miktarını azaltmak için bir yama isteği kullanın.
Örnek
Aşağıdaki örnekte, fields
parametresinin genel (kurgusal) &Demo" API'si ile kullanımı gösterilmektedir.
Basit istek: Bu HTTP GET
isteği, fields
parametresini çıkarır ve tam kaynağı döndürür.
https://www.googleapis.com/demo/v1
Tam kaynak yanıtı: Kısa veri, sadelik nedeniyle çıkarılan diğer alanların yanı sıra aşağıdaki alanları içerir.
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
Kısmi yanıt isteği: Aynı kaynak için aşağıdaki istekte, döndürülen veri miktarını önemli ölçüde azaltmak üzere fields
parametresi kullanılmaktadır.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Kısmi yanıt: Yukarıdaki isteğe yanıt olarak, sunucu yalnızca tür bilgilerini içeren bir yanıtın yanı sıra her bir öğede yalnızca HTML başlığı ve uzunluk özelliği bilgilerini içeren ayrıştırılmış bir öğe dizisi gönderir.
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Yanıtın yalnızca seçili alanları ve çevresindeki üst nesneleri içeren bir JSON nesnesi olduğunu unutmayın.
fields
parametresinin biçimlendirilmesiyle ilgili ayrıntılara, ardından yanıtta tam olarak ne döndürüldüğüyle ilgili ayrıntılara değiniliyor.
Alanlar parametresi söz dizimi özeti
fields
istek parametresi değerinin biçimi, XPath söz dizimine dayanır. Desteklenen söz dizimi aşağıda özetlenmiştir ve aşağıdaki bölümde ek örnekler verilmiştir.
- Birden fazla alan seçmek için virgülle ayrılmış bir liste kullanın.
a
iç içe yerleştirilmiş birb
alanını seçmek içina/b
kullanın;b
içine yerleştirilmişc
alanını seçmek içina/b/c
kullanın.
İstisna: Yanıtın
data: { ... }
gibi görünen birdata
nesnesinin içine yerleştirilmiş olduğu ""sarmalayıcı" kullanan API yanıtları içinfields
spesifikasyonuna "data
" dahil etmeyin. Veri nesnesinindata/a/b
gibi bir alan spesifikasyonuyla eklenmesi hataya neden olur. Bunun yerine,a/b
gibi birfields
spesifikasyonu kullanın.- İfadeleri veya nesneleri parantez içine alarak bir dizi alt alan belirlemek için alt seçici kullanın.
( )
".Örneğin:
fields=items(id,author/email)
, öğe dizisindeki her bir öğe için yalnızca öğe kimliğini ve yazarın e-posta adresini döndürür. Ayrıcafields=items(id)
,fields=items/id
ile eşdeğer olan tek bir alt alan da belirtebilirsiniz. - Gerekirse alan seçimlerinde joker karakter kullanın.
Örneğin:
fields=items/pagemap/*
, sayfa haritasındaki tüm nesneleri seçer.
Alanlar parametresini kullanmaya ilişkin diğer örnekler
Aşağıdaki örnekler, fields
parametre değerinin yanıtı nasıl etkilediğini açıklayan açıklamalar içerir.
Not: Tüm sorgu parametresi değerlerinde olduğu gibi fields
parametre değeri de URL olarak kodlanmalıdır. Daha iyi okunabilirlik için bu dokümandaki örneklerde kodlama göz ardı edilir.
- Döndürülmesini istediğiniz alanları belirleyin veya alan seçimleri yapın.
fields
istek parametresi değeri alanların virgülle ayrılmış bir listesidir ve her alan, yanıtın köküne göre belirtilir. Dolayısıyla, bir liste işlemi yapıyorsanız yanıt bir koleksiyondur ve genellikle bir dizi kaynak içerir. Tek bir kaynağı döndüren bir işlem gerçekleştiriyorsanız alanlar bu kaynağa göre belirtilir. Seçtiğiniz alan bir diziyse (veya parçasıysa) sunucu, dizideki tüm öğelerin seçilen kısmını döndürür.
Koleksiyon düzeyinde bazı örnekler:
Örnekler Efekt items
Öğeler dizisindeki her bir öğe alanı dahil olmak üzere öğe dizisindeki tüm öğeleri döndürür, ancak diğer alanları döndürmez. etag,items
Hem etag
alanını hem de items dizisindeki tüm öğeleri döndürür.items/title
items dizisindeki tüm öğeler için yalnızca title
alanını döndürür.
İç içe yerleştirilmiş bir alan her döndürüldüğünde yanıt, çevreleyen üst nesneleri içerir. Üst alanlar, açıkça seçilmediği sürece diğer alt alanları içermez.context/facets/label
Kendisi context
nesnesinin altında yer alanfacets
dizisinin tüm üyeleri için yalnızcalabel
alanını döndürür.items/pagemap/*/title
Öğeler dizisindeki her bir öğe için, pagemap
öğesinin alt öğeleri olan tüm nesnelerin yalnızcatitle
alanını (varsa) döndürür.
Kaynak düzeyiyle ilgili bazı örnekleri aşağıda bulabilirsiniz:
Örnekler Efekt title
İstenen kaynağın title
alanını döndürür.author/uri
İstenen kaynaktaki author
nesnesininuri
alt alanını döndürür.links/*/href
links
öğesinin alt öğeleri olan tüm nesnelerinhref
alanını döndürür.- Alt seçimleri kullanarak belirli alanların yalnızca bölümlerini isteyin.
- Varsayılan olarak, isteğinizde belirli alanlar belirtiliyorsa sunucu, nesneleri veya dizi öğelerini bütünüyle döndürür. Yalnızca belirli alt alanları içeren bir yanıt belirtebilirsiniz. Bunun için aşağıdaki örnekte olduğu gibi"
( )
"alt seçim söz dizimini kullanırsınız.Örnek Efekt items(title,author/uri)
items dizisindeki her bir öğe için yalnızca title
ve author\s39;suri
değerlerini döndürür.
Kısmi yanıtları işleme
Sunucu, fields
sorgu parametresini içeren geçerli bir isteği işledikten sonra, istenen verilerle birlikte bir HTTP 200 OK
durum kodu geri gönderir. fields
sorgu parametresinde bir hata varsa veya geçersizse sunucu, HTTP 400 Bad Request
durum kodunu ve kullanıcıya alan seçimiyle ilgili sorunun ne olduğunu (örneğin, "Invalid field selection a/b"
) belirten bir hata mesajı döndürür.
Yukarıdaki giriş bölümü bölümünde gösterilen kısmi yanıt örneği aşağıda verilmiştir. İstek, döndürülecek alanları belirtmek için fields
parametresini kullanır.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Kısmi yanıt şu şekilde görünür:
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Not: Verileri sayfalara ayırma için sorgu parametrelerini (ör. maxResults
ve nextPageToken
) destekleyen API'ler söz konusu olduğunda, her bir sorgunun sonuçlarını yönetilebilir bir boyuta indirmek için bu parametreleri kullanın. Aksi takdirde, kısmi yanıtın mümkün olduğu durumlarda performans artışı gerçekleşmeyebilir.
Yama (kısmi güncelleme)
Kaynaklarda değişiklik yaparken gereksiz veriler göndermekten de kaçınabilirsiniz. Yalnızca değiştirdiğiniz belirli alanlar için güncellenmiş veriler göndermek istiyorsanız HTTP PATCH
fiilini kullanın. Bu dokümanda açıklanan yama semantiği, kısmi güncellemenin eski GData uygulaması için yapılandan farklı (ve daha basittir).
Aşağıdaki kısa örnek, yama kullanımının, küçük bir güncelleme yapmak için göndermeniz gereken verileri nasıl en aza indirdiğini göstermektedir.
Örnek
Bu örnekte, yalnızca genel (kurgusal) &Demo" API kaynağının başlığını güncellemek için basit bir yama isteği gösterilmektedir. Kaynağın da bir yorumu, bir dizi özelliği, durumu ve daha başka alanları da vardır ancak bu istek yalnızca title
alanını gönderir. Çünkü değiştirilen alan budur.
PATCH https://www.googleapis.com/demo/v1/324 Authorization: Bearer your_auth_token Content-Type: application/json { "title": "New title" }
Yanıt:
200 OK
{ "title": "New title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }
Sunucu, 200 OK
kaynağının durum kodunu ve güncellenmiş kaynağın tam temsilini döndürür. Yama isteğine yalnızca title
alanı eklendiğinden bu, öncekinden farklı olan tek değerdir.
Not: Kısmi yanıt fields
parametresini yama ile birlikte kullanırsanız güncelleme isteklerinizin verimliliğini daha da artırabilirsiniz. Bir yama isteği yalnızca isteğin boyutunu küçültür. Kısmi yanıt, yanıtın boyutunu küçültür. Bu nedenle, her iki yönde gönderilen veri miktarını azaltmak için bir yama isteği kullanarak fields
parametresi kullanın.
Yama isteğinin semantiği
Yama isteğinin gövdesinde yalnızca değiştirmek istediğiniz kaynak alanları yer alır. Bir alan belirttiğinizde, çevresindeki üst nesneleri de (ör. çevreleyen ebeveynler) kısmi bir yanıtla döndürülmesi gerekir. Gönderdiğiniz değiştirilmiş veriler, varsa ana nesnenin verileriyle birleştirilir.
- Ekle: Henüz var olmayan bir alan eklemek için yeni alanı ve değerini belirtin.
- Değiştir: Mevcut bir alanın değerini değiştirmek için alanı belirtin ve yeni değere ayarlayın.
- Sil: Bir alanı silmek için alanı belirtin ve
null
olarak ayarlayın. Örneğin,"comment": null
. Nesnenin tamamını (varsa),null
değerine ayarlayarak da silebilirsiniz. Java API İstemci Kitaplığı'nı kullanıyorsanız bunun yerineData.NULL_STRING
'yi kullanın. Ayrıntılar için JSON null sayfasına göz atın.
Diziler hakkında not: Dizi içeren yama istekleri, mevcut diziyi sağladığınız diziyle değiştirir. Dizideki öğeleri özet halinde değiştiremez, ekleyemez veya silemezsiniz.
Okuma-değiştirme-yazma döngüsünde yama kullanma
Değiştirmek istediğiniz verilerle kısmi bir yanıt alarak işe başlamanız faydalı bir uygulama olabilir. Kaynağı başarılı bir şekilde güncellemek için If-Match
HTTP üst bilgisinde geçerli ETag değerini sağlamanız gerektiğinden bu özellikle ETag kullanan kaynaklar için önemlidir. Verileri aldıktan sonra, değiştirmek istediğiniz değerleri değiştirebilir ve değiştirilen kısmi gösterimi bir yama isteğiyle geri gönderebilirsiniz. Demo kaynağının ETag etiketleri kullandığını varsayan bir örneği aşağıda bulabilirsiniz:
GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token
Kısmi yanıt şu şekildedir:
200 OK
{ "etag": "ETagString" "title": "New title" "comment": "First comment.", "characteristics": { "length": "short", "level": "5", "followers": ["Jo", "Will"], } }
Aşağıdaki yama isteği, bu yanıta dayanmaktadır. Aşağıda gösterildiği gibi, yama yanıtında döndürülen verileri sınırlandırmak için fields
parametresini de kullanır:
PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json If-Match: "ETagString"
{ "etag": "ETagString" "title": "", /* Clear the value of the title by setting it to the empty string. */ "comment": null, /* Delete the comment by replacing its value with null. */ "characteristics": { "length": "short", "level": "10", /* Modify the level value. */ "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */ "accuracy": "high" /* Add a new characteristic. */ }, }
Sunucu, 200 OK HTTP durum kodu ve güncellenmiş kaynağın kısmi bir temsili ile yanıt verir:
200 OK
{ "etag": "newETagString" "title": "", /* Title is cleared; deleted comment field is missing. */ "characteristics": { "length": "short", "level": "10", /* Value is updated.*/ "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */ "accuracy": "high" /* New characteristic is present. */ } }
Doğrudan yama isteği oluşturma
Bazı yama istekleri için bu istekleri daha önce aldığınız verilere dayandırmanız gerekir. Örneğin, bir diziye öğe eklemek ve mevcut dizi öğelerinin hiçbirini kaybetmek istemiyorsanız öncelikle mevcut verileri almanız gerekir. Benzer şekilde, bir API ETag kullanıyorsa, kaynağı başarılı bir şekilde güncellemek için önceki ETag değerini isteğinizle birlikte göndermeniz gerekir.
Not: ETag etiketleri kullanılırken bir yamanın uygulanmasını zorunlu kılmak için bir "If-Match: *"
HTTP üst bilgisi kullanabilirsiniz. Bunu yaparsanız yazma işleminden önce okumanız gerekmez.
Ancak diğer durumlarda, önce mevcut verileri almadan, yama isteğini doğrudan oluşturabilirsiniz. Örneğin, bir alanı yeni bir değerle güncelleyen veya yeni bir alan ekleyen bir yama isteği kolaylıkla oluşturabilirsiniz. Aşağıda bununla ilgili bir örnek verilmiştir:
PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json { "comment": "A new comment", "characteristics": { "volume": "loud", "accuracy": null } }
Bu istekte, yorum alanında mevcut bir değer varsa yeni değer, üzerine yazılır. Aksi takdirde yeni değere ayarlanır. Benzer şekilde, hacim özelliği varsa değerin üzerine yazılır; oluşturulmadıysa oluşturulur. Ayarlanmışsa doğruluk alanı kaldırılır.
Bir yama yanıtı işleme
Geçerli bir yama isteği işlendikten sonra, API bir 200 OK
HTTP yanıt kodu ve değiştirilen kaynağın tam temsilini döndürür. ETag'ler API tarafından kullanılırsa yama isteğini başarılı bir şekilde işlediğinde sunucu ETag değerlerini günceller. Bunun için PUT
örneğinde olduğu gibi.
Yama isteği, döndürdüğü veri miktarını azaltmak için fields
parametresini kullanmadığınız sürece kaynak temsilinin tamamını döndürür.
Bir yama isteği söz dizimsel veya semantik olarak geçersiz olan yeni bir kaynak durumuyla sonuçlanırsa, sunucu 400 Bad Request
veya 422 Unprocessable Entity
HTTP durum kodu döndürür ve kaynak durumu değişmeden kalır. Örneğin, gerekli bir alanın değerini silmeye çalışırsanız sunucu bir hata döndürür.
YAMA HTTP fiilinin desteklenmediği alternatif notasyon
Güvenlik duvarınız HTTP PATCH
isteklerine izin vermiyorsa bir HTTP POST
isteği yapın ve aşağıda gösterildiği gibi geçersiz kılma başlığını PATCH
olarak ayarlayın:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
Yama ile güncelleme arasındaki fark
Pratikte, HTTP PUT
fiilini kullanan bir güncelleme isteği için veri gönderdiğinizde, yalnızca zorunlu veya isteğe bağlı alanları göndermeniz gerekir; sunucu tarafından ayarlanan alanlar için değer gönderirseniz bu alanlar yok sayılır. Bu kısmi bir güncellemenin başka bir yolu gibi görünse de bu yaklaşımın bazı sınırlamaları vardır. HTTP PUT
fiilini kullanan güncellemelerde, gerekli parametreleri sağlamazsanız istek başarısız olur ve isteğe bağlı parametreler sağlamazsanız, daha önce ayarlanmış olan veriler temizlenir.
Bu nedenle yama kullanmak çok daha güvenlidir. Yalnızca değiştirmek istediğiniz alanlara ait verileri sağlarsınız; dahil etmediğiniz alanlar silinmez. Bu kuralın tek istisnası, yinelenen öğeler veya diziler olabilir. Bunların tümünü atlarsanız olduğu gibi kalırlar. Bunlardan herhangi birini sağlarsanız tüm grup, sağladığınız grupla değiştirilir.