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

Performans ipuçları

Bu dokümanda, uygulamanızın performansını artırmak için kullanabileceğiniz bazı teknikler anlatılmaktadır. Bazı durumlarda, sunulan fikirleri göstermek için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak aynı kavramlar Directory API için de geçerlidir.

gzip ile 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. Sıkıştırılmış sonuçların açılması için ek CPU zamanı 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 düzgün şekilde oluşturulmuş 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ı iyileştirmenin 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 kullanabilir.

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

Kısmi yanıt: Yanıta dahil edilecek alanları belirttiğiniz bir istek (fields istek parametresini kullanın).
Düzeltme: 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 fazla 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 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.

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ı ve 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: Bu 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 sadece tür bilgilerini içeren bir yanıt ve her bir öğede sadece HTML başlığı ve uzunluk karakteristik bilgilerini içeren ayrıştırılmış bir items 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ı çevreleyen üst nesneleri 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, ardından yanıtta tam olarak nelerin döndürüldüğüne dair 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 bağlıdır. Desteklenen söz dizimi aşağıda özetlenmiş ve ek örnekler aşağıdaki bölümde 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ş bir b alanını seçmek için a/b tuşunu kullanın. b alanının içine yerleştirilmiş bir c alanını seçmek için a/b/c değerini 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" ifadesini eklemeyin. Veri nesnesini data/a/b gibi bir alan spesifikasyonuyla eklemek hataya neden olur. Bunun yerine, a/b gibi bir fields spesifikasyonu kullanın.
"( )" parantezine ifadeler yerleştirerek dizi veya nesnelerin belirli bir alt alan kümesini 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-postasını 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 parametresinin kullanımıyla ilgili daha fazla örnek

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 URL kodlamalı olmalıdır. Daha iyi 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. Bu nedenle, bir liste işlemi gerçekleştiriyorsanız yanıt bir koleksiyondur 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.

Aşağıda, koleksiyon düzeyinde bazı örnekler verilmiştir:

Örnekler	Etki
`items`	Öğeler dizisindeki her bir öğedeki tüm alanlar dahil olmak üzere tüm öğeleri döndürür ancak başka hiçbir alan 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, ilişkili ü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 iç içe yerleştirilmiş olan `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` 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` alt öğesi olan tüm nesnelerin `href` alanını döndürür.

Alt seçimler kullanarak belirli alanların yalnızca bazı 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 öğe için yalnızca `title` değerlerini ve yazarın `uri` değerini 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 gönderir. fields sorgu parametresinde hata varsa veya geçersizse sunucu, kullanıcıya alan seçimiyle ilgili sorunu bildiren bir hata mesajıyla (örneğin, "Invalid field selection a/b") 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ğ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ırmaya yönelik sorgu parametrelerini (örneğin, maxResults ve nextPageToken) destekleyen API'lerde bu parametreleri kullanarak her sorgunun sonuçlarını yönetilebilir bir boyuta indirin. Aksi takdirde kısmi yanıt ile olası performans kazanımları fark edilmeyebilir.

Yama (kısmi güncelleme)

Ayrıca, kaynakları değiştirirken gereksiz verilerin gönderilmesini de önleyebilirsiniz. Yalnızca değiştirdiğiniz belirli alanlar için güncellenmiş verileri göndermek istiyorsanız HTTP PATCH fiilini kullanın. Bu dokümanda açıklanan yama semantiği, kısmi güncellemenin eski GData uygulamasında olduğundan farklı (ve daha basit).

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 yapılan basit bir yama isteği gösterilmektedir. Kaynağın bir yorum, özellik grubu, durum ve daha birçok alanı da vardır ancak değiştirilen tek alan olduğu için bu istek 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ı eklendiğinden ö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. Bu nedenle, 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ı bulunur. Bir alan belirttiğinizde, çevreleyen üst nesnelerin kısmi yanıt ile döndürüldüğü gibi çevreleyen tüm üst nesneleri de eklemeniz gerekir. Gönderdiğiniz değiştirilmiş 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ılı bilgi için JSON null başlıklı makaleyi inceleyin.

Diziler hakkında not: Dizi içeren yama istekleri, mevcut diziyi sizin sağladığınız diziyle değiştirir. Bir dizideki öğeleri parça parça şeklinde 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ı bir uygulama olabilir. 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 bu durum, özellikle ETag kullanan kaynaklar açısından önemlidir. Verileri aldıktan sonra, değiştirmek istediğiniz değerleri değiştirebilir ve değiştirilen kısmi gösterimi bir yama isteğiyle geri gönderebilirsiniz. Aşağıda, demo kaynağının ETag kullandığını varsayan bir örneği görebilirsiniz:

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 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 kodu ve güncellenen kaynağın kısmi gösterimiyle 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, bir diziye öğe eklemek ve mevcut dizi öğelerinin hiçbirini kaybetmek istemiyorsanız önce mevcut verileri almanız gerekir. Benzer şekilde, bir API'de ETag kullanılıyorsa kaynağı başarıyla güncellemek için önceki ETag değerini isteğinizle birlikte göndermeniz gerekir.

Not: ETag'ler kullanımdayken bir yamayı zorunlu kılmak için "If-Match: *" HTTP üst bilgisi kullanabilirsiniz. Bunu yaparsanız yazma işleminden ö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 oluşturabilirsiniz. Ö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 oluşturulur. Doğruluk alanı (ayarlanmışsa) kaldırılır.

Yamaya verilen yanıtı işleme

Geçerli bir yama isteğini işledikten sonra, API değiştirilen kaynağın tam gösterimiyle 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'da 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ö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 bu alanlar yoksayılır. Bu, kısmi güncelleme yapmanın başka bir yolu gibi görünse de bu yaklaşımda bazı sınırlamalar mevcuttur. HTTP PUT fiilini kullanan güncellemelerde, gerekli parametreleri sağlamazsanız istek başarısız olur ve isteğe bağlı parametreler 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 dizilerdir: Tümünü çıkarırsanız oldukları gibi kalırlar; herhangi birini sağlarsanız, tüm grup sağladığınız kümeyle değiştirilir.