Korzystanie z biblioteki klienta Java

W tym dokumencie opisujemy, jak za pomocą biblioteki klienta Java wysyłać zapytania do interfejsu Google Data API („GData”) i interpretować zwracane odpowiedzi.

Google udostępnia zestaw bibliotek klienta w różnych językach programowania, które umożliwiają interakcję z usługami mającymi interfejsy API danych. Za pomocą tych bibliotek możesz tworzyć żądania GData, wysyłać je do usługi i otrzymywać odpowiedzi.

W tym dokumencie znajdziesz ogólne informacje o korzystaniu z biblioteki klienta Java oraz przykłady typowych zastosowań.

Aby korzystać z tej biblioteki klienta, musisz mieć zainstalowaną Javę w wersji 1.5.

Pobierz bibliotekę klienta Java

Przykłady w tym przewodniku odnoszą się do interfejsu Google Calendar API, ale nie jest to dokładny ani aktualny przewodnik po korzystaniu z tego interfejsu. Informacje o korzystaniu z biblioteki klienta Java z interfejsem Data API konkretnej usługi znajdziesz w dokumentacji tej usługi. Jeśli na przykład pracujesz z Kalendarzem, przeczytaj przewodnik dla programistów korzystających z interfejsu Calendar Data API.

Spis treści

  1. Odbiorcy
  2. Omówienie modelu danych
  3. Samouczek i przykłady
    1. Kompilowanie i uruchamianie klienta
    2. Prośba o plik danych
    3. Wstawianie nowego elementu
    4. Prośba o określony wpis
    5. Wyszukiwanie wpisów
    6. Wyszukiwanie według kategorii
    7. Aktualizowanie elementu
    8. Usuwanie elementu
  4. Produkty

Odbiorcy

Ten dokument jest przeznaczony dla programistów Java, którzy chcą pisać aplikacje klienckie, które mogą wchodzić w interakcje z usługami GData.

W tym dokumencie zakładamy, że znasz ogólne założenia protokołu interfejsów API danych Google. Zakładamy też, że znasz język programowania Java.

Informacje referencyjne o klasach i metodach udostępnianych przez bibliotekę klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta Java (w formacie Javadoc).

Ten dokument należy czytać po kolei, ponieważ każdy przykład opiera się na poprzednich.

Omówienie modelu danych

Biblioteka klienta Java używa zestawu klas do reprezentowania elementów używanych przez interfejsy Google Data API. Na przykład klasa Feed odpowiada elementowi <atom:feed> i ma metody tworzenia wpisu, pobierania i ustawiania wartości różnych elementów podrzędnych itp. Jest też klasa Entry, która odpowiada elementowi <atom:entry>. Nie każdy element zdefiniowany w interfejsach Google Data API ma własną klasę. Szczegółowe informacje znajdziesz w dokumentacji referencyjnej.

Biblioteka może automatycznie analizować treść Atom i umieszczać wartości elementów Atom w odpowiednich obiektach. Na przykład metoda getFeed pobiera plik danych, analizuje go i zwraca obiekt Feed z wynikowymi wartościami.

Aby wysłać plik danych lub wpis do usługi, utwórz obiekt Feed lub Entry, a następnie wywołaj metodę biblioteki (np. metodę insert), aby automatycznie przetłumaczyć obiekt na XML i go wysłać.

Jeśli wolisz, możesz samodzielnie analizować lub generować pliki XML. Najłatwiej to zrobić za pomocą odpowiedniej biblioteki innej firmy, np. Rome.

Podobnie jak składnia XML interfejsu Google Data API jest rozszerzalna, tak samo jest rozszerzalny odpowiadający jej model obiektowy. Na przykład biblioteka klienta udostępnia klasy odpowiadające elementom zdefiniowanym w przestrzeni nazw Google Data.

Samouczek i przykłady

Poniższe przykłady pokazują, jak wysyłać różne żądania interfejsu Data API przy użyciu biblioteki klienta Java.

Aby były bardziej konkretne, te przykłady pokazują, jak korzystać z określonej usługi: Kalendarza Google. Wskażemy miejsca, w których Kalendarz różni się od innych usług Google, aby pomóc Ci dostosować te przykłady do innych usług. Więcej informacji o Kalendarzu znajdziesz w dokumentacji interfejsu Google Calendar Data API.

Tworzenie i uruchamianie klienta

Aby skompilować przykłady w tym dokumencie, musisz użyć tych instrukcji importowania:

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

Prośba o plik danych

Zgodnie z opisem w dokumencie Google Calendar Data API możesz poprosić o plik danych Kalendarza, wysyłając do Kalendarza to żądanie HTTP:

GET http://www.google.com/calendar/feeds/userID/private/full

Oczywiście musisz zastąpić userID adresem e-mail użytkownika. Szczegółowe informacje znajdziesz w dokumencie Kalendarza. Zamiast tego możesz użyć specjalnego domyślnego adresu URL do interakcji z Kalendarzem (zgodnie z opisem w dokumencie Kalendarza), ale w tym dokumencie będziemy używać prywatnego pełnego adresu URL kanału, który zawiera identyfikator użytkownika.

