API kullanım ipuç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 açıklamak için diğer API'lerden veya genel API'lerden örnekler kullanılır. Ancak aynı kavramlar Google Search Console API için de 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ırılmış sürümünü açmak için ek CPU süresi gerektirse de ağ maliyetlerindeki denge genellikle bu husus için çok değerli bir çözümdür.

Gzip ile kodlanmış bir yanıt almak için iki şey yapmanız gerekir: Bir Accept-Encoding üst bilgisi ayarlayın ve kullanıcı aracınızı gzip dizesini içerecek şekilde değiştirin. gzip sıkıştırmasını etkinleştirmek için düzgün şekilde oluşturulmuş bir HTTP üstbilgileri örneğini burada bulabilirsiniz:

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 diğer yolu da verilerin yalnızca ilgilendiğiniz kısmını istemektir. Bu sayede uygulamanız gereksiz alanları aktarmaktan, ayrıştırmaktan ve depolamaktan kaçınarak ağ, CPU ve bellek gibi kaynakları daha verimli kullanabilir.

Kısmi yanıt

Sunucu, istekleri işledikten sonra varsayılan olarak 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 yanıt alabilirsiniz.

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 herhangi bir istekle kullanabilirsiniz.

Örnek

Aşağıdaki örnekte, fields parametresinin genel (kurmaca) bir "Demo" API'si 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ısaltılması için atlanan diğer 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 gönderilen aşağıdaki istek, döndürülen veri miktarını önemli ölçüde azaltmak amacıyla 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 tür bilgilerini içeren bir yanıtın yanı sıra her öğede yalnızca HTML başlığı ve uzunluk özelliği bilgilerini içeren, sadeleştirilmiş bir öğeler 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ı kapsayan üst öğeleri içeren bir JSON nesnesi olduğunu unutmayın.

Ardından, fields parametresinin nasıl biçimlendirileceğiyle ilgili ayrıntılar ve ardından yanıtta tam olarak nelerin döndürüleceğiyle ilgili daha fazla ayrıntı ele alınmaktadır.

Alanlar 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ştir ve daha fazla örnek aşağıda verilmiştir.

• Birden fazla alan seçmek için virgülle ayrılmış liste kullanın.
• a alanında iç içe yerleştirilmiş bir b alanını seçmek için a/b'ü, b alanında iç içe yerleştirilmiş bir c alanını seçmek için a/b/c'ı kullanın.
  

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

• İfadeleri paranteze "( )" yerleştirerek dizi veya nesnelerin belirli bir alt alan grubunu 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 (fields=items(id), fields=items/id ile eşdeğerdir).

• Gerekirse alan seçimlerinde joker karakterler kullanın.

  Örneğin: fields=items/pagemap/*, bir sayfa haritasındaki tüm nesneleri seçer.

Domains parametresini kullanmayla ilgili diğer örnekler

Aşağıdaki örneklerde, fields parametre değerinin yanıtı nasıl etkilediği açıklanmaktadır.

Not: Tüm sorgu parametresi değerlerinde olduğu gibi, fields parametre değeri URL olarak kodlanmalıdır. Bu dokümandaki örneklerde, okunabilirliği artırmak için kodlama atlanmıştır.

Döndürülmesini istediğiniz alanları tanımlayın 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, 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 bu kaynağa göre belirtilir. Seçtiğiniz alan bir diziyse (veya dizinin parçasıysa) sunucu, dizideki tüm öğelerin seçili kısmını döndürür.

Koleksiyon düzeyinde bazı örnekleri aşağıda bulabilirsiniz:

Örnekler	Etki
items	Her öğ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, kapsayıcı üst nesneleri içerir. Üst alanlar, açıkça seçilmediği sürece başka alt alanları içermez.
context/facets/label	facets dizisinin tüm üyeleri için yalnızca label alanını döndürür. Bu alan da context nesnesi altında iç içe yerleştirilmiştir.
items/pagemap/*/title	items dizisindeki her öğ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ı ö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 öğ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.

İsteğiniz belirli alanları belirtiyorsa sunucu varsayılan olarak nesneleri veya dizi öğelerini tamamen döndürür. Yalnızca belirli alt alanları içeren bir yanıt belirtebilirsiniz. Bunu, 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 ve yazarın uri değerlerini döndürür.

Kısmi yanıtlarla ilgilenme

Bir 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 parametre geçersizse sunucu, kullanıcıya alan seçiminde neyin yanlış olduğunu belirten 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, 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 sorgu parametrelerini destekleyen API'lerde (örneğin, maxResults ve nextPageToken) her sorgunun sonuçlarını yönetilebilir bir boyuta küçültmek için bu parametreleri kullanın. Aksi takdirde, kısmi yanıtla elde edilebilecek performans kazanımları elde edilemeyebilir.