JavaScript İstemci Kitaplığı'nı (v2.0) Kullanma

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, Google Data API sorguları göndermek ve döndürülen yanıtları yorumlamak için JavaScript istemci kitaplığının nasıl kullanılacağı açıklanmaktadır.

Google, veri API'leri olan hizmetlerle etkileşimde bulunmak için çeşitli programlama dillerinde bir dizi istemci kitaplığı sağlar. Bu kitaplıkları kullanarak API istekleri oluşturabilir, bunları bir hizmete gönderebilir ve yanıtları alabilirsiniz.

Bu dokümanda, JavaScript istemci kitaplığının kullanımıyla ilgili bazı genel bilgilerin yanı sıra yaygın kullanımlara ilişkin örnekler de sağlanmaktadır.

Kitle

Bu doküman, Google veri hizmetleriyle etkileşime girebilecek istemci uygulamaları yazmak isteyen JavaScript programcıları için hazırlanmıştır.

Bu dokümanda, Google Veri API'leri protokolü ile ilgili genel fikirleri anladığınız varsayılmaktadır. Ayrıca, JavaScript'te nasıl programlama yapacağınızı bildiğiniz de varsayılır.

İstemci kitaplığı tarafından sağlanan sınıflar ve yöntemler hakkında referans bilgiler için JavaScript istemci kitaplığı API referansı (JSdoc biçiminde) bölümüne bakın.

Bu belge, düzenli bir şekilde okunacak şekilde tasarlanmıştır. Her örnek önceki örneklere dayanır.

Kullanım şartları

JavaScript istemci kitaplığını kullanırken Google JavaScript İstemci Kitaplığı Kullanım Şartları'na uymayı kabul edersiniz.

Veri modeline ve kontrol akışına genel bakış

JavaScript istemci kitaplığı, Google Veri API'ları tarafından kullanılan öğeleri temsil etmek için bir sınıf kümesi kullanır.

Not: Verilerin temel temsili JSON'dur ancak istemci kitaplığı bir soyutlama katmanı sağladığından doğrudan JSON verileriyle çalışmak zorunda kalmazsınız. İstemci kitaplığı olmadan doğrudan JSON ile çalışmak istiyorsanız Google Veri API'leriyle JSON kullanma başlıklı makaleyi inceleyin.

Kitaplık, data API'si olan bir hizmete eşzamansız olarak veri göndermenize ve bunlardan veri almanıza olanak tanıyan yöntemler sunar. Örneğin, google.gdata.calendar.CalendarService.getEventsFeed() yöntemi, Google Takvim'e bir feed isteği gönderir. İlettiğiniz parametrelerden biri geri çağırma olarak da bilinen bir devam etme işlevidir; hizmet, devam ettirme işlevini çağırarak feed'i JSON biçiminde döndürür. Ardından istemci, verileri JavaScript nesneleri biçiminde kullanmak için çeşitli get yöntemleri çağırabilir.

Yeni bir giriş eklemek için istemci kitaplığının sınıflarını ve yöntemlerini kullanarak girişi oluşturursunuz, ardından yeni yöntemi hizmete göndermek için feed.insertEntry() yöntemini çağırırsınız. Yine, bir giriş işlevi başarıyla eklendiğinde, hizmetin çağırdığı bir devam etme işlevi sağlarsınız.

JavaScript'i kullanmaya yeni başladıysanız kontrol akışı biraz kafa karıştırıcı olabilir. Çoğu durumda komut dosyanız, getEventsFeed() veya insertEntry() gibi bir yöntemle çağrıldıktan sonra sona erer. Hizmet istenen verileri döndürdüğünde yürütme işlemi, devam etme işlevinde devam eder. Bu nedenle, istemcinizin döndürülen verilere yaptığı işlemler devam etme işlevinde yapılmalı veya bu işlevden çağrılmalıdır. Bazı değişkenleri birden çok işlevde kullanabilmek için global hale getirmeniz gerekebilir.

Bu tür programlama hakkında daha fazla bilgi edinmek için Wikipedia'da "Devamı iletme stili" bölümüne bakın.

Desteklenen ortamlar hakkında

Şu anda yalnızca tarayıcıda web sayfasında çalışan JavaScript istemci uygulamalarını destekliyoruz. Şu anda desteklenen tarayıcılar şunlardır:

  • Firefox 2.x ve 3.x
  • Internet Explorer 6, 7 ve 8
  • Safari 3.x ve 4.x
  • Google Chrome (tüm sürümler)

