Performansı Artırma

Bu dokümanda, uygulamanızın performansını artırmak için kullanabileceğiniz bazı teknikler açıklanmaktadı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 Classroom API için de geçerlidir.

Gzip kullanarak sıkıştırma

Her bir istek için gereken bant genişliğini azaltmanın kolay ve rahat bir yolu gzip sıkıştırmasını etkinleştirmektir. Sonuçları açmak için ek CPU süresi gerekse de, ağ maliyetlerinin dengelenmesi genellikle çok değerlidir.

gzip kodlamalı bir yanıt almak için iki şey yapmanız gerekir: Bir Accept-Encoding üstbilgisi ayarlayın ve kullanıcı aracınızı gzip dizesini içerecek şekilde değiştirin. Burada, gzip sıkıştırmasını etkinleştirmek için doğru şekilde biçimlendirilmiş bir HTTP üst bilgisi örneği verilmiştir:

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 bir bölümünü istemektir. Böylece uygulamanız, gerekli olmayan alanları aktarmaktan, ayrıştırmaktan ve depolamaktan kaçınabilir. Böylece, ağ, CPU ve bellek gibi kaynakları daha verimli bir ş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 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 (kurmaca) "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ısa olması için atlanmış olan diğer birçok alanın yanı sıra aşağıdaki alanları da 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 aşağıdaki istekte, döndürülen veri miktarını önemli ölçüde azaltmak için fields parametresi kullanılı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 içeren bir yanıt ve her bir öğede yalnızca HTML başlık ve uzunluk karakteristik bilgilerini içeren ayrıştırılmış bir öğe dizisi 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ı çevreleyen ü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ılara, ardından yanıtta tam olarak nelerin döndürüldüğüne dair daha fazla bilgiye değineceğiz.

Alan parametresi söz dizimi özeti

fields istek parametresi değerinin biçimi genel olarak XPath söz dizimine dayalıdır. Desteklenen söz dizimi aşağıda özetlenmiş ve aşağıdaki bölümde ek örnekler 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ı seçmek için a/b tuşunu kullanın. b içinde iç içe yerleştirilmiş c alanını seçmek için a/b/c kullanın.

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

  • İfadeleri parantez "( )" içine yerleştirerek dizi veya nesnelerin belirli bir alt alanlarından oluşan bir küme 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 e-postasını döndürür. fields=items(id) değerinin fields=items/id olduğu 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.

Fields parametresini kullanmayla ilgili diğer örnekler

Aşağıdaki örneklerde, fields parametre değerinin yanıtı nasıl etkilediğiyle ilgili 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. Daha kolay okunabilirlik için bu belgedeki örneklerde kodlama kullanılmamaktadır.

Döndürülmesini istediğiniz alanları belirleyin 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. Dolayısıyla, bir liste 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 söz konusu kaynağa göre belirtilir. Seçtiğiniz alan bir dizinin parçasıysa (veya bir dizinin parçasıysa) sunucu, dizideki tüm öğelerin seçilen bölümünü döndürür.

Aşağıda, koleksiyon düzeyinde bazı örnekler verilmiştir:
Ö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 geçmiş 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 Kendisi context nesnesinin altına yerleştirilen 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 pagemap öğesinin alt öğesi olan tüm nesnelerin yalnızca title alanını (varsa) döndürür.

Kaynak düzeyinde 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 öğesi olan tüm nesnelerin href alanını döndürür.
Alt seçimler kullanarak belirli alanların yalnızca belirli bölümlerini isteyin.
Varsayılan olarak, isteğiniz belirli alanları belirtiyorsa sunucu, nesneleri veya dizi öğelerinin tamamını 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 yaparsınız.
Örnek Etki
items(title,author/uri) items dizisindeki her bir öğe için yalnızca title değerlerini ve yazar uri 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 hata varsa veya geçersizse sunucu, kullanıcıya alan seçiminde (örneğin, "Invalid field selection a/b") neyin yanlış olduğunu bildiren bir hata mesajıyla birlikte bir HTTP 400 Bad Request durum kodu döndürür.

Yukarıdaki giriş bölümünde gösterilen kısmi yanıt örneği aşağıda verilmiştir. İ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ırmaya yönelik sorgu parametrelerini (örneğin, maxResults ve nextPageToken) destekleyen API'lerde, her sorgunun sonuçlarını yönetilebilir bir boyuta düşürmek için bu parametreleri kullanın. Aksi takdirde, kısmi yanıtla olası performans kazanımları gerçekleşmeyebilir.