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 açıklanmaktadır. Bazı durumlarda, sunulan fikirleri göstermek için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak, Fitness 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 kolay yolu gzip sıkıştırmayı etkinleştirmektir. Bu işlem, sonuçları ortaya çıkarmak için ek CPU süresi gerektirse de ağ maliyetlerinin dengelenmesi genellikle çok değerlidir.

Gzip kodlu bir yanıt almak için iki şey yapmanız gerekir: Bir Accept-Encoding başlığı ayarlayın ve kullanıcı aracısını gzip dizesini içerecek şekilde değiştirin. Aşağıda, gzip sıkıştırmasını etkinleştirmek için uygun şekilde biçimlendirilmiş 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ı iyileştirmenin bir başka yolu, verilerin yalnızca ilgilendiğiniz bölümünü göndermek ve almaktır. Bu yaklaşım, uygulamanızın gereksiz alanları aktarmasını, ayrıştırmasını ve depolamasını önler. 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).
Patch: Yalnızca değiştirmek istediğiniz alanları gönderdiğiniz güncelleme isteği (PATCH HTTP fiilini kullanın).

Kısmi istek oluşturmayla ilgili daha ayrıntılı bilgiyi aşağıdaki bölümlerde bulabilirsiniz.

Kısmi yanıt

Varsayılan olarak sunucu, istekleri işleme aldıktan sonra bir 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 bir yanıt alabilirsiniz.

Kısmi 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 tüm isteklerle kullanabilirsiniz.

fields parametresinin yalnızca yanıt verilerini etkilediğini unutmayın. Varsa göndermeniz gereken veriler bu durumdan etkilenmez. Kaynakları değiştirirken gönderdiğiniz veri miktarını azaltmak için bir yama isteği kullanın.

Örnek

Aşağıdaki örnekte, fields parametresinin genel (kurgusal) &Demo" API'si ile kullanımı gösterilmektedir.

Basit istek: Bu HTTP GET isteği, fields parametresini çıkarır ve tam kaynağı döndürür.

https://www.googleapis.com/demo/v1

Tam kaynak yanıtı: Kısa veri, sadelik nedeniyle çıkarılan diğer alanları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ı kaynak için aşağıdaki istekte, döndürülen veri miktarını önemli ölçüde azaltmak üzere fields parametresi kullanılmaktadı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ın yanı sıra 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 çevresindeki üst nesneleri içeren bir JSON nesnesi olduğunu unutmayın.

fields parametresinin biçimlendirilmesiyle ilgili ayrıntılara, ardından yanıtta tam olarak ne döndürüldüğüyle ilgili ayrıntılara değiniliyor.

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 aşağıdaki bölümde ek örnekler verilmiştir.