JavaScript istemci kitaplığı, hizmet sunucusuyla tüm iletişimleri yürütür. Deneyimli bir JS geliştiricisiyseniz şunu düşünebilirsiniz: "Peki aynı kaynak politikası mı?" JavaScript istemci kitaplığı, istemcinizin tarayıcı güvenlik modeliyle uyumluluğu korurken herhangi bir alandan Google Veri istekleri göndermesine olanak tanır.

Google Veri API'leriyle kimlik doğrulamaya genel bakış için Google Veri API'leri Kimlik Doğrulamasına Genel Bakış başlıklı makaleye bakın. Bu belgenin geri kalanında, bu sistemin nasıl çalıştığıyla ilgili temel bilgilere sahip olduğunuzu varsayıyoruz.

Örnek istemci uygulamaları

JavaScript istemci kitaplığının nasıl çalıştığını görmek için örnekler sayfamızı ziyaret edin.

Eğitim ve örnekler

Aşağıdaki örneklerde, JavaScript istemci kitaplığı kullanılarak farklı veri API isteklerinin nasıl gönderileceği gösterilmektedir.

Bunları daha somut hale getirmek için belirli bir hizmetle nasıl etkileşimde bulunulacağını gösteren şu örnekler gösterilmektedir: Google Takvim. Takvim'in diğer Google hizmetlerinden farklı olduğu noktalara dikkat çekmek için bu örnekleri diğer hizmetlerle birlikte kullanmanıza yardımcı olacağız. Takvim hakkında daha fazla bilgi için Google Calendar Data API dokümanını inceleyin.

Kitaplık yükleniyor

İstemcinizin istemci kitaplığını kullanabilmesi için istemciden istemci kitaplığı kodunu istemesi gerekir.

Google AJAX API yükleyicisini getirmek için HTML dokümanınızın <head> bölümünde bir <script> etiketi kullanarak başlayın:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Google'ın sunucularına yapılan gidiş gelişleri en aza indirebilir ve kitaplığı önceden yükleyerek gecikmeyi azaltabilirsiniz. Belirli paketleri doğrudan Google AJAX API yükleyicisinden önceden yüklemek için (google.load() kullanılmadan aşağıya bakın) aşağıdakileri kullanın:

<script type="text/javascript"
      src="https://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3Agdata%2Cversion%3A2.x%2Cpackages%3A%5Bblogger%2Ccontacts%5D%7D%5D%7D"></script>

Not: Komut dosyasının src URL'si tamamen url olarak kodlanmış olmalıdır. Örneğin, önceki örnek
<script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script>.

Modülleri otomatik olarak yüklemiyorsanız Google Yükleyici istemci kitaplığını, genel yükleyiciyi aldıktan sonra JavaScript kurulum kodunuzdaki sonraki örneği kullanarak yükleyebilirsiniz. Bu çağrı, HTML dokümanınızın <head> bölümünden (veya HTML dokümanınızın <head> bölümünde bir <script> etiketi kullanılarak eklenmiş bir JavaScript dosyasından) yapılmalıdır:

google.load("gdata", "2");

Alternatif olarak, kitaplığın tamamı yerine belirli hizmetleri isteyebilirsiniz. Bu örnekte yalnızca Blogger ve Kişiler için paketler indirilir:

google.load("gdata", "2.x", {packages: ["blogger", "contacts"]});

İkinci parametre, google.load() JavaScript istemci kitaplığı için istenen sürüm numarasıdır.Sürüm numaralandırma şemamız, Google Haritalar API'si tarafından kullanılan model temel alınarak modellenmiştir. Olası sürüm numaraları ve bunların ne anlama geldiği aşağıda açıklanmıştır:

"1"
Ana sürüm 1'in sondan ikincisine düzeltme.
"1.x"
Ana sürüm 1'in en son düzeltmesi.
"1.s"
Ana sürüm 1'in en son kararlı sürümü. Bazen geliştiricilerden aldığımız geri bildirimlere göre, istemci kitaplığının belirli bir sürümünün "kararlı" olduğunu beyan ederiz. Ancak, bu sürüm en son özelliklere sahip olmayabilir.
"1.0", "1.1" vb.
Kütüphanenin belirli bir ana ve küçük düzeltme numarasıyla belirli bir sürümü.

google.load() çağırdıktan sonra, yükleyiciye sayfanın yüklenmesinin tamamlanmasını beklemesini ve ardından kodunuzu çağırmasını sağlamanız gerekir:

google.setOnLoadCallback(getMyFeed);

