开发者指南:Java

重要提示:这是此页面的旧版。要查看最新版本,请使用左侧导航栏中的链接。

Blogger Data API 允许客户端应用以 Google Data API Feed 的形式查看和更新 Blogger 内容。

您的客户端应用可以使用 Blogger 数据 API 创建新的博文、修改或删除现有的博文,以及查询符合特定条件的博文。

除了介绍一些有关 Blogger 数据 API 功能的背景信息之外,本文还提供了使用 Java 客户端库进行基本数据 API 交互的示例。如果您想详细了解该库使用的底层协议,请参阅本开发者指南的协议部分

目录

受众

本文档适用于想要编写可与 Blogger 交互的 Java 客户端应用的程序员。

本文档假定您了解 Google Data API 协议的一般概念。

如需了解客户端库提供的类和方法,请参阅 Java 客户端库 API 参考文档。如需了解通用的 Blogger 数据 API 参考信息,请参阅协议参考指南

开始使用

如需有关设置客户端库的帮助,请参阅入门指南

Java 客户端库需要 Java 1.5。下载客户端库后,您会在 java/lib/gdataclient-1.0.jar 文件中找到开始使用所需的类。

创建 Blogger 帐号

您可以注册 Blogger 帐号以进行测试。Blogger 使用的是 Google 帐号,因此如果您已经拥有 Google 帐号,就大功告成了。

运行示例代码

包含本文档中显示的所有示例代码的完整工作客户端客户端可在 Java 客户端库发行版 gdata/java/sample/blogger/BloggerClient.java 下找到。构建和执行说明包含在 README.txt 文件的同一目录中。

示例客户端会对提供的博客执行多项操作,以演示如何使用 Blogger Data API。

如需将本文档中的示例编译到自己的代码中,您需要以下 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 服务进行身份验证

您可以使用 Blogger 数据 API 访问公开 Feed 和不公开 Feed。 公开 Feed 不需要任何身份验证,但它们是只读的。如果您想修改博客,那么您的客户端需要先进行身份验证,然后才能请求不公开 Feed。身份验证可以使用以下两种方法之一进行身份验证:AuthSub 代理身份验证或 StreetView 用户名/密码身份验证。

如需详细了解通常如何使用 Google 数据 API 进行身份验证,请参阅身份验证文档

本文档后续部分中的大多数示例都假定您有一个经过身份验证的 GoogleService 对象。

AuthSub 代理身份验证

需要向 Google 帐号对用户进行身份验证的 Web 应用会使用 AuthSub 代理身份验证。网站运营商和客户端代码无法访问 Blogger 用户的用户名和密码;客户端会获取特殊的 AuthSub 令牌,这些令牌使客户端能够代表特定用户执行操作。如需了解详情,请参阅 AuthSub 文档

用户首次访问您的应用时,尚未经过身份验证。在这种情况下,您需要显示一些信息和一个链接,将用户定向到一个 Google 页面,以对您访问其博客的请求进行身份验证。Java 客户端库提供了一个用于生成 Google 网页的网址的函数。以下代码会检索 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 处理程序使用的查询参数相对应):

下一步
身份验证完成后,Google 应将用户重定向到的网页网址。
范围
表示应用正在请求令牌以访问 Blogger Feed。要使用的范围字符串为 http://www.blogger.com/feeds/(当然是网址编码)。
安全
指示客户端是否请求安全令牌。
session
指示是否可以用返回的令牌交换多用途(会话)令牌。

上面的示例展示了没有请求安全令牌的调用(secure 的值为 false)。生成的请求网址可能如下所示:

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 系统会将用户重定向到您在 AuthSubRequest 网址的 next 查询参数中指定的网址。AuthSub 系统会在该网址中附加一个身份验证令牌,作为 token 查询参数的值。例如:

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

此令牌值代表一个单次使用的 AuthSub 令牌。在此示例中,因为指定了 session = true,所以可以通过调用 AuthSubSessionToken 服务使用此令牌来交换 AuthSub 会话令牌,如下所示,其中 urlFromAuthSub 是 AuthSub 附加到令牌的网址:

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

也就是说,您将一次性令牌与 null(针对未注册模式)或私钥(针对注册模式)一起传递给 exchangeForSessionToken 方法,AuthSub 接口会返回会话令牌。如需详细了解已注册的应用和私钥,请参阅 AuthSub 文档的“对请求进行签名”部分。

然后,您的应用可以在后续与 Blogger 互动时使用会话令牌。如需告知 Java 客户端库随每个请求自动发送会话令牌,请调用 GoogleService 对象的 setAuthSubToken 方法:

GoogleService.setAuthSubToken(sessionToken, null);

之后,客户端库会自动随每个请求发送令牌。

ClientLogin 用户名/密码身份验证

如果您的客户端是独立的单用户“安装”客户端(例如桌面应用),请使用 EGL 身份验证。只需对 GoogleService 对象调用 setUserCredentials 方法,即可验证与 Blogger 的所有后续互动:

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

