开发者指南：协议

重要提示：我们将于 2024 年 9 月 30 日停止对 2.0 版 Google Data API 的支持。为确保可继续使用相关功能，请将依赖 v2.0 Google Data API 的应用更新到最新 API 版本。如需获取最新版本，请使用左侧导航栏中的链接。注意：虽然某些 GET 请求（例如商家信息帖子）作为 Feed 网址继续受到支持，但这些请求的行为方式略有不同。 如需了解详情，请参阅 Blogger 帮助文档。

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

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

除了提供有关 Blogger Data API 功能的一些背景信息外，本文档还提供了使用原始 XML 和 HTTPS 进行基本 Data API 交互的示例。阅读本文档后，您可能需要阅读本开发者指南中针对编程语言的部分，以详细了解如何使用我们的客户端库与 API 进行交互。

目录

  1. 观众群
  2. 开始使用
    1. 创建 Blogger 帐号
  3. 向请求授权
  4. 指定版本
  5. 检索博客列表
  6. 创建帖子
    1. 发布博文
    2. 创建博文草稿
  7. 检索帖子
    1. 检索所有博文
    2. 再次检索博文
    3. 使用查询参数检索帖子
  8. 更新帖子
  9. 删除帖子
  10. 备注
    1. 创建评论
    2. 检索评论
    3. 删除评论
  11. 导出格式

观众群

本文面向的是特定程序员，他们希望编写可使用 XML 和 HTTPS 与 Blogger 进行交互的客户端应用。

本文假定您了解 Google 数据 API 协议背后的一般概念。

如果您使用的是 UNIX 系统，并且希望试用本文档中的示例而不编写任何代码，您会发现 UNIX 命令行实用程序 curl 或 wget 很实用；如需了解详情，请参阅这些实用程序的手册页面。

如需了解 Blogger Data API 参考信息，请参阅 Protocol 参考指南。

使用入门

创建 Blogger 账号

您可能需要注册 Blogger 帐号进行测试。Blogger 使用 Google 帐号，因此如果您已拥有 Google 帐号，那就万事俱备了。

向请求授权

当您的应用请求非公开用户数据时，它必须包含授权令牌。Google 也可通过此令牌识别您的应用。

关于授权协议

建议您使用 OAuth 2.0 为请求授权。

Blogger GData API 还支持旧版授权选项，例如 OAuth 1.0、AuthSub 或 ClientLogin；但是，在大多数情况下，我们不建议使用那些其他选项。如果您的应用已在使用这些选项，我们建议您尽可能迁移到 OAuth 2.0。

如果您的应用有某些特殊授权要求，例如在请求数据访问权限时登录 (hybrid) 或全网域授权委托 (2LO)，则您目前无法使用 OAuth 2.0 令牌。在此类情况下，您必须改用 OAuth 1.0 令牌。

使用 OAuth 2.0 给请求授权

针对非公开用户数据向 Blogger GData API 发出的请求必须由经过身份验证的用户授权。

根据您所编写的应用的类型，OAuth 2.0 的具体授权流程会略有不同。以下常规流程适用于所有应用类型：

  1. 创建应用时，您需要向 Google 注册应用。然后，Google 会提供您稍后需要用到的信息，例如客户端 ID 和客户端密钥。
  2. 当您的应用需要访问用户数据时，它会请求 Google 提供特定范围的访问权限。
  3. Google 会向用户显示 OAuth 对话框，要求用户授权您的应用请求他们的某些数据。
  4. 如果用户批准，Google 会为您的应用提供一个短期访问令牌。
  5. 您的应用会请求获取用户数据，并在请求中附上该访问令牌。
  6. 如果 Google 确定您的请求和令牌有效，就会返回请求的数据。

有些流程还包含其他步骤，例如使用刷新令牌获取新的访问令牌。如需详细了解适用于各类应用的流程，请参阅 Google 的 OAuth 2.0 文档。

以下是 Blogger GData API 的 OAuth 2.0 范围信息：

https://www.blogger.com/feeds/

如需通过 OAuth 2.0 请求访问权限，您的应用既需要范围信息，也需要 Google 在应用注册期间提供的信息（如客户端 ID 和/或客户端密钥）。

提示：Google API 客户端库可帮您处理某些授权流程。并且支持各种编程语言；如需了解详情，请参阅库和示例页面。

指定版本

您使用 Blogger Data API 发送的每个请求都应指定 API 版本 2。

如需指定版本号，请使用 GData-Version HTTP 标头：

GData-Version: 2

或者，如果您无法设置 HTTP 标头，则可以在网址中将 v=2 指定为查询参数。但应尽可能首选使用 HTTP 标头。

注意：客户端库会自动提供适当的版本标头，因此请勿在使用客户端库时使用 v=2 查询参数。