Burada getMyFeed(), bu dokümanın bir sonraki bölümünde tanımlanan bir işlevdir. <body> öğesine bir onload işleyici eklemek yerine bu yaklaşımı kullanın.

Kimliği doğrulanmamış bir feed isteme

Kimliği doğrulanmamış bir feed istemek için aşağıdaki kodu JavaScript dosyanıza veya HTML dosyanızdaki bir <script> etiketine ekleyin.

Aşağıdaki kodda ilk olarak getMyFeed() çağrılır (bir önceki bölümde açıklandığı gibi AJAX API yükleyicisi tarafından).

Bu dosya, Google Takvim ile bağlantı (TakvimService nesnesi tarafından temsil edilir) oluşturmak için setupMyService() yöntemini çağırır. Hizmet oluşturma kodunu modülerlik için ayrı bir işleve taşıdık. Daha sonra setupMyService() işlevinde kimlik doğrulama seçimlerinize bağlı olarak değişiklik yapacağız.

Hizmetin kurulumundan sonra getMyFeed(), feed istemek için istemci kitaplığının getEventsFeed() yöntemini çağırır.

Feed URL'sini daha sonraki işlevlerde kullanılabilmesi için genel bir değişkende belirtiyoruz. Bu örnekte, liz@gmail.com adlı bir kullanıcı için herkese açık (kimliği doğrulanmamış) feed URL'sini kullanıyoruz. Ayrıca, kimliği doğrulanmış kullanıcıyı temsil etmek için kullanıcının e-posta adresi yerine default kullanabilirsiniz.

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/public/full";

function setupMyService() {
  var myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
  return myService;
}

function getMyFeed() {
  myService = setupMyService();

  myService.getEventsFeed(feedUrl, handleMyFeed, handleError);
}

Daha sonraki işlevlerde kullanım kolaylığı sağlamak amacıyla myService özelliğini genel bir değişken haline getirdiğimizi unutmayın.

Yukarıdaki kodun kendi istemcinizde çalışması için, herkese açık olarak paylaşılan bir takvimi olan Takvim hesabında gerçek bir kullanıcının e-posta adresini kullanmanız gerekir.

Not: Yeni bir CalendarService nesnesi oluşturduğunuzda istemci kitaplığı, istemcinin çalıştığı tarayıcının desteklenip desteklenmediğini kontrol eden google.gdata.client.init() adlı bir yöntem çağırır. Bir hata varsa istemci kitaplığı kullanıcıya bir hata mesajı gösterir. Bu tür hataları kendiniz işlemek istiyorsanız hizmeti oluşturmadan önce google.gdata.client.init(handleInitError) işlevini açıkça çağırabilirsiniz. Burada handleInitError() işlevi kullanılır. Bir init hatası oluşursa işleviniz standart bir Hata nesnesi alır. Bu nesneyle istediğiniz şeyi yapabilirsiniz.

getEventsFeed() çağrısında ikinci bağımsız değişken olan handleMyFeed, geri çağırma işlevidir. Aşağıya bakın. Google Takvim isteği işler ve ardından, istek başarılı olursa geri çağırmaya, istenen feed'i içeren bir "feed root" nesnesi iletir. Feed kökü, feed içeren bir kapsayıcı nesnedir.

getEventsFeed() bağımsız değişkenine ait üçüncü bağımsız değişken, isteğe bağlı bir hata işleme işlevidir. İstemci kitaplığı bir hatayla karşılaşırsa başarılı geri çağırma işlevi yerine belirtilen hata işleyiciyi çağırır. İstemci kitaplığının hata işleyiciye bağımsız değişken olarak ilettiği nesne, ek bir cause özelliği olan JavaScript Error nesnesinin bir örneğidir.

Geri çağırma işlevinin ve hata işleyicinin basit sürümleri şunlardır: 

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
}

function handleError(e) {
  alert("There was an error!");
  alert(e.cause ? e.cause.statusText : e.message);
}

Hataları sadece kullanıcıya göstererek ele alıyoruz. Müşterinizin hata işleyicisi büyük olasılıkla daha gelişmiş olmalıdır. Bazı durumlarda neden belirtilmemiş olabilir. Bu gibi durumlarda örnek hata işleyicimiz standart message özelliğini gösterir.

Bu kod kimlik doğrulama yapmadığından, yalnızca herkese açık bir feed almak için kullanabileceğinizi unutmayın.

Kimlik Doğrulama

