Performans ipuçları

gzip ile sıkıştırma

Her istek için gereken bant genişliğini azaltmanın kolay ve rahat bir yolu, gzip sıkıştırmayı etkinleştirmektir. Bu işlem, sonuçların sıkıştırılmasını açmak için ek CPU süresi gerektirse de ağ maliyetleriyle ilgili avantajları sayesinde genellikle çok faydalıdır.

Gzip kodlu bir yanıt almak için iki işlem yapmanız gerekir: Accept-Encoding üst bilgisini ayarlayın ve kullanıcı aracınızı gzip dizesini içerecek şekilde değiştirin. Gzip sıkıştırmayı etkinleştirmek için uygun şekilde oluşturulmuş HTTP üstbilgilerine dair bir örneği aşağıda 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 diğer yolu da yalnızca ilgilendiğiniz veri bölümü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

Varsayılan olarak, sunucu istekleri işledikten sonra bir kaynağın tam gösterimini 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 istemek için fields istek parametresini kullanarak döndürülmesini istediğiniz alanları belirtin. Bu parametreyi, yanıt verisi döndüren tüm isteklerle kullanabilirsiniz.

Örnek

Aşağıdaki örnekte, fields parametresinin genel (kurgusal) bir "Demo" API ile kullanımı gösterilmektedir.

Basit istek: Bu HTTP GET isteğinde fields parametresi atlanır ve kaynağın tamamı döndürülür.

https://www.googleapis.com/demo/v1

Tam kaynak yanıtı: Tam kaynak verileri, kısa olması için çıkarılan 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ı kaynak için yapılan aşağıdaki istekte, döndürülen veri miktarını önemli ölçüde azaltmak üzere fields parametresi kullanılıyor.

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 ve her öğede yalnızca HTML başlığı ve uzunluk özelliği bilgilerini içeren, öğeler dizisinin kısaltılmış bir sürümünü geri 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çilen alanları ve bunları içeren üst nesneleri içeren bir JSON nesnesi olduğunu unutmayın.

fields parametresinin nasıl biçimlendirileceğiyle ilgili ayrıntılar bir sonraki bölümde, yanıtta tam olarak neyin döndürüldüğüyle ilgili daha fazla ayrıntı ise ondan sonraki bölümde ele alınmaktadır.

Alanlar parametresi söz dizimi özeti

fields istek parametresi değerinin biçimi, XPath söz dizimine kabaca dayanır. Desteklenen söz dizimi aşağıda özetlenmiştir. Ek örnekler ise sonraki bölümde verilmiştir.

• Birden fazla alan seçmek için virgülle ayrılmış bir liste kullanın.
• a/b simgesini kullanarak a alanı içine yerleştirilmiş bir b alanı seçin; a/b/c simgesini kullanarak b alanı içine yerleştirilmiş bir c alanı seçin.
  

  İstisna: Yanıtın data: { ... } gibi görünen bir data nesnesinin içine yerleştirildiği, "data" sarmalayıcılarını kullanan API yanıtları için fields spesifikasyonuna "data" ifadesini eklemeyin. data/a/b gibi bir alan belirtimiyle veri nesnesinin eklenmesi hataya neden olur. Bunun yerine, a/b gibi bir fields spesifikasyonu kullanın.

• Dizilerin veya nesnelerin belirli bir alt alan kümesini istemek için alt seçiciyi kullanın. İfadeleri parantez içine "( )" yerleştirin.

  Örneğin: fields=items(id,author/email), öğeler dizisindeki her öğe için yalnızca öğe kimliğini ve yazarın e-posta adresini döndürür. Ayrıca, fields=items(id) ile fields=items/id aynı anlama gelecek şekilde tek bir alt alan da belirtebilirsiniz.

• Gerekirse alan seçimlerinde joker karakterler kullanın.

  Örneğin: fields=items/pagemap/*, bir sayfa haritasındaki tüm nesneleri seçer.

Alanlar parametresini kullanmayla ilgili daha fazla örnek

Aşağıdaki örneklerde, fields parametre değerinin yanıtı nasıl etkilediği açıklanmaktadı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 belgedeki örneklerde kodlama atlanmıştır.

Döndürülmesini istediğiniz alanları belirleyin veya alan seçimi yapın.

fields istek parametresinin değeri, virgülle ayrılmış bir alan listesidir ve her alan, yanıtın köküne göre belirtilir. Bu nedenle, list işlemi gerçekleştiriyorsanız yanıt bir koleksiyondur ve genellikle bir kaynak dizisi 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 dizi ise (veya dizinin bir parçasıysa) sunucu, dizideki tüm öğelerin seçilen kısmını döndürür.

Aşağıda bazı koleksiyon düzeyinde örnekler verilmiştir:

Örnekler	Etki
items	Öğeler dizisindeki tüm öğeleri (her öğedeki tüm alanlar dahil) döndürür ancak başka alan döndürmez.
etag,items	Hem etag alanını hem de öğeler 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, kapsayan üst nesneleri içerir. Üst alanlar, açıkça seçilmedikleri sürece başka alt alan içermez.
context/facets/label	label alanını yalnızca facets dizisinin tüm üyeleri için döndürür. Bu dizi, context nesnesinin altında yer alır.
items/pagemap/*/title	Öğeler dizisindeki her öğe için, pagemap öğesinin alt öğeleri olan tüm nesnelerin yalnızca title alanı (varsa) döndürülür.

Kaynak düzeyinde bazı örnekler:

Örnekler	Etki
title	İstenen kaynağın title alanını döndürür.
author/uri	İstenen kaynakta author nesnesinin uri alt alanını döndürür.
links/*/href	links öğesinin alt öğeleri olan tüm nesnelerin href alanını döndürür.

Alt seçimleri kullanarak belirli alanların yalnızca bir kısmını isteyin.

Varsayılan olarak, isteğinizde belirli alanlar belirtiliyorsa sunucu, 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 gösterildiği gibi "( )" alt seçim söz dizimini kullanarak yaparsınız.

Örnek	Etki
items(title,author/uri)	Öğeler dizisindeki her öğe için yalnızca title ve yazarın uri 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 kodu gönderir. fields sorgu parametresinde bir hata varsa veya parametre başka bir şekilde geçersizse sunucu, HTTP 400 Bad Request durum koduyla birlikte kullanıcının alan seçimiyle ilgili sorunu (örneğin, "Invalid field selection a/b") bildiren bir hata mesajı döndürür.

Yukarıdaki giriş bölümünde gösterilen kısmi yanıt örneğini aşağıda 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 ş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 (ör. maxResults ve nextPageToken) destekleyen API'lerde, 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 artışları gerçekleşmeyebilir.