Musisz też zapewnić odpowiednie uwierzytelnianie. Główne różnice między tym przykładem a pierwszym przykładem w dokumencie Kalendarza polegają na tym, że (1) ten przykład obejmuje uwierzytelnianie, a (2) ten przykład korzysta z bardziej ogólnej klasy GoogleService zamiast klasy CalendarService, która jest specyficzna dla Kalendarza.

Pamiętaj, że system uwierzytelniania, którego tu używamy (znany jako „Uwierzytelnianie Google w przypadku zainstalowanych aplikacji”), jest odpowiedni tylko do użytku w zainstalowanych aplikacjach klienckich, takich jak aplikacje na komputery, a nie w aplikacjach internetowych. Więcej informacji o uwierzytelnianiu znajdziesz w dokumentacji Uwierzytelnianie konta Google.

Aby poprosić o plik danych Kalendarza za pomocą biblioteki klienta Java dla użytkownika o adresie e-mail „liz@gmail.com” i haśle „mypassword”, użyj tego kodu:

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

Klasa GoogleService reprezentuje połączenie klienta (z uwierzytelnianiem) z usługą GData. Ogólna procedura wysyłania zapytania do usługi za pomocą biblioteki klienta obejmuje te kroki:

  1. Uzyskaj lub utwórz odpowiedni adres URL.
  2. Jeśli wysyłasz dane do usługi (np. wstawiasz nowy wpis), przekształć surowe dane w obiekty za pomocą klas biblioteki klienta. (Ten krok nie ma zastosowania, jeśli tylko prosisz o plik danych, jak w tym przykładzie).
  3. Utwórz nową instancję GoogleService, ustawiając nazwę usługi (np. "cl" dla Kalendarza) i nazwę aplikacji (w formacie companyName-applicationName-versionID).
  4. Ustaw odpowiednie dane logowania.
  5. Wskaż bibliotece klienta, jakich rozszerzeń będzie używać plik danych, aby biblioteka mogła prawidłowo analizować zwracane pliki danych.
  6. Wywołaj metodę, aby wysłać żądanie i otrzymać wyniki.

Metoda setUserCredentials określa identyfikator i hasło użytkownika, w imieniu którego klient wysyła zapytanie. Przykłady w tym dokumencie korzystają z systemu uwierzytelniania „Uwierzytelnianie w przypadku aplikacji zainstalowanych”. Więcej informacji o systemach uwierzytelniania znajdziesz w dokumentacji Uwierzytelnianie konta Google.

Po ustawieniu danych logowania wskaż rozszerzenia, których będzie używać plik danych, wywołując metodę declareExtensions. W tym przypadku informujemy, że plik danych to plik danych o wydarzeniach, a więc będzie on używać rozszerzeń zdefiniowanych przez rodzaj wydarzenia.

Aby poprosić o cały plik danych, wywołaj metodę getFeed, która przyjmuje adres URL i zwraca cały plik danych znaleziony pod tym adresem. W dalszej części tego dokumentu pokażemy, jak wysyłać bardziej szczegółowe zapytania.

Podobnie jak inne metody klasy GoogleService, metoda getFeed obsługuje uwierzytelnianie i przekierowania w razie potrzeby.

Wstawianie nowego elementu

Aby utworzyć nowe wydarzenie w kalendarzu, możesz użyć tego kodu:

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

Po ustawieniu adresu URL tworzymy obiekt EventEntry. EventEntry pochodzi z abstrakcyjnej klasy bazowej BaseEntry, która jest też klasą nadrzędną dla klasy Entry reprezentującej element <atom:entry>.

Klasa EventEntry reprezentuje rodzaj zdarzenia. Więcej informacji znajdziesz w dokumencie Rodzaje. W przypadku usług innych niż Kalendarz zwrócony wpis możesz przypisać do obiektu Entry zamiast do obiektu EventEntry.

Tytuł wpisu to TextConstruct, czyli klasa zawierająca tekst w różnych formach (zwykły tekst, HTML lub XHTML). Treść wpisu jest reprezentowana przez obiekt Content, czyli klasę, która może zawierać zwykły tekst lub inne formy treści, w tym dane XML i binarne. (Ale metoda setContent może też akceptować TextConstruct).

Każdy autor jest reprezentowany przez nazwę, identyfikator URI i adres e-mail. (W tym przykładzie pomijamy identyfikator URI). Aby dodać autora do wpisu, wywołaj metodę getAuthors().add wpisu.

Używamy tego samego obiektu GoogleService, który został utworzony w poprzednim przykładzie. W tym przypadku wywoływana metoda to insert, która wysyła element do określonego adresu URL wstawienia.

Usługa zwraca nowo utworzony wpis, który może zawierać dodatkowe elementy wygenerowane przez serwer, takie jak adres URL do edycji wpisu.

Kody stanu HTTP są zwracane jako wyjątki.

Powyższy kod jest odpowiednikiem wysłania POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (z odpowiednim uwierzytelnianiem) i podania wpisu w formie typu zdarzenia.

Prośba o konkretny wpis