JavaScript istemci kitaplığı iki modda kullanılabilir. Bir gadget yazıyorsanız bu kimlik doğrulama için OAuth Proxy adı verilen bir özellik kullanır. Bağımsız bir JavaScript uygulamasından erişiliyorsa AuthSub kimlik doğrulama sistemini kullanır. Kimlik doğrulama hakkında bilgi edinmek için Google Veri API'leri Kimlik Doğrulamasına Genel Bakış dokümanını inceleyin. Bu bölümün geri kalanında, bu sistemin işleyiş şekliyle ilgili temel bilgilere sahip olduğunuz varsayılır.

Bu dokümanda sağlanan örnek kodla kimlik doğrulamayı kullanmadan önce, feed URL'sini herkese açık yerine gizli olarak değiştirin:

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/private/full";

AuthSub ile web istemcisinde kimlik doğrulama

Google'ın "JavaScript için AuthSub" yetkilendirme sistemi artık kullanılamamaktadır.

Bunun yerine istemci tarafı uygulamalar için OAuth 2.0'ı kullanmanızı öneririz.

Bir OAuth'ta OAuth Proxy'siyle Kimlik Doğrulama

Aşağıda, bir gadget'ın kimlik doğrulama sürecinde ne olacağına ilişkin kısa bir genel bakış verilmiştir:

  1. Gadget'ınız ilk kez yükleniyor ve Google Veri API'larından birini kullanarak kullanıcının verilerine erişmeye çalışıyor.
  2. Kullanıcı henüz verilerine erişim izni vermediğinden istek başarısız oldu. Yanıt nesnesi, OAuth onay sayfası için bir URL (response.oauthApprovalUrl URL'si) içeriyor. Gadget'ınız, bu URL ile yeni bir pencere başlatmak için bir yöntem sağlamalıdır.
  3. Onay sayfasında kullanıcı, gadget'ınıza erişim izni vermeyi/reddetmeyi seçer. İstek başarılı olursa kullanıcı belirttiğiniz oauth_callback sayfasına yönlendirilir. En iyi kullanıcı deneyimi için http://oauth.gmodules.com/gadgets/oauthcallback kullanın.
  4. Ardından, kullanıcı pop-up penceresini kapatır. Kullanıcının onay verdiğini gadget'ınıza bildirmenize yardımcı olmak için onay penceresi kapanışını algılamak üzere kullanabileceğiniz bir pop-up işleyici sağladık. Alternatif olarak, gadget'ınız bu pencere kapandıktan sonra kullanıcının manuel olarak tıklaması için bir bağlantı (ör. "Erişimi onayladım") gösterebilir.
  5. Gadget'ınız, kullanıcı verilerini yeniden talep ederek Google Data API'sine ikinci kez erişmeyi dener. Bu deneme başarılı.
  6. Gadget'ınızın kimliği doğrulanmıştır ve normal şekilde çalışmaya başlayabilir.

Gadget'ınızın <ModulePrefs> bölümüne bir <OAuth> öğesi ekleyin:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" /> 
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" /> 
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" /> 
  </Service>
</OAuth>
...
</ModulePrefs>

Bu bölümde aşağıdaki sorgu parametrelerini değiştirin:

  • scope

    İstek URL'sinde gerekli bir parametre. Gadget'ınız, yalnızca bu parametrede kullanılan scope öğelerindeki verilere erişebilir. Bu örnekte, gadget Blogger ve Takvim verilerinize erişir. Bir gadget tek bir kapsam veya birden çok kapsam için veri isteyebilir (bu örnekte olduğu gibi).

  • oauth_callback

    Yetkilendirme URL'sinde isteğe bağlı bir parametredir. Kullanıcı, verilerine erişimi onayladıktan sonra OAuth onay sayfası bu URL'ye yönlendirilir. Bu parametreyi değiştirmeyi, kendi "onaylanan sayfanız" olarak ayarlamayı veya tercihen http://oauth.gmodules.com/gadgets/oauthcallback kullanmayı seçebilirsiniz. Daha sonra, kullanıcılar gadget'ınızı ilk kez yüklediklerinde en iyi kullanıcı deneyimini sağlar. Bu sayfa, pop-up penceresini otomatik olarak kapatan bir JavaScript snippet'i sağlar.

Ardından, gadget'ınızın <Content> bölümüne JavaScript istemci kitaplığını yükleyin. Hizmet nesnesinin useOAuth() yöntemini çağırmak için önceki örneklerden setupMyService() işlevini değiştirin. Bu işlem, gadget'a kimlik doğrulaması için AuthSub yerine OAuth Proxy'yi kullanmasını bildirir. Aşağıdaki şablon ile başlamanıza yardımcı olabilir:

<Content type="html">
<![CDATA[
  ...
  <script src="https://www.google.com/jsapi"></script>
  <script type="text/javascript">
    var myService = null;
    
    function setupMyService() {
      myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
      myService.useOAuth('google');
      fetchData();
    }
    
    function initGadget() {
      google.load('gdata', '2.x');
      google.setOnLoadCallback(setupMyService);
    }

    function fetchData() {            
      var callback = function(response) {
        if (response.oauthApprovalUrl) {
        
          // TODO: Display "Sign in" link (response.oauthApprovalUrl contains the URL) 
          
        } else if (response.feed) {
        
          // TODO: show results
          
        } else {
        
          // TODO: handle the error
          
        }
      };

      myService.getEventsFeed('http://www.google.com/calendar/feeds/default/public/full', callback, callback);
    }
    
    gadgets.util.registerOnLoadHandler(initGadget);
  </script>
  ...
]]> 
</Content>

google.accounts.user.login(scope) numaralı telefona yapılan aramanın kaldırıldığına dikkat edin. Proxy, kimlik doğrulama işlemini sizin yerinize yapar.

fetchData() uygulamasının içermesi gerekenlerle ilgili ayrıntılar da dahil olmak üzere Google Data API gadget'ları yazma hakkında daha fazla bilgi için Google Veri Gadget'ı oluşturma konulu makalemizi veya OAuth Gadget'ları Yazma dokümanlarının tamamını inceleyin.

Yeni öğe ekleme

Yeni bir takvim etkinliği oluşturmak için önceki işlevi yerine getirmek üzere handleMyFeed() işlevinin sonunu değiştirerek yeni bir işlev yürütün:

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
  insertIntoMyFeed(myResultsFeedRoot);
}