Birden fazla alan seçmek için virgülle ayrılmış bir liste kullanın.
a iç içe yerleştirilmiş bir b alanını seçmek için a/b kullanın; b içine 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ştirilmiş olduğu ""sarmalayıcı" kullanan API yanıtları için fields spesifikasyonuna "data" dahil etmeyin. Veri nesnesinin data/a/b gibi bir alan spesifikasyonuyla eklenmesi hataya neden olur. Bunun yerine, a/b gibi bir fields spesifikasyonu kullanın.
İfadeleri veya nesneleri parantez içine alarak bir dizi alt alan belirlemek için alt seçici kullanın.( )&quot.
Örneğin: fields=items(id,author/email), öğe dizisindeki her bir öğe için yalnızca öğe kimliğini ve yazarın e-posta adresini 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 karakter 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 örnekler, fields parametre değerinin yanıtı nasıl etkilediğini açıklayan açıklamalar içerir.

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 göz ardı edilir.

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ış bir listesidir ve her alan, yanıtın köküne 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 kaynağı döndüren bir işlem gerçekleştiriyorsanız alanlar bu kaynağa göre belirtilir. Seçtiğiniz alan bir diziyse (veya 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`	Öğeler dizisindeki her bir öğe alanı 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ça seçilmediği sürece diğer alt alanları içermez.
`context/facets/label`	Kendisi `context` nesnesinin altında yer alan `facets` dizisinin tüm üyeleri için yalnızca `label` alanını döndürür.
`items/pagemap/*/title`	Öğeler dizisindeki her bir öğe için, `pagemap` öğesinin alt öğeleri olan tüm nesnelerin yalnızca `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` öğesinin alt öğeleri olan tüm nesnelerin `href` alanını döndürür.

Alt seçimleri kullanarak belirli alanların yalnızca bölümlerini isteyin.

Varsayılan olarak, isteğinizde belirli alanlar belirtiliyorsa sunucu, nesneleri veya dizi öğelerini bütünüyle döndürür. Yalnızca belirli alt alanları içeren bir yanıt belirtebilirsiniz. Bunun için aşağıdaki örnekte olduğu gibi "( )" alt seçim söz dizimini kullanırsınız.

Örnek	Etki
`items(title,author/uri)`	items dizisindeki her bir öğe için yalnızca `title` ve author\s39;s `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, HTTP 400 Bad Request durum kodunu ve kullanıcıya alan seçimiyle ilgili sorunun ne olduğunu (örneğin, "Invalid field selection a/b") belirten bir hata mesajı döndürür.

Yukarıdaki giriş bölümü bölümünde gösterilen kısmi yanıt örneği aşağıda verilmiştir. İstek, döndürülecek alanları 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: Verileri sayfalara ayırma için sorgu parametrelerini (ör. maxResults ve nextPageToken) destekleyen API'ler söz konusu olduğunda, her bir sorgunun sonuçlarını yönetilebilir bir boyuta indirmek için bu parametreleri kullanın. Aksi takdirde, kısmi yanıtın mümkün olduğu durumlarda performans artışı gerçekleşmeyebilir.

Yama (kısmi güncelleme)

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

Aşağıdaki kısa örnek, yama kullanımını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&quot API kaynağının başlığını güncellemek için basit bir yama isteği gösterilmektedir. Kaynağın da bir yorumu, bir dizi özelliği, durumu ve daha başka alanları da vardır ancak bu istek yalnızca title alanını gönderir. Çünkü değiştirilen alan budur.

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, 200 OK kaynağının durum kodunu ve güncellenmiş kaynağın tam temsilini döndürür. Yama isteğine yalnızca title alanı eklendiğinden bu, öncekinden farklı olan tek değerdir.

Not: Kısmi yanıt fields parametresini yama ile birlikte kullanırsanız güncelleme isteklerinizin verimliliğini daha da artırabilirsiniz. Bir 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 bir yama isteği kullanarak fields parametresi kullanın.

Yama isteğinin semantiği

Yama isteğinin gövdesinde yalnızca değiştirmek istediğiniz kaynak alanları yer alır. Bir alan belirttiğinizde, çevresindeki üst nesneleri de (ör. çevreleyen ebeveynler) kısmi bir yanıtla döndürülmesi gerekir. Gönderdiğiniz değiştirilmiş veriler, varsa ana nesnenin verileriyle birleştirilir.

Ekle: Henüz var 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. Nesnenin tamamını (varsa), null değerine ayarlayarak da silebilirsiniz. Java API İstemci Kitaplığı'nı kullanıyorsanız bunun yerine Data.NULL_STRING'yi kullanın. Ayrıntılar için JSON null sayfasına göz atın.

Diziler hakkında not: Dizi içeren yama istekleri, mevcut diziyi sağladığınız diziyle değiştirir. Dizideki öğeleri özet 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 işe başlamanız faydalı bir uygulama 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 ö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 bir yama isteğiyle geri gönderebilirsiniz. Demo kaynağının ETag etiketleri kullandığı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 şu şekildedir:

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ı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üncellenmiş kaynağın kısmi bir 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 bu istekleri daha önce aldığınız verilere dayandırmanız gerekir. Örneğin, bir diziye öğe eklemek ve mevcut dizi öğelerinin hiçbirini kaybetmek istemiyorsanız öncelikle mevcut verileri almanız gerekir. Benzer şekilde, bir API ETag kullanıyorsa, kaynağı başarılı bir şekilde güncellemek için önceki ETag değerini isteğinizle birlikte göndermeniz gerekir.

Not: ETag etiketleri kullanılırken bir yamanın uygulanmasını zorunlu kılmak için bir "If-Match: *" HTTP üst bilgisi kullanabilirsiniz. Bunu yaparsanız yazma işleminden önce okumanız gerekmez.

Ancak diğer durumlarda, önce mevcut verileri almadan, yama isteğini doğrudan oluşturabilirsiniz. Örneğin, bir alanı yeni bir değerle güncelleyen veya yeni bir alan ekleyen bir yama isteği kolaylıkla 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 istekte, yorum alanında mevcut bir değer varsa yeni değer, üzerine yazılır. Aksi takdirde yeni değere ayarlanır. Benzer şekilde, hacim özelliği varsa değerin üzerine yazılır; oluşturulmadıysa oluşturulur. Ayarlanmışsa doğruluk alanı kaldırılır.

Bir yama yanıtı işleme

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

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.

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

YAMA HTTP fiilinin desteklenmediği alternatif notasyon

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 ile 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ı alanları göndermeniz gerekir; sunucu tarafından ayarlanan alanlar için değer gönderirseniz bu alanlar yok sayılır. Bu kısmi bir güncellemenin başka bir yolu gibi görünse de bu yaklaşımın 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ı parametreler sağlamazsanız, daha önce ayarlanmış olan veriler temizlenir.

Bu nedenle yama kullanmak çok daha güvenlidir. Yalnızca değiştirmek istediğiniz alanlara ait verileri sağlarsınız; dahil etmediğiniz alanlar silinmez. Bu kuralın tek istisnası, yinelenen öğeler veya diziler olabilir. Bunların tümünü atlarsanız olduğu gibi kalırlar. Bunlardan herhangi birini sağlarsanız tüm grup, sağladığınız grupla değiştirilir.