Руководство разработчика: Java

Важно ! Мы прекратим поддержку API данных Google v2.0 30 сентября 2024 г. Чтобы обеспечить бесперебойную работу, обновите свои приложения, использующие API данных Google v2.0, до последней версии API. Для получения последней версии используйте ссылки на левой панели навигации. Примечание. Хотя некоторые запросы GET (например, публикации в списках) будут по-прежнему поддерживаться как URL-адреса каналов, в их поведении есть небольшие различия. Подробную информацию можно найти в справочной документации Blogger .

API данных Blogger позволяет клиентским приложениям просматривать и обновлять контент Blogger в виде каналов API данных Google.

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

Помимо общей информации о возможностях API данных Blogger, в этом документе приводятся примеры базового взаимодействия API данных с использованием клиентской библиотеки Java . Если вы хотите узнать больше о базовом протоколе, который использует библиотека, см. раздел «Протокол» данного руководства для разработчиков.

Содержание

  1. Аудитория
  2. Начиная
    1. Создание учетной записи Blogger
    2. Запуск примера кода
  3. Аутентификация в сервисе Blogger
    1. аутентификация OAuth
    2. Аутентификация прокси-сервера AuthSub
    3. Аутентификация по имени пользователя и паролю ClientLogin
  4. Получение списка блогов
  5. Создание постов
    1. Публикация сообщения в блоге
    2. Создание черновика записи в блоге
  6. Получение сообщений
    1. Получение всех сообщений блога
    2. Получение сообщений с использованием параметров запроса
  7. Обновление сообщений
  8. Удаление сообщений
  9. Комментарии
    1. Создание комментариев
    2. Получение комментариев
    3. Удаление комментариев

Аудитория

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

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

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

Начиная

Для получения помощи по настройке клиентской библиотеки см. Руководство по началу работы .

Для клиентской библиотеки Java требуется Java 1.5. После загрузки клиентской библиотеки вы найдете классы, необходимые для начала работы, в файле java/lib/gdataclient-1.0.jar .

Создание учетной записи Blogger

Возможно, вы захотите зарегистрировать учетную запись Blogger в целях тестирования. Blogger использует учетные записи Google , поэтому, если у вас уже есть учетная запись Google, все готово.

Запуск примера кода

Полный рабочий пример клиента, содержащий весь пример кода, показанный в этом документе, доступен в дистрибутиве клиентской библиотеки Java в каталоге gdata/java/sample/blogger/BloggerClient.java . Инструкции по сборке и выполнению находятся в одном каталоге файла README.txt .

Пример клиента выполняет несколько операций с предоставленным блогом, чтобы продемонстрировать использование API данных Blogger.

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

import com.google.gdata.client.*;
import com.google.gdata.data.*;
import com.google.gdata.util.*;
import java.io.IOException;
import java.net.URL;

Аутентификация в сервисе Blogger

Вы можете получить доступ как к общедоступным, так и к частным каналам с помощью API данных Blogger. Публичные каналы не требуют аутентификации, но доступны только для чтения. Если вы хотите изменить блоги, вашему клиенту необходимо пройти аутентификацию перед запросом частных каналов. Он может аутентифицироваться с использованием любого из трех подходов: аутентификация OAuth , аутентификация прокси-сервера AuthSub или аутентификация по имени пользователя и паролю ClientLogin .

Дополнительную информацию об аутентификации с помощью API данных Google в целом см. в документации по аутентификации .

В большинстве примеров в последующих разделах этого документа предполагается, что у вас есть аутентифицированный объект GoogleService .

аутентификация OAuth

Документацию по аутентификации OAuth с использованием библиотеки Java GData см. в разделе OAuth в клиентских библиотеках протокола данных Google .

Аутентификация прокси-сервера AuthSub

Аутентификация прокси-сервера AuthSub используется веб-приложениями, которым необходимо аутентифицировать своих пользователей в учетных записях Google. Оператор веб-сайта и клиентский код не имеют доступа к имени пользователя и паролю пользователя Blogger; вместо этого клиент получает специальные токены AuthSub, которые позволяют клиенту действовать от имени конкретного пользователя. Более подробную информацию смотрите в документации AuthSub .

