Korzystanie z biblioteki klienta JavaScript (wersja 2.0)

Ostrzeżenie: ta strona dotyczy starszych interfejsów API Google – interfejsów API danych Google – dotyczy tylko interfejsów API wymienionych w katalogu interfejsów API danych Google, z których wiele zostało zastąpionych nowszych. Informacje na temat konkretnego nowego interfejsu API można znaleźć w dokumentacji nowego interfejsu API. Informacje o autoryzowaniu żądań za pomocą nowszego interfejsu API znajdziesz w artykule Uwierzytelnianie i autoryzacja kont Google.

Ten dokument opisuje, jak używać biblioteki klienta JavaScript do wysyłania zapytań do interfejsu Google Data API i interpretowania zwróconych odpowiedzi.

Google udostępnia zestaw bibliotek klientów w różnych językach programowania przeznaczonych do interakcji z usługami korzystającymi z interfejsów API danych. Korzystając z tych bibliotek, możesz tworzyć żądania do interfejsu API, wysyłać je do usługi i otrzymywać odpowiedzi.

Ten dokument zawiera ogólne informacje na temat korzystania z biblioteki klienta JavaScript oraz przykłady jego typowych zastosowań.

Odbiorcy

Ten dokument jest przeznaczony dla programistów JavaScriptu, którzy chcą tworzyć aplikacje klienckie, które mogą współpracować z usługami dotyczącymi danych Google.

W tym dokumencie założono, że rozumiesz ogólne pojęcia związane z protokołem interfejsów API danych Google. Zakładamy też, że umiesz się programować w języku JavaScript.

Więcej informacji o klasach i metodach dostępnych w bibliotece klienta znajdziesz w przewodniku po interfejsie API biblioteki klienta JavaScript (w formacie JSdoc).

Ten dokument został zaprojektowany w taki sposób, aby można go było łatwo czytać. Każdy z przykładów bazuje na poprzednich przykładach.

Warunki korzystania z usługi

Korzystając z biblioteki klienta JavaScript, akceptujesz Warunki korzystania z biblioteki klienta Google JavaScript.

Omówienie modelu danych i procesu sterowania

Biblioteka klienta JavaScript używa zestawu klas do reprezentowania elementów używanych przez interfejsy API danych Google.

Uwaga: podstawowa reprezentacja danych to JSON, ale biblioteka klienta zawiera warstwę abstrakcji, która nie wymaga bezpośredniego działania z danymi JSON. Jeśli chcesz pracować bezpośrednio z plikiem JSON bez biblioteki klienta, zapoznaj się z artykułem Używanie JSON z interfejsami API danych Google.

Biblioteka udostępnia metody, które umożliwiają asynchroniczne wysyłanie danych do usługi korzystającej z interfejsu API danych oraz odbieranie ich z tej usługi. Na przykład metoda google.gdata.calendar.CalendarService.getEventsFeed() wysyła żądanie kanału do Kalendarza Google. Jeden z przekazywanych parametrów to funkcja kontynuacji, zwana także wywołaniem zwrotnym. Usługa zwraca plik w formacie JSON przez wywołanie funkcji kontynuacji. Klient może następnie wywołać różne metody get, aby użyć danych w postaci obiektów JavaScript.

Aby dodać nowy wpis, utwórz go za pomocą klas i metod z biblioteki klienta, a następnie wywołaj metodę feed.insertEntry(), aby wysłać nowy wpis do usługi. Ponownie otrzymasz funkcję kontynuacji, która jest wywoływana przez usługę po dodaniu wpisu.

Jeśli nie masz doświadczenia w korzystaniu z JavaScriptu, procedura sterowania może być nieco skomplikowana. W większości przypadków po wywołaniu metody takiej jak getEventsFeed() lub insertEntry() Wykonanie usługi jest kontynuowane, gdy usługa zwraca żądane dane. Dlatego wszystko, co klient zrobi w zwróconych danych, należy wykonać w funkcji kontynuacji lub wywołać z tej funkcji. Aby używać tych zmiennych w różnych funkcjach, może być konieczne ich utworzenie na całym świecie.