Yeni işlevde, yeni girişi oluşturmak için önce CalendarEventEntry oluşturucuyu kullanın. Ardından, ekleme tamamlandığında hizmetin çağırması için geri çağırma sağlayarak girişi ekleyin.

function insertIntoMyFeed(feedRoot) {
  var newEntry = new google.gdata.calendar.CalendarEventEntry({
      authors: [{
        name: "Elizabeth Bennet",
        email: "liz@gmail.com"
      }],
      title: {
        type: 'text', 
        text: 'Tennis with Darcy'
      },
      content: {
        type: 'text', 
        text: 'Meet for a quick lesson'
      },
      locations: [{
        rel: "g.event",
        label: "Event location",
        valueString: "Netherfield Park tennis court"
      }],
      times: [{
        startTime: google.gdata.DateTime.fromIso8601("2007-09-23T18:00:00.000Z"),
        endTime: google.gdata.DateTime.fromIso8601("2007-09-23T19:00:00.000Z")
      }]
  });
  feedRoot.feed.insertEntry(newEntry, handleMyInsertedEntry, handleError);
}

Oluşturucuda kullanılan her nesne özelliğinin adının, bu mülk için kullanılan seter yönteminin adıyla eşleştiğini unutmayın. (Örneğin, karşılık gelen JSON alanı adıyla eşleşmez.)

Ayrıca, startTime ve endTime için ISO 8601 tarih ve saat dizelerini sağlayamayacağınızı da unutmayın. Bu tür dizeleri önce fromIso8601() yöntemiyle çalıştırmanız gerekir.

Hizmet, eklenen girişin bir kopyasını entryRoot nesnesi olarak döndürür ve bu nesneyi geri çağırmaya iletir:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
}

Belirli bir giriş isteme

Belirli bir girişi istemek için öncelikle handleMyInsertedEntry() işlevini yeni bir giriş-istek işlevini çağıracak şekilde değiştirin:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
  requestMySpecificEntry(insertedEntryRoot.entry.getSelfLink().getHref());
}

Aşağıdaki kod, önceki örnekte eklediğiniz giriş için istekte bulunmanıza olanak tanır.

Bu örnek dizisi bağlamında, Takvim zaten eklenen girişi döndürdüğünden bu girişi almak çok da gerekli değildir, ancak bir girişin URI'sını bildiğinizde aynı teknik uygulanabilir.

function requestMySpecificEntry(entryURI) {
  myService.getEventsEntry(entryURI, handleMySpecificEntry, handleError);
}

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}