Когда пользователь впервые посещает ваше приложение, он еще не прошел аутентификацию. В этом случае вам необходимо отобразить некоторую информацию и ссылку, направляющую пользователя на страницу Google для подтверждения вашего запроса на доступ к их блогам. Клиентская библиотека Java предоставляет функцию для создания URL-адреса страницы Google. Код ниже получает URL-адрес страницы AuthSubRequest:

String next = "http://www.example.com/welcome.html";
String scope = "http://www.blogger.com/feeds/";
boolean secure = false;
boolean session = true;
String authSubLogin = AuthSubUtil.getRequestUrl(next, scope, secure, session);

Метод getRequestUrl принимает следующие параметры (соответствующие параметрам запроса, используемым обработчиком AuthSubRequest):

следующий
URL-адрес страницы, на которую Google должен перенаправить пользователя после аутентификации.
объем
Указывает, что приложение запрашивает токен для доступа к каналам Blogger. Используемая строка области действия — http://www.blogger.com/feeds/ (разумеется, в URL-кодировке).
безопасный
Указывает, запрашивает ли клиент безопасный токен.
сессия
Указывает, можно ли обменять возвращенный токен на многоразовый (сессионный) токен.

В приведенном выше примере показан вызов, который не запрашивает токен безопасности (значение secure — false ). Результирующий URL-адрес запроса может выглядеть следующим образом:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

Пользователь переходит по ссылке на сайт Google и авторизуется в своей учетной записи Google.

После аутентификации пользователя система AuthSub перенаправляет его на URL-адрес, указанный в next параметре запроса URL-адреса AuthSubRequest. Система AuthSub добавляет токен аутентификации к этому URL-адресу в качестве значения параметра запроса token . Например:

http://www.example.com/welcome.html?token=yourAuthToken

Это значение токена представляет собой одноразовый токен AuthSub. В этом примере, поскольку был указан session = true , этот токен можно обменять на токен сеанса AuthSub, вызвав службу AuthSubSessionToken , как показано ниже, где urlFromAuthSub — это URL-адрес, к которому AuthSub добавил токен:

String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub);
String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);

То есть вы передаете свой одноразовый токен методу exchangeForSessionToken вместе с null (для незарегистрированного режима) или закрытым ключом (для зарегистрированного режима), а интерфейс AuthSub возвращает токен сеанса. Дополнительную информацию о зарегистрированных приложениях и закрытых ключах см. в разделе « Запросы на подпись » документации AuthSub.

Затем ваше приложение сможет использовать токен сеанса при последующем взаимодействии с Blogger. Чтобы сообщить клиентской библиотеке Java автоматически отправлять токен сеанса с каждым запросом, вызовите метод setAuthSubToken объекта GoogleService :

GoogleService.setAuthSubToken(sessionToken, null);

После этого клиентская библиотека автоматически отправляет токен вместе с каждым запросом.

Аутентификация по имени пользователя и паролю ClientLogin

Используйте аутентификацию ClientLogin, если ваш клиент является автономным, однопользовательским «установленным» клиентом (например, настольным приложением). Просто вызовите метод setUserCredentials вашего объекта GoogleService , и все последующие взаимодействия с Blogger будут аутентифицированы:

GoogleService myService = new GoogleService("blogger", "exampleCo-exampleApp-1");
myService.setUserCredentials("user@example.com", "secretPassword");

В приведенном выше фрагменте мы передаем два параметра конструктору GoogleService . Первый параметр — это имя сервиса, с которым мы хотим взаимодействовать. Второй параметр — это имя нашего приложения в формате companyName - applicationName - versionID .

Дополнительные сведения об аутентификации ClientLogin, включая примеры запросов и ответов, см. в документации по аутентификации для установленных приложений .

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

Примечание . Как описано в документации ClientLogin, запрос аутентификации может завершиться неудачей и запросить запрос CAPTCHA. Если вы хотите, чтобы Google выполнил и обработал запрос CAPTCHA, отправьте пользователя на https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (а не на URL-адрес обработки CAPTCHA, указанный в документации ClientLogin).

Получение списка блогов

API данных Blogger предоставляет канал, в котором перечислены блоги конкретного пользователя; этот канал известен как «метафид».

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

