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

Protokol Referansı

Uyarı: Bu sayfa, Google'ın eski API'leri olan Google Veri API'leriyle ilgilidir. Bu sayfalar, çoğu yeni API'lerle değiştirilen Google Veri API'leri dizininde listelenen API'lerle ilgilidir. Belirli bir yeni API ile ilgili bilgi edinmek için yeni API'nin belgelerine bakabilirsiniz. Yeni bir API ile istekleri yetkilendirme hakkında bilgi için Google Hesaplarında Kimlik Doğrulama ve Yetkilendirme başlıklı makaleyi inceleyin.

Bu dokümanda, birçok Google API'si tarafından kullanılan Google Veri Protokolü (sorgunun nasıl göründüğü, sonuçların nasıl görüneceği vb. dahil) açıklanmaktadır.

Google Veri Protokolü hakkında daha fazla bilgi için Geliştirici Kılavuzu genel bakış sayfasına ve Protokol Temelleri dokümanına bakın.

Kitle

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

Yalnızca bu API'lerden birini 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 Protokolü mimarisini değerlendirme
sağlanan istemci kitaplıklarını kullanmadan 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 Protokolü mesajları gönderebilir ve alabilirsiniz.

Protokol ayrıntıları

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

Doküman biçimi

Google Veri Protokolü ve Atom aynı temel veri modelini paylaşır: hem bazı global verileri hem de herhangi bir sayıda giriş barındıran 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.

Atom, Google Veri Protokolü için varsayılan biçimdir. Başka bir biçimde yanıt isteğinde bulunmak için alt sorgu parametresini kullanın. Daha fazla bilgi için Sorgu istekleri bölümüne bakın.

Not: Protokol Temelleri'nde verilen örneklerde gösterildiği gibi, Atom biçimindeki çoğu Google Veri Protokolü özet akışı, feed öğesinde bir xmlns özelliği belirterek varsayılan ad alanı olarak Atom ad alanını kullanır. 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 temsilini göstermektedir. Bu tablolarda belirtilmeyen tüm veriler düz XML olarak işlenir. Aksi belirtilmedikçe, belirli bir sütundaki XML öğeleri Atom ad alanındadır.

Not: 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 Protokolü feed'indeki öğeler gösterilmektedir:

Feed Şema Öğesi	Atom Temsili
Özet Akışı Başlığı	`/feed/title`
Özet akışı kimliği	`/feed/id`
Feed HTML Bağlantısı	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Feed Açıklaması	`/feed/subtitle`
Feed Dili	`/feed/@xml:lang`
Özet Akışı Telif Hakkı	`/feed/rights`
Feed Yazarı	`/feed/author/name` `/feed/author/email` (Belirli durumlarda gereklidir, Atom spesifikasyonuna bakın.)
Feed Son Güncelleme Tarihi	`/feed/updated` (RFC 3339 biçimi)
Feed Kategorisi	`/feed/category/@term`
Feed Kategorisi Şeması	`/feed/category/@scheme`
Feed Oluşturma Aracı	`/feed/generator` `/feed/generator/@uri`
Feed Simgesi	`/feed/icon`
Feed Logosu	`/feed/logo`

Aşağıdaki tabloda, Google Veri Protokolü arama sonuçları feed'inin öğeleri gösterilmektedir. Protokol, arama sonuçları feed'lerinde bazı OpenSearch 1.1 Yanıt öğelerini gösterir.

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

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