Więcej informacji o tym programie znajdziesz w sekcji „Styl przekazywania dalej” w Wikipedii.

Informacje o obsługiwanych środowiskach

Obecnie obsługujemy tylko aplikacje klienckie JavaScript, które działają w przeglądarce na stronie internetowej. Obecnie obsługiwane przeglądarki:

  • Firefox 2.x i 3.x
  • Internet Explorer 6, 7 i 8
  • Safari 3.x i 4.x
  • Google Chrome (wszystkie wersje)

Biblioteka klienta JavaScript obsługuje całą komunikację z serwerem usługi. Jeśli jesteś doświadczonym deweloperem JS, możesz się zastanawiać: „A co z tymi samymi zasadami dotyczącymi źródła?”. Biblioteka klienta JavaScript umożliwia klientowi wysyłanie żądań danych Google z dowolnej domeny przy zachowaniu zgodności z modelem zabezpieczeń przeglądarki.

Omówienie uwierzytelniania za pomocą interfejsów Google Data API znajdziesz w artykule Omówienie uwierzytelniania przy użyciu interfejsów API danych Google. W pozostałej części tego artykułu założono, że znasz już podstawowe zasady działania tego systemu.

Przykładowe aplikacje klienckie

Aby zapoznać się z działaniem biblioteki JavaScript, odwiedź naszą stronę z przykładami.

Samouczek i przykłady

Poniższe przykłady pokazują, jak wysyłać różne żądania do interfejsu API danych za pomocą biblioteki klienta JavaScript.

Aby zobaczyć bardziej szczegółowe informacje, poniżej znajdziesz przykłady interakcji z konkretną usługą: Kalendarz Google. Wskażemy miejsca, w których Kalendarz różni się od innych usług Google. Ułatwi to dostosowanie tych przykładów do innych usług. Więcej informacji o Kalendarzu znajdziesz w dokumencie Google Calendar Data API.

Wczytuję bibliotekę

Aby klient mógł korzystać z biblioteki klienta, musi przesłać kod biblioteki biblioteki z serwera.

Zacznij od użycia tagu <script> w sekcji <head> dokumentu HTML, aby pobrać komponent Google AJAX API:

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

Minimalizując przesyłanie danych do serwerów Google i zmniejszając opóźnienie, wstępnie wczytuj bibliotekę. Aby wstępnie wczytać określone pakiety bezpośrednio z modułu wczytującego interfejs API Google AJAX (bez google.load() poniżej), użyj tego:

<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>

Uwaga: URL src skryptu powinien być w pełni zakodowany. Poprzedni przykład to
<script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script>.

Jeśli nie wczytujesz modułów automatycznie, możesz wczytać bibliotekę klienta Google Data, korzystając ze następnego przykładu w kodzie konfiguracji JavaScriptu po pobraniu typowego popularnych programów. Wywołanie należy wykonać w sekcji <head> dokumentu HTML (lub w pliku JavaScript dołączonym za pomocą tagu <script> w sekcji <head> dokumentu HTML):

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

Zamiast z całej biblioteki możesz też wybrać konkretne usługi. Ten przykład pobiera tylko pakiety dla Bloggera i Kontaktów:

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

Drugim parametrem jest google.load() – numer wersji biblioteki klienta JavaScript.System numeracji wersji jest oparty na modelu używanym przez interfejs API Map Google. Oto możliwe numery wersji i ich znaczenie:

"1"
Druga do ostatniej wersji głównej wersji 1.
"1.x"
Najnowsza wersja głównej wersji 1.
"1.s"
Najnowsza stabilna wersja głównej wersji 1. Od czasu do czasu zadeklarujemy, że określona wersja biblioteki klienta jest stabilna, na podstawie opinii deweloperów. Może ona jednak nie zawierać najnowszych funkcji.
"1.0", "1.1 itp.
Konkretna wersja biblioteki z określonym głównym i mniejszym numerem wersji.

Po wywołaniu elementu google.load() musisz ustawić, aby moduł ładowania czekał na zakończenie wczytywania strony, a następnie wywołać kod:

google.setOnLoadCallback(getMyFeed);

