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

Protokol Temel Bilgileri

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 sorgunun görünümü, sonuçların görünümü vb. örneklerle birlikte birçok Google API'si tarafından kullanılan Google Veri Protokolü ile ilgili temel bilgiler verilmektedir.

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

Kitle

Bu doküman, Google Veri API'ları tarafından kullanılan XML biçimi ve protokolü hakkında genel bir fikir edinmek isteyen kişiler içindir.

Dile özgü istemci kitaplıkları kullanan bir kod yazmak istiyor olsanız bile, istemci kitaplığı soyutlama katmanının içeriğini anlamak için bu dokümanı okuyabilirsiniz.

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. İstemciniz, HTTP isteklerinde bulunmanıza ve XML tabanlı yanıtlar ayrıştırmanıza olanak tanıyan herhangi bir programlama dilini kullanarak sunucuyla etkileşim kurabilir.

Bu dokümandaki örnekleri kod yazmadan denemek istiyorsanız cURL veya Wget komut satırı yardımcı programlarını yararlı bulabilirsiniz. Daha fazla bilgi için Google Veri Protokolü'nü kullanan hizmetlerle etkileşimde bulunmak üzere bu yardımcı programlar için manuel sayfalara veya cURL kullanma başlıklı dokümana bakın.

Örnekler

Aşağıdaki örneklerde, doğrudan Google Data Protocol API protokolünü kullanarak genel bir hizmete gönderebileceğiniz HTTP istekleri ve elde edebileceğiniz sonuçlar gösterilmektedir. İsteklerin çeşitli programlama dilleri kullanılarak nasıl gönderileceğine yönelik örnekler için dile özgü örnekleri ve istemci kitaplıklarını inceleyin. Google Veri Protokolü'nü belirli Google hizmetleriyle kullanma hakkında bilgi edinmek için hizmete özel dokümanları inceleyin.

Feed veya başka bir kaynak isteğinde bulunma

/myFeed adlı bir özet akışının olduğunu ve şu anda herhangi bir giriş içermediğini varsayalım. Görmek için aşağıdaki HTTP isteğini sunucuya gönderin:

GET /myFeed

Sunucunun yanıtı:

200 OK

<?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."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Feed herhangi bir giriş içermese de başlık ve yazarın adı gibi meta verileri içerdiğini unutmayın. Ayrıca, HTTP ETag biçiminde bir sürüm tanımlayıcısı da içerir.

Yeni giriş ekleme

Yeni bir giriş oluşturmak için bir POST isteği gönderin ve yeni girişin XML gösterimini sağlayın:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Standart Atom <id>, <link> veya <updated> öğelerini sağlamadığınızı unutmayın. Sunucu, POST isteğinize yanıt olarak bunları oluşturur. Ayrıca, özet akışının yazarının girişin yazarıyla aynı kişi olması gerekmediğini unutmayın.

Sunucunun yanıtı:

201 CREATED

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Dize arama

Belirli bir dizede tam metin araması yapmak için tam metin aramalarını destekleyen bir hizmeti kullanırken q parametresiyle bir GET isteği gönderin. Sorgu parametreleri hakkında daha fazla bilgi için protokol başvuru dokümanındaki Sorgu istekleri bölümüne bakın.

GET /myFeed?q=This

Sunucu, This arama dizesiyle eşleşen tüm girişleri içeren bir feed ile yanıt verir. (Bu durumda yalnızca bir tane vardır.)

200 OK

<?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/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

Bir girişi güncelleme

Mevcut bir girişi güncellemek için aşağıdaki adımları uygulamanız gerekir.

Güncellemek istediğiniz girişi alın.
İstediğiniz gibi değiştirin.
Girişin düzenleme URI'sine, mesaj gövdesinde güncellenmiş girişle birlikte bir PUT isteği gönderin. Düzenleme URI'si önceki örnekte <link rel='edit'> öğesinin href özelliği olarak görünür.

Ayrıca, başka birinin değişikliklerinin üzerine yazmadığınızdan emin olmak için orijinal girişin ETag'ini de belirtmeniz gerekir.

Aşağıdaki örnekte, girişin metnini eski değerinden ("Bu, benim girişim") yeni bir değerle değiştiriyoruz ("Bu benim ilk girişim").