Bu örnek temel olarak getEventsFeed() örneğiyle aynıdır. Aradaki tek fark, belirli bir girişi almak için hizmetin getEventEntry() yöntemini çağırmamız ve URI'nın biraz farklı olmasıdır. Kimliği doğrulanmış kullanıcının ana takvimini belirtmek için "varsayılan" ifadesini kullanır ve sonunda da bir giriş kimliği vardır.

Ayrıca, alınan girişi daha sonra kullanabilmemiz için global bir değişkene kopyalıyoruz.

Girişler aranıyor

Tam metin araması gerçekleştirmek için önce, handleMySpecificEntry() işlevini yeni bir arama işlevi çağıracak şekilde değiştirin:

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
  searchMyFeed();
}

Ardından, aramadan ilk eşleşmeyi almak için aşağıdaki kodu kullanın:

function searchMyFeed() {
  var myQuery = new google.gdata.calendar.CalendarEventQuery(feedUrl);
  myQuery.setFullTextQuery("Tennis");
  myQuery.setMaxResults(10);
  myService.getEventsFeed(myQuery, handleMyQueryResults, handleError);
}

function handleMyQueryResults(myResultsFeedRoot) {
  if (myResultsFeedRoot.feed.getEntries()[0]) {
    alert("The first search-match entry's title is: " + myResultsFeedRoot.feed.getEntries()[0].getTitle().getText());
  }
  else {
    alert("There are no entries that match the search query.");
  }
}

Öğe güncelleme

Mevcut bir öğeyi güncellemek için önce handleMyQueryResults() sonuna bir satır ekleyerek yeni bir güncelleme işlevi çağırın:

  updateMyEntry();

Ardından aşağıdaki kodu kullanın. Bu örnekte, daha önce alınan girişin başlığını (önceki bir örnekte myEntryRoot adlı genel nesnede bulunan) eski metninden "Tenis ile Tenis"in başlığını "Önemli toplantı" olarak değiştiriyoruz.

function updateMyEntry() {
  myEntryRoot.entry.getTitle().setText("Important meeting");
  myEntryRoot.entry.updateEntry(handleMyUpdatedEntry, handleError);
}

function handleMyUpdatedEntry(updatedEntryRoot) {
  alert("Entry updated. The new title is: " + updatedEntryRoot.entry.getTitle().getText());
}

Tüm Takvim yöntemlerinde olduğu gibi updateEntry() yöntemi, girişi güncellerken kullanılacak doğru düzenleme URI'sını otomatik olarak belirler. Böylece bu URI'yı açık bir şekilde sağlamanız gerekmez.

Öğe silme

Güncellenen girişi silmek için öncelikle handleMyUpdatedEntry() satırına satır ekleyin:

 deleteMyEntry(updatedEntryRoot);

Ardından aşağıdaki kodu kullanın:

function deleteMyEntry(updatedEntryRoot) {
  updatedEntryRoot.entry.deleteEntry(handleMyDeletedEntry, handleError);
}

function handleMyDeletedEntry() {
  alert("Entry deleted");
}

deleteEntry() yöntemi, girişi silmek için kullanılacak doğru düzenleme URI'sini otomatik olarak belirler.

Herhangi bir girişin döndürülmediğini unutmayın. Geri çağırma çağrılırsa silme işleminin başarılı olduğunu biliriz; silme başarısız olursa deleteEntry(), handleMyDeletedEntry() yerine handleError() numarasını arar.

E-Etiketleri Kullanma

Not: ETag'ler yalnızca Google Veri Protokolü 2.0 sürümünü çalıştıran hizmetlerle kullanılabilir.

Giriş

Google Veri JavaScript İstemcisi'nin 2. sürümü, ETag'ler için destek sunmaktadır. E-etiketler, belirli bir girişin belirli bir sürümünü belirten tanımlayıcılardır. Bu, iki durumda önemlidir:

  • "Koşullu alma" yöntemini (bir istemcinin giriş istediği) ve sunucu yalnızca girişi istemcinin son isteği istemesinden sonra değişmiş olması durumunda gönderir.
  • Birden fazla müşterinin yanlışlıkla birbirlerinin yaptığı değişikliklerin üzerine yazmadığından emin olmak. İstemciler giriş için eski bir ETag belirtiyorsa Veri API'leri bunu güncelleme ve silme yaparak gerçekleştirir.

