Bu dokümanda, uygulamanızın performansını artırmak için kullanabileceğiniz bazı teknikler ele alınmaktadır. Bazı durumlarda, sunulan fikirleri göstermek için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak, aynı kavramlar Google Slides API'si için de 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ı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 yararlıdır.
gzip kodlu bir yanıt almak için yapmanız gereken iki şey vardır: Bir Accept-Encoding
başlığı belirlemek ve kullanıcı aracınızı gzip
dizesini içerecek şekilde değiştirmek. Aşağıda, gzip sıkıştırmasını etkinleştirmek için düzgün şekilde oluşturulmuş HTTP üstbilgileri yer almaktadır:
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 başka bir yolu da verilerin yalnızca ilgilendiğiniz bölümünü istemektir. Böylece, uygulamanız gereksiz alanları aktarmak, ayrıştırmak ve depolamaktan kaçınabilir. Böylece ağ, CPU ve bellek gibi kaynakları daha verimli şekilde kullanabilir.
Kısmi yanıt
Varsayılan olarak sunucu, istekleri işledikten sonra kaynağın tam temsilini geri gönderir. Daha iyi performans için sunucudan yalnızca gerçekten ihtiyacınız olan alanları göndermesini ve bunun yerine kısmi yanıt almasını isteyebilirsiniz.
Kısmi yanıt istemek için, fields
isteği parametresini kullanarak döndürülmesini istediğiniz alanları belirtin. Bu parametreyi, yanıt verileri döndüren tüm isteklerde kullanabilirsiniz.
Örnek
Aşağıdaki örnekte fields
parametresinin genel (kurgusal) "Demo" API ile kullanımı gösterilmektedir.
Basit istek: Bu HTTP GET
isteği, fields
parametresini çıkarır ve tüm kaynağı döndürür.
https://www.googleapis.com/demo/v1
Tam kaynak yanıtı: Kaynak verilerinin tamamı, kısa olması için çıkarılan diğerlerin 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 isteme: Aynı kaynak için aşağıdaki istek, döndürülen veri miktarını önemli ölçüde azaltmak üzere 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 öğe türü bilgilerini içeren bir yanıt ile birlikte 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 bunlara ilişkin üst nesneleri içeren bir JSON nesnesi olduğunu unutmayın.
fields
parametresinin nasıl biçimlendirileceğiyle ilgili ayrıntılara ek olarak yanıtta tam olarak nelerin döndürüldüğüyle ilgili ayrıntılara yer verilmiştir.
Alanlar parametresi söz dizimi özeti
fields
istek parametresi değerinin biçimi XPath söz dizimine dayalıdır. Desteklenen söz dizimi aşağıda özetlenmiştir. Ek bölümde aşağıdaki örnekler verilmiştir.
- Birden çok alan seçmek için virgülle ayrılmış bir liste kullanın.
a
alanının içine yerleştirilmişb
alanını seçmek içina/b
kullanın.b
alanının içine yerleştirilmişc
alanını seçmek içina/b/c
tuşunu kullanın.
İstisna:
data: { ... }
gibi görünen birdata
nesnesinin içine yerleştirilmiş "veriler" sarmalayıcılarını kullanan API yanıtları içinfields
spesifikasyonuna "data
" eklemeyin. Veri nesnesinindata/a/b
gibi bir alan spesifikasyonuyla eklenmesi hataya neden olur. Bunun yerinea/b
gibi birfields
spesifikasyonu kullanın.- İfadeleri "
( )
" içine yerleştirerek bir dizi veya nesneden oluşan belirli bir alt alanı istemek için bir 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-postasını 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 karakterler 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 örneklerde, fields
parametre değerinin yanıtı nasıl etkilediğiyle ilgili açıklamalar bulunmaktadır.
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 yer almaz.
- Geri 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ış listesidir. Her alan, yanıtın kök dizinine 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 kaynak döndüren bir işlem yapıyorsanız alanlar bu kaynağa göre belirtilir. Seçtiğiniz alan bir diziyse (veya bir dizi parçasıysa) sunucu, dizideki tüm öğelerin seçilen kısmını döndürür.
Koleksiyon düzeyinde örneklerden bazıları:
Örnekler Etki items
Her bir öğedeki tüm alanlar 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 bir şekilde seçilmediği sürece diğer alt alanları da içermez.context/facets/label
facets
dizisinin tüm üyeleri için yalnızcalabel
alanını döndürür. Bu alan,context
nesnesinin altında iç içe yerleştirilmiştir.items/pagemap/*/title
items dizisindeki her bir öğe için yalnızca pagemap
alt öğesi olan tüm nesnelerintitle
alanını (varsa) döndürür.
Kaynak düzeyiyle ilgili 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
alt öğesi olan tüm nesnelerinhref
alanını döndürür.- Alt seçimleri kullanarak belirli alanların yalnızca belirli bölümlerini isteyin.
- Varsayılan olarak, isteğiniz belirli alanları belirtiyorsa sunucu, nesneleri veya dizi öğelerini bütünüyle döndürür. Yalnızca belirli alt alanları içeren bir yanıt belirtebilirsiniz. Bu işlemi aşağıdaki örnekte olduğu gibi "
( )
" alt seçim söz dizimini kullanarak yapabilirsiniz.Örnek Etki items(title,author/uri)
items dizisindeki her bir öğe için yalnızca title
ve yazarınuri
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 başka bir nedenle geçersizse sunucu, kullanıcıya alan seçimiyle ilgili sorunu belirten bir hata mesajıyla birlikte (ör. "Invalid field selection a/b"
) HTTP 400 Bad Request
durum kodu döndürür.
Yukarıdaki giriş bölümünde gösterilen kısmi yanıt örneğini burada bulabilirsiniz. İstek, hangi alanların döndürüleceğini belirtmek için fields
parametresini kullanır.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Kısmi yanıt şöyle görünür:
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Not: Veri sayfalandırma için sorgu parametrelerini (ör. maxResults
ve nextPageToken
) destekleyen API'lerde her sorgu için sonuçları yönetilebilir bir boyuta indirmek üzere bu parametreleri kullanın. Aksi takdirde, kısmi yanıtla elde edilebilecek performans artışları gerçekleşmeyebilir.