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

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 Tasks 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 kullanışlı bir yolu da gzip sıkıştırmayı etkinleştirmektir. Sonuçları açmak için ek CPU zamanı gerektirse de ağ maliyetlerinin dengelenmesi genellikle buna çok değer.

gzip olarak kodlanmış 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 düzgün şekilde biçimlendirilmiş bir HTTP üstbilgileri ö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 bölümünü gönderip almaktır. 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.

İ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 bir güncelleme isteği (PATCH HTTP fiilini kullanın).

Kısmi isteklerde bulunmayla ilgili daha ayrıntılı bilgiyi aşağıdaki bölümlerde bulabilirsiniz.

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 isteyip bunun yerine kısmi yanıt almasını isteyebilirsiniz.

Kısmi yanıt istemek için fields istek parametresini kullanarak döndürülmesini istediğiniz alanları belirtin. Bu parametreyi, yanıt verilerini döndüren tüm isteklerle kullanabilirsiniz.

fields parametresinin yalnızca yanıt verilerini etkilediğini, varsa göndermeniz gereken verileri 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) 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, aşağıdaki alanların yanı sıra kısa olması nedeniyle çıkarılan diğer birçok alanı 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 öğede yalnızca HTML başlığı 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.

Sonraki bölümde, fields parametresinin nasıl biçimlendirileceğiyle ilgili ayrıntılar, ardından yanıtta tam olarak nelerin döndürüldüğüne ilişkin ayrıntılar ele alınmıştır.

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 ek örnekler sonraki bölümde 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 operatörünü, b içine yerleştirilmiş bir c alanını seçmek için a/b/c politikasını kullanın.

İstisna: Yanıtın data: { ... } gibi görünen bir data nesnesinin içine yerleştirildiği "veri" 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 olur. Bunun yerine, a/b gibi bir fields spesifikasyonu kullanın.
"( )" parantezine ifadeler yerleştirerek dizi veya nesnelerin belirli alt alanlarını istemek için 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, tek bir alt alan da belirtebilirsiniz. Burada 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.

Alanlar parametresini kullanmaya ilişkin daha fazla örnek

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 okunabilmesi 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, 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 diziyse (veya bir dizinin parçasıysa) sunucu, dizideki tüm öğelerin seçilen kısmını döndürür.

Koleksiyon düzeyinde 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, ç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ı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 `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çimleri kullanarak belirli alanların yalnızca bazı bölümlerini isteyin.

Varsayılan olarak, isteğiniz belirli alanları belirtiyorsa sunucu nesnelerin 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` 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 geçersizse sunucu, kullanıcıya alan seçimiyle ilgili sorunun ne olduğunu bildiren bir hata mesajıyla birlikte bir 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 sayfalandırmaya yönelik sorgu parametrelerini (örneğin, 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 kazançları gerçekleşmeyebilir.

Yama (kısmi güncelleme)

Ayrıca, kaynakları değiştirirken gereksiz veri göndermekten de kaçınabilirsiniz. Yalnızca değiştirdiğiniz belirli alanlar için güncellenmiş verileri göndermek isterseniz HTTP PATCH fiilini kullanın. Bu belgede açıklanan yama semantiği, eski GData kısmi güncelleme uygulamasına göre 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) bir "Demo" API kaynağının başlığını güncellemek için 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ştirilen 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ği için öncekinden farklı olan tek değer budur.

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

Yama isteğinin anlamı

Yama isteğinin gövdesinde yalnızca değiştirmek istediğiniz kaynak alanları yer alır. Bir alan belirttiğinizde, çevreleyen üst nesneleri kısmi yanıtla döndürüldüğü gibi çevreleyen tüm üst nesneleri de eklemeniz gerekir. Gönderdiğiniz değiştirilen veriler, varsa üst nesnenin verileriyle birleştirilir.

Ekle: Mevcut olmayan bir alanı eklemek için yeni alanı ve değerini belirtin.
Değiştir: Mevcut bir alanın değerini değiştirmek için alanı belirtin ve yeni değere ayarlayın.
Sil: Bir alanı silmek için alanı belirtin ve null olarak ayarlayın. Örneğin, "comment": null. Ayrıca, bir nesneyi null olarak ayarlayarak tamamen silebilirsiniz (değişebilirse). Java API İstemci Kitaplığı kullanıyorsanız bunun yerine Data.NULL_STRING kullanın. Ayrıntılar için JSON null bölümüne bakın.

