Performans ipuçları

Bu dokümanda, uygulamanızın performansını artırmak için kullanabileceğiniz bazı teknikler ele alınmaktadır. Bazı durumlarda, sunulan fikirleri açıklamak için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak aynı kavramlar Google Fotoğraflar API'leri 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ı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 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 doğru şekilde oluşturulmuş HTTP üstbilgilerini gösteren örnek:

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 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 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 (hayali) bir "Demo" API ile kullanımı gösterilmektedir.

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, 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çilen alanları ve bunları kapsayan üst öğeleri 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.

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 daha fazla örnek aşağıda verilmiştir.

Birden çok alan seçmek için virgülle ayrılmış liste kullanın.
a alanında iç içe yerleştirilmiş bir b alanını seçmek için a/b'ü, b alanında iç içe yerleştirilmiş bir c alanını seçmek için a/b/c'ı kullanın.

İstisna: Yanıtın data: { ... } gibi görünen bir data nesnesi içine yerleştirildiği "data" sarmalayıcıları kullanan API yanıtları için fields spesifikasyonuna "data" eklemeyin. Veri nesnesini data/a/b gibi bir alan spesifikasyonuyla dahil etmek hataya neden olur. Bunun yerine a/b gibi bir fields spesifikasyonu kullanın.
İfadeleri parantez içine alarak dizi veya nesnelerin belirli bir alt alanlarından oluşan bir grup istemek için bir 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, fields=items(id)'ün fields=items/id ile eşdeğer olduğu 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.

Domains parametresini kullanmayla ilgili diğer örnekler

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 kodlamalı olmalıdır. Bu dokümandaki örneklerde, okunabilirliği artırmak için kodlama atlanmıştır.

Döndürülmesini istediğiniz alanları tanımlayın 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ü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 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 öğe için `pagemap` öğesinin alt öğesi olan tüm nesnelerin yalnızca `title` 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` 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 bölümlerini 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. 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)`	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 kodunu geri 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 ş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ıtta elde edilecek performans artışı gerçekleşmeyebilir.