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

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

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

Этот документ предоставляет некоторую общую информацию об использовании клиентской библиотеки Java, а также набор примеров частого использования.

Чтобы использовать эту клиентскую библиотеку, вы должны использовать Java 1.5.

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

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

Содержание

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

Аудитория

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

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

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

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

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

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

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

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

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

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

Учебник и примеры

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

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

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

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

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;

Запрос фида

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

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

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

Вы также должны предоставить соответствующую аутентификацию. Основные различия между этим примером и первым примером в документе Calendar заключаются в том, что (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" для Календаря) и имя вашего приложения (в формате 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; для получения дополнительной информации см. документ «Виды» . Для служб, отличных от календаря, вы можете назначить возвращаемую запись объекту 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 , указывая, что мы ожидаем, что служба вернет событие, а не просто запись. Для служб, отличных от Календаря, вместо этого вы можете просто передать 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 не связывает ярлыки с событиями, поэтому этот пример не работает с Календарем.

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

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

Вернуться к вершине