Gdzie getMyFeed() to funkcja zdefiniowana w następnej sekcji tego dokumentu. Użyj tej metody, zamiast używać modułu obsługi onload do elementu <body>.

Żądanie nieuwierzytelnionego kanału

Aby poprosić o nieuwierzytelniony kanał, dodaj poniższy kod do pliku JavaScript lub do tagu <script> w pliku HTML.

W poniższym kodzie wywołania getMyFeed() są najpierw wywoływane (przez moduł wczytujący interfejs API AJAX zgodnie z opisem w poprzedniej sekcji).

Wywołuje funkcję setupMyService(), aby utworzyć połączenie (reprezentowane przez obiekt CalendarService) z Kalendarzem Google. Wyodrębniliśmy kod tworzenia usługi do oddzielnej funkcji modułowej. Później zmodyfikujemy funkcję setupMyService() w zależności od wybranych opcji uwierzytelniania.

Po skonfigurowaniu usługi getMyFeed() wywołuje metodę getEventsFeed() biblioteki klienta, aby zażądać pliku danych.

Adres URL kanału określamy w zmiennej globalnej, aby można go było używać w późniejszych funkcjach. W tym przykładzie używamy adresu URL publicznego (nieuwierzytelnionego) pliku danych użytkownika o nazwie [email protected]. Możesz też użyć default zamiast adresu e-mail użytkownika, aby wskazać uwierzytelnionego użytkownika.

var feedUrl = "http://www.google.com/calendar/feeds/[email protected]/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);
}

Udostępniamy zmienną myService jako zmienną globalną, aby ułatwić korzystanie z niej później.

Aby użyć powyższego kodu we własnym kliencie, musisz użyć adresu e-mail prawdziwego użytkownika konta Kalendarza z publicznie udostępnionym kalendarzem.

Uwaga: gdy utworzysz nowy obiekt CalendarService, biblioteka klienta wywołuje metodę o nazwie google.gdata.client.init(), która sprawdza, czy przeglądarka, w której działa klient, jest obsługiwana. Jeśli wystąpi błąd, wyświetli się komunikat o błędzie w bibliotece klienta. Jeśli chcesz samodzielnie rozwiązać ten problem, możesz jednoznacznie wywołać funkcję google.gdata.client.init(handleInitError) przed utworzeniem usługi, gdzie handleInitError() jest Twoją funkcją. Jeśli wystąpi błąd inicjacji, funkcja otrzyma standardowy obiekt błędu. Dzięki nim możesz zrobić z nim dokładnie to, co chcesz.

W wywołaniu funkcji getEventsFeed() drugi argument to handleMyFeed – funkcja wywołania zwrotnego – patrz niżej. Kalendarz Google przetwarza żądanie, a jeśli się uda, przekazuje do wywołania zwrotnego obiekt „feed root” kanału, który jest żądany. Element główny kanału to obiekt kontenera zawierający plik danych.

Trzeci argument funkcji getEventsFeed() jest opcjonalną funkcją obsługi błędów. Jeśli biblioteka klienta napotka błąd, zamiast określonej funkcji wywołania zwrotnego wywołuje określony moduł obsługi błędów. Obiekt przekazywany przez bibliotekę klienta jako argument do modułu obsługi błędów jest instancją obiektu JavaScript Error z dodatkową właściwością cause.

Oto proste wersje funkcji wywołania zwrotnego i modułu obsługi błędów: 

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);
}

My zajmujemy się błędami, po prostu wyświetlając je użytkownikowi. Moduł obsługi błędów klienta powinien prawdopodobnie być bardziej złożony. W niektórych sytuacjach może nie być określona żadna przyczyna. W takich przypadkach przykładowy moduł obsługi błędów wraca do wyświetlania standardowej właściwości message.

Pamiętaj, że ten kod nie uwierzytelnia, więc możesz go użyć tylko do uzyskania publicznego kanału.

Uwierzytelniam

Biblioteki klienta JavaScript można używać w dwóch trybach. Jeśli tworzysz gadżet, do uwierzytelniania używana jest funkcja Serwer proxy OAuth. W przypadku uzyskiwania do niej dostępu z samodzielnej aplikacji JavaScript używa systemu uwierzytelniania AuthSub. Więcej informacji o uwierzytelnianiu znajdziesz w artykule Omówienie uwierzytelniania przy użyciu interfejsów API danych Google. W dalszej części tej sekcji przyjęto założenie, że znasz już podstawowe zasady działania tego systemu.

