Bu dokümanda, uygulamanızın performansını iyileştirmek için kullanabileceğiniz bazı teknikler açıklanmaktadır. Bazı durumlarda, sunulan fikirleri açıklamak için diğer API’lerden veya genel API’lerden örnekler kullanılır. Ancak Google Classroom API için de aynı kavramlar geçerlidir.
gzip kullanarak sıkıştırma
Her istek için gereken bant genişliğini azaltmanın kolay ve kullanışlı bir yolu, gzip sıkıştırmasını etkinleştirmektir. Sonuçların sıkıştırmasını kaldırmak için ek CPU zamanı gerekir ancak ağ maliyetleriyle olan denge genellikle bu işlemin çok faydalı olmasını sağlar.
Gzip ile kodlanmış 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. gzip sıkıştırmasını etkinleştirmek için düzgün şekilde oluşturulmuş bir HTTP üstbilgileri örneğini burada bulabilirsiniz:
Accept-Encoding: gzip User-Agent: my program (gzip)
Kısmi kaynaklarla çalışma
API çağrılarınızın performansını artırmanın bir başka yolu da verilerin yalnızca ilgilendiğiniz kısmını istemektir. Bu sayede uygulamanız gereksiz alanları aktarmaktan, ayrıştırmaktan ve depolamaktan kaçınarak ağ, CPU ve bellek gibi kaynakları daha verimli kullanabilir.
Kısmi yanıt
Sunucu, istekleri işledikten sonra varsayılan olarak 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 yanıt alabilirsiniz.
Kısmi yanıt isteğinde bulunmak için döndürülmesini istediğiniz alanları belirtmek üzere fields
istek parametresini kullanın. Bu parametreyi, yanıt verileri döndüren tüm isteklerle kullanabilirsiniz.
Örnek
Aşağıdaki örnekte, fields
parametresinin genel (hayali) bir "Demo" API ile kullanımı gösterilmektedir.
Basit istek: Bu HTTP GET
isteği, fields
parametresini atlar ve kaynağın tamamını döndürür.
https://www.googleapis.com/demo/v1
Tam kaynak yanıtı: Tam kaynak verileri, kısalık için atlanan diğer birçok alanı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ı kaynağa yönelik aşağıdaki istek, döndürülen veri miktarını önemli ölçüde azaltmak için fields
parametresini kullanır.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Kısmi yanıt: Sunucu, yukarıdaki isteğe yanıt olarak yalnızca tür bilgilerini içeren bir yanıtın yanı sıra her öğede yalnızca HTML başlığı ve uzunluk özelliği bilgilerini içeren, sadeleştirilmiş bir öğeler 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 bunları kapsayan üst nesnelerini içeren bir JSON nesnesi olduğunu unutmayın.
Bir sonraki bölümde, fields
parametresinin nasıl biçimlendirileceğiyle ilgili ayrıntılar ve yanıtta tam olarak neyin döndürüleceği hakkında ayrıntılı bilgi yer almaktadır.
Alan 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. Aşağıdaki bölümde ek örnekler verilmiştir.
- Birden fazla alan seçmek için virgülle ayrılmış liste kullanın.
a
alanında iç içe yerleştirilmiş birb
alanını seçmek içina/b
'ü,b
alanında iç içe yerleştirilmiş birc
alanını seçmek içina/b/c
'ı kullanın.
İstisna: Yanıtın,
data: { ... }
gibi görünen birdata
nesnesinin içine yerleştirildiği "veri" sarmalayıcılarını kullanan API yanıtları içinfields
spesifikasyonuna "data
" ifadesini eklemeyin. Veri nesnesinidata/a/b
gibi bir alan spesifikasyonuyla eklemek hataya neden olur. Bunun yerinea/b
gibi birfields
spesifikasyonu kullanın.- İfadeleri paranteze "
( )
" yerleştirerek dizi veya nesnelerin belirli bir alt alan grubunu istemek için alt seçici kullanın.Örneğin:
fields=items(id,author/email)
, items dizisindeki her öğe için yalnızca öğe kimliğini ve yazarın e-posta adresini döndürür. Ayrıca tek bir alt alan da belirtebilirsiniz (fields=items(id)
,fields=items/id
ile eşdeğerdir). - Gerekirse alan seçimlerinde joker karakterler kullanın.
Örneğin:
fields=items/pagemap/*
, bir sayfa haritasındaki tüm nesneleri seçer.
fields parametresinin kullanıldığı diğer örnekler
Aşağıdaki örneklerde, fields
parametre değerinin yanıtı nasıl etkilediğine dair açıklamalar yer almaktadır.
Not: Tüm sorgu parametresi değerlerinde olduğu gibi, fields
parametre değeri URL olarak kodlanmalıdır. Okunabilirliği artırmak için bu belgedeki örneklerde kodlamaya yer verilmemiştir.
- Döndürülmesini istediğiniz alanları tanımlayın veya alan seçimleri yapın.
fields
istek parametresi değeri, virgülle ayrılmış bir alan listesidir ve her alan, yanıtın köküne göre belirtilir. Bu nedenle, liste işlemi gerçekleştiriyorsanız yanıt bir koleksiyondur ve genellikle bir dizi kaynak içerir. Tek bir kaynak döndüren bir işlem gerçekleştiriyorsanız alanlar bu kaynağa göre belirtilir. Seçtiğiniz alan bir diziyse (veya dizinin parçasıysa) sunucu, dizideki tüm öğelerin seçili kısmını döndürür.
Koleksiyon düzeyinde bazı örnekleri aşağıda bulabilirsiniz:
Örnekler Etki items
Her öğedeki tüm alanlar dahil olmak üzere items 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 döndürüldüğünde yanıt, kapsayıcı üst nesneleri içerir. Üst alanlar, açıkça seçilmediği sürece başka alt alanları içermez.context/facets/label
facets
dizisinin tüm üyeleri için yalnızcalabel
alanını döndürür. Bu alan dacontext
nesnesi altında iç içe yerleştirilmiştir.items/pagemap/*/title
items dizisindeki her öğe için pagemap
öğesinin alt öğesi olan tüm nesnelerin yalnızcatitle
alanını (varsa) döndürür.
Kaynak düzeyinde bazı örnekleri aşağıda bulabilirsiniz:
Örnekler Etki 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 öğesi olan tüm nesnelerinhref
alanını döndürür.- Alt seçimleri kullanarak yalnızca belirli alanların belirli bölümlerini isteyin.
- İsteğiniz belirli alanları belirtiyorsa sunucu varsayılan olarak nesneleri veya dizi öğelerini tamamen döndürür. Yalnızca belirli alt alanları içeren bir yanıt belirtebilirsiniz. Bunu, aşağıdaki örnekte olduğu gibi "
( )
" alt seçim söz dizimini kullanarak yaparsınız.Örnek Etki items(title,author/uri)
items dizisindeki her öğe için yalnızca title
ve yazarınuri
değerlerini döndürür.
Kısmi yanıtları işleme
Bir sunucu, fields
sorgu parametresini içeren geçerli bir isteği işledikten sonra istenen verilerle birlikte bir HTTP 200 OK
durum kodunu geri gönderir. fields
sorgu parametresinde hata varsa veya parametre geçersizse sunucu, kullanıcıya alan seçiminde neyin yanlış olduğunu belirten bir hata mesajıyla birlikte bir HTTP 400 Bad Request
durum kodu döndürür (örneğin, "Invalid field selection a/b"
).
Yukarıdaki giriş bölümünde gösterilen kısmi yanıt örneğini burada bulabilirsiniz. İ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: Veri sayfalandırması için sorgu parametrelerini destekleyen API'lerde (ör. maxResults
ve nextPageToken
), her sorgunun sonuçlarını yönetilebilir bir boyuta indirmek için bu parametreleri kullanın. Aksi takdirde, kısmi yanıtla elde edilebilecek performans kazanımları elde edilemeyebilir.