开发者指南：Java

重要提示： 我们将于 2024 年 9 月 30 日停止支持 2.0 版 Google Data API。 为了确保功能继续正常运行，请将依赖于 v2.0 Google Data API 的应用更新为最新的 API 版本。 如需使用最新版本，请使用左侧导航栏中的链接。 注意：虽然我们仍会继续支持某些 GET 请求（如列出帖子） 那么它们的行为存在细微的差异。 有关详情，请参阅 Blogger 帮助文档。

通过 Blogger 数据 API，客户端应用程序可以查看和更新 Blogger 以 Google Data API Feed 的形式导出内容。

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

除了介绍 Blogger Data API 功能的一些背景信息外，本文档还提供了使用 Java 客户端库进行基本 Data API 交互的示例。如果您想详细了解 协议使用的协议，请参阅 API 规范的协议部分 此开发者指南。

目录

  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 互动的应用

本文假定您了解 Google 数据 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 数据 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 Data API 访问公开和私密 Feed。公开 Feed 不需要任何身份验证，但只能读取。如果您想修改博客，则客户端需要先进行身份验证，然后才能请求私享 Feed。它可以使用以下三种方法中的任意一种进行身份验证：OAuth 身份验证、AuthSub 代理身份验证或 ClientLogin 用户名/密码身份验证。

如需详细了解如何使用 Google Data API 进行身份验证，请参阅身份验证文档。

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

OAuth 身份验证

如需了解使用 Java GData 库进行 OAuth 身份验证的文档，请参阅 Google 数据协议客户端库中的 OAuth。

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/（当然，是经过网址编码的）。
安全
指示客户端是否请求安全令牌。
会话
指示返回的令牌能否兑换为可重复使用的（会话）令牌。

上面的示例展示了一个未请求安全令牌的调用（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);

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

然后，您的应用可以在与 Blogger 的后续互动中使用会话令牌。为了指示 Java 客户端库自动发送会话 令牌，调用 GoogleService 对象的 setAuthSubToken 方法：

GoogleService.setAuthSubToken(sessionToken, null);

之后，客户端库会在每次请求时自动发送令牌。

ClientLogin 用户名/密码身份验证

如果您的客户端是独立的单用户，请使用 ClientLogin 身份验证 “已安装”客户端（例如桌面应用）。只需对 GoogleService 对象调用 setUserCredentials 方法，系统就会对与 Blogger 的所有后续互动进行身份验证：

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

在上面的代码段中，我们向 GoogleService 构造函数传递了两个参数。第一个参数是 希望与之互动的服务第二个参数是我们 表单 companyName-applicationName-versionID。

如需详细了解 ClientLogin 身份验证（包括示例请求和响应），请参阅已安装应用的身份验证文档。

注意：请为同一个请求中的所有请求 指定会话；不会为每个 Blogger 请求获取新的令牌。

注意：正如 ClientLogin 中所述 身份验证请求可能会失败，并请求进行人机识别系统验证， 挑战。如果您希望 Google 发出并处理人机识别系统验证，请将用户发送到 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger（而不是 ClientLogin 文档中提供的人机识别系统验证处理网址）。

检索博客列表

Blogger Data 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 替换为 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 验证。

检索所有博文

如需检索用户的帖子，请调用所使用的 getFeed 方法 来检索博客元供稿，但这次要发送博文供稿网址：

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 对象的 setPublishedMin 和 setPublishedMax 方法。通过 以下代码段会输出在 指定的开始时间和结束时间：

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 Data API 支持以下 Query 方法：

addCategoryFilter
指定类别（也称为标签）以过滤 Feed 结果。例如，http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 会返回同时带有标签 Fritz 和 Laurie 的条目。
setMaxResults
设置要返回的最大条目数。
setPublishMin、setPublishMax
为条目发布日期设置边界。
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 数据 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);
}

注意：目前，您只能对以下内容发表评论： 。

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

正在检索评论

您可以从帖子的评论供稿网址检索特定帖子的评论：

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

正在删除评论

如需删除某条评论，请将该评论的修改网址传递给 delete 方法，如下所示：GoogleService

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

返回页首