Zanim użyjesz uwierzytelniania z przykładowym kodem podanym w tym dokumencie, zmień URL kanału z publicznego na prywatny:

var feedUrl = "http://www.google.com/calendar/feeds/[email protected]/private/full";

Uwierzytelnianie w kliencie internetowym za pomocą AuthSub

System autoryzacji Google „AuthSub for JavaScript” nie jest już dostępny.

Zamiast tego zalecamy używanie OAuth 2.0 w przypadku aplikacji po stronie klienta.

Uwierzytelnianie w gadżecie za pomocą serwera proxy OAuth

Oto krótkie omówienie tego, co się dzieje podczas uwierzytelniania gadżetu:

  1. Gadżet wczytuje się po raz pierwszy i próbuje uzyskać dostęp do danych użytkownika za pomocą jednego z interfejsów API danych Google.
  2. Żądanie nie zostało zrealizowane, ponieważ użytkownik nie przyznał jeszcze dostępu do jego danych. Obiekt odpowiedzi zawiera adres URL (w polu response.oauthApprovalUrl) strony zatwierdzania OAuth. Gadżet powinien udostępniać metodę uruchamiania nowego okna z tym adresem URL.
  3. Na stronie zatwierdzania użytkownik decyduje się przyznać/odmówić dostępu do Twojego gadżetu. Jeśli operacja się powiedzie, użytkownik otworzy stronę oauth_callback, którą wskażesz. Aby zapewnić użytkownikom jak najlepsze wrażenia, skorzystaj z http://oauth.gmodules.com/gadgets/oauthcallback.
  4. Następnie użytkownik zamyka wyskakujące okienko. Aby ułatwić użytkownikom powiadamianie gadżetu, że użytkownik wyraził zgodę, udostępniliśmy wyskakujący moduł obsługi, którego możesz użyć do wykrywania okna zamykania. Możesz też wyświetlić link (np. „Uprawnienia zatwierdzone), które użytkownik może kliknąć ręcznie po zamknięciu tego okna.
  5. Gadżet ponownie próbuje uzyskać dostęp do interfejsu Google Data API, wysyłając żądanie danych użytkownika. Ta próba się powiodła.
  6. Twój gadżet został uwierzytelniony i może normalnie działać.

W gadżecie dodaj element <OAuth> w sekcji <ModulePrefs>:

<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>

W tej sekcji zmień następujące parametry zapytania:

  • scope

    Wymagany parametr w adresie URL żądania. Gadżet będzie mógł uzyskać dostęp tylko do danych z zakresu scope używanych w tym parametrze. W tym przykładzie gadżet będzie miał dostęp do danych z Bloggera i Kalendarza. Gadżet może zażądać danych dla pojedynczego zakresu lub wielu zakresów (jak w tym przykładzie).

  • oauth_callback

    Opcjonalny parametr w adresie URL autoryzacji. Strona zgody OAuth zostanie przekierowana na ten adres URL, gdy użytkownik zatwierdzi dostęp do jego danych. Możesz pominąć ten parametr, ustawić go na własną „zatwierdzoną stronę” albo użyć http://oauth.gmodules.com/gadgets/oauthcallback. Następnym razem zapewni Ci największą wygodę, gdy użytkownik zainstaluje gadżet. Ta strona zawiera fragment kodu JavaScript, który automatycznie zamyka wyskakujące okienko.

Następnie wczytaj bibliotekę klienta JavaScript w sekcji <Content> gadżetu. Zmodyfikuj funkcję setupMyService() z poprzednich przykładów, aby wywołać metodę useOAuth() obiektu usługi. W ten sposób gadżet będzie uwierzytelniał się przy użyciu serwera proxy OAuth, a nie AuthSub. Zacznij od tego szablonu:

<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>

Zwróć uwagę, że połączenie z numerem google.accounts.user.login(scope) zostało usunięte. Proxy wykonuje uwierzytelnianie za Ciebie.