Giriş Şeması Öğesi	Atom Temsili
Giriş kimliği	`/feed/entry/id`
Giriş Başlığı	`/feed/entry/title`
Giriş Bağlantısı	`/feed/entry/link`
Giriş Özeti	`/feed/entry/summary` (Belirli durumlarda gereklidir, Atom spesifikasyonuna bakın.)
Giriş İçeriği	`/feed/entry/content` (İçerik öğesi yoksa giriş en az bir `<link rel="alternate">` öğesi içermelidir.)
Giriş Yazarı	`/feed/entry/author/name` `/feed/entry/author/email` (Belirli durumlarda gereklidir, Atom spesifikasyonuna bakın.)
Giriş Kategorisi	`/feed/entry/category/@term`
Giriş Kategorisi Şeması	`/feed/entry/category/@scheme`
Giriş Yayınlanma Tarihi	`/feed/entry/published` (RFC 3339)
Giriş Güncelleme Tarihi	`/feed/entry/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

İstemci, HTTP GET isteği göndererek bir Google 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 Protokolü, HTTP Koşullu GET özelliğini destekler. Protokolü uygulayan API'ler, 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 beri içerik değişmediyse hizmet, bir 304 (Değiştirilmedi) HTTP yanıtı döndürür.

Google Veri Protokolü'nü uygulayan API'ler 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
`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 (yalnızca okumalar için). RSS biçimindeki bir hizmetten istekte bulunduğunuzda hizmet, RSS biçiminde bir feed (veya kaynağın başka bir temsili) sağlar. Belirli bir Data API mülkü için eşdeğer RSS mülkü yoksa hizmet, Atom mülkünü kullanır ve RSS uzantısı olduğunu belirtmek için uygun bir ad alanı ile etiketler. `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 `alt=atom-in-script` Bir komut dosyası etiketinde XML dizesi sarmalayan bir Atom yanıtı ister. `alt=rss-in-script` Bir komut dosyası etiketinde XML dizesi sarmalayan RSS yanıtı isteğinde bulunur. `alt=atom-service` Feed'i açıklayan bir Atom hizmet dokümanı ister.
`author`	Girişin yazarı	Hizmet, yazar adı ve/veya e-posta adresinin sorgu dizenizle eşleştiği girişleri döndürür.
`category`	Kategori sorgu 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.
`/-/category`	Kategori sorgu 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. Hizmet, 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.
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 hizmet 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`.
`fields`	Yanıt filtresi	Kaynağın tam temsili yerine yalnızca istenen alanları döndürür. Örneğin: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Bu isteği aldığında sunucu, yalnızca feed'in bağlantı ve giriş öğelerini içeren bir yanıt döndürür. Ayrıca, döndürülen giriş öğeleri yalnızca ETag, kimlik, güncellenmiş ve bağlantı ilişkilerini içeren kısmi girişlerdir. Alan değeri, tüm sorgu parametresi değerlerinde olduğu gibi URL olarak kodlanmalıdır. Daha fazla bilgi için Kısmi yanıt bölümüne bakın. Bu parametre şu anda deneysel bir özelliktir.
`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.
`prettyprint`	Kimlikleri ve satır sonlarını içeren bir XML yanıtı döndürür	`prettyprint=true` ise sunucu tarafından döndürülen XML okunaklı olur (çok kolay yazdırılır). Varsayılan: `prettyprint=false`
`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.
`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.) Hizmet, 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 bir hizmet 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`
`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.
`strict`	Sıkı sorgu parametresi kontrolü	Sorgu parametrelerinizin her birinin hizmet tarafından tanındığını doğrulamak için `strict=true` değerini ayarlayın. Parametre tanınmazsa bir hata döndürülür. Varsayılan: `strict=false`
`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. Bazı durumlarda (örneğin, Calendar Data API'nin v2.1 veya daha yeni bir sürümünü kullanırken) çok eski bir `updated-min` belirtildiğinde HTTP 410 (Gitti) durumunun döndürülmesine neden olur.

Kategori sorguları hakkında

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

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

Şunları kullanıma sunduk:

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

Bu yaklaşım bir kaynağı sorgu parametreleri kullanmadan tanımlar ve daha net URI'ler oluşturur. Kategoriler için bu yaklaşımı, kategori sorgularının en sık kullanılan sorgulardan biri olacağını düşündüğümüzden seçtik.

Bu yaklaşımın dezavantajı, bu tür kategori sorgularında /-/ kullanmanızı gerektirmesidir. Böylece hizmetler, 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şler, aşağıdaki Atom ve Data API öğelerinin (Atom spesifikasyonunda listelenenler dahil) 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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, Veri API'leri bağlamında çeşitli HTTP durum kodlarının ne anlama geldiği 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.
410 ÜST	İstenen değişiklik geçmişi artık sunucuda kullanılamıyor. Ayrıntılı bilgi için hizmete özel belgelere bakın.
500 DAHİLİ SUNUCU HATASI	Dahili hata. Bu, tanınmayan tüm sunucu hataları için kullanılan varsayılan koddur.

Kaynak sürümü oluşturma (ETag'ler)

Bazen belirli bir girişin belirli bir versiyonuna referans verebilmeniz gerekir.

Bu, özellikle iki durumda önemlidir:

İstemcinizin bir giriş istediği ve sunucunun yalnızca istemcinin son isteği istemesinden sonra değişmiş olması durumunda girişi gönderdiği "koşullu alma" işlemini yapma.
Birden fazla müşterinin yanlışlıkla birbirlerinin yaptığı değişikliklerin üzerine yazmadığından emin olmak. İstemciler giriş için eski bir sürüm tanımlayıcısı belirtiyorsa Veri API'leri bunu güncelleme ve silme yaparak gerçekleştirir.

Google Veri API'ları, bu durumların her ikisini de HTTP'nin standart bir parçası olan ETags'i kullanarak yönetir.

ETag, belirli bir girişin belirli bir sürümünü belirten bir tanımlayıcıdır. Sunucu, müşterilerine gönderdiği giriş ve feed öğelerine bir ETag ekler. Bir giriş veya feed değiştiğinde, ETag'i de değişir.

Google Veri API'leri, ETag'leri iki yerde sunar: ETag HTTP üst bilgisi ve <feed> ile <entry> öğelerinin gd:etag özelliğinde.

Google Veri API'larında ETag, genellikle kısa çizgi ve rakamlardan oluşan bir dize ve sayıdır. Dize genellikle tırnak içine alınır. (Tırnak işareti ETag'in bir parçasıdır.) Örneğin, bir Data API girişinden aldığınız ETag: "S0wCTlpIIip7ImA0X0QI".

İki tür ETag etiketi vardır: güçlü ve zayıf. Güçlü EEtiketler, belirli bir girişin belirli bir sürümünü tanımlar ve diğer müşterilerin değişikliklerinin üzerine yazmamak için kullanılabilir. Google Veri API'leri bağlamında zayıf ETag'ler, yalnızca koşullu alma için kullanılır. Zayıf bir ETag her zaman W/ ile başlar. Örneğin: W/"D08FQn8-eil7ImA9WxZbFEw."

Tüm Google Veri API'leri güçlü ETag'leri desteklemez. Giriş yapan kullanıcılar için güçlü ETag'ler yalnızca girişler için kullanılır; feed'lerdeki ETag'ler her zaman zayıftır.

Güçlü ETag'leri destekleyen bir hizmetten alınan feed örneği (bazı HTTP üstbilgileri dahil):

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Veri API'lerinin 2. sürümünü destekleyen istemci kitaplıkları, ETag'leri sizin için şeffaf bir şekilde yönetir. Aşağıdaki bilgiler istemci kitaplıkları kullanmayan istemciler ve sürüm düzeyinde protokol düzeyinde işlenmesine yönelik okuyucular içindir.

Not: Veri API'lerinin 1.0 sürümünde kullanılan sürüm sürümü sistemi hakkında bilgi edinmek için 1.0 referans kılavuzuna bakın.

Koşullu alma

Daha önce aldığınız bir girişi almak istiyorsanız sunucudan girişi yalnızca en son aldığınız tarihten sonra değişmiş olması durumunda göndermesini söyleyebilirsiniz.

Bu tür koşullu almaları yapmak için HTTP If-None-Match başlığı içeren bir HTTP GET isteği gönderin. Başlıkta girişin ETag değerini belirtin.

If-None-Match üst bilgi örneğini aşağıda görebilirsiniz:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Sunucu bu isteği aldığında, istediğiniz girişin belirttiğiniz ETag ile aynı ETag etiketine sahip olup olmadığını kontrol eder. ETag'ler eşleşirse giriş değişmemiştir ve sunucu bir HTTP 304 Not Modified durum kodu döndürür.

ETag'ler eşleşmezse giriş, en son istekte bulunmanızdan sonra değiştirilir ve sunucu, girişi döndürür.

Girişler güncelleniyor

Başka bir istemcideki değişikliklerin üzerine yazmanın en kolay yolu, sunucunuz güncellenmiş bir giriş gönderdiğinde sunucunuzun, istemcinin başlattığı giriş sürümünün sunucu tarafından depolanan geçerli sürümle aynı olmasını sağlamaktır. İstemciniz daha önce ikinci bir güncelleme yaparsa, müşterinizin yaptığı değişiklikler artık en son sürüme dayalı olmadığından müşterinizin güncellemesi reddedilir.

İstemciniz, güçlü ETag'leri destekleyen bir hizmetten veri aldığında her girişin, söz konusu girişin bu sürümü için benzersiz bir sürüm tanımlayıcısı görevi gören bir ETag'i vardır.

Not: ETag kullanarak güncelleme yalnızca güçlü ETag'lerle çalışır. Zayıf ETag etiketleri sağlayan hizmetlerde, girişi aldıktan sonra başka birinin güncelleyip güncellemediğine bakılmaksızın tüm güncellemeler başarılı olur. En yeni güncelleme her zaman önceki güncellemelerin üzerine yazar. Bu nedenle, güncelleme veya silme sırasında zayıf ETag'ler göndermeyin; bunu yaparsanız bir hata mesajı alırsınız.

Bu nedenle, müşteriniz güçlü bir E-Etiket hizmeti için güncelleme gönderdiğinde, girişin hangi sürümünü güncellediğini belirtmelidir. Bunu yapmanın iki yolu vardır:

If-Match HTTP üst bilgisi kullanma.
<atom:entry> öğesinde gd:etag özelliğini kullanın.

Mümkün olduğunda If-Match yaklaşımını öneririz.

If-Match kullanarak bir girişi güncellemek için öncelikle güncellediğiniz girişi alarak başlayın. Girişte istediğiniz değişiklikleri yapın ve ardından değiştirilen girişi içeren yeni bir PUT isteği oluşturun. (Kullanılacak URL'ler hakkında ayrıntılı bilgi için hizmete özel belgelere bakın.)

PUT göndermeden önce orijinal girişten ETag'i içeren bir HTTP If-Match üstbilgisi ekleyin:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Ardından PUT isteğini gönderin.

Güncelleme başarılı olursa sunucu bir HTTP 200 OK durum kodu ve güncellenmiş girişin bir kopyasını döndürür.

Belirttiğiniz ETag, girişteki geçerli ETag ile eşleşmediği için güncelleme başarısız olursa (yani girişin en son aldığınız tarihten itibaren sunucuda değiştiği anlamına gelir), sunucu bir HTTP 412 Precondition Failed durum kodu döndürür.

Kolayca HTTP üst bilgisi yazamıyorsanız veya If-Match başlığını kullanmaktan kaçınmak için başka bir nedeniniz varsa bunun yerine gd:etag özelliğini kullanabilirsiniz.

Bir If-Match başlığı göndermezseniz sunucu, güncellenen girişin gd:etag özellik değerini ima edilen bir If-Match değeri olarak kullanır.

Sürüm belirleme sistemini geçersiz kılmak ve girişi aldıktan sonra başka birinin güncelleyip güncellemediğine bakılmaksızın girişi güncellemek için başlıkta ETag'i belirtmek yerine If-Match: * özelliğini kullanın.

Hangi hizmetlerin güçlü ETag'leri desteklediği hakkında bilgi edinmek için Taşıma Kılavuzu'na bakın.

Girişleri silme

Güçlü ETag'ler kullanan girişleri silmeye benzer.

Güçlü bir ETag'e sahip olan bir girişi silmek için öncelikle silmek istediğiniz girişi alın ve ardından girişin düzenleme URL'sine bir DELETE isteği gönderin.

Aldığınız tarihten itibaren başka bir istemci tarafından değiştirilen bir girişi silmediğinizden emin olmak istiyorsanız, orijinal girişin ETag değerini içeren bir HTTP If-Match üstbilgisi ekleyin.

Sürüm oluşturma sistemini geçersiz kılmak ve girişi kendiniz aldıktan sonra başka birinin güncelleyip güncellemediğine bakılmaksızın girişi silmek istiyorsanız başlıkta ETag'i belirtmek yerine If-Match: * özelliğini kullanın.

Bir girişin güçlü bir ETag etiketi yoksa DELETE isteği her zaman başarılı olur.

Kısmi yanıt (Deneysel)

Varsayılan olarak sunucu, istekleri işledikten sonra hedef kaynağın tam temsilini geri gönderir. Kısmi yanıt, tam kaynak gösterimi yerine yalnızca ilgilendiğiniz öğeleri veya özellikleri istemenize olanak sağlar. Bu sayede istemci uygulamanız gereksiz alanları aktarmak, ayrıştırmak ve depolamaktan kaçınabilir. Böylece ağ, CPU ve bellek kaynaklarını daha verimli kullanabilir.

Kullandığınız ürüne ilişkin kısmi yanıtın olup olmadığını öğrenmek için API dokümanlarına bakın.

Kısmi yanıt istemek için, fields sorgu parametresini kullanarak döndürülmesini istediğiniz öğeleri veya özellikleri belirtin. Aşağıda bir örnek verilmiştir:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

Sunucunun yanıtı yalnızca feed için bağlantı ve giriş öğelerini içerir; giriş öğeleri yalnızca ETag, Kimlik, güncellenmiş ve bağlantı bilgilerini düzenle içerir. fields sorgu parametresi söz dizimi aşağıdaki bölümlerde ele alınmıştır. Yanıt hakkında daha fazla bilgi için Kısmi yanıtları işleme başlıklı makaleye bakın.

Not: fields sorgu parametresini, veri döndüren tüm isteklerde kullanabilirsiniz. GET metriğine ek olarak, POST ve PUT da (kısmi güncellemeler yapmak için kullanılan PATCH dahil) içerir. Ancak fields sorgu parametresi yalnızca yanıt verilerini etkiler. Sağlamanız gereken veriler veya güncellenen ya da oluşturulan alanlar bu durumdan etkilenmez.

Alanlar parametresi söz dizimi özeti

fields sorgu parametresi değerinin biçimi XPath söz dizimine dayalıdır ancak geçerli XPath ifadelerinin yalnızca bir alt kümesini destekler. Desteklenen söz dizimi aşağıda özetlenmiştir. Ek bölümde aşağıdaki örnekler verilmiştir.

Birkaç alan seçmek için virgülle ayrılmış bir liste kullanın.
a öğesinin içine yerleştirilmiş b öğesini seçmek için a/b kullanın. b öğenin içine yerleştirilmiş c öğesini seçmek için a/b/c kullanın.
Belirtilen ada sahip bir özelliği tanımlamak için '@' önekini kullanın; bir öğeye işaret etmek için '@' önekini çıkarın.
Kısıtlamak istediğiniz öğeden sonra "[ ]" parantez içine ifade koyarak belirli ölçütlerle eşleşen öğeleri seçmek için alan koşulları uygulayın.
Örneğin, fields=entry[author/name='Elizabeth'] yalnızca yazarı Elizabeth'in yer aldığı feed girişlerini döndürür.
Yalnızca belirli özellikleri veya alt öğeleri istemek için alt alan seçicilerini belirtin.
Örneğin, fields=entry(id,author/email) her feed girişi için yalnızca kimliği ve yazarın e-postasını döndürür.
Dizeleri çift veya tek tırnak kullanarak sınırlandırabilirsiniz.

Çift tırnak veya tek tırnak işaretinden kaçınmak için alıntıyı tekrarlayın. Örneğin, """Hello,"" he said" "Hello," he said, '''Hello,'' he said' ise 'Hello,' he said dizesini üretir.
Alan seçimlerinde joker karakterler kullanabilirsiniz.
Örneğin, entry/gd:*, gd ad alanındaki tüm alt öğe öğelerini, entry/@gd:* ise aynı ad alanındaki alt öğe özelliklerini seçer.

fields sorgu parametresi bir çıkış filtresi görevi görür. Bu, kısmi yanıtın yalnızca sorgunun geri kalanı işlendikten sonra hesaplanacağı anlamına gelir. Örneğin, sayfa başına 20 sonuç istediğinizi belirtmek için bir max-results sorgu parametresi de belirtirseniz ilk 20 sonuç oluşturulur ve kısmi yanıt bundan hesaplanır. fields spesifikasyonu, sorgu tarafından seçilen ilk 20 girişten hiçbiriyle eşleşmiyorsa boş bir feed alırsınız. Eşleşen ilk 20 girişi almazsınız.

Not: Sorgu koşulları olarak alan koşullarını kullanmaya çalışmayın. Diğer bir deyişle, çok büyük bir veri kümesindeki ilgilenilen öğeleri filtrelemek için tam feed almaya ve alan koşulları uygulamaya çalışmayın. Her sorgunun sonuçlarını yönetilebilir bir boyuta indirmek için, mümkün olduğunda start-index ve max-results gibi diğer sorgu parametrelerini kullanın. Aksi halde, kısmi yanıtın mümkün olduğu performans artışları, yanlış kullanımdan kaynaklanan ciddi performans düşüşüne göre ağır basabilir.

Alanlar parametresi değerini biçimlendirme

Aşağıdaki yönergelerde fields sorgu parametresi değerinin nasıl oluşturulacağı açıklanmaktadır. Her kuralda örnekler bulunur ve parametre değerinin yanıtı nasıl etkilediğiyle ilgili açıklamalar sunulur.

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 aşağıdaki örneklerde kodlama yer almamaktadır.

Geri döndürülmesini istediğiniz alanları belirleyin veya alan seçimleri yapın.

fields sorgu parametresi değeri, öğelerin veya özelliklerin (topluca alanlar olarak adlandırılır) virgülle ayrılmış listesidir ve her alan, kaynak gösteriminin kök öğesine göre belirtilir. Dolayısıyla, bir feed alıyorsanız alanlar <feed> öğesine göre belirtilir ve tek bir giriş alıyorsanız alanlar <entry> öğesine göre belirtilir. Seçtiğiniz öğe, feed'de tekrarlanan bir öğeyse (veya parçasıysa) hizmet bu öğenin tüm örneklerini döndürür.

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

Örnekler	Etki
`entry`	Tüm `<entry>` öğelerini ve bu girişlerin tüm alt öğelerini döndürür, ancak diğer `<feed>` alt öğelerini döndürmez.
`id,entry`	Hem feed `<id>` hem de tüm `<entry>` öğelerini döndürür.
`entry/title`	Tüm feed girişleri için `<title>` öğesini döndürür. İç içe yerleştirilmiş bir öğe her döndürüldüğünde, yanıtta üst öğelerinin çevre etiketleri de yer alır. Üst etiketler, açıkça seçilmediği sürece başka alt öğe veya özellik içermez.
`entry/author/uri`	Tüm feed girişleri için `<author>` öğesinin yalnızca `<uri>` alt öğesini döndürür.
`entry/*:rating`	Tüm feed girişleri için yalnızca herhangi bir ad alanında `rating` yerel adına sahip alt öğeleri döndürür.

Giriş düzeyindeki bazı örnekler:

Örnekler	Etki
`author`	Hedef girişin `<author>` alt öğesini döndürür.
`@gd:etag`	Hedef girişin `etag` özelliğini döndürür.
`author/uri`	Hedef giriş için `<author>` öğesinin `<uri>` alt öğesini döndürür.
`media:group/media:*`	Hedef giriş için `media` ad alanındaki `<media:group>` öğesinin tüm alt alanlarını döndürür.

Yanıtı belirli ölçütlerle eşleşen seçili alanlarla kısıtlayın veya alan koşullarını kullanın.

Varsayılan olarak, isteğiniz birden fazla kez meydana gelen bir öğeyi belirtiyorsa kısmi yanıt bu öğenin tüm örneklerini içerir. Bununla birlikte, aşağıdaki örneklerde gösterildiği gibi, yanıtın yalnızca belirli bir özellik değerine sahip öğeleri veya "[ ]" söz dizimini kullanan başka bir koşulu karşılayan öğeleri de içermesi gerektiğini belirtebilirsiniz. Daha fazla ayrıntı için alan koşulu söz dizimi bölümüne bakın.

Örnekler	Etki
`entry[link/@rel='edit']`	`rel` özellik değeri `'edit'` olan bir `<link>` öğesi içeren tüm feed girişlerini döndürür.
`entry/title[text()='Today']`	İçeriği `'Today'` ise feed girişlerinde gerçekleşen tüm `<title>` öğelerini döndürür.
`entry/author[name='Jo']`	`'Jo'` içeriğine sahip bir `<name>` alt öğesi varsa feed girişlerinde gerçekleşen tüm `<author>` öğelerini döndürür.
`author[name='Jo']`	`'Jo'` içeriğine sahip bir `<name>` alt öğesi varsa hedef girişteki `<author>` öğesini döndürür.

Seçili öğelerin yalnızca bir kısmını isteyin veya alan alt seçimlerini kullanın.

Varsayılan olarak, isteğiniz belirli öğeleri belirtiyorsa hizmet, öğelerin tamamını döndürür. Yanıtın, seçili öğelerde yalnızca belirli alt öğeleri içermesi gerektiğini belirtebilirsiniz. Bunun için aşağıdaki örneklerde olduğu gibi "( )" alt seçim söz dizimini kullanın.

Örnekler	Etki
`entry/author(uri)`	Feed girişlerindeki yazarlar için yalnızca `<uri>` alt alt öğesini döndürür.
`entry/author[name='Jo'](uri)`	Yazar adı `'Jo'` olan tüm girişler için yalnızca `<author>` `<uri>` alt öğesini döndürür.
`entry(link(@rel,@href))`	Feed girişlerindeki her bir `<link>` öğesi için yalnızca `rel` ve `href` özelliklerinin değerlerini döndürür.
`entry(title,link[@rel='edit'])`	Her feed girişi için yalnızca `rel` düzenleme özelliklerine sahip `<title>` ve `<link>` öğelerini döndürür.
`entry(title,author(uri)`	Her feed girişi için hem `<title>` öğelerini hem de yazar `<uri>` öğelerini döndürür.

Alan koşulu söz dizimi hakkında daha fazla bilgi

Alan koşullarını alanlarda veya alt alanlarda kullanabilirsiniz. Seçili alanın sonuçlara dahil edilmesi için koşul doğru olarak değerlendirilmelidir.Alan koşulu yoksa seçili türdeki tüm alanlar dahil edilir.

Seçili alanın metin değeri karşılaştırmalar için kullanılır. Bu bağlamda, alan bir öğeyse metin değeri içeriktir; alan bir özellikse metin değeri özelliğin değeridir. Alanda metin değeri yoksa karşılaştırma başarısız olur ve alan sonuçlara dahil edilmez.

Aşağıdaki tabloda, alan koşulları için desteklenen XPath operatörleri gösterilmektedir ve bazı örnekler verilmiştir.

Operatör	Söz dizimi	Örnekler
Dize karşılaştırma	`=` veya `eq` `!=` veya `ne`	`rel` özelliği "`self'`" olarak ayarlanmış bir `<link>` öğesi içeriyorsa tüm girişi döndürür: `entry[link/@rel='self']` `'unknown'` dizesine eşit içeriğe sahip bir `<title>` öğesi içeriyorsa tüm girişi döndürür: `entry[title eq 'unknown']` İçeriği `'unknown'` değilse `<title>` öğesinin tamamını döndürür: `title[text() != 'unknown']`
Mantıksal karşılaştırma	`and or not`	`rel` özelliği `'self'` veya `'edit'` olarak ayarlanmış tüm bağlantıları döndürür: `link[@rel='self' or @rel='edit']` `rel` özelliği `'self'`, `type` özelliği ise `'application/atom+xml'` olarak ayarlanmış tüm bağlantıları döndürür: `link[@rel='self' and @type='application/atom+xml']` `'self'` değerine sahip `rel` özelliği olmayan tüm bağlantıları döndürür: `link[not(@rel='self')]` XPath'de olduğu gibi `not` bir işlev çağrısı gibi görünür.
Sayısal karşılaştırma	`=` veya `eq` `!=` veya `ne` `>` veya `gt` `>`= veya `ge` `<` ya da `lt` `<=` veya `le`	Tam sayı 5'e dönüştürülebilen `value` özelliğine sahip `<gd:rating>` öğesini döndürür: `gd:rating[@value=5]` 4.3'ten büyük bir hareketli değere dönüştürülebilen `average` özelliğine sahip `<gd:rating>` öğelerini döndürür : `gd:rating[@average gt 4.3]`
Tarih karşılaştırması	Örneklerde gösterildiği gibi sayısal karşılaştırma operatörleri kullanma	Tarih veya tarih/saat karşılaştırmaları yapmak için öğeleri, özellikleri ya da dize değişmez değerlerini `xs:date` veya `xs:dateTime` içinde yayınlayabilirsiniz. `xs:dateTime` için varsayılan saat dilimi UTC'dir ancak saat dilimini açıkça belirtmeniz önerilir. 1 Ocak 2005'ten beri tarih içeren tüm `<yt:recorded>` öğelerini döndürür: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Belirtilen tarihten sonra güncellenen, UTC saat diliminde belirtilen tüm girişleri döndürür: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Varlık	Örneklerde gösterildiği gibi öğenin veya özelliğin adını kullanın.	`rel` özelliğine sahip bir bağlantı içeren tüm girişleri döndürür: `entry[link/@rel]` `value` adlı özelliğe sahip `<gd:rating>` öğelerini döndürür: `entry/gd:rating[@value]`
Boole	`true()false()`	Boole'lar, test sırasında alan koşullarını doğru veya yanlış durumuna zorlamak için faydalı olabilir. `<link>` öğelerini döndürür: `link[true()]`

Kısmi yanıtları işleme

Kısmi yanıtı destekleyen bir sunucu, fields sorgu parametresini içeren geçerli bir isteği işledikten sonra, istenen özellikler veya öğelerle birlikte bir HTTP 200 OK durum kodu geri gönderir. fields sorgu parametresinde bir hata varsa veya başka bir nedenle geçersizse sunucu bir HTTP 400 Bad Request durum kodu döndürür.

Hedef URI'ye bağlı olarak yanıtın kök öğesi <feed> veya <entry> olur. Kök öğenin içeriği, bu feed veya giriş için yalnızca seçilen alanları ve üst öğelerin çevresindeki etiketleri içerir.

İsteğin fields sorgu parametresinin değeri, iki şekilde tekrarlanabilir:

Kök öğe, istekte belirtilen fields sorgu parametresinin değerini gösteren bir gd:fields özelliğine sahip.
Hedef URI bir feed ise her düzenlenebilir girişte fields seçiminin ona uygulanan kısmını gösteren bir gd:fields özelliği bulunur.

Not: Bu gd:fields özellik değerlerini kısmi yanıtınızda görmek için bunları fields sorgu parametresi spesifikasyonuna eklemeniz gerekir. Bu işlemi açıkça veya @gd:fields kullanarak ya da ETag bilgilerini içeren daha genel @gd:* kullanarak yapabilirsiniz.

Aşağıdaki örnek sorgu, sunucudan yalnızca gd ad alanındaki özellikleri (hem feed hem de giriş düzeyinde) içeren bir dokümanı, feed kimliğini, başlığını ve her bir feed girişi için düzenleme bağlantısını döndürmesini ister:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

Sunucu, 200 Successful HTTP durum koduyla birlikte aşağıdaki kısmi yanıtı döndürür:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

Seçilen alanlar hiçbir şeyle eşleşmiyorsa hizmet yine de bir 200 Successful HTTP durum kodu döndürür, ancak kısmi yanıt boş bir feed'dir:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Kısmi güncelleme (Deneysel)

Kısmi yanıt ve düzenlenebilir kaynakları destekleyen Google ürünleri, kısmi güncellemeleri kullanmanıza da olanak tanır. Kısmi güncellemede, yalnızca tam kaynak temsilinin değiştirilmiş bir sürümünü göndermek yerine yalnızca güncellemek istediğiniz alanları gönderirsiniz. Böylece, istemci uygulamanızın güncelleme yaparken ve verileri almak için kısmi yanıtı kullanırken daha verimli olmasını sağlayabilirsiniz.

Ancak kısmi bir güncelleme yaparken PUT yerine PATCH isteğini kullanmanız gerekir. PATCH için semantik, belirli bir girişe ait belirli alanları tek bir istekle eklemenize, değiştirmenize ve silmenize olanak tanıyacak kadar güçlüdür.

Kullandığınız üründe kısmi güncelleme olup olmadığını öğrenmek için ürüne özel belgelere bakın.

Kısmi güncelleme isteği gönderme

Kısmi güncelleme isteği göndermek için normalde PUT ile kullandığınız URL'ye bir HTTP PATCH isteği gönderir ve kaynağı güncellersiniz. PATCH isteğinin gövdesi, eklemek veya değiştirmek istediğiniz alanları belirten kısmi bir <entry> öğesidir. Girişin gd:fields özelliği, silmek istediğiniz alanları belirtir.

Sunucu, PATCH isteğini belirli bir sırada işler:

İlk olarak gd:fields özelliği tarafından belirtilen alanları kaynak gösteriminden kaldırır.
gd:fields özelliğinin söz dizimi, kısmi bir yanıt istenirken kullanılan fields sorgu parametresiyle aynıdır. Daha fazla ayrıntı için Desteklenen söz dizimi bölümüne bakın.
Ardından bu istek, isteğin gövdesinde sağlanan verileri mevcut kaynak temsiliyle birleştirilir.
Verilerin nasıl birleştirildiğiyle ilgili daha fazla bilgiyi aşağıdaki Alan ekleme veya güncelleme bölümünde bulabilirsiniz.

Not: PATCH isteğinin gövdesi genellikle Atom Sendikasyon Biçimi ile uyumlu olmadığından, PATCH isteğiyle kullandığınız Content-Type application/xml olur.

Kısmi güncelleme isteğiyle ilgili bir örnek:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

Bu PATCH isteği, hedef URI'nın girişi için sunucuda depolanan kaynak temsilinde aşağıdaki değişiklikleri yapar:

<description> öğesini kaldırır.
<title> öğesini günceller.

Kısmi güncelleme isteğinin semantiği

Aşağıdaki talimatlarda, bir girişteki belirli alanları silmek, eklemek veya güncellemek için PATCH isteğinizin nasıl ayarlanacağı açıklanmaktadır. Tek bir PATCH isteği, bu işlemlerin herhangi bir kombinasyonunu gerçekleştirebilir.

Alanlar siliniyor. Kaynaktan silinmesini istediğiniz alanları tanımlamak için <entry> öğesinin gd:fields özelliğini kullanın. Aşağıdaki örnek istek, bir girişle ilişkili başlığı ve özeti siler. Ancak istek, girişle ilgili başka verileri eklemez veya güncellemez.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
Alan ekleme veya güncelleme. Bir kaynak için eklemek veya güncellemek istediğiniz verileri belirtmek amacıyla <entry> öğesinin gövdesini kullanın. Bu alanlar, aşağıdaki kurallara göre herhangi bir silme işlemi yapıldıktan sonra kaynağın mevcut verileriyle birleştirilir:
- Mevcut olmayan alanlar eklenir. Kaynak veriler bir alan için zaten bir değer belirtmiyorsa bu alan, mevcut verilere eklenir. Örneğin, bir girişin başlığı yoksa ve PATCH isteğiniz <title> öğesi içeriyorsa yeni başlık girişe eklenir.
- Mevcut alanlar değiştirilir veya eklenir. Kaynak verilerde daha önce belirtilen alanların birleştirilmesiyle ilgili belirli davranış, alanın özelliklerine bağlıdır:
  - Tekrarlanmayan alanlar değiştirildi. Kaynak veriler zaten tekrarlanmayan bir öğeye ilişkin bir değeri belirtiyorsa PATCH isteğinde belirttiğiniz değer, o öğenin mevcut değerinin yerini alır. Örneğin, aşağıdaki örnekte yeni başlık mevcut başlığın yerini alır.
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    Aşağıda daha karmaşık bir örnek verilmiştir. Bu örnekte, girişin yalnızca bir yazarı olabileceğini ve hedef kaynağın yazarın adı ve e-posta adresi için zaten değer içerdiğini varsayalım. <author> öğesinin iki alt alanı olsa da sağlanan verilerde yalnızca <name> öğesi mevcuttur. Sonuç olarak, yalnızca bu alanın değerinin üzerine yazılır. Sağlanan verilerde eksik olan <email> öğesinin değeri değişmez.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - Yinelenen alanlar eklendi. Kaynak veriler tekrarlanan bir öğe için zaten bir değer belirtiyorsa sağladığınız yeni öğe mevcut değer grubuna eklenir.
    
    Bazı durumlarda, tekrar eden öğenin yeni bir örneğini eklemek dışında bir işlem yapmak isteyebilirsiniz. Örneğin, aşağıdakilerden birini yapmak isteyebilirsiniz:
    - Tekrarlanan öğeler listesinin tamamını değiştirin. Tekrarlanan tüm alanları gd:fields özelliğini (ör. gd:fields='ns:accessControl') kullanarak silebilir ve değiştirme alanlarının tamamını girebilirsiniz. İlk olarak mevcut öğelerin tümü silindiğinden, sağladığınız alan grubu eklendiklerinde mevcut değerlerle çakışmaz.
    - Tekrarlanan bir öğe için mevcut değerler kümesindeki bir değeri değiştirin. Bu durumda, gd:fields değerini, korumak istediğiniz diğer değerlerin silinmesini önleyecek kadar dar bir şekilde tanımlayarak tek bir öğeyi kaldırın. Örneğin, yalnızca action tutarında embed içeren bir erişim denetimini kaldırmak için gd:fields='ns:accessControl[@action="embed"]' işlevini kullanabilirsiniz. Ardından, bunu değiştirmek istediğiniz tek alanı <entry> öğesinin gövdesinde sağlarsınız:
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

Kısmi bir güncellemeye verilen yanıtı işleme

Geçerli bir kısmi güncelleme isteği işlendikten sonra API, 200 OK HTTP yanıt kodu döndürür. Varsayılan olarak yanıtın gövdesi, güncellediğiniz tam giriş olur. Sunucu, PATCH isteğini başarıyla işlediğinde PUT etiketinde olduğu gibi ETag değerlerini günceller.

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

Not: Farklı alanların birbiriyle nasıl ilişkili olduğunu anlamak önemlidir. Bir kaynağı birbirine bağımlı değerlerin yalnızca bir kısmını güncelleyerek tutarsız bir duruma getirmeniz mümkün olabilir. Örneğin, başlangıç zamanını bitiş zamanından sonraki bir değere güncellemek mümkün olabilir. API bir hata kodu döndürmelidir ancak tutarlılığı sağlamak için bu tür koşulları tam olarak test etmenizi öneririz.

PATCH desteklenmediğinde alternatif gösterim

Güvenlik duvarınız PATCH hizmetine izin vermiyorsa bir HTTP POST isteği yapın ve geçersiz kılma başlığını aşağıda gösterildiği gibi PATCH olarak ayarlayın:

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

Kısmi güncellemeyle kısmi yanıt kullanma

Sonraki kısmi kısmi güncelleme isteğinin temeli olarak kısmi bir yanıt kullanabilirsiniz. Bunu yaparsanız @gd:* ve düzenleme bağlantılarını içeren bir fields sorgu parametresi belirtin. Bu, kısmi yanıtın sonraki istekler için önemli olan ETag ve gd:fields özellik değerleri gibi bilgileri içermesini sağlar.

Gelecekteki bir kısmi güncellemenin temeli olarak kullanabileceğiniz kısmi bir yanıt döndüren bir örneği burada bulabilirsiniz:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

Sunucunun yanıtı:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

'jane@gmail.com' e-posta adresine sahip kullanıcıyı kaldırmak, 'will@gmail.com' e-posta adresine sahip bir kullanıcı eklemek ve 'jo@gmail.com' olarak listelenen kullanıcının e-posta adresini 'josy@gmail.com' olarak değiştirmek istediğinizi varsayalım.

Bu değişiklikleri, önceki yanıtın sonuçlarından başlayarak yalnızca farklı alanları değiştirerek ve değiştirilen kısmi girişi PATCH isteğinin gövdesi olarak göndererek yapabilirsiniz. Bu örnekte, gerekli değişiklikler şunlardır:

Sağlanan öğeler listesinden <gd:who email='jane'/> öğesini silin.
Sağlanan öğeler listesine <gd:who email='will@gmail.com'/> ekleyin.
<gd:who email='jo@gmail.com'/> öğesini <gd:who email='josy@gmail.com'/> ile değiştirin.

Sonsuz kısmi yanıta dayalı PATCH isteği aşağıda gösterilmiştir:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Not: Bu yaklaşım, girişin kısmi yanıtına dahil edilen gd:fields ve gd:etag (destekleniyorsa) özelliklerine bağlıdır. Kısmi girişin gövdesi, açık bir şekilde kaldırmak istedikleriniz hariç olmak üzere kısmi yanıtta bulunan tüm alanları ve özellikleri korumalıdır. Gövdedeki mevcut alanlardan herhangi birini yeni değerlerle güncelleyebilir ve eklemek istediğiniz yeni alanları dahil edebilirsiniz.

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:

Masaüstü uygulamaları Yüklü Uygulamalar İçin Hesap Kimlik Doğrulaması ("İstemci Girişi" olarak da bilinir) adlı Google'a özel bir kimlik doğrulama sistemi kullanmalıdır. (Web tabanlı istemciler bu sistemi kullanmamalıdır.)
Web tabanlı istemciler (ör. Google hizmetlerinin üçüncü taraf kullanıcı arabirimleri), Web Tabanlı Uygulamalar için Hesap Kimlik Doğrulaması Proxy'si ("AuthSub" olarak da bilinir) adlı Google'a özel bir kimlik doğrulama sistemi kullanmalı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 Data API istekleri gönderdiğinde istemcinin kullandığı bir jetonu (HTTP Yetkilendirme başlığında) 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 API'leri Kimlik Doğrulamaya 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, Veri API'leriyle ç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:

Birbiriyle kesişen Atom ve RSS karşılaştırması
IBM'den Atom'a Genel Bakış
RSS'ye Dublin Core uzantıları
HTTP 1.1 yöntem tanımları; GET, POST, PUT ve DELETE için spesifikasyon
HTTP 1.1 durum kodu tanımları
REST Protokolü oluşturma
Web Hizmetlerini REST Yolu Olarak Oluşturma
XML'e Teknik Giriş
Örneğe göre XML Ad Alanları
HTTP spesifikasyonunun ETag bölümü

Başa dön