Ten dokument opisuje sposób użycia biblioteki klienta w języku Java do wysyłania zapytań interfejsu Google Data API („GData”) 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. Za pomocą tych bibliotek możesz tworzyć żądania GData, wysyłać je do usługi i otrzymywać odpowiedzi.
Ten dokument zawiera ogólne informacje na temat korzystania z biblioteki klienta w języku Java wraz z zestawem typowych przykładów użycia.
Aby korzystać z tej biblioteki klienta, musisz korzystać z Javy 1.5.
Pobierz bibliotekę klienta w języku Java
Przykłady w tym przewodniku odnoszą się do interfejsu Google Calendar API, ale nie jest on dokładny ani aktualny. Informacje o używaniu biblioteki klienta w języku Java z interfejsem API danych konkretnej usługi znajdziesz w dokumentacji tej usługi. Jeśli na przykład korzystasz z Kalendarza, przeczytaj Przewodnik dla programistów korzystających z interfejsu Calendar Data API.
Spis treści
Odbiorcy
Ten dokument jest przeznaczony dla programistów Java, którzy chcą tworzyć aplikacje klienckie, które mogą współpracować z usługami GData.
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 znasz się na języku Java.
Więcej informacji o klasach i metodach dostępnych w bibliotece klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta w języku Java (w formacie Javadoc).
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.
Omówienie modelu danych
Biblioteka klienta w języku Java używa zestawu klas do reprezentowania elementów używanych przez interfejsy API danych Google. Występuje na przykład klasa pliku danych, która odpowiada elementowi <atom:feed>, zawiera metody tworzenia wpisu, pobierania i ustawiania wartości różnych elementów podrzędnych itd. Istnieje też klasa wpisów odpowiadająca elementowi <atom:entry>. Nie każdy element zdefiniowany w interfejsach Google Data API ma własną klasę. Szczegółowe informacje znajdziesz w dokumentacji.
Biblioteka może automatycznie analizować zawartość Atom i umieszczać wartości elementów Atom w odpowiednich obiektach. Na przykład metoda getFeed pobiera plik danych, analizuje go i zwraca wynikowy plik danych z uzyskanymi wartościami.
Aby wysłać kanał lub wpis do usługi, musisz utworzyć obiekt kanału lub wpisu, a potem wywołać metodę biblioteki (np. metodę insert), by automatycznie przetłumaczyć obiekt na format XML i wysłać go.
Jeśli chcesz, możesz przeanalizować lub wygenerować plik XML samodzielnie. Najłatwiej zrobić to za pomocą odpowiedniej biblioteki zewnętrznej, takiej jak Rzym.
Tak jak w przypadku składni XML interfejsu API danych Google, również można stosować tę samą strukturę obiektów. Na przykład biblioteka klienta udostępnia klasy odpowiadające elementom zdefiniowanym w przestrzeni nazw danych Google.
Samouczek i przykłady
Poniższe przykłady pokazują, jak wysyłać różne żądania do interfejsu API danych za pomocą biblioteki klienta w języku Java.
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 dokumentacji interfejsu Google Calendar Data API.
Tworzenie i uruchamianie klienta
Aby skompilować przykłady w tym dokumencie, musisz użyć tych instrukcji importu:
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;
Żądanie pliku danych
Zgodnie z opisem w dokumencie Google Calendar Data API możesz poprosić o dostęp do kanału Kalendarza, wysyłając do niego to żądanie HTTP:
GET http://www.google.com/calendar/feeds/userID/private/full
Oczywiście adres userID użytkownika należy zastąpić adresem e-mail użytkownika. Szczegółowe informacje znajdziesz w dokumencie Kalendarz. Zamiast niego możesz używać specjalnego domyślnego adresu URL do interakcji z Kalendarzem (jak opisano w dokumencie Kalendarz), ale w tym dokumencie będziemy używać prywatnego pełnego adresu URL kanału, który zawiera identyfikator użytkownika.
Musisz też podać odpowiednie dane o uwierzytelnieniu. Główna różnica między tym przykładem a pierwszym przykładem w dokumencie Kalendarz polega na tym, że (1) ten przykład zawiera uwierzytelnianie i (2) ten przykład używa bardziej ogólnej klasy GoogleService zamiast klasy CalendarService.
Pamiętaj, że używany przez nas system uwierzytelniania (określany jako „Uwierzytelnianie Google dla zainstalowanych aplikacji”) jest odpowiedni tylko w przypadku zainstalowanych aplikacji klienckich, takich jak klienty komputerowe, a nie w aplikacjach internetowych. Więcej informacji o uwierzytelnianiu znajdziesz w dokumentacji uwierzytelniania konta Google.
Aby poprosić o dodanie kanału Kalendarza przy użyciu biblioteki klienta w języku Java, użyj poniższego kodu użytkownika dla adresu e-mail „liz@gmail.com” i hasła „mypassword”.
// 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 składa się z następujących kroków:
- Uzyskaj lub utwórz odpowiedni adres URL.
- Jeśli wysyłasz dane do usługi (np. wstawiając nowy wpis), przekształć nieprzetworzone dane w obiekty za pomocą klas biblioteki klienta. (Ten krok nie ma zastosowania, gdy prosisz tylko o plik danych – robimy to w przykładzie).
- Utwórz nową instancję
GoogleService, ustawiając nazwę usługi (np."cl"w przypadku Kalendarza) i nazwę aplikacji (w formaciecompanyName-applicationName-versionID). - Ustaw odpowiednie dane logowania.
- Wskaż w bibliotece klienta, z jakich rozszerzeń będzie korzystać plik danych, aby biblioteka mogła prawidłowo analizować zwrócone pliki danych.
- Wywołaj metodę wysłania żądania i otrzymywania wyników.
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 „Authentication for Zainstalowane aplikacje”. Więcej informacji o systemach uwierzytelniania znajdziesz w dokumentacji uwierzytelniania konta Google.
Po ustawieniu danych logowania możesz określić, których rozszerzeń będzie używać, wywołując metodę declareExtensions. W tym przypadku jest to kanał zdarzenia, więc będą używane rozszerzenia zdefiniowane przez rodzaj zdarzenia.
Aby zażądać całego pliku, wywołujesz metodę getFeed, która pobiera adres URL i zwraca cały plik danych znaleziony pod tym adresem URL. W dalszej części tego artykułu pokażemy, jak wysyłać bardziej szczegółowe zapytania.
Tak jak inne metody klasy GoogleService, getFeed obsługuje uwierzytelnianie i przekierowania w razie potrzeby.
Wstawianie nowego elementu
Aby utworzyć nowe wydarzenie w kalendarzu, możesz użyć następującego 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 jest określany na podstawie abstrakcyjnej klasy podstawowej BaseEntry, która jest też nadrzędną klasą Entry, która reprezentuje element <atom:entry>.
Klasa EventEntry reprezentuje rodzaj zdarzenia. Więcej informacji znajdziesz w dokumentacji rodzaju. W przypadku usług innych niż Kalendarz możesz zwrócić zwrócony wpis do obiektu Entry, a nie do obiektu EventEntry.
Tytuł wpisu to klasa TextConstruct, która zawiera tekst w różnych postaciach (zwykły tekst, HTML lub XHTML). Treść wpisu jest reprezentowana przez obiekt Content. Klasa może zawierać zwykły tekst lub inne rodzaje treści, w tym dane XML i binarne. (Metoda setContent może też akceptować TextConstruct).
Każdy autor jest reprezentowany jako nazwa, identyfikator URI i adres e-mail. (W tym przykładzie pominiemy identyfikator URI). Aby dodać autora do wpisu, wywołaj jego metodę getAuthors().add.
Używamy tego samego obiektu GoogleService, który utworzyliśmy w poprzednim przykładzie. W tym przypadku jest to metoda insert, która wysyła element pod określony wstawiony adres URL.
Usługa zwraca nowo utworzony wpis, który może zawierać dodatkowe elementy wygenerowane przez serwer, takie jak adres URL edycji wpisu.
Kody stanu HTTP są zwracane jako wyjątki.
Powyższy kod jest odpowiednikiem wysyłania POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (z odpowiednim uwierzytelnianiem) i udostępniania wpisu w rodzaju zdarzenia.
Prośba o określony wpis
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.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
Wstawiony wpis zawiera metodę getSelfLink, która zwraca obiekt Link zawierający adres URL tego wpisu. Klasa Link ma metodę getHref, która zwraca adres URL jako String, ponieważ możemy utworzyć obiekt adresu URL.
Następnie musimy wywołać metodę getEntry usługi, aby pobrać wpis.
Należy pamiętać, że parametr EventEntry.class jest parametrem getEntry, co wskazuje, że oczekujemy, że usługa zwróci zdarzenie, a nie tylko zwykły wpis. W przypadku usług innych niż Kalendarz wystarczy przekazać Entry.class.
Powyższy kod jest odpowiednikiem wysyłania GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID do Kalendarza z odpowiednim uwierzytelnianiem.
Wyszukiwanie wpisów
Aby pobrać pierwsze dopasowanie w wyszukiwaniu pełnotekstowym, 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();
}
Ten przykład zaczyna się od utworzenia obiektu Query, który składa się głównie z adresu URL i powiązanych parametrów zapytania. Każdy ze standardowych parametrów zapytania z danymi GData korzysta z metody ustawiania. Możesz też ustawić niestandardowe parametry zapytania dla konkretnej usługi przy użyciu metody addCustomParameter.
Po utworzeniu Query przekazujemy go do metody query usługi, która zwraca plik danych z wynikami zapytania. Możesz też utworzyć adres URL samodzielnie (dołączając parametry zapytania do adresu URL kanału), a następnie wywołać metodę getFeed, przy czym metoda query dostarcza użyteczną warstwę abstrakcji, która nie wymaga samodzielnego tworzenia adresu URL.
Metoda getEntries pliku danych zwraca listę pozycji w kanale, a getEntries().size zwraca liczbę wpisów w kanale.
W tym przypadku, jeśli zapytanie zwróciło jakieś wyniki, do obiektu Entry przypisujemy pierwszy pasujący wynik. Następnie używamy metody getTitle().getPlainText klasy Entry, aby pobrać tytuł wpisu i przekonwertować go na tekst.
Powyższy kod jest odpowiednikiem wysyłania GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis do Kalendarza.
Zapytania według kategorii
Uwaga: Kalendarz Google nie wiąże etykiet z wydarzeniami, więc ten przykład nie działa w przypadku Kalendarza.
Aby pobrać kanał zawierający wszystkie wpisy, które pasują do wcześniejszego wyszukiwania pełnotekstowego i należą do określonej kategorii lub mają określoną etykietę, użyj następującego 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 zostanie użyta w filtrze kategorii. Klasa Query.CategoryFilter może zawierać wiele kategorii, ale w tym przypadku tworzymy filtr mający tylko jedną kategorię.
Następnie dodaj ten filtr do istniejącego zapytania, które nadal zawiera pełny ciąg zapytania z poprzedniego przykładu.
Ponownie używamy metody query do wysłania zapytania do usługi.
Jeśli Kalendarz zezwoli na wyszukiwanie kategorii, powyższy kod będzie odpowiednikiem wysłania GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis do Kalendarza.
Aktualizowanie elementu
Aby zaktualizować istniejący element, użyj tego kodu. W tym przykładzie zmieniamy tytuł pobranego wcześniej pliku ze starego tekstu („Tenis z Daleka”) 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ł pobranego wcześniej. 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 adres URL nowej wersji tego wpisu. Więcej informacji o wersjach wpisów znajdziesz w sekcji dotyczącej optymalizacji równoczesnych w dokumentacji referencyjnej protokołu.
Powyższy kod jest zbliżony do wysyłania do usługi PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID razem z nowym wpisem (w formacie Atom), aby 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 używany do usunięcia jest taki sam jak edytowany adres URL, więc ten przykład jest bardzo podobny do poprzedniego, z wyjątkiem wywołania metody delete zamiast update.
Powyższy kod jest odpowiednikiem wysłania DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID do usługi.
Materiały referencyjne
Więcej informacji o klasach i metodach dostępnych w bibliotece klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta w języku Java (w formacie Javadoc).