Использование клиентской библиотеки Java

В этом документе описывается, как использовать клиентскую библиотеку Java для отправки запросов Google Data API («GData») и интерпретации возвращенных ответов.

Google предоставляет набор клиентских библиотек на различных языках программирования для взаимодействия с сервисами, имеющими API для работы с данными. Используя эти библиотеки, вы можете создавать запросы GData, отправлять их сервису и получать ответы.

В этом документе содержится общая информация об использовании клиентской библиотеки Java, а также ряд примеров ее распространенных применений.

Для использования этой клиентской библиотеки необходимо использовать Java 1.5.

Загрузите клиентскую библиотеку Java.

Примеры в этом руководстве относятся к API Google Calendar, но оно не является точным или актуальным руководством по использованию API Calendar. Сведения об использовании клиентской библиотеки Java с API данных конкретного сервиса см. в документации по данному сервису. Например, если вы работаете с Calendar, ознакомьтесь с Руководством разработчика по API данных Calendar .

Содержание

  1. Аудитория
  2. Обзор модели данных
  3. Учебное пособие и примеры
    1. Создание и запуск вашего клиента
    2. Запрос фида
    3. Вставка нового элемента
    4. Запрос конкретной записи
    5. Поиск записей
    6. Запрос по категории
    7. Обновление элемента
    8. Удаление элемента
  4. Ссылка

Аудитория

Этот документ предназначен для программистов Java, которые хотят писать клиентские приложения, способные взаимодействовать со службами GData.

Предполагается, что этот документ знаком с общими принципами протокола Google Data API . Также предполагается, что вы умеете программировать на Java.

Справочную информацию о классах и методах, предоставляемых клиентской библиотекой, см. в справочнике API клиентской библиотеки Java (в формате Javadoc).

Этот документ следует читать по порядку: каждый пример основывается на предыдущих примерах.

Обзор модели данных

Клиентская библиотека Java использует набор классов для представления элементов, используемых API Google Data. Например, существует класс Feed, соответствующий элементу <atom:feed> ; он содержит методы для создания записи, получения и установки значений различных подэлементов и так далее. Также существует класс Entry, соответствующий элементу <atom:entry> . Не каждый элемент, определённый в API Google Data, имеет свой собственный класс; подробности см. в справочной документации .

Библиотека может автоматически анализировать содержимое Atom и помещать значения элементов Atom в соответствующие объекты. Например, метод getFeed получает ленту, анализирует её и возвращает объект Feed с полученными значениями.

Чтобы отправить канал или запись в службу, вы создаете объект Feed или Entry, а затем вызываете библиотечный метод (например, метод insert ), чтобы автоматически перевести объект в XML и отправить его.

При желании вы можете самостоятельно анализировать и/или генерировать XML; проще всего это сделать с помощью соответствующей сторонней библиотеки, например Rome .

Подобно тому, как синтаксис XML API Google Data является расширяемым, соответствующая объектная модель также является расширяемой. Например, клиентская библиотека предоставляет классы, соответствующие элементам, определённым в пространстве имён Google Data .

Учебное пособие и примеры

В следующих примерах показано, как отправлять различные запросы API данных с помощью клиентской библиотеки Java.

Чтобы сделать примеры более конкретными, мы покажем, как взаимодействовать с конкретным сервисом: Google Calendar. Мы укажем на отличия Calendar от других сервисов Google, чтобы помочь вам адаптировать эти примеры для использования с другими сервисами. Подробнее о Calendar см. в документации по API данных Google Calendar .

Создание и запуск вашего клиента

Чтобы скомпилировать примеры из этого документа, вам необходимо использовать следующие операторы импорта:

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;

Запрос фида

Как описано в документе API данных Календаря Google , вы можете запросить канал Календаря, отправив следующий HTTP-запрос в Календарь:

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

Конечно, вам необходимо заменить userID на адрес электронной почты пользователя; подробности см. в документе «Календарь». Вместо этого вы можете использовать специальный URL-адрес по умолчанию для взаимодействия с Календарем (как описано в документе «Календарь»), но в этом документе мы будем использовать закрытый URL-адрес полной ленты, содержащий идентификатор пользователя.

