Google Veri API'leri Protokolü Referansı

Bu dokümanda, bir sorgunun nasıl göründüğü ve sonuçların nasıl göründüğü gibi bilgiler dahil olmak üzere Google Veri API'leri tarafından kullanılan protokol açıklanmaktadır.

Google Veri API'ları hakkında daha fazla bilgi için Google Veri Geliştirici Kılavuzu dokümanını ve Protokol Kılavuzu'nu inceleyin.

Kitle

Bu doküman, Google Veri API'ları tarafından kullanılan XML biçimi ve protokolün ayrıntılarını anlamak isteyen kişiler için hazırlanmıştır.

Yalnızca Google Veri İstemcisi API'lerini kullanan bir kod yazmak istiyorsanız bu ayrıntıları bilmeniz gerekmez. Bunun yerine dile özel istemci kitaplıklarını kullanabilirsiniz.

Ancak protokolü anlamak istiyorsanız bu dokümanı okuyun. Örneğin, aşağıdaki görevlerde size yardımcı olması için bu dokümanı okuyabilirsiniz:

  • Google Veri mimarisini değerlendirme
  • sağlanan Google Veri İstemcisi kitaplıkları olmadan protokolü kullanarak kodlama
  • yeni bir dilde istemci kitaplığı yazıyor

Bu dokümanda XML, ad alanları, ortak kullanılan feed'ler ve HTTP'deki GET, POST, PUT, DELETE istekleri ile HTTP'nin "kaynak" kavramı hakkında bilgi sahibi olduğunuz varsayılır. Bunlar hakkında daha fazla bilgi için bu dokümanın Ek kaynaklar bölümüne bakın.

Bu dokümanda belirli bir programlama dili kullanılmıyor. HTTP isteklerinde bulunmanıza ve XML tabanlı yanıtlar ayrıştırmanıza olanak tanıyan herhangi bir programlama dilini kullanarak Google Veri mesajları gönderebilir ve alabilirsiniz.

Protokol ayrıntıları

Bu bölümde, Google Veri dokümanı biçimi ve sorgu söz dizimi açıklanmaktadır.

Doküman biçimi

Google Verileri, Atom ve RSS 2.0'ın tümü, aynı temel veri modelini paylaşır: hem bazı global verileri hem de herhangi bir sayıda girişi içeren bir kapsayıcıdır. Her protokol için biçim temel bir şemayla tanımlanır ancak yabancı ad alanları kullanılarak uzatılabilir.

Google Veri API'leri, Atom sendikasyon biçimini (okuma ve yazmalar için) veya RSS biçimini (yalnızca okumalar için) kullanabilir.

Atom, Google Verileri'nin varsayılan biçimidir. RSS biçiminde yanıt istemek için /alt=rss/ parametresini kullanın. Daha fazla bilgi için Sorgu istekleri bölümüne bakın.

RSS biçiminde veri isteğinde bulunduğunuzda Google Verileri, RSS biçiminde bir feed (veya kaynağın başka bir temsili) sağlar. Belirli bir Google Veri mülkü için eşdeğer RSS mülkü yoksa Google Verileri, RSS'nin bir uzantısı olduğunu belirtmek için Atom özelliğini uygun bir ad alanı ile etiketler.

Not: Atom biçimindeki çoğu Google Veri feed'i, feed öğesinde bir xmlns özelliği belirterek varsayılan ad alanı olarak Atom ad alanını kullanır. Bu işlemin nasıl yapılacağına dair örnekler için örneklere bakın. Bu nedenle, bu belgedeki örneklerde Atom biçimindeki bir feed'de yer alan öğeler açıkça atom: belirtilmiyor.

Aşağıdaki tablolar, şemanın Atom ve RSS gösterimlerini göstermektedir. Bu tablolarda belirtilmeyen tüm veriler düz XML olarak ele alınır ve her iki temsilde de aynı şekilde gösterilir. Aksi belirtilmediği sürece belirli bir sütundaki XML öğeleri, söz konusu sütuna karşılık gelen ad alanındadır. Bu özette standart XPath gösterimi kullanılır. Özellikle eğik çizgiler, öğe hiyerarşisini gösterirken, @ işareti de öğenin bir özelliğini belirtir.