Diziler hakkında not: Dizi içeren yama istekleri, mevcut diziyi sizin sağladığınız diziyle değiştirir. Bir dizideki öğeleri parçalı bir şekilde değiştiremez, ekleyemez veya silemezsiniz.

Yamayı okuma-değiştirme-yazma döngüsünde kullanma

Değiştirmek istediğiniz verileri içeren kısmi bir yanıt alarak başlamak faydalı olabilir. Bu, kaynağı başarılı bir şekilde güncellemek için If-Match HTTP başlığında geçerli ETag değerini sağlamanız gerektiğinden, ETag kullanan kaynaklar için özellikle önemlidir. Verileri aldıktan sonra, değiştirmek istediğiniz değerleri değiştirebilir ve değiştirilmiş kısmi gösterimi bir yama isteğiyle geri gönderebilirsiniz. Aşağıda, Demo kaynağının ETag kullandığını varsayan bir örnek verilmiştir:

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

Bu, kısmi yanıttır:

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 dayalıdır. Aşağıda gösterildiği gibi, yama yanıtında döndürülen verileri sınırlandırmak için fields parametresini de kullanı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 kodu ve güncellenen kaynağın kısmi temsili ile 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, daha önce aldığınız verileri temel almanız gerekir. Örneğin, diziye bir öğe eklemek ve mevcut dizi öğelerinin hiçbirini kaybetmek istemiyorsanız önce mevcut verileri almanız gerekir. Benzer şekilde, bir API ETags kullanıyorsa kaynağı başarıyla güncellemek için isteğinizle birlikte önceki ETag değerini göndermeniz gerekir.

Not: ETag'ler kullanımdayken bir yamayı uygulamaya zorlamak için "If-Match: *" HTTP üst bilgisi kullanabilirsiniz. Bunu yaparsanız yazmadan önce okuma işlemini yapmanız gerekmez.

Ancak diğer durumlarda yama isteğini, önce mevcut verileri almadan doğrudan oluşturabilirsiniz. Örneğin, bir alanı yeni bir değerle güncelleyen veya yeni bir alan ekleyen bir yama isteğini kolayca ayarlayabilirsiniz. Örnek:

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 istekle birlikte, yorum alanında mevcut bir değer varsa yeni değer bunun üzerine yazılır; aksi takdirde yeni değere ayarlanır. Benzer şekilde, bir hacim özelliği varsa değerinin üzerine yazılır; değilse bu özellik oluşturulur. Ayarlanırsa doğruluk alanı kaldırılır.

Yamaya verilen yanıtı işleme

API, geçerli bir yama isteğini işledikten sonra değiştirilen kaynağın tam temsiliyle birlikte bir 200 OK HTTP yanıt kodu döndürür. API tarafından ETag'ler kullanılıyorsa sunucu, yama isteğini başarıyla işlediğinde (PUT'de 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 tüm kaynak gösterimini döndürür.

Bir yama isteği söz dizimsel veya semantik olarak geçersiz yeni bir kaynak durumuyla sonuçlanırsa sunucu bir 400 Bad Request veya 422 Unprocessable Entity HTTP durum kodu döndürür ve kaynak durumu değişmeden kalır. Örneğin, zorunlu bir alanın değerini silmeye çalışırsanız sunucu bir hata döndürür.

YAMA HTTP fiili desteklenmediğinde alternatif gösterim

Güvenlik duvarınız HTTP PATCH isteklerine izin vermiyorsa aşağıda gösterildiği gibi bir HTTP POST isteği yapın ve 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önderirken, yalnızca zorunlu veya isteğe bağlı olan alanları göndermeniz gerekir. Sunucu tarafından ayarlanan alanlar için değer gönderirseniz bu alanlar yoksayılır. Bu yöntem kısmi güncelleme yapmanın başka bir yoluymuş gibi görünse de, bu yaklaşımda bazı sınırlamalar vardır. HTTP PUT fiilini kullanan güncellemelerde, gerekli parametreleri sağlamazsanız istek başarısız olur ve isteğe bağlı parametreleri sağlamazsanız önceden ayarlanmış verileri temizler.

Bu nedenle, yama kullanmak çok daha güvenlidir. Yalnızca değiştirmek istediğiniz alanlar için veri sağlarsınız; atladığınız alanlar temizlenmez. Bu kuralın tek istisnası, tekrarlanan öğeler veya dizilerle ilgilidir: Bunların tümünü atlarsanız oldukları gibi kalırlar; bunlardan herhangi birini sağlarsanız, tüm grup, sağladığınız kümeyle değiştirilir.