Вам также необходимо обеспечить соответствующую аутентификацию. Основные различия между этим примером и первым примером в документе «Календарь» заключаются в том, что (1) этот пример включает аутентификацию и (2) в этом примере используется более общий класс GoogleService, а не класс CalendarService, специфичный для Календаря.

Обратите внимание, что используемая нами система аутентификации (известная как «Аутентификация Google для установленных приложений») подходит только для использования в установленных клиентских приложениях, таких как настольные клиенты, но не в веб-приложениях. Подробнее об аутентификации см. в документации по аутентификации учётной записи Google .

Чтобы запросить ленту календаря с помощью клиентской библиотеки Java, для пользователя с адресом электронной почты «liz@gmail.com» и паролем «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);

Класс GoogleService представляет собой клиентское подключение (с аутентификацией) к сервису GData. Общая процедура отправки запроса к сервису с использованием клиентской библиотеки состоит из следующих шагов:

  1. Получите или создайте соответствующий URL-адрес.
  2. Если вы отправляете данные в службу (например, если вы вставляете новую запись), преобразуйте необработанные данные в объекты, используя классы клиентской библиотеки. (Этот шаг неприменим, если вы просто запрашиваете канал, как мы делаем в этом примере.)
  3. Создайте новый экземпляр GoogleService , указав имя службы (например, "cl" для Calendar) и имя вашего приложения (в форме companyName - applicationName - versionID ).
  4. Установите соответствующие учетные данные.
  5. Укажите клиентской библиотеке, какие расширения будет использовать канал, чтобы библиотека могла правильно анализировать возвращаемые каналы.
  6. Вызовите метод для отправки запроса и получения результатов.

Метод setUserCredentials задаёт идентификатор и пароль пользователя, от имени которого ваш клиент отправляет запрос. В примерах в этом документе используется система аутентификации «Аутентификация для установленных приложений»; дополнительную информацию о системах аутентификации см. в документации по аутентификации учётной записи Google .

После установки учётных данных вы указываете, какие расширения будет использовать фид, вызывая метод declareExtensions . В данном случае мы говорим, что фид является фидом событий и, следовательно, он будет использовать расширения, определённые типом события .

Чтобы запросить весь фид, вы вызываете метод getFeed , который принимает URL-адрес и возвращает весь фид, найденный по этому URL-адресу. Далее в этом документе мы покажем, как отправлять более конкретные запросы.

Как и другие методы класса GoogleService , getFeed выполняет аутентификацию и перенаправления по мере необходимости.

Вставка нового элемента

Чтобы создать новое событие в календаре, вы можете использовать следующий код:

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

После установки URL-адреса мы создаем объект EventEntry ; EventEntry является производным от абстрактного базового класса BaseEntry , который также является родительским классом для класса Entry , представляющего элемент <atom:entry> .

Класс EventEntry представляет тип Event; дополнительные сведения см. в документе «Виды» . Для служб, отличных от Calendar, возвращаемую запись можно назначить объекту Entry вместо объекта EventEntry .

Заголовок записи — это TextConstruct — класс, содержащий текст в различных форматах (обычный текст, HTML или XHTML). Содержимое записи представлено объектом Content — классом, который может содержать как обычный текст, так и другие форматы контента, включая XML и двоичные данные. (Однако метод setContent также может принимать TextConstruct .)

Каждый автор представлен именем, URI и адресом электронной почты. (В этом примере мы опускаем URI.) Автора можно добавить к записи, вызвав метод getAuthors ().add записи.

Мы используем тот же объект GoogleService , что и в предыдущем примере. В этом случае вызываемый метод — insert , который отправляет элемент по указанному URL-адресу вставки.

Служба возвращает вновь созданную запись, которая может содержать дополнительные элементы, сгенерированные сервером, такие как URL-адрес редактирования записи.

Коды состояния HTTP возвращаются как исключения.

Приведенный выше код эквивалентен отправке POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (с надлежащей аутентификацией) и предоставлению записи в виде типа События.

Запрос конкретной записи