Poniższy kod umożliwia przesłanie żądania konkretnego wpisu, który został wstawiony w poprzednim przykładzie.

W kontekście tej serii przykładów pobieranie wpisu nie jest konieczne, ponieważ Kalendarz już zwrócił wstawiony wpis. Jednak tę samą technikę można zastosować, gdy znasz identyfikator URI wpisu.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

Wstawiony wpis ma metodę getSelfLink, która zwraca obiekt Link zawierający adres URL wpisu. Klasa Link ma metodę getHref, która zwraca adres URL jako String, z którego możemy utworzyć obiekt URL.

Następnie wystarczy wywołać metodę getEntry usługi, aby uzyskać wpis.

Zwróć uwagę, że przekazujemy EventEntry.class jako parametr do getEntry, co oznacza, że oczekujemy, że usługa zwróci zdarzenie, a nie tylko zwykły wpis. W przypadku usług innych niż Kalendarz możesz po prostu przekazać wartość Entry.class.

Powyższy kod jest odpowiednikiem wysłania do Kalendarza wartości GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID z odpowiednim uwierzytelnieniem.

Wyszukiwanie wpisów

Aby pobrać pierwsze dopasowanie z wyszukiwania pełnotekstowego, użyj tego kodu:

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

W tym przykładzie zaczynamy od utworzenia obiektu Query, który składa się głównie z adresu URL i powiązanych z nim parametrów zapytania. Każdy ze standardowych parametrów zapytania GData ma metodę ustawiającą. Możesz też ustawić niestandardowe parametry zapytania dla konkretnej usługi za pomocą metody addCustomParameter.

Po utworzeniu obiektu Query przekazujemy go do metody query usługi, która zwraca plik danych zawierający wyniki zapytania. Innym rozwiązaniem jest samodzielne utworzenie adresu URL (przez dodanie parametrów zapytania do adresu URL pliku danych) i wywołanie metody getFeed, ale metoda query zapewnia przydatną warstwę abstrakcji, dzięki czemu nie musisz samodzielnie tworzyć adresu URL.

Metoda getEntries pliku danych zwraca listę wpisów w pliku danych, a metoda getEntries().size zwraca liczbę wpisów w pliku danych.

W takim przypadku, jeśli zapytanie zwróciło jakiekolwiek wyniki, przypisujemy pierwszy pasujący wynik do obiektu Entry. Następnie używamy metody getTitle().getPlainText klasy Entry, aby pobrać tytuł wpisu i przekonwertować go na tekst.

Powyższy kod jest odpowiednikiem wysłania do Kalendarza wartości GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis.

Wyszukiwanie według kategorii

Uwaga: Kalendarz Google nie przypisuje etykiet do wydarzeń, więc ten przykład nie działa w Kalendarzu.

Aby pobrać plik danych zawierający wszystkie wpisy pasujące do wcześniejszego wyszukiwania pełnotekstowego i należące do określonej kategorii lub mające określoną etykietę, użyj tego kodu:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

Klasa Category reprezentuje oczywiście kategorię, która będzie używana w filtrze kategorii. Klasa Query.CategoryFilter może zawierać wiele kategorii, ale w tym przypadku tworzymy filtr z tylko jedną kategorią.

Następnie dodajemy ten filtr do istniejącego zapytania, które nadal zawiera ciąg zapytania pełnotekstowego z poprzedniego przykładu.

Ponownie używamy metody query, aby wysłać zapytanie do usługi.

Gdyby Kalendarz umożliwiał wyszukiwanie kategorii, powyższy kod byłby równoznaczny z wysłaniem do niego znaku GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis.

Aktualizowanie elementu

Aby zaktualizować istniejący element, użyj tego kodu. W tym przykładzie zmieniamy tytuł wcześniej pobranego wpisu z „Tenis z Darcy” na „Ważne spotkanie”.

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

Najpierw ustawiamy nowy tytuł dla pobranego wcześniej wpisu. Następnie pobieramy adres URL edycji wpisu za pomocą metody getEditLink. Następnie wywołujemy metodę update usługi, aby wysłać zaktualizowany wpis.

Usługa zwraca zaktualizowany wpis, w tym nowy URL nowej wersji tego wpisu. (Więcej informacji o wersjach wpisów znajdziesz w sekcji Optymistyczne współbieżność w dokumencie referencyjnym protokołu).

Powyższy kod jest w przybliżeniu równoważny wysłaniu do usługi kodu PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID wraz z nowym wpisem (w formacie Atom), który zastąpi oryginalny wpis.

Usuwanie elementu

Aby usunąć zaktualizowany wpis, użyj tego kodu:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

Adres URL do usunięcia jest taki sam jak adres URL do edycji, więc ten przykład jest bardzo podobny do poprzedniego, z tym wyjątkiem, że wywołujemy metodę delete zamiast update.

Powyższy kod jest w przybliżeniu odpowiednikiem wysłania do usługi znaku DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID.

Dokumentacja

Informacje referencyjne o klasach i metodach udostępnianych przez bibliotekę klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta Java (w formacie Javadoc).

Powrót do góry