İki tür ETag etiketi vardır: zayıf ve güçlü. Zayıf bir ETag her zaman W/ ile başlar. Örneğin: W/"D08FQn8-eil7ImA9WxZbFEw". Zayıf ETag'lerin giriş değiştiğinde değişmesi garanti edilmez. Bu nedenle HTTP, bunların yalnızca koşullu alma için kullanılmasına olanak tanır. Güçlü ETag'ler belirli bir girişin belirli bir sürümünü tanımlar, diğer müşterilerin değişikliklerinin üzerine yazmamak için hem koşullu alma hem de güncelleme veya silme işlemleri sırasında kullanılabilir. Bu fark nedeniyle, istemci kitaplığı güncelleme veya silme isteğiyle zayıf ETag etiketleri göndermenize izin vermez.

ETag'ler, sunucunun yanıtında iki konumda bulunabilir:

  • ETag HTTP üst bilgisinde.
  • Feed'de/girişte gd:etag özelliği olarak.

Bir hizmet Sürüm 2'yi destekliyorsa her feed ve giriş nesnesinin ETag değerini almak için bir getEtag() yöntemi olur.

JavaScript istemcisi, bir istekle birlikte ETag'leri dahil etmek için iki yöntemi destekler. İlk nesne, yeni opt_params nesnesidir. İstemci kitaplığının 2. sürümündeki tüm get/update/insert işlevleri için yeni bir opt_params parametresi var. Bu nesne, istekte bulunurken isteğe bağlı parametreleri belirtmek için kullanılır. Şu anda 'etag', desteklenen tek isteğe bağlı parametredir (ileride başka parametreler de sunulabilir). Örneğin, bir GET isteğine aşağıdaki gibi bir ETag ekleyebilirsiniz:

var opt_params = {};
opt_params['etag'] = 'ETAG GOES HERE';
service.getFeed(uri, successHandler, errorHandler, opt_params);

Ayrıca, feed'deki/girişteki setEtag() yöntemini çağırarak doğrudan feed'e veya giriş nesnesine ETag ekleyebilirsiniz.

EG etiketleri hakkında daha fazla bilgiyi GData Protocol Reference (GVeri Protokolü Referansı) sayfasında bulabilirsiniz.

Verileri almak için ETag'leri kullanma

ETag'ler, verileri alırken bant genişliğinin ve yürütme süresinin azaltılmasına yardımcı olabilir. ETag, If-None-Match header: ile birlikte bir GET isteğine dahil edilebilir

If-None-Match: ETAG GOES HERE

ETag, feed'in veya girişin geçerli sürümüyle eşleşirse sunucu, 304 NOT MODIFIED yanıtı ve boş gövdeyle yanıt verir. Aksi takdirde sunucu, 200 OK yanıtı ve feed veya giriş verileriyle yanıt verir.

İstekte bulunurken bir 'etag' parametresi ekleyerek JavaScript istemcisinde ETag'leri kullanabilirsiniz:

var etag = feed.getEtag(); // Feed loaded from a previous request
var opt_params = {};
opt_params['etag'] = etag;
service.getFeed(feedUrl, successHandler, errorHandler, opt_params);

Koşullu almalar hem güçlü hem de zayıf ETag etiketleriyle çalışır. ETag bir eşleşmeyse hata işleyici, 304 yanıtıyla birlikte çağrılır:

function successHandler(feedRoot) {
  // 200 response
  // Update UI to display updates
}

function errorHandler(errorObj) {
  if (errorObj.cause.getStatus() == 304) {
    // 304 response, do nothing
  }
  // otherwise the response is some other error
}

JavaScript istemcisinde ETag'lerin kullanımı hakkında daha pratik bir örnek görmek için Blogger Kullanarak Koşullu Alma örneğine göz atın. Bu örnek, blogunuzda güncelleme olup olmadığının belirlenmesi için 5 saniyelik aralıklarla Blogger'a anket yapar. Değişiklikler olduğunda örnek, yayın listesini günceller.

Verileri Güncellemek ve Silmek için E-Etiketleri Kullanma

Güncelleme/silme isteklerinde ETag'lerin kullanılması, birden fazla istemcinin birbirlerinin yaptığı değişikliklerin üzerine yanlışlıkla yazmasını önler. Bu durumda, If-Match üstbilgisine bir ETag eklenir:

If-Match: ETAG GOES HERE

İstekteki ETag, sunucudaki ETag ile eşleşiyorsa güncelleme/silme işlemi başarılı olur. Ancak bir ETag uyuşmazlığı, girişin değiştiğini ve güncelleme/silme işleminin başarısız olduğunu gösterir. Bu durumda uygulama, verilerin yeni bir örneğini istemeli ve ardından güncellemeyi/silmeyi tekrar denemelidir.

