重要提示:这是此页面的旧版本。要查看最新版本,请使用左侧导航栏中的链接。
Blogger Data API 可让客户端应用以 Google Data API Feed 的形式查看和更新 Blogger 内容。
您的客户端应用可以使用 Blogger Data API 创建新的博文、修改或删除现有博文,以及查询符合特定条件的博文。
除了提供有关 Blogger Data API 功能的一些背景信息之外,本文档还提供了使用原始 XML 和 HTTP 进行基本 Data API 交互的示例。阅读本文档后,您可能需要阅读本开发者指南中针对编程语言的部分,详细了解如何使用我们的客户端库与 API 进行交互。
目录
观众群
本文面向的是特定程序员,他们希望编写能够使用 XML 和 HTTP 与 Blogger 进行交互的客户端应用。
本文档假定您已了解 Google Data API 协议背后的一般概念。
如果您使用的是 UNIX 系统,并且希望在不编写任何代码的情况下尝试本文档中的示例,您会发现 UNIX 命令行实用程序 curl
或 wget
非常有用;如需了解详情,请参阅这些实用程序的手册页面。
有关 Blogger Data API 参考信息,请参阅协议参考指南。
使用入门
创建 Blogger 账号
您可能需要注册 Blogger 账号才能进行测试。Blogger 使用的是 Google 帐号,因此,如果您已拥有 Google 帐号,就大功告成了。
在 Blogger 服务中进行身份验证
您可以使用 Blogger 数据 API 访问公开和私有 Feed。公开 Feed 不需要任何身份验证,但会处于只读状态。如果您想修改博客,您的客户端需要先进行身份验证,然后才能请求不公开 Feed。它可以使用以下两种方法之一进行身份验证:AuthSub 代理身份验证或 ClientLogin 用户名/密码身份验证。
如需全面详细地了解使用 Google Data API 进行身份验证的信息,请参阅身份验证文档。
本文档后续部分中的大多数示例都假定您提供了适当的身份验证。
AuthSub 代理身份验证
需要向 Google 帐号验证用户身份的 Web 应用会使用 AuthSub 代理身份验证。网站运营商和客户端代码无权访问 Blogger 用户的用户名和密码;相反,客户端会获取特殊的 AuthSub 令牌,允许客户端代表特定用户执行操作。如需了解详情,请参阅 AuthSub 文档。
用户首次访问您的应用时,尚未通过身份验证。在这种情况下,您需要显示一些信息和一个链接,将用户定向到某个 Google 页面,以验证您对访问其博客的请求进行身份验证。
AuthSubRequest 网址中包含以下查询参数:
- 下一个
- Google 应在完成身份验证后将用户重定向到的网页的网址。
- 范围
- 表示应用正在请求令牌以访问 Blogger Feed。使用的范围字符串是
http://www.blogger.com/feeds/
(当然,是经过网址编码的)。 - 安全
- 指示客户端是否请求安全令牌。
- session
- 指示返回的令牌是否可以交换为可多次使用的(会话)令牌。
AuthSubRequest 网址可能如下所示:
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 系统会将用户重定向到您在 AuthSub 请求网址的 next
查询参数中指定的网址。AuthSub 系统会在该网址上附加一个身份验证令牌,作为 token
查询参数的值。例如:
http://www.example.com/welcome.html?token=yourAuthToken
此令牌值代表一个单次使用的 AuthSub 令牌。在此示例中,由于指定了 session=1
,因此可通过在 Authorization 标头中使用一次性令牌调用 AuthSubSessionToken
服务来将此令牌交换为 AuthSub 会话令牌,如下所示:
GET /accounts/AuthSubSessionToken HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: AuthSub token="yourAuthToken" User-Agent: Java/1.5.0_06 Host: www.google.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive
AuthSubSessionToken 服务响应包括一个包含会话令牌的 Token
标头和一个指示令牌有效期的 Expiration
标头。
然后,您的应用可以在与 Blogger 的后续互动中使用 Authorization
标头中的会话令牌值。
下面是一个包含非安全令牌的 HTTP 请求示例,您可以将其发送给 Blogger:
GET /feeds/blogID/blogs/posts/defaults HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: AuthSub token="yourSessionToken" User-Agent: Java/1.5.0_06 Host: www.blogger.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive
ClientLogin 用户名/密码身份验证
如果您的客户端是独立的单用户“已安装”客户端(例如桌面应用),请使用 ClientLogin 身份验证。要使用 ClientLogin 机制请求身份验证令牌,请向以下网址发送 POST
请求:
https://www.google.com/accounts/ClientLogin
POST
正文应包含一组查询参数,它们类似于 HTML 表单传递的参数,使用 application/x-www-form-urlencoded
内容类型。这些参数包括:
- 用户的电子邮件地址。
- Passwd
- 用户的密码。
- 服务
- Blogger 服务名称为
blogger
。(如需了解其他服务名称,请参阅服务名称列表。) - accountType
- 使用 Blogger API 时,应始终将其设置为
GOOGLE
。如果未设置此参数,则拥有 G Suite 帐号的用户也无法访问。 - source
- 标识客户端应用。格式应为 companyName-applicationName-versionID。以下示例使用名称
exampleCo-exampleApp-1
。
如需详细了解这些参数,请参阅对已安装的应用进行身份验证文档。
如果身份验证请求失败,服务器将返回 HTTP 403 Forbidden
状态代码。
如果成功,服务器将返回一个 HTTP 200 OK
状态代码,以及响应正文中的三个长字母数字代码:SID、LSID 和 Auth。Auth 值是您要随每个后续请求一起发送到 Blogger 的授权令牌,因此请保留该值的副本。您可以忽略 SID 和 LSID 值。
由于对不公开 Feed 的所有请求都需要进行身份验证,因此,您必须在与 Blogger 的所有后续互动中使用以下格式设置 Authorization 标头:
Authorization: GoogleLogin auth=yourAuthToken
其中,yourAuthToken
是 ClientLogin 请求返回的 Auth 字符串。
要详细了解 ClientLogin 身份验证(包括示例请求和响应),请参阅为已安装的应用进行身份验证文档。
注意:给定会话中的所有请求应使用相同的令牌;不要为每个 Blogger 请求获取新的令牌。
注意:如 ClientLogin 文档中所述,身份验证请求可能会失败并请求进行人机识别系统质询。如果您希望 Google 发出并处理人机识别系统质询,请将用户发送到 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger
(而不是 ClientLogin 文档中提供的人机识别系统处理网址)。
检索博客列表
Blogger 数据 API 提供了一个列出特定用户的博客的 Feed;该 Feed 称为“元 Feed”。
将 HTTP GET
发送到以下网址以检索博客列表:
http://www.blogger.com/feeds/userID/blogs
注意:您还可以将用户 ID 替换为 default
,让 Blogger 针对请求返回凭据的用户返回博客列表。
元供稿中的条目可能如下所示:
<entry> <id>tag:blogger.com,1999:blog-blogID.post-postID</id> <published>2006-08-02T18:44:43.089-07:00</published> <updated>2006-11-08T18:10:23.020-08:00</updated> <title type='text'>Lizzy's Diary</title> <summary type='html'>Being the journal of Elizabeth Bennet</summary> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/'> </link> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default'> </link> <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default'> </link> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/userID/blogs/blogID'> </link> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/userID/blogs/blogID'> </link> <author> <name>Elizabeth Bennet</name> <email>noreply@blogger.com</email> <uri>http://www.blogger.com/profile/profileID</uri> </author> </entry>
如需了解每个元素的含义,请参阅 Google 数据 API 协议参考文档或 Atom 1.0 规范。
如果您的请求由于某种原因失败,Blogger 可能会返回其他状态代码。有关 HTTP 状态代码的详细信息,您也可以参阅 Google Data API 协议参考文档。
创建帖子
使用 Blogger Data API,您可以创建和发布新的博客条目,以及创建条目的草稿。
发布博文
完成身份验证后,您就可以发布新的博客文章了。
首先,创建要发布的帖子的 XML 表示形式。此 XML 需要采用 Atom <entry>
元素的形式,可能如下所示:
<entry xmlns='http://www.w3.org/2005/Atom'> <title type='text'>Marriage!</title> <content type='xhtml'> <div xmlns="http://www.w3.org/1999/xhtml"> <p>Mr. Darcy has <em>proposed marriage</em> to me!</p> <p>He is the last man on earth I would ever desire to marry.</p> <p>Whatever shall I do?</p> </div> </content> <category scheme="http://www.blogger.com/atom/ns#" term="marriage" /> <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" /> </entry>
注意:目前不支持为帖子设置自定义作者。所有新帖子都会显示为由当前经过身份验证的用户创建的。
要发布此条目,请按如下方式将其发送到博客的帖子网址。首先,使用 application/atom+xml
内容类型将 Atom <entry>
元素放在新的 POST
请求的正文中。然后,通过在 rel
属性以 #post
结尾的 <link>
元素中找到博客的博文网址,从而在元 Feed 中找到该博文的网址。博客的博文网址指定为此元素的 href
属性,格式如下:
http://www.blogger.com/feeds/blogID/posts/default
注意:此网址与人类可读版本的博客的 <head>
部分中显示的 <link rel="service.post">
标记中的网址相同。
Blogger 使用您发送的条目创建博文,然后返回一个 HTTP 201 CREATED
状态代码,以及 <entry>
元素形式的新博文副本。返回的条目就是您发送的条目,但其中还包含 Blogger 添加的各种元素,例如 <id>
元素。
如果您的请求由于某种原因失败,Blogger 可能会返回其他状态代码。有关状态代码的信息,请参阅 Google Data API 协议参考文档。
创建博文草稿
草稿帖子的创建方式与公开帖子相同,但会在条目中添加 <app:control>
元素,以表明帖子不应发布。
此 <app:control>
元素应包含一个 <app:draft>
元素作为子元素:
<app:control xmlns:app='http://purl.org/atom/app#'> <app:draft>yes</app:draft> </app:control>
<app:draft>
元素中包含的数据必须是字符串 yes,系统才会将帖子识别为草稿。
您可以检索现有的博文草稿,将 <app:draft>
元素的数据设置为字符串 no,然后更新这篇博文,从而将其转换为已发布的博文。接下来的两部分会介绍如何检索和更新帖子。
注意:如需详细了解 Atom 发布协议(包括 <app:control>
和 <app:draft>
命名空间),请参阅 RFC 5023。
检索帖子
以下部分介绍了如何检索博文列表(无论是否使用查询参数)。
您可以在不进行身份验证的情况下查询 Blogger 公开 Feed。因此,从公开博客检索博文时,您无需设置 Authorization 参数。
检索所有博客帖子
如需检索用户的帖子,请向博客的 Feed 网址发送 HTTP GET
请求。然后,Blogger 会返回包含相应博客条目的 Feed。例如,要获取 liz@gmail.com 的博文列表,请向 Blogger 发送以下 HTTP 请求(当然,要用适当的值替换 blogID
):
GET http://www.blogger.com/feeds/blogID/posts/default
然后,Blogger 会返回 HTTP 200 OK
状态代码和包含博文的标准 Atom 1.0 Feed。
下面是一个仅包含一篇博文的博客 Feed 示例。请注意,我们稍微修改了此示例,使其更便于用户阅读。特别是,真实的 Blogger Feed 包含实际的 ID 和网址。
<feed xmlns='http://www.w3.org/2005/Atom'> <id>tag:blogger.com,1999:blog-blogID</id> <updated>2006-11-08T18:10:23.020-08:00</updated> <title type='text'>Lizzy's Diary</title> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/index.html'> </link> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default'> </link> <link rel='self' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default'> </link> <author> <name>Elizabeth Bennet</name> <email>noreply@blogger.com</email> <uri>http://www.blogger.com/profile/profileID</uri> </author> <generator version='7.00' uri='http://www2.blogger.com'>Blogger</generator> <entry> <id>tag:blogger.com,1999:blog-blogID.post-postID</id> <published>2006-11-08T18:10:00.000-08:00</published> <updated>2006-11-08T18:10:14.954-08:00</updated> <title type='text'>Quite disagreeable</title> <content type='html'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></content> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2006/11/quite-disagreeable.html'> </link> <link rel='self' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default/postID'> </link> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID'> </link> <author> <name>Elizabeth Bennet</name> <email>noreply@blogger.com</email> <uri>http://www.blogger.com/profile/profileID</uri> </author> </entry> </feed>
使用查询参数检索博文
利用 Blogger Data API,您可以请求一组符合指定条件的条目,例如,请求在给定日期范围内发布或更新的博文。
例如,如需发送日期范围查询,请在请求网址中添加 published-min
和 published-max
参数。要获取在 2008 年 3 月 16 日至 2008 年 3 月 24 日期间创建的所有博客条目,请向博客的 Feed 网址发送 HTTP 请求:
GET http://www.blogger.com/feeds/blogID/posts/default?published-min=2008-03-16T00:00:00&published-max=2008-03-24T23:59:59
您发送该 GET
请求时,Blogger 会返回 HTTP 200 OK
状态代码以及一个包含指定日期范围内创建的所有博文的 Feed。
updated-min
和 updated-max
参数也可用于获取指定范围内更新的所有博客条目。不过请注意,除非 orderby
参数也设置为 updated
,否则系统会忽略这些参数。
Blogger 数据 API 支持以下查询参数:
- alt
- 要返回的 Feed 类型,例如
atom
(默认)或rss
。 - /category
- 指定用于过滤 Feed 结果的类别(也称为标签)。例如,
http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie
会返回同时带有Fritz
和Laurie
标签的条目。 - max-results
- 要返回的最大条目数。
- orderby
- 返回条目的顺序,例如
lastmodified
(默认)、starttime
或updated
。 - “publish-min”“publish-max”
- 条目发布日期的边界。
- start-index
- 要检索的第一个结果的索引(从 1 开始,用于分页)。
- 更新最小值、更新最大值
- 条目更新日期的边界。除非
orderby
参数设置为updated
,否则系统会忽略这些查询参数。
如需详细了解查询参数,请参阅 Blogger Data API 参考指南和 Google Data API 参考指南。
正在更新帖子
如需更新现有博文,请先检索要更新的条目,对其进行修改,然后向该博文的修改网址发送 PUT
请求(消息正文中包含更新后的条目)。确保您 PUT
的条目中的 <id>
值与现有条目的 <id>
完全匹配。
修改网址在以下条目中突出显示:
<entry> <id>tag:blogger.com,1999:blog-blogID.post-postID</id> <published>2006-11-08T18:10:00.000-08:00</published> <updated>2006-11-08T18:10:14.954-08:00</updated> <title type='text'>Quite disagreeable</title> <content type='html'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></content> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2006/11/quite-disagreeable.html'> </link> <link rel='self' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default/postID'> </link> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID'> </link> <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Bingley" /> <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" /> <author> <name>Elizabeth Bennet</name> <email>noreply@blogger.com</email> <uri>http://www.blogger.com/profile/profileID</uri> </author> </entry>
重要提示:为确保向前兼容性,请务必在对更新后的条目执行 PUT
操作时保留从 Blogger 检索该条目时存在的所有 XML。否则,当我们实现新内容并在 Feed 中添加 <new-awesome-feature>
元素时,客户端不会返回这些元素,导致用户错失良机。Google Data API 客户端库都可以正确处理这种情况,因此,如果您使用的是其中一个库,便大功告成了。
注意:目前不支持修改与帖子关联的作者数据。
问题排查提示:某些防火墙会阻止 HTTP PUT
消息。为解决此问题,您可以在 POST
请求中添加 X-HTTP-Method-Override: PUT
标头。如需了解详情,请参阅 Google Data API 协议基础知识文档。
正在删除帖子
如需删除某个博文,请向该博文的修改网址发送 DELETE
请求。此网址与用于更新帖子的网址相同。
问题排查提示:某些防火墙会阻止 HTTP DELETE
消息。为解决此问题,您可以在 POST
请求中添加 X-HTTP-Method-Override: DELETE
标头。如需了解详情,请参阅 Google Data API 协议基础知识文档。
注释
Blogger Data API 允许创建、检索和删除评论。不支持更新注释(网页界面中也不支持更新)。
创建评论
如需发表评论,请创建如下所示的 Atom <entry>
元素:
<entry xmlns='http://www.w3.org/2005/Atom'> <title type="text">This is my first comment</title> <content type="html">This is my first comment</content> </entry>
如需发布此注释,请使用 application/atom+xml
内容类型将 Atom <entry>
元素放在新的 POST
请求的正文中。然后,将 POST
请求发送到相应的 Blogger 网址:
POST http://www.blogger.com/feeds/blogID/postID/comments/default
注意:目前,您只能在经过身份验证的用户所拥有的博客上发表评论。
注意:目前不支持为评论设置自定义作者。所有新评论都会显示为由当前经过身份验证的用户创建的。
正在检索评论
您可以检索特定帖子的评论,只需向该帖子的评论 Feed 网址发送 GET
即可:
GET http://www.blogger.com/feeds/blogID/postID/comments/default
或者,您可以使用博客的评论 Feed 网址获取所有博文的评论:
GET http://www.blogger.com/feeds/blogID/comments/default
这些请求会返回如下所示的评论供稿:
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:thr="http://purl.org/syndication/thread/1.0"> <id>tag:blogger.com,1999:blog-blogID.post-postID.comment-commentID</id> <updated>2007-04-04T21:56:29.803-07:00</updated> <title type="text">My Blog : Time to relax</title> <link rel="alternate" type="text/html" href="http://blogName.blogspot.com/2007/04/first-post.html"/> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default"/> <link rel="self" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default"/> <author> <name>Blog Author name</name> </author> <generator version="7.00" uri="http://www2.blogger.com">Blogger</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <entry> <id>tag:blogger.com,1999:blog-blogID.post-commentID</id> <published>2007-04-04T21:56:00.000-07:00</published> <updated>2007-04-04T21:56:29.803-07:00</updated> <title type="text">This is my first comment</title> <content type="html">This is my first comment</content> <link rel="alternate" type="text/html" href="http://blogName.blogspot.com/2007/04/first-post.html#commentID"/> <link rel="self" type="application/atom+xml" href="http://blogName.blogspot.com/feeds/postID/comments/default/commentID"/> <link rel="edit" type="application/atom+xml" href="http://www.blogger.com/feeds/blogID/postID/comments/default/commentID"/> <thr:in-reply-to href="http://blogName.blogspot.com/2007/04/first-post.html" ref="tag:blogger.com,1999:blog-blogID.post-postID" source="http://www.blogger.com/feeds/posts/default/blogID" type="text/html"/> <author> <name>Blog Author name</name> <email>blog_author@gmail.com</email> <uri>http://www.blogger.com/profile/userID</uri> </author> <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0' href='http://blogName.blogspot.com/2007/04/first-post.html' ref='tag:blogger.com,1999:blog-blogID.post-postID' source='http://blogName.blogspot.com/feeds/posts/default/postID' type='text/html' /> </entry> </feed>
正在删除评论
如需删除某条评论,请向该评论的修改网址发送 DELETE
请求。此网址在上方的评论 Feed 中会突出显示。
导出格式
Blogger 允许用户使用 Blogger 导出文件来导出和导入自己的博客。此导出文件包含某个博客的所有博文和评论。导出文件的格式与检索帖子和评论的部分中描述的 Atom 格式完全相同。此导出文件将包含博文 Feed 的内容以及评论 Feed 的内容合并为一个文档。
如需使用导出格式导出或导入博客数据,您可以访问博客的设置页面。如需使用 Data API 检索博客的导出文件,请使用以下网址:
GET http://www.blogger.com/feeds/blogID/archive
如需导入导出文件,请创建对以下网址的 POST
请求,并将导出文件的内容作为请求数据,并使用 application/atom+xml
作为内容类型:
POST http://www.blogger.com/feeds/blogID/archive/full
上述两个网址均不支持查询参数。这两个请求还必须包含身份验证信息,只有博客管理员可以使用这些 Feed 网址导入/导出博客。
注意:如果您要创建自己的 Blogger 导出文件,目前在博文和评论条目的顺序方面存在一个限制。Blogger 导出文件会先列出所有博文 然后列出所有评论允许交错博文和评论条目,但前提是评论条目在评论所针对的帖子之后。
如需详细了解 Blogger 如何在导出文件中使用 Atom 格式,请参阅协议参考指南。