public static void printUserBlogs(GoogleService myService)
    throws ServiceException, IOException {

  // Request the feed
  final URL feedUrl = new URL("http://www.blogger.com/feeds/default/blogs");
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
  }
}

Обратите внимание на URL-адрес, используемый методом getFeed . Это URL-адрес метафида по умолчанию; он возвращает список блогов для текущего аутентифицированного пользователя. Чтобы получить доступ к каналу для другого пользователя, вы можете указать идентификатор пользователя вместо default в URL-адресе метафида. Идентификатор пользователя — это строка цифр в конце URL-адреса профиля пользователя.

Создание постов

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

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

Публикация сообщения в блоге

Вы можете использовать клиентскую библиотеку Java для публикации новых записей в блоге.

Сначала создайте объект Entry , представляющий сообщение в блоге. Затем вы можете установить заголовок, содержание и другие атрибуты сообщения в блоге. Наконец, используйте объект GoogleService , чтобы вставить сообщение. Вот пример того, как опубликовать новую запись в блоге:

public static Entry createPost(
    GoogleService myService, String blogID, String title,
    String content, String userName)
    throws ServiceException, IOException {
  // Create the entry to insert
  Entry myEntry = new Entry();
  myEntry.setTitle(new PlainTextConstruct(title));
  myEntry.setContent(new PlainTextConstruct(content));

  // Ask the service to insert the new entry
  URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  return myService.insert(postUrl, myEntry);
}

Метод insert принимает URL-адрес публикации службы в качестве параметра. Затем метод возвращает запись в том виде, в котором она была сохранена в Blogger. Возвращенная запись аналогична отправленной вами, но она также содержит различные элементы, добавленные Blogger, например идентификатор публикации.

Если по какой-либо причине ваш запрос не будет выполнен, Blogger может вернуть другой код состояния. Информацию о кодах состояния см. в справочном документе по протоколу API данных Google .

Создание черновика записи в блоге

Черновики публикаций создаются так же, как и публичные публикации, но вам необходимо установить атрибут draft объекта Entry . Вы можете создать черновик сообщения в блоге, подобного приведенному выше, добавив выделенную строку:

public static Entry createPost(GoogleService myService, String blogId,
    String title, String content, String userName,
    Boolean isDraft)
    throws ServiceException, IOException {
  // Create the entry to insert
  Entry myEntry = new Entry();
  myEntry.setTitle(new PlainTextConstruct(title));
  myEntry.setContent(new PlainTextConstruct(content));
  myEntry.setDraft(isDraft);

  // Ask the service to insert the new entry
  URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  return myService.insert(postUrl, myEntry);
}

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

Получение сообщений

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

Вы можете запросить общедоступный канал Blogger без аутентификации. Таким образом, вам не нужно вызывать метод setUserCredentials или выполнять аутентификацию AuthSub перед получением сообщений из общедоступного блога.

Получение всех сообщений блога

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

public static void printAllPosts(
    GoogleService myService, String blogId)
    throws ServiceException, IOException {
  // Request the feed
  URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
  }
  System.out.println();
}

Получение сообщений с использованием параметров запроса

API данных Blogger позволяет запрашивать набор записей, соответствующих заданным критериям, например запрос публикаций в блоге или обновлений в заданном диапазоне дат. Для этого вы создаете объект Query и передаете его методу GoogleService.getQuery .

Например, чтобы отправить запрос диапазона дат, используйте методы setPublishedMin и setPublishedMax объекта Query . Следующий фрагмент кода печатает заголовок каждой записи блога, опубликованной между заданным временем начала и временем окончания:

public static void printDateRangeQueryResults(
    GoogleService myService, String blogId,
    DateTime startTime, DateTime endTime)
    throws ServiceException, IOException {
  // Create query and submit a request
  URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  Query myQuery = new Query(feedUrl);
  myQuery.setPublishedMin(startTime);
  myQuery.setPublishedMax(endTime);
  Feed resultFeed = myService.query(myQuery, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText() +
      " posts between " + startTime + " and " + endTime);
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
    System.out.println("\t" + entry.getUpdated().toStringRfc822());
  }
  System.out.println();
}

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