Więcej informacji na temat tworzenia gadżetów interfejsu Google Data API, w tym zawartość elementów fetchData(), znajdziesz w artykule Tworzenie gadżetu danych Google lub w pełnej dokumentacji Pisanie gadżetów OAuth.

Wstawianie nowego elementu

Aby utworzyć nowe wydarzenie w kalendarzu, wykonaj wykonanie poprzedniego kroku przez zmodyfikowanie końca funkcji handleMyFeed() w taki sposób, aby wywoływała nową funkcję:

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

W nowej funkcji najpierw utwórz konstruktor CalendarEventEntry, korzystając z konstruktora. Następnie wstaw wpis, aby umożliwić usłudze wywołanie zwrotne po zakończeniu wstawiania.

function insertIntoMyFeed(feedRoot) {
  var newEntry = new google.gdata.calendar.CalendarEventEntry({
      authors: [{
        name: "Elizabeth Bennet",
        email: "[email protected]"
      }],
      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);
}

Pamiętaj, że nazwa właściwości obiektu użytej w konstruktorze pasuje do nazwy metody ustawiania używanej w tej właściwości. (np. zamiast dopasowania do odpowiedniej nazwy pola JSON).

Pamiętaj, że w przypadku znaczników startTime i endTime nie możesz podawać tylko ciągów daty i godziny w standardzie ISO 8601. Musisz je najpierw wygenerować za pomocą metody fromIso8601().

Usługa zwraca kopię wstawionego wpisu jako obiekt entryRoot i przekazuje go do wywołania zwrotnego:

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

Prośba o określony wpis

Aby wysłać żądanie określonego wpisu, najpierw zmodyfikuj funkcję handleMyInsertedEntry() w taki sposób, aby wywoływała nową funkcję żądania:

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());
}

Ten kod pozwala zażądać konkretnej pozycji wstawionej w poprzednim przykładzie.

W kontekście serii przykładów pobranie tego wpisu nie jest konieczne, ponieważ Kalendarz zwrócił już wstawiony wpis. Tę samą metodę można jednak zastosować, gdy znasz identyfikator URI wpisu.

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());
}

Zasadniczo ten przykład jest taki sam jak w przykładzie getEventsFeed(), z tym że wywołujemy metodę getEventEntry() usługi, aby uzyskać określony wpis, a identyfikator URI jest nieco inny – w odniesieniu do głównego kalendarza użytkownika uwierzytelnionego używa on wartości domyślnej, która na końcu ma identyfikator wpisu.

Poza tym musimy mieć możliwość wykorzystania pobranego wpisu później, dlatego kopiujemy go do zmiennej globalnej.

Wyszukiwanie wpisów

Aby przeprowadzić wyszukiwanie pełnotekstowe, najpierw zmień funkcję handleMySpecificEntry() w taki sposób, by wywoływała nową funkcję wyszukiwania:

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

Następnie, aby pobrać pierwsze dopasowanie z wyników wyszukiwania, użyj tego kodu:

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.");
  }
}

Aktualizowanie elementu

Aby zaktualizować istniejący element, najpierw dodaj wiersz na końcu handleMyQueryResults(), aby wywołać nową funkcję aktualizacji:

  updateMyEntry();

Następnie użyj tego kodu. W tym przykładzie zmieniamy tytuł pobranego wcześniej elementu (który w poprzednim przykładzie znajdował się w globalnym obiekcie myEntryRoot) z dotychczasowego tekstu („Tenis z Darcy”) na „Ważne spotkanie”.

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());
}

Tak jak w przypadku wszystkich metod Kalendarza, metoda updateEntry() automatycznie określa poprawny identyfikator URI do edycji, który służy do aktualizowania wpisu, więc nie musisz go podawać.

Usuwanie elementu

Aby usunąć zaktualizowany wpis, najpierw dodaj wiersz w wierszu handleMyUpdatedEntry():

 deleteMyEntry(updatedEntryRoot);

Następnie użyj tego kodu:

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

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

Metoda deleteEntry() automatycznie określa prawidłowy identyfikator URI edycji używany do usunięcia wpisu.