PUT /myFeed/1/1/

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Sunucunun yanıtı:

200 OK

<?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='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

ETag'in değiştiğini unutmayın. Kaynakların sürümleri hakkında daha fazla bilgi için protokol referans dokümanındaki Kaynak sürümü oluşturma (ETag) bölümüne bakın.

Yeni girişi bağlam içinde görmek için kaynağın tamamını tekrar isteyin:

GET /myFeed

Sunucunun yanıtı:

200 OK

<?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/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Not: Güvenlik duvarınız PUT hizmetine izin vermiyorsa bir HTTP POST yapın ve yöntemi geçersiz kılma başlığını şu şekilde ayarlayın:

X-HTTP-Method-Override: PUT

Girişi silme

Mevcut bir girişi silmek için, girişin düzenleme URI'sını kullanarak (önceki örnekte sunucu tarafından sağlandığı şekilde) bir DELETE isteği gönderin.

Güvenlik duvarınız DELETE hizmetine izin vermiyorsa bir HTTP POST uygulayın ve yöntem geçersiz kılma başlığını şu şekilde ayarlayın:

X-HTTP-Method-Override: DELETE

Bir girişi sildiğinizde, koşullu silme (yalnızca, girişi son aldığınız zamandan bu yana değişmediyse silin) veya koşulsuz silme seçeneklerinden birini tercih edebilirsiniz. Daha fazla bilgi için protokol başvuru dokümanının Kaynak sürüm oluşturma (ETag) bölümüne bakın. Koşulsuz şekilde silmek için aşağıdaki HTTP üstbilgisini ayarlayın:

If-Match: *

Aşağıdaki örnekte bir giriş silinir (başlıklar uygun şekilde ayarlanmışsa):

DELETE /myFeed/1/

Sunucunun yanıtı:

200 OK

Feed'de artık herhangi bir giriş olmadığını görmek için GET işlemi daha yapın:

GET /myFeed

Sunucu, yalnızca meta veri içeren bir feed ile yanıt verir:

200 OK

<?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/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Silme işlemi başarısız olursa sunucu bir hata koduyla yanıt verir. Daha fazla bilgi için protokol başvuru dokümanındaki HTTP durum kodları bölümüne bakın.

Kısmi feed veya giriş isteme (Deneysel)

Bu dokümanda gösterilen basit örnek feed'in aksine, feed'ler pratikte oldukça karmaşık olabilir. Bazı API'lerde, kaynağın tam temsili yerine yalnızca ilgili öğeleri veya özellikleri isteyebilirsiniz. Gereksiz verileri almaktan ve ayrıştırmaktan kaçınarak istemci uygulamanızın verimliliğini önemli ölçüde artırabilirsiniz.

Kısmi yanıt istemek için hangi sorgu ve öğelerin döndürülmesini istediğinizi belirtmek üzere fields sorgu parametresini kullanın. Daha fazla bilgi için protokol başvuru dokümanındaki Kısmi yanıt bölümüne bakın.

Aşağıdaki örnekte her bir feed girişi için yalnızca feed kimliği, yazar ve başlık gösterilmektedir.

GET /myFeed?fields=id,entry(author)

Sunucunun yanıtı:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

fields parametresini veri döndüren herhangi bir istekle kullanabilirsiniz. GET metriğine ek olarak, POST ve PUT da (kısmi güncelleme istekleri için kullanılan PATCH) dahildir.

Not: fields sorgu parametresi yalnızca bir isteğe yanıt olarak geri gönderilen verileri kontrol eder. PUT, POST veya PATCH isteğinin gövdesinde sağlamanız gereken verileri etkilemez.

POST ve PUT ile ilgili örnekler aşağıda verilmiştir.

