Bu sayfa, Cloud Translation API ile çevrilmiştir.

Performans İpuç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 göstermek için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak Books API için aynı kavramlar 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 bir başka yolu, ilgilendiğiniz verilerin yalnızca bir kısmını gönderip almaktır. 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.

İki tür kısmi istek vardır:

Kısmi yanıt: Yanıta hangi alanların dahil edileceğini belirttiğiniz bir istek (fields istek parametresini kullanın).
yama: Yalnızca değiştirmek istediğiniz alanları gönderdiğiniz güncelleme isteği (PATCH HTTP fiilini kullanın).

Kısmi istekte bulunmayla ilgili daha fazla ayrıntı aşağıdaki bölümlerde sağlanmıştır.

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.

fields parametresinin yalnızca yanıt verilerini etkilediğini, göndermeniz gereken verileri (varsa) etkilemediğini unutmayın. Kaynakları değiştirirken gönderdiğiniz veri miktarını azaltmak için yama isteği kullanın.

Ö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çin a/b kullanın. b alanının içine yerleştirilmiş c alanını seçmek için a/b/c tuşunu kullanın.

İstisna: data: { ... } gibi görünen bir data nesnesinin içine yerleştirilmiş "veriler" sarmalayıcılarını kullanan API yanıtları için fields spesifikasyonuna "data" eklemeyin. Veri nesnesinin data/a/b gibi bir alan spesifikasyonuyla eklenmesi hataya neden olur. Bunun yerine a/b gibi bir fields 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ıca fields=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ızca `label` 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 nesnelerin `title` 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` nesnesinin `uri` alt alanını döndürür.
`links/*/href`	`links` alt öğesi olan tüm nesnelerin `href` 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ın `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 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.

Yama (kısmi güncelleme)

Kaynakları değiştirirken gereksiz veriler göndermekten de kaçınabilirsiniz. Yalnızca değiştirdiğiniz belirli alanlar için güncellenmiş veriler göndermek üzere HTTP PATCH fiilini kullanın. Bu belgede açıklanan yama semantiği, kısmi güncellemenin eski GData uygulaması için kullanılandan farklı (ve daha basittir).

Aşağıdaki kısa örnek, yama kullanmanın küçük bir güncelleme yapmak için göndermeniz gereken verileri nasıl en aza indirdiğini göstermektedir.

Örnek

Bu örnekte, yalnızca genel (kurgusal) "Demo" API kaynağının başlığını güncellemeye yönelik basit bir yama isteği gösterilmektedir. Kaynakta ayrıca bir yorum, bir dizi özellik, durum ve daha birçok alan bulunur. Ancak bu istek, değişiklik yapılan tek alan olduğu için yalnızca title alanını gönderir:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Yanıt:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Sunucu, güncellenen kaynağın tam temsiliyle birlikte bir 200 OK durum kodu döndürür. Yama isteğine yalnızca title alanı dahil edildiğinden bu, öncekinden farklı olan tek değerdir.

Not: Kısmi yanıt fields parametresini yama ile birlikte kullanıyorsanız güncelleme isteklerinizin verimliliğini daha da artırabilirsiniz. Yama isteği yalnızca isteğin boyutunu azaltır. Kısmi yanıtlar, yanıtın boyutunu küçültür. Bu nedenle, her iki yönde gönderilen veri miktarını azaltmak için fields parametresiyle bir yama isteği kullanın.

Yama isteği semantiği

Yama isteğinin gövdesinde yalnızca değiştirmek istediğiniz kaynak alanları bulunur. Bir alan belirttiğinizde, çevreleyen üst nesneler kısmi yanıt ile döndürüldüğü gibi, bu nesneleri de dahil eden üst nesneleri dahil etmeniz gerekir. Gönderdiğiniz değiştirilmiş veriler, üst nesneye ait verilerle (varsa) birleştirilir.

Ekle: Henüz var olmayan bir alan eklemek için yeni alanı ve değerini belirtin.
Değiştirme: Mevcut bir alanın değerini değiştirmek için alanı belirtin ve yeni değere ayarlayın.
Silme: Bir alanı silmek için alanı belirtin ve null olarak ayarlayın. Örneğin, "comment": null. Nesnenin tamamını (değişebilirse) null değerine ayarlayarak da silebilirsiniz. Java API İstemci Kitaplığı'nı kullanıyorsanız bunun yerine Data.NULL_STRING kullanın. Ayrıntılar için JSON null başlıklı makaleye bakın.

Diziler hakkında not: Dizi içeren yama istekleri, mevcut diziyi, sağladığınız diziyle değiştirir. Dizideki öğeleri bölüm halinde değiştiremez, ekleyemez veya silemezsiniz.

Okuma-değiştirme-yazma döngüsünde yama kullanma

Değiştirmek istediğiniz verilerle kısmi bir yanıt alarak başlamanız yararlı olabilir. Kaynağı başarılı bir şekilde güncellemek için If-Match HTTP üst bilgisinde geçerli ETag değerini sağlamanız gerektiğinden, bu durum özellikle ETag kullanan kaynaklar için önemlidir. Verileri aldıktan sonra, değiştirmek istediğiniz değerleri değiştirebilir ve değiştirilen kısmi gösterimi yama isteğiyle tekrar gönderebilirsiniz. Demo kaynağında ETag'lerin kullanıldığını varsayan bir örneği aşağıda bulabilirsiniz:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Kısmi yanıt:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Aşağıdaki yama isteği bu yanıta dayanmaktadır. Aşağıda gösterildiği gibi, yama yanıtında döndürülen verileri sınırlamak için fields parametresi de kullanılır:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Sunucu 200 OK HTTP durum koduyla ve güncellenen kaynağın kısmi temsiliyle yanıt verir:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Doğrudan yama isteği oluşturma

Bazı yama istekleri için bunları daha önce aldığınız verilere dayandırmanız gerekir. Örneğin, bir diziye öğe eklemek istiyorsanız ve mevcut dizi öğelerinin hiçbirini kaybetmek istemiyorsanız önce mevcut verileri almanız gerekir. Benzer şekilde, EAPI kullanan bir API varsa kaynağı başarılı bir şekilde güncellemek için önceki ETag değerini isteğinizle birlikte göndermeniz gerekir.

Not: ETag'ler kullanılırken yama uygulamak için "If-Match: *" HTTP üst bilgisi kullanabilirsiniz. Bu işlemi yaparsanız yazma işleminden önce okuma işlemini gerçekleştirmeniz gerekmez.

Ancak diğer durumlarda, önce mevcut verileri almadan yama isteğini doğrudan oluşturabilirsiniz. Örneğin, bir alanı yeni değerle güncelleyen veya yeni bir alan ekleyen bir yama isteği oluşturabilirsiniz. Aşağıda bununla ilgili bir örnek verilmiştir:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Bu istek ile yorum alanında mevcut bir değer varsa yeni değer bu değerin üzerine yazar, aksi takdirde yeni değere ayarlanır. Benzer şekilde, hacim özelliği varsa değerinin üzerine yazılır. Aksi takdirde oluşturulur. Doğruluk alanı ayarlanmışsa ayarlanır.

Yamayla ilgili yanıtı işleme

Geçerli bir yama isteği işlendikten sonra API, değiştirilen kaynağın tam temsiliyle birlikte bir 200 OK HTTP yanıt kodu döndürür. ETag'ler API tarafından kullanılıyorsa sunucu bir yama isteğini başarılı bir şekilde işlediğinde (PUT'te olduğu gibi) ETag değerlerini günceller.

Yama isteği, döndürdüğü veri miktarını azaltmak için fields parametresini kullanmadığınız sürece kaynak temsilinin tamamını döndürür.

Yama isteği söz dizimsel veya semantik olarak geçersiz olan yeni bir kaynak durumuna neden olursa sunucu bir 400 Bad Request ya da 422 Unprocessable Entity HTTP durum kodu döndürür ve kaynak durumu değişmez. Örneğin, zorunlu bir alanın değerini silmeye çalışırsanız sunucu bir hata döndürür.

PATCH HTTP fiilinin desteklenmediği alternatif gösterim

Güvenlik duvarınız HTTP PATCH isteklerine izin vermiyorsa bir HTTP POST isteği yapın ve aşağıda gösterildiği gibi geçersiz kılma başlığını PATCH olarak ayarlayın:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Yama ve güncelleme arasındaki fark

Pratikte, HTTP PUT fiilini kullanan bir güncelleme isteği için veri gönderdiğinizde yalnızca zorunlu veya isteğe bağlı olan alanları göndermeniz gerekir. Sunucu tarafından ayarlanan alanlar için değer gönderirseniz bunlar yok sayılır. Kısmi güncelleme yapmak için başka bir yol gibi görünse de bu yaklaşım bazı sınırlamalar içermektedir. HTTP PUT fiilini kullanan güncellemelerde, gerekli parametreleri sağlamazsanız istek başarısız olur ve isteğe bağlı parametre sağlamamanız durumunda, daha önce ayarlanan verileri temizler.

Bu nedenle yama kullanmak çok daha güvenlidir. Yalnızca değiştirmek istediğiniz alanlarla ilgili verileri sağlarsınız. Dahil etmediğiniz alanlar silinmez. Bu kuralın tek istisnası tekrarlanan öğeler veya diziler olabilir: Bunların tümünü çıkarırsanız olduğu gibi kalırlar. Herhangi birini sağlarsanız tüm grup, sağladığınız grupla değiştirilir.