Pamiętaj, że wpisy nie są zwracane. Jeśli wywołanie zwrotne jest skuteczne, to wiemy, że udało się usunąć połączenie. Jeśli nie uda się go usunąć, deleteEntry() wywoła metodę handleError(), a nie handleMyDeletedEntry().

Korzystanie z tagów ETag

Uwaga: tagów ETag można używać tylko z usługami korzystającymi z Google Data Protocol 2.0.

Wprowadzenie

Wersja 2 klienta JavaScript danych Google wprowadza obsługę tagów ETag. Tagi eTagów określają konkretną wersję konkretnego wpisu. Jest to istotne w dwóch przypadkach:

  • „Pobieranie warunkowe”, w którym klient żąda wpisu, a serwer wysyła wpis tylko wtedy, gdy wpis zmienił się od czasu, gdy klient ostatnio go o to poprosił.
  • Zadbaj o to, aby wielu klientów nie przypadkiem nie zastępowało swoich zmian. Interfejsy API danych wykonują tę czynność przez aktualizowanie i usuwanie, jeśli klient określi w nim stary tag ETag.

Istnieją 2 rodzaje ETagów: słabe i silne. Słaby tag ETag zawsze zaczyna się od W/, na przykład: W/"D08FQn8-eil7ImA9WxZbFEw". Słabe tagi ETag nie zmieniają się wraz ze zmianą wpisu, więc HTTP pozwala na ich wykorzystanie tylko do pobierania warunkowego. Silne znaczniki eTagów określają konkretną wersję konkretnego wpisu i mogą być używane zarówno do pobierania warunkowego, jak i do aktualizowania lub usuwania w celu uniknięcia zastępowania zmian innych klientów. Z tego powodu biblioteka klienta nie pozwala na wysyłanie słabych tagów ETag z żądaniem aktualizacji lub usunięcia.

Tagi eTag można znaleźć w odpowiedzi serwera na 2 miejsca:

  • W nagłówku HTTP ETag.
  • W pliku danych lub wpisie jako atrybut gd:etag.

Jeśli usługa obsługuje wersję 2, każdy plik danych i obiekt wpisu mają metodę getEtag() umożliwiającą pobranie wartości ETag.

Klient JavaScript obsługuje 2 metody umieszczania tagów ETag w żądaniu. Pierwszy to nowy obiekt opt_params. Wszystkie funkcje get/update/insert w wersji 2 biblioteki klienta mają nowy parametr opt_params. Ten obiekt służy do określania parametrów opcjonalnych podczas wysyłania żądania. Obecnie jedynym obsługiwanym parametrem parametrem jest 'etag', ale w przyszłości możemy dodać inne. Na przykład do żądania GET możesz dodać tag ETag:

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

Tag ETag możesz też dodać bezpośrednio do obiektu kanału lub wpisu, wywołując metodę setEtag() w kanale lub wpisie.

Więcej informacji o tagach ETag znajdziesz w dokumentacji protokołu GData.

Używanie tagów ETag do pobierania danych

Tagi ETag mogą pomóc zmniejszyć obciążenie sieci i czas wykonywania podczas pobierania danych. W żądaniu GET do tagu If-None-Match header: może być zawarty tag ETag.

If-None-Match: ETAG GOES HERE

Jeśli tag ETag pasuje do bieżącej wersji kanału lub wpisu, serwer wysyła odpowiedź 304 NOT MODIFIED i puste treści. W przeciwnym razie serwer przesyła odpowiedź 200 OK i dane kanału lub wpisu.

W przypadku klienta JavaScript możesz używać tagów ETag, dodając w żądaniu parametr 'etag':

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

Pobieranie warunkowe działa zarówno w przypadku silnych, jak i słabych tagów ETag. Jeśli tag ETag jest zgodny, moduł obsługi błędów będzie wywoływany z odpowiedzią 304:

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
}

Zapoznaj się z przykładem Pobieranie warunkowe przy użyciu Bloggera, aby poznać praktyczny przykład korzystania z tagów ETag w kliencie JavaScript. W tym przykładzie ankieta jest wysyłana do Bloggera w 5-sekundowych odstępach czasu w poszukiwaniu danych dotyczących Twojego bloga. W przypadku wprowadzenia zmian lista przykładów aktualizuje listę postów.