Kısmi yanıt için POST isteğinde bulunsanız da Yeni giriş ekleme bölümünde açıklananlarla aynı verileri sağlamanız gerekir. Aşağıdaki örnekte yalnızca yeni oluşturulan girişin başlığını içeren kısmi bir yanıt isteyebilirsiniz:
```
POST /myFeed?fields=title
      
...data...
```
Sunucunun yanıtı:
```
200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
```
Kısmi yanıt için PUT isteğinde bulunsanız da Girişleri güncelleme bölümünde açıklandığı gibi tam kaynak temsilinin değiştirilmiş bir sürümünü sağlamanız gerekir. Aşağıdaki örnekte, yalnızca değiştirilen girişin yeni ETag değerini içeren kısmi bir yanıt isteyebilirsiniz:
```
PUT /myFeed/1/1?fields=@gd:etag
  
...data...
```
Sunucunun yanıtı:
```
200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>
```

Belirli alanları güncelleme (Deneysel)

Kullandığınız API kısmi yanıtı destekliyorsa ve düzenlenebilir alanlar varsa, bir girişi değiştirirken gereksiz verileri göndermekten de kaçınabilirsiniz. Kısmi güncelleme yalnızca değiştirmek istediğiniz alanlar için veri göndermenize olanak tanır.

Kısmi güncelleme kullanmak için PUT ile kullandığınız düzenleme URI'sına PATCH isteği gönderirsiniz. PATCH ile gönderdiğiniz veriler belirli kurallara uygun olmalıdır. Ancak semantik, tek bir istekle hedef kaynaktaki verileri değiştirmeniz, ona veri eklemeniz veya hatta silme işlemi yapmanız için yeterli düzeyde esnektir.

Not: PUT ürününde olduğu gibi, başka birinin değişikliklerini geçersiz kılmadığınızdan emin olmak için orijinal girişin ETag'ini belirtmeniz gerekir.

PATCH ve anlamları hakkında daha fazla bilgi için protokol referans dokümanındaki Kısmi güncelleme bölümüne bakın.

Bu örnekte, girişin başlığını değiştiren kısmi bir güncelleme isteği gösterilmektedir:

PATCH /myFeed/1/1/

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

Sunucu bir PATCH isteği aldığında önce girişin gd:fields özelliği tarafından belirtilen tüm alanları (varsa) kaldırır ve ardından istek gövdesinde sağlanan verileri hedef kaynakla birleştirir. Bu örnekte, başlık öğesi ilk olarak hedef kaynaktan kaldırılır, ardından yeni başlık değeri birleştirilir. Bu istek, eski başlığın yerine yenisini koyar.

Ancak PATCH öğesinin semantiğinin, kısmi temsili mevcut kaynağa birleştireceğini unutmayın. Değerini güncellemek için her zaman bir alanı kaldırmanız gerekmez.

Alan, hedef girişte yalnızca bir kez mevcutsa birleştirmede kısmi temsildeki alan, hedef girişte karşılık gelen alanın üzerine yazar.
Alan, hedef girişte birden fazla kez mevcut olabilirse birleştirilen kısmi alan hedef girişe eklenir.

Tekrarlanan ve yinelenmeyen alanların nasıl birleştirileceği bir sonraki örnekle gösterilir. Bu örnek, bunlardan birini kaldırmak için gd:fields özelliğini kullanmadan girişe yeni bir başlık ve yazar ekler.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Kısmi giriş temsilinde gd:fields özelliği olmadığından hiçbir alan kaldırılmaz. Ancak <title> ve <author> öğelerinin yeni değerleri hedef kaynakla birleştirilir:

Atom giriş başına yalnızca bir başlığa izin verdiğinden, yeni başlık mevcut değerin üzerine yazar.
Atom giriş başına birden fazla yazara izin verdiğinden, yeni yazar zaten hedef kaynakta bulunan yazar öğeleri listesine eklenir.

Not: Tüm API'ler Atom standardına uygun değildir. Örneğin, bazı API'ler giriş başına yalnızca tek bir <author> öğesine izin verirken diğerleri, feed düzeyinden giriş girişini devralır ve alanı salt okunur hale getirir.

Sunucu geçerli bir PATCH isteğini işledikten sonra, HTTP 200 durum kodunu ve güncellenmiş girişin tam temsilinin bir kopyasını döndürür.

Sunucunun yalnızca belirli öğeleri veya özellikleri döndürmesini tercih ederseniz kısmi yanıt istemek için fields sorgu parametresini PATCH ile kullanabilirsiniz.

Ek kaynaklar

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

IBM'den Atom'a Genel Bakış
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ı

Başa dön