检索博客列表

Blogger Data API 提供的 Feed 会列出特定用户的博客；该 Feed 称为“元 Feed”。

将 HTTP GET 发送到以下网址，以检索博客列表：

https://www.blogger.com/feeds/profileID/blogs

其中个人资料 ID 是用户个人资料网页的网址中的数字。

注意：您还可以将用户 ID 替换成 default，这会让 Blogger 返回凭据一起请求的用户的博客列表。

元供稿中的条目可能如下所示：

<entry gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'>
  <id>tag:blogger.com,1999:user-userNumber.blog-blogID</id>
  <published>2006-08-02T18:44:43.089-07:00</published>
  <updated>2008-04-17T00:03:33.152-07:00</updated>
  <title>Lizzy's Diary</title>
  <summary type='html'>Being the journal of Elizabeth Bennet</summary>
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/profileID/blogs/blogID' />
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/' />
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default' />
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default' />
  ...
  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://www.blogger.com/profile/profileID</uri>
    <email>noreply@blogger.com</email>
  </author>
</entry>

如需了解每个元素的含义，请参阅 Google 数据 API 协议参考文档或 Atom 1.0 规范。

如果您的请求由于某种原因失败，Blogger 可能会返回其他状态代码。如需详细了解 HTTP 状态代码，您也可以参阅 Google 数据 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 属性，其格式如下：

https://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://www.w3.org/2007/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 的博文列表，请将以下 HTTP 请求发送到 Blogger（当然，使用相应的值代替 blogID）：

GET https://www.blogger.com/feeds/blogID/posts/default

然后，Blogger 会返回 HTTP 200 OK 状态代码和包含博文的标准 Atom 1.0 Feed。

以下是仅有一篇博文的博客 Feed 示例。请注意，我们对此示例稍作修改，以方便用户阅读。特别是，真实的 Blogger Feed 包含实际 ID 和网址。

<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet href="http://www.blogger.com/styles/atom.css"
  type="text/css"?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'>
  <id>tag:blogger.com,1999:blog-blogID</id>
  <updated>2008-04-17T00:03:33.152-07:00</updated>
  <title>Lizzy's Diary</title>
  <subtitle type='html'></subtitle>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://blogName.blogspot.com/feeds/posts/default' />
  <link rel='self' type='application/atom+xml'
    href='http://www.blogger.com/feeds/blogID/posts/default' />
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/' />
  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://www.blogger.com/profile/profileID</uri>
    <email>noreply@blogger.com</email>
  </author>
  <generator version='7.00'
    uri='http://www2.blogger.com'>Blogger</generator>
  <entry gd:etag='W/"D0YHRn84eip7ImA9WxZUFk8."'>
    <id>tag:blogger.com,1999:blog-blogID.post-postID</id>
    <published>2008-04-07T20:25:00.005-07:00</published>
    <updated>2008-04-07T20:25:37.132-07:00</updated>
    <title>Quite disagreeable</title>
    <content type='html'>&lt;p&gt;I met Mr. Bingley's friend Mr. Darcy
      this evening. I found him quite disagreeable.&lt;/p&gt;</content>
    <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/posts/default/postID' />
    <link rel='self' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/posts/default/postID' />
    <link rel='alternate' type='text/html'
      href='http://blogName.blogspot.com/2008/04/quite-disagreeable.html' />
    <author>
      <name>Elizabeth Bennet</name>
      <uri>http://www.blogger.com/profile/profileID</uri>
      <email>noreply@blogger.com</email>
    </author>
  </entry>
</feed>

再次检索博文

如果要检索之前检索到的博文，您可以指示 Blogger 仅在自您上次检索后发生更改时发送该博文，从而提高效率。

如需执行此类条件检索，请发送包含 HTTP If-None-Match 标头的 HTTP GET 请求。在标头中，指定条目的 eSIM 卡（可在 <entry> 元素的 gd:etag 属性中找到）。

例如：

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

当 Blogger 收到此请求时，它会检查您请求的条目是否具有与您指定的 ETag 相同的 ETag。如果这两个 ETag 匹配，则表示条目未更改，并且 Blogger 会返回 HTTP 304 Not Modified 状态代码。

如果这两个 ETag 不匹配，则说明自您上次请求该条目后，该条目发生了修改，Blogger 会返回该条目。

如需详细了解 ETag，请参阅 Google Data API 参考指南。

使用查询参数检索博文

通过 Blogger Data API，您可以请求一组符合指定条件的条目，例如请求在给定日期范围内发布或更新的博文。

例如，如需发送日期范围查询，请在请求网址中添加 published-min 和 published-max 参数。要获取在 2008 年 3 月 16 日至 2008 年 3 月 24 日期间创建的所有博客条目，请向博客的 Feed 网址发送 HTTP 请求：