在上面的代码段中,我们将两个参数传递给 GoogleService 构造函数。第一个参数是要与之交互的服务的名称。第二个参数是应用的名称,格式为 companyName-applicationName-versionID

如需详细了解 EGL 身份验证(包括示例请求和响应),请参阅针对已安装应用的身份验证文档。

注意:对于给定会话中的所有请求,都使用相同的令牌;不要为每个 Blogger 请求获取新的令牌。

注意:如 EGL 文档中所述,身份验证请求可能会失败并发出人机识别系统质询。如果您希望 Google 发出并处理人机识别系统质询,请将用户定向到 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger(而不是发送到 EGL 文档中提供的人机识别系统处理网址)。

检索博客列表

Blogger 数据 API 提供的 Feed 列出了特定用户的博客;该 Feed 称为“元 Feed”。

以下示例代码使用经过身份验证的 GoogleService 对象检索元 Feed,然后输出每个博客的标题。

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

记下 getFeed 方法使用的网址。这是默认的元 Feed 网址;它会返回当前已通过身份验证的用户的博客列表。如需访问其他用户的 Feed,您可以将该用户的 ID 替换到元 Feed 网址中 default 的位置。用户 ID 是用户个人资料网址末尾的一串数字。

创建帖子

您可以使用 Blogger Data API 创建和发布新的博客条目,以及创建条目草稿。

注意:目前不支持为帖子设置自定义作者。所有新帖子都会显示为它们是由当前经过身份验证的用户创建的。

发布博文

您可以使用 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 方法将服务的帖子网址作为参数。 然后,该方法会返回 Blogger 存储的条目。返回的条目就是您发送的条目,但其中还包含 Blogger 添加的各种元素,例如帖子 ID。

如果您的请求因某种原因失败,Blogger 可能会返回其他状态代码。如需了解状态代码,请参阅 Google 数据 API 协议参考文档

创建博文草稿

草稿帖子的创建方式与公开帖子相同,但您需要设置 Entry 对象的 draft 属性。您可以通过添加突出显示的行,以草稿形式创建与上述示例类似的博文:

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 公开 Feed。因此,在从公开博客检索博文之前,无需调用 setUserCredentials 方法或执行 AuthSub 身份验证。

检索所有博文

如需检索用户的帖子,请调用与检索博客元 Feed 相同的 getFeed 方法,但这次要发送博文 Feed 网址:

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

使用查询参数检索帖子

借助 Blogger Data API,您可以请求符合指定条件的一组条目,例如请求在指定日期范围内发布或更新的博文。为此,您需要创建 Query 对象并将其传递给 GoogleService.getQuery 方法。

例如,如需发送日期范围查询,请使用 Query 对象的 setPublishedMinsetPublishedMax 方法。以下代码段会输出在指定的开始时间和结束时间之间发布的每篇博文的标题:

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 对象是使用与检索帖子相同的帖子 Feed 网址构建的。

Blogger 数据 API 支持以下 Query 方法:

addCategoryFilter
指定类别(也称为标签)以过滤 Feed 结果。例如,http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 会返回带有 FritzLaurie 标签的条目。
setMaxResults
设置要返回的条目数上限。
setPublishedMin、setPublishedMax
设置条目发布日期的边界。
setStartIndex
设置要检索的第一个结果的索引(从 1 开始),用于分页。
setUpdatedMin、setUpdatedMax
设置条目更新日期的边界。除非 orderby 参数设置为 updated,否则这些查询参数将被忽略。

注意orderby 查询参数目前没有 setter。不过,如果您需要设置此属性,则仍然可以使用 Query.addCustomParameter() 方法。

如需详细了解查询参数,请参阅 Blogger Data API 参考指南Google Data API 参考指南

正在更新帖子

如需更新现有博文,请先检索要更新的条目,接着修改该条目,然后使用 update 方法将其发送到 Blogger。以下代码段修改了博客标题,并假定您已从服务器检索到该条目。

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。如需更新任何其他属性,只需在调用 update 之前在 Entry 对象中设置这些属性。

注意:目前不支持修改与帖子相关联的作者数据。

删除帖子

要删除帖子,请将帖子的修改网址传递给 GoogleService 对象的 delete 方法,如下所示:

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

备注

Blogger Data API 允许创建、检索和删除评论。 不支持更新评论(也不支持网页界面)。

创建评论

要发布注释,请创建一个 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);
}

注意:目前,您只能向经过身份验证的用户拥有的博客发表评论。

注意:目前不支持为评论设置自定义作者。所有新评论将显示为由当前经过身份验证的用户创建。

检索评论

您可以从帖子的评论 Feed 网址中检索特定帖子的评论:

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

或者,您也可以使用博客的评论 Feed 网址来获取所有博文中的评论:

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

删除评论

要删除注释,请将注释的修改网址传递给 GoogleService 对象的 delete 方法,如下所示:

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

返回页首