API данных Blogger поддерживает следующие методы Query :

добавитьCategoryFilter
Укажите категории (также называемые метками), чтобы фильтровать результаты ленты. Например, http://www.blogger.com/feeds/ blogID /posts/default/-/Fritz/Laurie возвращает записи с метками Fritz и Laurie .
setMaxResults
Установите максимальное количество возвращаемых записей.
setPublishedMin, setPublishedMax
Установите границы дат публикации записей.
setStartIndex
Установите индекс с отсчетом от 1 для первого результата, который нужно получить (для разбиения по страницам).
setUpdatedMin, setUpdatedMax
Установите границы дат обновления записей. Эти параметры запроса игнорируются, если для параметра orderby не установлено значение updated .

Примечание . В настоящее время нет установщиков для параметра запроса orderby . Однако вы все равно можете использовать метод Query.addCustomParameter() если вам нужно его установить.

Дополнительную информацию о параметрах запроса см. в Справочном руководстве по API данных Blogger и Справочном руководстве по API данных Google .

Обновление сообщений

Чтобы обновить существующую публикацию в блоге, сначала вы получаете запись, которую хотите обновить, затем изменяете ее, а затем отправляете ее в Blogger, используя метод update . Следующий фрагмент кода изменяет заголовок записи блога, предполагая, что вы уже получили запись с сервера.

public static Entry updatePostTitle(
    GoogleService myService, Entry entryToUpdate, String newTitle)
    throws ServiceException, IOException {
  entryToUpdate.setTitle(new PlainTextConstruct(newTitle));
  URL editUrl = new URL(entryToUpdate.getEditLink().getHref());
  return myService.update(editUrl, entryToUpdate);
}

Приведенный выше код возвращает Entry , содержащую всю недавно обновленную публикацию. Чтобы обновить любые другие свойства, просто установите их в объекте Entry перед вызовом update .

Примечание . Изменение данных автора, связанных с сообщениями, в настоящее время не поддерживается.

Удаление сообщений

Чтобы удалить сообщение, передайте URL-адрес редактирования сообщения в метод delete вашего объекта GoogleService , например:

public static void deletePost(
    GoogleService myService, String editLinkHref)
    throws ServiceException, IOException {
  URL deleteUrl = new URL(editLinkHref);
  myService.delete(deleteUrl);
}

Комментарии

API данных Blogger позволяет создавать, получать и удалять комментарии. Обновление комментариев не поддерживается (и недоступно в веб-интерфейсе).

Создание комментариев

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

public static Entry createComment(
    GoogleService myService, String blogID, String postId,
    String commentText)
    throws ServiceException, IOException {
  // Build the comment feed URI
  String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
  URL feedUrl = new URL(commentsFeedUri);

  // Create a new entry for the comment and submit it to the GoogleService
  Entry myEntry = new Entry();
  myEntry.setContent(new PlainTextConstruct(commentText));
  return myService.insert(feedUrl, myEntry);
}

Примечание . В настоящее время вы можете публиковать комментарии только в блоге, принадлежащем авторизованному пользователю.

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

Получение комментариев

Вы можете получить комментарии к определенному сообщению из URL-адреса ленты комментариев к этому сообщению:

public static void printAllComments(
    GoogleService myService, String blogID, String postId)
    throws ServiceException, IOException {
  // Build comment feed URI and request comments on the specified post
  String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
  URL feedUrl = new URL(commentsFeedUri);
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Display the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" +
        ((TextContent) entry.getContent()).getContent().getPlainText());
    System.out.println("\t" + entry.getUpdated().toStringRfc822());
  }
  System.out.println();
}

Или вы можете получить комментарии ко всем публикациям, используя URL-адрес ленты комментариев блога:

http://www.blogger.com/feeds/blogID/comments/default

Удаление комментариев

Чтобы удалить комментарий, передайте URL-адрес редактирования комментария в метод delete вашего объекта GoogleService следующим образом:

public static void deleteComment(GoogleService myService, String editLinkHref)
    throws ServiceException, IOException {
  URL deleteUrl = new URL(editLinkHref);
  myService.delete(deleteUrl);
}

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