GET https://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 结果的类别（也称为标签）。例如，https://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，否则系统会忽略这些查询参数。
path
信息的固定链接路径。例如，对于网址为 http://buzz.blogger.com/2011/08/bloggers-fresh-new-look.html 的帖子，固定链接路径为 /2011/08/bloggers-fresh-new-look.html。
季度
全文查询字符串。这可让您在博客中搜索与查询匹配的博文。

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

正在更新帖子

如需更新现有博文，请先检索要更新的条目，然后对其进行修改，接着向该博文的修改网址发送 PUT 请求（更新后的条目会在消息正文中）。请确保 PUT 条目中的 <id> 值与现有条目的 <id> 完全匹配。

以下条目中突出显示了修改网址：

<entry gd:etag='W/"CUYDSXo8fSp7ImA9WB9UFkU."'>
  <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'>&lt;p&gt;I met Mr. Bingley's friend Mr. Darcy
    this evening. I found him quite disagreeable.&lt;/p&gt;</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 https://www.blogger.com/feeds/blogID/postID/comments/default

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

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

检索评论

您可以通过向此博文的评论 Feed 网址发送 GET 来检索特定博文的评论：

GET https://www.blogger.com/feeds/blogID/postID/comments/default

或者，您可以使用博客的评论 Feed 网址获取所有博文的评论：

GET https://www.blogger.com/feeds/blogID/comments/default

这些请求会返回如下所示的评论 Feed：

<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet href="http://www.blogger.com/styles/atom.css"
  type="text/css"?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"CUYMQ348fyp7ImA9WB9UFkU."'>
  <id>tag:blogger.com,1999:blog-blogID.postpostID..comments</id>
  <updated>2007-12-14T17:46:22.077-08:00</updated>
  <title>Comments on Lizzy's Diary: Quite disagreeable</title>
  <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://www.blogger.com/feeds/blogID/postID/comments/default' />
  <link rel='alternate' type='text/html'
    href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html' />
  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://www.blogger.com/profile/profileID</uri>
    <email>noreply@blogger.com</email>
  </author>
  <generator version='7.00'
    uri='http://www.blogger.com'>Blogger</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <entry gd:etag='W/"CUYCQX47eSp7ImA9WB9UFkU."'>
    <id>tag:blogger.com,1999:blog-blogID.post-commentID</id>
    <published>2007-12-14T17:46:00.001-08:00</published>
    <updated>2007-12-14T17:46:00.001-08:00</updated>
    <title>Darcy FTW!</title>
    <content type='html'>Darcy FTW!</content>
    <link rel='edit' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' />
    <link rel='self' type='application/atom+xml'
      href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' />
    <link rel='alternate' type='text/html'
      href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html?showComment=1197683160001#ccommentID'
      title='' />
    <author>
      <name>Elizabeth Bennet</name>
      <uri>http://www.blogger.com/profile/profileID</uri>
      <email>liz@gmail.com</email>
    </author>
    <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0'
      href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html'
      ref='tag:blogger.com,1999:blog-blogID.post-postID'
      source='http://www.blogger.com/feeds/blogID/posts/default/postID'
      type='text/html' />
  </entry>
</feed>

正在删除评论

如需删除评论，请向评论的修改网址发送 DELETE 请求。该网址在上述评论 Feed 中突出显示。

导出格式

Blogger 允许用户使用 Blogger 导出文件导出和导入自己的博客。此导出文件包含一个博客的所有帖子和评论。导出文件的格式与“检索帖子和评论”部分中介绍的 Atom 格式完全相同。此导出文件将包含博文 Feed 和评论 Feed 的内容合并到一个文档中。

如需使用导出格式导出或导入博客数据，您可以访问博客的设置页面。要使用 Data API 检索博客的导出文件，请使用以下网址：

GET https://www.blogger.com/feeds/blogID/archive

如需导入导出文件，请创建对以下网址的 POST 请求，并将导出文件的内容作为请求数据，application/atom+xml 作为内容类型：

POST https://www.blogger.com/feeds/blogID/archive/full

上述两个网址都不支持查询参数。这两个请求还必须包含身份验证信息，并且只有博客管理员才能使用这些 Feed 网址导入/导出博客。

注意：如果您要创建自己的 Blogger 导出文件，目前存在一项关于博文和评论条目顺序的限制。Blogger 导出文件将首先列出所有博文，然后列出所有评论。您可以交错发布帖子和评论条目，但前提是评论条目排在评论所属的帖子之后。

如需详细了解 Blogger 如何在导出文件中使用 Atom 格式，请参阅协议参考指南。

返回页首