Aşağıdaki tabloların her birinde, vurgulanan öğeler gereklidir.

Aşağıdaki tabloda, Google Veri feed'i öğeleri gösterilmektedir:

Feed Şema Öğesi Atom Temsili RSS Temsili
Özet Akışı Başlığı /feed/title /rss/channel/title
Özet akışı kimliği /feed/id /rss/channel/atom:id
Feed HTML Bağlantısı /feed/link[@rel="alternate"]\
[@type="text/html"]/@href
/rss/channel/link
Feed Açıklaması /feed/subtitle /rss/channel/description
Feed Dili /feed/@xml:lang /rss/channel/language
Özet Akışı Telif Hakkı /feed/rights /rss/channel/copyright
Feed Yazarı

/feed/author/name
/feed/author/email

(Belirli durumlarda gereklidir, Atom spesifikasyonuna bakın.)

/rss/channel/managingEditor
Feed Son Güncelleme Tarihi /feed/updated
(RFC 3339 biçimi)
/rss/channel/lastBuildDate
(RFC 822 biçimi)
Feed Kategorisi /feed/category/@term /rss/channel/category
Feed Kategorisi Şeması /feed/category/@scheme /rss/channel/category/@domain
Feed Oluşturma Aracı /feed/generator
/feed/generator/@uri
/rss/channel/generator
Feed Simgesi /feed/icon /rss/channel/image/url (logo yoksa logo feed'e eklenmez)
Feed Logosu /feed/logo /rss/channel/image/url

Aşağıdaki tabloda, Google Veri arama sonuçları feed'indeki öğeler gösterilmektedir. Google Verilerinin, arama sonuçları feed'lerinde bazı OpenSearch 1.1 Yanıt öğelerini gösterdiğini unutmayın.

Arama Sonucu Feed Şema Öğesi Atom Temsili RSS/OpenSearch Temsili
Arama Sonuçlarının sayısı /feed/openSearch:totalResults /rss/channel/openSearch:totalResults
Arama Sonucu Başlangıç Dizini /feed/openSearch:startIndex /rss/channel/openSearch:startIndex
Sayfa Başına Arama Sonucu Sayısı /feed/openSearch:itemsPerPage /rss/channel/openSearch:itemsPerPage

Aşağıdaki tabloda, Google Veri girişinin öğeleri gösterilmektedir:

Giriş Şeması Öğesi Atom Temsili RSS Temsili
Giriş kimliği /feed/entry/id /rss/channel/item/guid
Giriş Sürümü Kimliği İsteğe bağlı olarak (ör. bu dokümanın Optimum eşzamanlılık bölümüne bakın) EditURI'a yerleştirin.
Giriş Başlığı /feed/entry/title /rss/channel/item/title
Giriş Bağlantısı /feed/entry/link /rss/channel/item/link
/rss/channel/item/enclosure
/rss/channel/item/comments
Giriş Özeti

/feed/entry/summary

(Belirli durumlarda gereklidir, Atom spesifikasyonuna bakın.)

/rss/channel/item/atom:summary
Giriş İçeriği

/feed/entry/content

(İçerik öğesi yoksa giriş en az bir <link rel="alternate"> öğesi içermelidir.)

/rss/channel/item/description
Giriş Yazarı

/feed/entry/author/name
/feed/entry/author/email

(Belirli durumlarda gereklidir, Atom spesifikasyonuna bakın.)

/rss/channel/item/author
Giriş Kategorisi /feed/entry/category/@term /rss/channel/item/category
Giriş Kategorisi Şeması /feed/entry/category/@scheme /rss/channel/item/category/@domain
Giriş Yayınlanma Tarihi /feed/entry/published
(RFC 3339)
/rss/channel/item/pubDate
(RFC 822)
Giriş Güncelleme Tarihi /feed/entry/updated
(RFC 3339)
/rss/channel/item/atom:updated
(RFC 3339)

Sorgular

Bu bölümde, sorgu sisteminin nasıl kullanılacağı açıklanmaktadır.

Sorgu modeli tasarım ilkeleri

Sorgu modeli kasıtlı olarak çok basittir. Temel ilkeler şunlardır:

  • Sorgular, HTTP üst bilgileri olarak veya yükün bir parçası olarak değil, HTTP URI'ları olarak ifade edilir. Bu yaklaşımın avantajlarından biri de bir sorguya bağlantı oluşturabilmenizdir.
  • Koşullar, tek bir öğenin kapsamında olur. Dolayısıyla, "Bugün en az 10 e-posta gönderen kişilerden gelen tüm e-postaları bul" gibi bir ilişki sorgusu gönderemezsiniz.
  • Sorguların temel alabileceği özellik kümesi çok sınırlıdır; çoğu sorgu yalnızca tam metin arama sorgularıdır.
  • Sonuç sıralaması uygulamaya bağlıdır.
  • Protokol, doğal olarak genişletilebilir. Hizmetinizde ek özellikler veya sıralama sunmak istiyorsanız yeni parametreleri kullanıma sunarak bunu kolayca yapabilirsiniz.

Sorgu istekleri

İstemciler, HTTP GET isteği göndererek bir Google Veri hizmetini sorguluyor. Sorgu URI'si, kaynağın URI'sinden (Atom'da FeedURI olarak adlandırılır) ve ardından sorgu parametrelerinden oluşur. Çoğu sorgu parametresi, geleneksel ?name=value[&...] URL parametreleri olarak gösterilir. Kategori parametreleri farklı şekilde işlenir. Aşağıya bakın.

Örneğin, FeedURI http://www.example.com/feeds/jo ise aşağıdaki URI ile bir sorgu gönderebilirsiniz:

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z

Google Veri hizmetleri, HTTP Koşullu GET özelliğini destekler. Bunlar, Last-Modified yanıt üstbilgisini döndürülen feed'deki veya girişteki <atom:updated> öğesinin değerine göre ayarlar. Bir istemci, değişmemişse içeriği tekrar almamak için bu değeri If-Modified-After istek başlığının değeri olarak geri gönderebilir. If-Modified- ayından bu yana içerik değişmediyse Google Veri hizmeti, 304 (Değiştirilmedi) HTTP yanıtı döndürür.

Bir Google Veri hizmeti, kategori sorgularını ve alt sorgularını desteklemelidir; diğer parametreler için destek isteğe bağlıdır. Belirli bir hizmet tarafından anlaşılmayan bir standart parametrenin iletilmesi, 403 Forbidden yanıtıyla sonuçlanır. Desteklenmeyen standart dışı bir parametrenin iletilmesi, 400 Bad Request yanıtıyla sonuçlanır. Diğer durum kodları hakkında bilgi edinmek için bu dokümanın HTTP durum kodları bölümünü inceleyin.

Standart sorgu parametreleri aşağıdaki tabloda özetlenmiştir. Tüm parametre değerlerinin URL olarak kodlanmış olması gerekir.

Parametre Anlamı Notlar
q Tam metin sorgu dizesi
  • Sorgu oluştururken arama terimlerini boşlukla ayırarak q=term1 term2 term3 biçiminde listeleyin. (Tüm sorgu parametresi değerlerinde olduğu gibi, boşluklar URL olarak kodlanmalıdır.) Google Veri hizmeti, tüm arama terimleriyle eşleşen tüm girişleri döndürür (ör. terimler arasında AND kullanılması). Google'ın web araması gibi Google Veri hizmeti de alt dizeler yerine tam kelimeleri (ve aynı köke sahip alakalı kelimeleri) arar.
  • Bir kelime öbeğini tam olarak aramak için ifadeyi tırnak içine alın: q="exact phrase".
  • Belirli bir terimle eşleşen girişleri hariç tutmak için q=-term formunu kullanın.
  • Arama büyük/küçük harfe duyarlı değildir.
  • Örnek: "Elizabeth Bennet" ifadesini ve "Armut" kelimesini içeren ancak "Austen" kelimesini içermeyen tüm girişleri aramak için şu sorguyu kullanın: ?q="Elizabeth Bennet" Darcy -Austen
/-/category Kategori filtresi
  • Her kategoriyi kaynağın URI'sinin bir parçası gibi, /categoryname/ biçiminde listeleyin. Bu, normal name=value formu için bir istisnadır.
  • Tüm kategorileri, diğer sorgu parametrelerinden önce listeleyin.
  • Bir kategori olduğunu netleştirmek için ilk kategorinin önüne /-/ ekleyin. Örneğin, Can'ın feed'inde Fritz ile ilgili girişler için bir kategori varsa bu girişler için istekte bulunabilirsiniz: http://www.example.com/feeds/jo/-/Fritz. Bu, uygulamanın kategoriyle ayrılmış sorgu URI'larını kaynak URI'larından ayırt etmesine olanak tanır.
  • Eğik çizgilerle ayırarak birden fazla kategori parametresi listeleyerek birden çok kategoride sorgu yapabilirsiniz. Google Veri hizmeti, tüm kategorilerle (ör. terimler arasında AND kullanımı) eşleşen tüm girişleri döndürür. Örneğin: http://www.example.com/feeds/jo/-/Fritz/Laurie her iki kategoriyle de eşleşen girişleri döndürür.
  • Terimler arasında OR yapmak için URL'yi %7C olarak kodlanan bir dikey çizgi karakteri (|) kullanın. Örneğin: http://www.example.com/feeds/jo/-/Fritz%7CLaurie iki kategoriden biriyle eşleşen girişleri döndürür.
  • Bir giriş, Atom spesifikasyonunda tanımlandığı gibi eşleşen bir terime veya etikete sahip bir kategoride yer alıyorsa belirli bir kategoriyle eşleşir. (Genel olarak "terim", ilgili kategorinin tanımlanması için yazılım tarafından kullanılan dahili dizedir. "Etiket" ise, bir kullanıcı arayüzünde kullanıcıya gösterilen, okunabilir dizedir.)
  • Belirli bir kategoriyle eşleşen girişleri hariç tutmak için /-categoryname/ formunu kullanın.
  • <category scheme="urn:google.com" term="public"/> gibi bir şemaya sahip bir kategoriyi sorgulamak için kategori adının önüne süslü ayraç eklemeniz gerekir. Örneğin: /{urn:google.com}public. Şemada eğik çizgi karakteri (/) varsa URL'nin %2F olarak kodlanması gerekir. Düzeni olmayan bir kategoriyi eşleştirmek için boş bir çift süslü ayraç kullanın. Küme ayracı belirtmezseniz şemadaki kategoriler eşleşir.
  • Yukarıdaki özellikler birleştirilebilir. Örneğin: /A%7C-{urn:google.com}B/-C, (A OR (NOT B)) AND (NOT C) anlamına gelir.
category Kategori filtresi
  • Kategori filtresi uygulamanın alternatif bir yolu. Bu iki yöntem eşdeğerdir.
  • Terimler arasında OR yapmak için dikey çizgi (|) URL'sini %7C olarak kodlayın. Örneğin: http://www.example.com/feeds?category=Fritz%7CLaurie iki kategoriden biriyle eşleşen girişleri döndürür.
  • Terimler arasında AND yapmak için virgül (,) kullanın. Örneğin, http://www.example.com/feeds?category=Fritz,Laurie her iki kategoriyle de eşleşen girişleri döndürür.
author Girişin yazarı
  • Hizmet, yazar adı ve/veya e-posta adresinin sorgu dizenizle eşleştiği girişleri döndürür.
alt Alternatif temsil türü
  • Bir alt parametresi belirtmezseniz hizmet, bir Atom feed'i döndürür. Bu değer alt=atom etiketine eşittir.
  • alt=rss, RSS 2.0 sonuç feed'ini döndürür.
  • alt=json, feed'in JSON gösterimini döndürür. Daha fazla bilgi
  • alt=json-in-script Bir komut dosyası etiketinde JSON'i sarmalayan bir yanıt ister. Daha fazla bilgi
updated-min, updated-max Giriş güncelleme tarihindeki sınırlar
  • RFC 3339 zaman damgası biçimini kullanın. Örneğin: 2005-08-09T10:57:00-08:00.
  • Alt sınır kapsayıcıdır, üst sınır ise hariçtir.
published-min, published-max Girişin yayınlanma tarihindeki sınırlar
  • RFC 3339 zaman damgası biçimini kullanın. Örneğin: 2005-08-09T10:57:00-08:00.
  • Alt sınır kapsayıcıdır, üst sınır ise hariçtir.
start-index Alınacak ilk sonucun 1 tabanlı dizini
  • Bunun genel bir işaretleme mekanizması olmadığını unutmayın. İlk olarak ?start-index=1&max-results=10 ile sorgu gönderir, ardından ?start-index=11&max-results=10 ile başka bir sorgu gönderirseniz hizmet, iki sorgu arasında ekleme ve silme işlemlerinin yapılmış olabileceği için sonuçların ?start-index=1&max-results=20 ile eşdeğer olduğunu garanti edemez.
max-results Alınacak maksimum sonuç sayısı Varsayılan max-results değerine sahip herhangi bir hizmette (varsayılan feed boyutunu sınırlamak için) tüm feed'i almak istiyorsanız çok büyük bir sayı belirtebilirsiniz.
giriş kimliği Alınacak belirli bir girişin kimliği
  • Bir giriş kimliği belirtirseniz başka parametre belirtemezsiniz.
  • Giriş kimliğinin biçimi Google veri hizmeti tarafından belirlenir.
  • Diğer sorgu parametrelerinin çoğundan farklı olarak giriş kimliği, bir ad=değer çifti olarak değil, URI'nın bir parçası olarak belirtilir.
  • Örnek: http://www.example.com/feeds/jo/entry1.

Kategori sorguları hakkında

Kategori sorguları için biraz sıra dışı bir biçim belirtmeye karar verdik. Aşağıdaki gibi bir sorgu yerine:

http://example.com/jo?category=Fritz&category=2006

Bunun için:

http://example.com/jo/-/Fritz/2006

Bu yaklaşım bir kaynağı sorgu parametreleri kullanmadan tanımlar ve daha net URI'ler oluşturur. Kategori sorgularının en yaygın sorgular olacağını düşündüğümüzden kategoriler için bu yaklaşımı seçtik.

Bu yaklaşımın dezavantajı, kategori sorgularında /-/ kullanmanızı gerektirmesidir. Böylece Google veri hizmetleri, kategori sorgularını http://example.com/jo/MyPost/comments gibi diğer kaynak URI'lardan ayırt edebilir.

Sorgu yanıtları

Sorgular, istek parametrelerine bağlı olarak bir Atom feed'i, bir Atom girişi veya RSS özet akışı döndürür.

Sorgu sonuçları, doğrudan <feed> öğesinin veya <channel> öğesinin altında aşağıdaki OpenSearch öğelerini içerir (sonuçların Atom veya RSS olup olmamasına bağlı olarak):

openSearch:totalResults
Sorguya ait arama sonuçlarının toplam sayısı (sonuç feed'inde bulunmayabilir).
openSearch:startIndex
İlk sonucun 1 tabanlı dizini.
openSearch:itemsPerPage
Bir sayfada görünen maksimum öğe sayısı. Bu, müşterilerin sonraki sayfa gruplarına doğrudan bağlantı oluşturmasına olanak tanır. Ancak bu numaradan kaynaklanan olası bir hata için Sorgu istekleri bölümündeki tablodan start-index ile ilgili nota bakın.

Atom yanıt feed'i ve girişleri, aşağıdaki Atom ve Google Veri öğelerinin yanı sıra (Atom spesifikasyonunda listelenenler) herhangi birini de içerebilir:

<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
Tam Atom feed'inin alınabileceği URI'yı belirtir.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
Atom feed'inin PostURI'unu (yeni girişlerin yayınlanabileceği yer) belirtir.
<link rel="self" type="..." href="..."/>
Bu kaynağın URI'sini içerir. type özelliğinin değeri, istenen biçime bağlıdır. Bu süre zarfında herhangi bir veri değişmezse bu URI'ye başka bir GET göndermek aynı yanıtı döndürür.
<link rel="previous" type="application/atom+xml" href="..."/>
Bu sorgu sonucu grubunun önceki parçanın URI'sını belirtir.
<link rel="next" type="application/atom+xml" href="..."/>
Bu sorgu sonucu grubunun bir sonraki parçasının URI'sını belirtir.
<link rel="edit" type="application/atom+xml" href="..."/>
Atom girişinin Düzenleme URI'sini (güncellenmiş bir giriş gönderdiğiniz) belirtir.

Aşağıda, bir arama sorgusuna yanıt olarak örnek bir yanıt gövdesi verilmiştir:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
  <id>http://www.example.com/feed/1234.1/posts/full</id> 
  <updated>2005-09-16T00:42:06Z</updated> 
  <title type="text">Books and Romance with Jo and Liz</title> 
  <link rel="alternate" type="text/html" href="http://www.example.net/"/> 
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="self" type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <generator version="1.0"
    uri="http://www.example.com">Example Generator Engine</generator> 
  <openSearch:totalResults>2</openSearch:totalResults> 
  <openSearch:startIndex>0</openSearch:startIndex> 
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id> 
    <published>2005-01-09T08:00:00Z</published> 
    <updated>2005-01-09T08:00:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1009</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id> 
    <published>2005-01-07T08:00:00Z</published> 
    <updated>2005-01-07T08:02:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1007</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
</feed>

İstenen özet akışı Atom biçimindeyse, hiçbir sorgu parametresi belirtilmemişse ve sonuç tüm girişleri içermiyorsa üst düzey özet akışına şu öğe eklenir: <link rel="next" type="application/atom+xml" href="..."/>. Sonraki giriş grubunu içeren bir feed'e işaret eder. Sonraki gruplar, karşılık gelen bir <link rel="previous" type="application/atom+xml" href="..."/> öğesi içeriyor. İstemci tüm sonraki bağlantıları izleyerek bir feed'deki tüm girişleri alabilir.

HTTP durum kodları

Aşağıdaki tabloda, çeşitli HTTP durum kodlarının Google Veri hizmetleri bağlamındaki anlamı açıklanmaktadır.

Kod Açıklama
200 Tamam Hata yok.
201 OLUŞTURULDU Kaynak başarıyla oluşturuldu.
304 DEĞİŞTİRİLMEDİ Kaynak, isteğin If-Modified-After üstbilgisinde belirtilen süreden bu yana değişmedi.
400 ROZET İSTEK Geçersiz istek URI'sı veya başlığı ya da desteklenmeyen standart dışı parametre.
401 YETKİLENDİRİLMEDİ Yetkilendirme gerekli.
403 YASAL Desteklenmeyen standart parametre veya kimlik doğrulama ya da yetkilendirme başarısız oldu.
404 BULUNAMADI Kaynak (ör. feed veya giriş) bulunamadı.
409 ÇALIŞMA Belirtilen sürüm numarası, kaynağın en son sürüm numarasıyla eşleşmiyor.
500 DAHİLİ SUNUCU HATASI Dahili hata. Bu, tanınmayan tüm hatalar için kullanılan varsayılan koddur.

İyimser eşzamanlılık (sürüm)

Bazen, birden fazla müşterinin yanlışlıkla birbirlerinin yaptığı değişikliklerin üzerine yazmadığından emin olmak önemlidir. Bu işlemi en kolay şekilde, istemcinin değiştirdiği girişin güncel sürümünün, istemcinin değişiklik yaptığı sürümle aynı olmasını sağlayarak gerçekleştirebilirsiniz. İkinci bir istemci, ilk istemciden önce bir güncelleme yaparsa birinci istemci yaptığı güncellemeye göre artık birinci istemcinin güncellemesini temel almaz. Bu nedenle, ilk istemcinin güncellemesi reddedilir.

Sürüm oluşturmayı destekleyen Google Veri feed'lerinde, bu girişleri semantik olarak her girişin EditURI'sine bir sürüm kimliği ekleyerek yaparız. Giriş kimliğini değil, yalnızca EditorURI'in etkilendiğini unutmayın. Bu şemada, her güncelleme girişin Düzenleme URI'sini değiştirir. Böylece, orijinal sürüme göre sonraki güncellemelerin başarısız olması garantilenir. Silme işlemleri elbette bu özellikle ilgili güncellemelerle aynıdır. Eski sürüm numarasıyla bir silme gönderirseniz silme işlemi başarısız olur.

Tüm Google veri feed'leri iyimser eşzamanlılığı desteklemez. Sunucu, bunu destekleyen bir feed'de PUT veya DELETE sürümünde bir sürüm çakışması tespit ederse sunucu 409 Conflict ile yanıt verir. Yanıtın gövdesi, girişin mevcut durumunu (Atom giriş dokümanı) içerir. Müşteriye, 409 yanıtındaki EditURI'yi kullanarak çakışmayı çözmesi ve isteği yeniden göndermesi önerilir.

Motivasyon ve tasarım notları

İyimserlikle ilgili bu yaklaşım, sürüm kimlikleri için yeni işaretlemeye gerek kalmadan istediğimiz semantiği uygulamamıza olanak sağlıyor. Bu da Google Verilerinin yanıtlarını Google Data Atom uç noktalarıyla uyumlu hale getiriyor.

Sürüm kimliklerini belirtmek yerine her girişteki (/atom:entry/atom:updated) güncelleme zaman damgasına bakmayı seçebilirdik. Ancak, güncelleme zaman damgasını kullanmayla ilgili iki sorun var:

  • Silme işlemlerinde değil, yalnızca güncelleme yapılır.
  • Bu şekilde, uygulamalar tarih/saat değerlerini sürüm kimliği olarak kullanmaya zorlar ve bu işlem Google Verileri'ni birçok mevcut veri deposunun üstüne sığdırmayı zorlaştırır.

Kimlik doğrulama

İstemci bir hizmete erişmeye çalıştığında, kullanıcının söz konusu işlemi gerçekleştirme yetkisine sahip olduğunu kanıtlamak için kullanıcının kimlik bilgilerini hizmete sağlaması gerekebilir.

İstemcilerin kimlik doğrulama için kullanması gereken yaklaşım, istemcinin türüne bağlıdır:

ClientLogin sisteminde masaüstü istemcisi kullanıcıdan kimlik bilgilerini ister ve ardından bu kimlik bilgilerini Google kimlik doğrulama sistemine gönderir.

Kimlik doğrulama başarılı olursa kimlik doğrulama sistemi, daha sonra Google Veri istekleri gönderdiğinde istemcinin (HTTP Yetkilendirme başlığında) kullandığı bir jetonu döndürür.

Kimlik doğrulama başarısız olursa sunucu, 403 Yasak durum kodu ve kimlik doğrulama için geçerli bir sorgulama içeren WWW-Authentication başlığı döndürür.

AuthSub sistemi de benzer şekilde çalışır. Tek fark, kullanıcıdan kimlik bilgilerini istemek yerine, kimlik bilgilerini isteyen bir Google hizmetine bağlanmasıdır. Hizmet, web uygulamasının kullanabileceği bir jeton döndürür. Bu yaklaşım, Google'ın (web kullanıcı arabirimi yerine) kullanıcının kimlik bilgilerini güvenli bir şekilde işleyip depolamasını sağlar.

Bu kimlik doğrulama sistemleriyle ilgili ayrıntılar için Google Veri Kimlik Doğrulaması'na Genel Bakış veya Google Hesabı Kimlik Doğrulama dokümanlarına bakın.

Oturum durumu

İş mantığı uygulamalarının çoğu, bir oturumun durumunu takip etmek için oturum kalıcılığı gerektirir.

Google, oturum durumunu iki şekilde izler: çerezleri kullanma ve sorgu parametresi olarak gönderilebilen bir jeton kullanma. Her iki yöntem de aynı etkiyi sağlar. Müşterilerin bu oturum durumu izleme yöntemlerinden birini desteklemesi önerilir (ikisi de yeterlidir). Bu yöntemlerden birini desteklemeyen istemciler Google Veri hizmetleriyle çalışmaya devam eder, ancak bu yöntemleri destekleyen istemcilere kıyasla performans düşebilir. Daha ayrıntılı olarak belirtmek gerekirse, bir istemci bu yöntemleri desteklemiyorsa her istek bir yönlendirme ile sonuçlanır. Bu nedenle, her istek (ve ilişkili tüm veriler) sunucuya iki kez gönderilir. Bu da hem istemcinin hem de sunucunun performansını etkiler.

Oturum durumunu sizin için Google istemci kitaplıkları halleder, dolayısıyla kitaplıklarımızı kullanıyorsanız oturum durumu desteği almak için herhangi bir işlem yapmanız gerekmez.

Ek kaynaklar

Aşağıdaki üçüncü taraf dokümanları sizin için yararlı olabilir:

Başa dön