Korzystanie z tagów ETag do aktualizowania i usuwania danych

Używanie tagów ETag w żądaniach aktualizacji/usuwania zapewnia, że wielu klientów nie przypadkiem nie zastępuje sobie wzajemnie zmian. W tym przypadku w nagłówku If-Match znajduje się tag ETag:

If-Match: ETAG GOES HERE

Jeśli tag ETag w żądaniu pasuje do tagu ETag na serwerze, aktualizacja zostanie usunięta. Niezgodność tagu ETag oznacza jednak, że wpisy zostały zmienione, a aktualizacja/usunięcie nie powiodło się. W takim przypadku aplikacja powinna zażądać nowej instancji danych, a potem ponownie przeprowadzić aktualizację/usunięcie danych.

W niektórych przypadkach możesz chcieć wymusić zmiany niezależnie od innych zmian we wpisie. Możesz to zrobić, przekazując * do nagłówka If-Match:

If-Match: *

Pamiętaj, że spowoduje to zastąpienie zmian wprowadzonych przez innych klientów.

Można aktualizować/usuwać wpisy tylko za pomocą silnego tagu ETag. Określenie słabego ETag spowoduje błąd. Aby zabezpieczyć się przed tą sprawą, klient JavaScript nie ustawia słabych tagów ETag podczas aktualizacji i usuwania.

Znaczniki ETag są używane w taki sam sposób jak pobieranie warunkowe:

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]
}

Podczas aktualizowania tagu ETag można określić w 2 miejscach:

  1. W wpisie za pomocą metod getEtag() i setEtag().
  2. w nagłówku, używając obiektu opt_params (jak pokazano powyżej),

Wpis pochodzący z poprzedniego żądania GET ma już ustawione pole ETag. Określenie tego samego tagu ETag w obiekcie opt_params jest zbędne. Jeśli ETag został określony zarówno w treści wpisu, jak i w opt_params, pierwszeństwo ma ETag w opt_params. Może to być trochę mylące, dlatego jeśli masz problemy z aktualizacjami warunkowymi, sprawdź ETag zarówno w obiekcie, jak i obiekcie opt_params.

Aby ułatwić zrozumienie, klasy google.gdata.Entry mają też własne metody updateEntry() i deleteEntry(). Jeśli klasa wpisów ma już tag ETag, nie musisz dodawać go do żądania. Biblioteka klienta wykona to automatycznie. Na przykład:

// 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);

Dzięki temu możesz korzystać z tagów ETag bez obaw o prawidłowe skonfigurowanie tagów. Jeśli chcesz wymuszać aktualizację za pomocą metody '*', musisz zawsze uwzględniać obiekt opt_params w polu 'etag' = '*'.

Aktualne informacje o warunkach pracy znajdziesz w sekcji Aktualizacje warunkowe w Kontaktach. W tym przykładzie najpierw zostanie utworzona testowa grupa kontaktów, w której zostaną utworzone wszystkie dane używane przez tę próbkę. Możesz usunąć tę grupę kontaktów, gdy skończysz korzystać z próbki. W tym drugim przykładzie ładowane są dwa elementy iframe z treścią z grupy kontaktów. Możesz wprowadzać zmiany w jednym elemencie iframe i sprawdzać, jak wpłynie to na inne elementy. Aby dowiedzieć się, jak z niej korzystać, zapoznaj się z przykładem.

Sample

  • Pobieranie warunkowe w Bloggerze – co najmniej 5 sekund wysyła ankietę do Bloggera i sprawdza dostępność aktualizacji.
  • Aktualizacja warunkowa w kontaktach – pokazuje dwa osobne elementy iframe z danymi kontaktów, dzięki czemu możesz odtworzyć interakcje dwóch klientów przy tworzeniu, aktualizowaniu i usuwaniu kontaktów.

Materiały referencyjne

Więcej informacji o klasach i metodach dostępnych w bibliotece klienta znajdziesz w przewodniku po interfejsie API biblioteki klienta JavaScript (w formacie JSdoc).

Powrót do góry