Performans ipuçları

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. Bu, sonuçların sıkıştırmasını açmak için ek CPU süresi gerektirse de ağ maliyetleriyle başa çıkmak genellikle çok zaman alır.

gzip kodlu bir yanıt almak için iki şey yapmanız gerekir: Accept-Encoding üstbilgisi 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ı aktarmak, ayrıştırmak ve depolamaktan kaçınarak ağ, CPU ve bellek gibi kaynakları daha verimli bir şekilde kullanabilir.

Kısmi yanıt

Varsayılan olarak sunucu, istekleri işlendikten sonra kaynağın tam temsilini geri gönderir. Daha iyi performans için sunucudan yalnızca gerçekten ihtiyaç duyduğunuz alanları göndermesini isteyebilir ve bunun yerine kısmi bir yanıt alabilirsiniz.

Kısmi bir 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 herhangi bir istekle kullanabilirsiniz.

Örnek

Aşağıdaki örnekte, fields parametresinin genel (kurmaca) "Demo" ile kullanımı gösterilmektedir API'ye gidin.

Basit istek: Bu HTTP GET isteği, fields parametresini atlar ve tam kaynağı döndürür.

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

Tam kaynak yanıtı: Tam kaynak verileri, aşağıdaki alanların yanı sıra kısaltılması için atlanan diğer 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 gönderilen aşağıdaki istek, döndürülen veri miktarını önemli ölçüde azaltmak amacıyla fields parametresini kullanı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 ve her öğede sadece HTML başlığı ile uzunluk karakteristik bilgilerini içeren sadeleştirilmiş bir öğe dizisi içeren bir yanıt 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ı 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 verilmiştir.

Alan parametresi söz dizimi özeti

fields istek parametresi değerinin biçimi genel olarak XPath söz dizimine bağlıdır. Desteklenen söz dizimi aşağıda özetlenmiştir ve daha fazla örnek aşağıda verilmiştir.

• Birden çok alan seçmek için virgülle ayrılmış liste kullanın.
• a alanı içine yerleştirilmiş bir b alanını seçmek için a/b öğesini kullanın; b içine iç içe yerleştirilmiş bir c alanını seçmek için a/b/c kullanın.
  

  İstisna: "data" (veri) kullanan API yanıtları için Yanıtın data: { ... } gibi görünen bir data nesnesinin içine yerleştirildiği sarmalayıcılar "data" içermez fields spesifikasyonunda. Veri nesnesini data/a/b gibi bir alan spesifikasyonuyla eklemek hataya neden olur. Bunun yerine, a/b gibi bir fields spesifikasyonu kullanın.

• İfadeleri parantez içine yerleştirerek dizi veya nesnelerin belirli bir alt alanını istemek için bir alt seçici kullanın "( )".

  Örneğin: fields=items(id,author/email), items dizisindeki her bir öğe için yalnızca öğe kimliğini ve yazarın e-postasını 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/*, sayfa haritasındaki tüm nesneleri seçer.

Domains parametresini kullanmayla ilgili 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 de URL kodlamalı olmalıdır. Okunabilirliği artırmak için bu belgedeki örneklerde kodlamaya yer verilmemiştir.

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. Bu nedenle, bir list işlemi gerçekleştiriyorsanız yanıt bir koleksiyon olur 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çilen bölümünü döndürür.
.
. Koleksiyon düzeyinden bazı örnekler:

Örnekler	Etki
items	Her bir öğ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 kendilerini çevreleyen üst nesneleri içerir. Üst alanlar, açıkça seçilmediği sürece başka hiçbir alt alanı içermez.
context/facets/label	context nesnesinin altında bulunan facets dizisinin tüm üyeleri için yalnızca label alanını döndürür.
items/pagemap/*/title	items dizisindeki her bir öğe için yalnızca pagemap öğesinin alt öğesi olan tüm nesnelerin title alanını (varsa) döndürür.

. Kaynak düzeyinden bazı örnekler:

Örnekler	Etki
title	İstenen kaynağın title alanını döndürür.
author/uri	İstenen kaynaktaki 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 yalnızca belirli alanların belirli kısımlarını isteyin.

Varsayılan olarak, isteğinizde belirli alanlar belirtilmişse sunucu, nesneleri veya dizi öğelerini olduğu gibi döndürür. Yalnızca belirli alt alanları içeren bir yanıt belirtebilirsiniz. Bu işlemi "( )" kullanarak yaparsınız alt seçim söz dizimini kullanabilirsiniz.

Örnek	Etki
items(title,author/uri)	items dizisindeki her bir öğ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 hata varsa veya başka bir şekilde geçersizse sunucu, kullanıcıya alan seçimiyle ilgili sorunun ne olduğunu bildiren bir hata mesajıyla birlikte 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, 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 aşağıdaki gibi 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 sorgu parametrelerini destekleyen API'lerde (örneğin, maxResults ve nextPageToken) her sorgunun sonuçlarını yönetilebilir bir boyuta küçültmek için bu parametreleri kullanın. Aksi takdirde, kısmi yanıtta elde edilecek performans artışı gerçekleşmeyebilir.