Следующий код позволяет вам запросить конкретную запись, вставленную в предыдущем примере.

В контексте этой серии примеров извлечение этой записи на самом деле не является необходимым, поскольку Calendar уже вернул вставленную запись; но тот же метод можно применять всякий раз, когда вам известен URI записи.

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

Вставленная запись содержит метод getSelfLink , который возвращает объект Link , содержащий URL-адрес записи. Класс Link содержит метод getHref , возвращающий URL-адрес в виде String , из которой можно создать объект URL.

Затем нам просто нужно вызвать метод getEntry сервиса, чтобы получить запись.

Обратите внимание, что мы передаем EventEntry.class в качестве параметра для getEntry , указывая, что мы ожидаем, что сервис вернет событие, а не просто запись. Для других сервисов, кроме Calendar, можно просто передать Entry.class .

Приведенный выше код эквивалентен отправке GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/ entryID в Календарь с надлежащей аутентификацией.

Поиск записей

Чтобы получить первое совпадение из полнотекстового поиска, используйте следующий код:

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

Этот пример начинается с создания объекта Query , состоящего в основном из URL-адреса и связанных с ним параметров запроса. Каждый стандартный параметр запроса GData имеет метод-сеттер. Вы также можете задать пользовательские параметры запроса для конкретного сервиса, используя метод addCustomParameter .

После создания Query мы передаём его методу query сервиса, который возвращает фид с результатами запроса. Альтернативный подход — самостоятельно сформировать URL (добавив параметры запроса к URL фида) и затем вызвать метод getFeed , но метод query предоставляет полезный уровень абстракции, так что вам не придётся создавать URL самостоятельно.

Метод getEntries фида возвращает список записей в ленте; getEntries().size возвращает количество записей в ленте.

В этом случае, если запрос вернул какие-либо результаты, мы присваиваем первый подходящий результат объекту Entry . Затем мы используем метод getTitle ().getPlainText класса Entry для получения заголовка записи и преобразования его в текст.

Приведенный выше код эквивалентен отправке GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis в Календарь.

Запрос по категории

Примечание : Google Calendar не связывает метки с событиями, поэтому этот пример не работает с Календарем.

Чтобы получить канал, состоящий из всех записей, соответствующих предыдущему полнотекстовому поиску и относящихся к определенной категории или имеющих определенную метку, используйте следующий код:

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

Класс Category , конечно же, представляет категорию, используемую в фильтре категорий. Класс Query.CategoryFilter может содержать несколько категорий, но в данном случае мы создаём фильтр только с одной категорией.

Затем мы добавляем этот фильтр к существующему запросу, который по-прежнему содержит строку полнотекстового запроса из предыдущего примера.

Мы снова используем метод query для отправки запроса в службу.

Если бы Календарь допускал поиск по категориям, указанный выше код был бы эквивалентен отправке GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis в Календарь.

Обновление элемента

Чтобы обновить существующий элемент, используйте следующий код. В этом примере мы меняем заголовок ранее полученной записи со старого текста («Теннис с Дарси») на «Важная встреча».

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

Сначала мы задаём новый заголовок для ранее полученной записи. Затем получаем URL-адрес для редактирования записи с помощью метода getEditLink . После этого вызываем метод update сервиса для отправки обновлённой записи.

Служба возвращает обновлённую запись, включая новый URL для новой версии этой записи. (Дополнительную информацию о версиях записи см. в разделе «Оптимистичный параллелизм» справочного документа протокола .)

Приведенный выше код примерно эквивалентен отправке PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/ entryID в службу вместе с новой записью (в формате Atom) для замены исходной записи.

Удаление элемента

Чтобы удалить обновленную запись, используйте следующий код:

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

URL-адрес, используемый для удаления, такой же, как URL-адрес редактирования, поэтому этот пример очень похож на предыдущий, за исключением того, что мы вызываем метод delete вместо update .

Приведенный выше код примерно эквивалентен отправке DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/ entryID в службу.

Ссылка

Справочную информацию о классах и методах, предоставляемых клиентской библиотекой, см. в справочнике API клиентской библиотеки Java (в формате Javadoc).

Вернуться наверх