开发者指南：协议

重要提示：我们将于 2024 年 9 月 30 日停止支持 v2.0 版 Google Data API。 为了确保功能继续正常运行，请将依赖于 v2.0 Google Data API 的应用更新为最新的 API 版本。 如需获取最新版本，请使用左侧导航栏中的链接。 注意：虽然某些 GET 请求（例如商家信息帖子）仍会作为 Feed 网址受支持，但其行为存在细微差异。 如需了解详情，请参阅 Blogger 帮助文档。

借助 Blogger Data 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 Data API 协议背后的一般概念。

如果您使用的是 UNIX 系统，并且希望在不编写任何代码的情况下试用本文档中的示例，则 UNIX 命令行实用程序 curl 或 wget 可能会对您有所帮助；如需了解详情，请参阅这些实用程序的手册页。

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

使用入门

创建 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 是用户个人资料页面网址中的数字。

注意：您也可以将 default 替换为用户 ID，以指示 Blogger 返回请求随附凭据的用户的博客列表。

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

<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 Data API 协议参考文档或 Atom 1.0 规范。

如果您的请求因某种原因而失败，Blogger 可能会返回其他状态代码。如需详细了解 HTTP 状态代码，还可以参阅 Google Data APIs 协议参考文档。

创建帖子

借助 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 请求的正文中。然后，找到 <link> 元素（其中 rel 属性以 #post 结尾），以便在元 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 的博文列表，请向 Blogger 发送以下 HTTP 请求（当然，请使用适当的值替换 blogID）：

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

然后，Blogger 会返回 HTTP 200 OK 状态代码和包含博文的标准 Atom 1.0 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 请求。在标头中，指定条目的 ETag，您可以在 <entry> 元素的 gd:etag 属性中找到该 ETag。

例如：

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

Blogger 收到此请求后，会检查您请求的条目与您指定的 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 Data 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。
published-min、published-max
条目发布日期的边界。
start-index
要检索的第一个结果的索引（从 1 开始，用于分页）。
updated-min、updated-max
条目更新日期的边界。除非将 orderby 参数设置为 updated，否则系统会忽略这些查询参数。
路径
帖子的永久链接路径。例如，如果某篇博文的网址为 http://buzz.blogger.com/2011/08/bloggers-fresh-new-look.html，则其永久链接路径为 /2011/08/bloggers-fresh-new-look.html。
q
全文查询字符串。这样，您就可以在博客中搜索与查询匹配的帖子。

如需详细了解查询参数，请参阅 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 请求。上述评论信息流中突出显示了此网址。

导出格式

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 格式，请参阅协议参考指南。

返回页首