Belirli durumlarda, girişteki başka değişikliklerden bağımsız olarak değişikliklerinizi zorla uygulamak isteyebilirsiniz. Bu işlemi If-Match başlığına * ileterek:

If-Match: *

Bu işlemin, diğer müşterilerin yaptığı değişiklikleri geçersiz kılacağını unutmayın. Bu nedenle, bu alanı dikkatli bir şekilde kullanın.

Yalnızca güçlü ETag'lerine sahip bir girişi güncelleyebilir veya silebilirsiniz. Zayıf bir ETag'in belirtilmesi hataya neden olur. Bu duruma karşı koruma sağlamak için JavaScript istemcisi güncelleme ve silme isteklerinde zayıf ETag'ler ayarlamaz.

E-etiketler, koşullu almalarla aynı şekilde kullanılır:

function updateData(entry, service) {
  var etag = entry.getEtag();
  var opt_params = {};
  opt_params['etag'] = etag; // Or use '*' to force an update.
  service.updateEntry(successHandler, errorHandler, opt_params);
}

function successHandler(response) {
  // Successful update
}

function errorHandler(errorObj) {
  // ERROR - Update failed. Could be due to an ETag mismatch, but check the
  // error message to make sure. An ETag error will be in the format:
  // Mismatch: etags = ["Qnc-fTVSLyp7ImA9WxJbFEsDRAw."], version = [1249675665358000]
}

Bir ETag, güncelleme yapılırken iki yerde belirtilebilir:

  1. Girişin içinde getEtag() ve setEtag() yöntemlerini kullanma.
  2. Başlıkta, opt_params nesnesi kullanılarak (yukarıda gösterildiği gibi).

Önceki bir GET isteğinden yüklenen giriş için zaten bir ETag alanı ayarlanmış. Bu nedenle opt_params nesnesinde aynı ETag'in belirtilmesi gereksizdir. Hem giriş gövdesinde hem de opt_params içinde bir ETag belirtilmişse opt_params içindeki ETag öncelikli olur. Bu durum biraz kafa karıştırıcı olabileceğinden, koşullu güncellemelerle ilgili sorun yaşıyorsanız hem giriş hem de opt_params nesnesindeki ETag'i kontrol ettiğinizden emin olun.

İşinizi kolaylaştırmak için google.gdata.Entry sınıflarının kendi updateEntry() ve deleteEntry() yöntemleri de vardır. Giriş sınıfı zaten bir ETag'e sahipse bunu isteğe eklemeniz gerekmez; istemci kitaplığı bunu sizin için otomatik olarak yapar. Örneğin:

// entry was loaded from a previous request.  No need to specify
// an ETag in opt_params here, it is added automatically.
entry.deleteEntry(successHandler, errorHandler);

Bu sayede, doğru şekilde ayarlarsanız ETag'lerin sağladığı avantajlardan endişelenmeniz gerekmez. Ancak, '*' kullanarak güncellemeye zorlamak istiyorsanız her zaman 'etag' = '*' ile opt_params nesnesini eklemeniz gerekir.

Kişiler'deki Koşullu Güncellemeler bölümünde çalışan koşullu güncellemeleri görebilirsiniz. Örnek ilk olarak, bu örnek tarafından kullanılan tüm verilerin oluşturulacağı bir test Kişi Grubu oluşturur. Örneği kullanmayı bitirdiğinizde bu Kişi Grubu'nu silebilirsiniz. Örnek, daha sonra Kişi Grubu'ndaki içerikle iki iframe yüklenir. Bir iframe'de güncelleme yapabilir ve diğer iframe'deki güncellemeleri nasıl etkilediğini görebilirsiniz. Nasıl kullanılacağıyla ilgili daha fazla bilgi için örneği ziyaret edin.

Örnekler

  • Blogger'da Koşullu Alma - Blogger'ı her 5 saniyede bir anket yapar ve güncellemeleri kontrol eder.
  • Kişiler'de Koşullu Güncelleme - Kişi verilerini içeren iki ayrı iframe'i gösterir. Böylece, kişileri oluştururken/güncellerken veya silerken iki istemcinin nasıl etkileşimde bulunabileceğini yeniden oluşturabilirsiniz.

Referans

İstemci kitaplığı tarafından sağlanan sınıflar ve yöntemler hakkında referans bilgiler için JavaScript istemci kitaplığı API referansı (JSdoc biçiminde) bölümüne bakın.

Başa dön