本文档将介绍如何开始使用 Blogger API。
前期准备
获取 Google 帐号
确保您已设置 Google 帐号。我们建议您使用单独的 Google 帐号进行开发和测试,以免意外丢失数据。如果您已有测试帐号,则无需进行任何操作;您可以访问 Blogger 界面来设置、修改或查看您的测试数据。
熟悉 Blogger
如果您不熟悉 Blogger 概念,请在开始编码之前阅读本文档并试用界面。本文档假定您熟悉 Blogger、网络编程概念以及网络数据格式。
了解如何向请求授权和识别应用
当您的应用请求私有数据时,该请求必须由有权访问该数据的经过身份验证的用户授权。
当您的应用请求公开数据时,该请求不需要经过授权,但需要附带标识符,例如 API 密钥。
如需了解如何授权请求和使用 API 密钥,请参阅“使用 API”文档中的向请求授权和标识应用。
Blogger API 背景
Blogger 概念
Blogger 基于以下 5 个基本概念构建而成:
- 博客:API 的根概念。博客包含博文和页面。这是博客元信息(如博客名称和说明)的容器。
- 博文:博文是指博文作者创建的可发布项。这些信息旨在及时反映作者想要向全世界发布的内容。可以理解的是,随着时间的推移,博文内容会越来越老,而且相关性会越来越低。
- 评论:评论是指博文作者之外的其他人对作者所写内容作出的回应。从砖到花束,应有尽有。
- 网页:网页是静态内容(如传记信息)或联系方式。这些信息通常是永不过时的,不会经常变化。
- 用户:用户与 Blogger 互动的用户,可以是作者、管理员或读者。对于公开博客,读者可能是匿名的,但在私密博客上,读者必须由 Blogger 识别。
Blogger API 数据模型
资源是具有唯一标识符的单个数据实体。Blogger JSON API 适用于五种类型的资源:
- 博客资源:代表博客。
- 博文资源:表示博文;每个博文资源都是博客资源的子资源。
- 评论资源:表示对特定帖子的评论;每个评论资源都是帖子资源的子项。
- 页面资源:表示静态页面;每个页面资源都是博客资源的子资源。
- 用户资源:表示非匿名用户。此属性用于标识网页、帖子或评论的作者。

Blogger API 数据模型基于称为“集合”的资源组:
- 博客集合
- <span=&apit&apit>blogs 集合包含用户有权访问的所有博客。您可以按用户列出博客,也可以根据 ID 检索单个博客。</span="apicollection">
- 帖子集合
- 帖子集合包含某个特定博客资源中的所有帖子资源。
- 评论集合
- 评论集合由特定帖子资源中的所有评论资源组成。
- 页面收集
- 网页集包含特定博客资源中的所有网页资源。
- 用户集合
- 用户集合由 Blogger 上的所有用户资源组成,因此无法列出。用户可以通过 ID 或使用标识符
self
检索自己的用户资源(而非他人的资源)。
Blogger API 操作
您可以在 Blogger API 中对集合和资源调用多种不同方法,如下表所述。
操作 | 说明 | REST HTTP 映射 |
---|---|---|
list | 列出集合中的所有资源。 | 对集合 URI 执行 GET 。 |
get | 获取特定资源。 | 对资源 URI 执行 GET 。 |
getByUrl | 获取资源,按网址查找。 | 将 GET 替换为以参数形式传入的网址。 |
getByPath | 按资源路径查询资源。 | GET ,其中包含以参数形式传入的路径。 |
listByUser | 列出用户拥有的资源。 | 用户拥有的集合上的 GET 。 |
search | 根据查询参数搜索资源。 | 针对搜索网址的 GET ,查询以参数的形式传入。 |
插入 | 在集合中创建资源。 | 对集合 URI 执行 POST 。 |
delete | 删除资源。 | 对资源 URI 执行 DELETE 。 |
补丁程序 | 使用修补语义更新资源。 | 对资源 URI 执行 PATCH 。 |
update | 更新资源。 | 对资源 URI 执行 PUT 。 |
下表显示了每种资源类型支持的方法。非公开博客上的所有 list 和 get 操作都需要进行身份验证。
资源类型 |
支持的方法 |
|||||||||
---|---|---|---|---|---|---|---|---|---|---|
列表 | 获取 | getByUrl | getByPath | listByUser | 搜索 | 插入 | 删除 | 补丁程序 | 更新 | |
博客 | 否 | 是 | 是 | 否 | 是 | 否 | 不 | 不 | 不 | 否 |
帖子 | 是 | 是 | 否 | 是 | 否 | 是 | 是 | 是 | 是 | 是 |
注释 | 是 | 是 | 否 | 不 | 不 | 不 | 不 | 不 | 不 | 否 |
页面 | 是 | 是 | 否 | 不 | 不 | 不 | 不 | 不 | 不 | 否 |
用户数 | 否 | 是 | 否 | 不 | 不 | 不 | 不 | 不 | 不 | 否 |
调用样式
调用 API 的方法有以下几种:
- 直接使用 REST 或使用 JavaScript(无需服务器端代码)
- 使用客户端库。
REST
REST 是一种软件架构样式,可提供便捷且一致的方法用于请求和修改数据。
术语 REST 是“具象状态传输”的简称。在 Google API 的上下文中,指的是使用 HTTP 谓词来检索和修改由 Google 存储的数据的表示法。
在 RESTful 系统中,资源存储在数据存储区中;在客户端发送要求服务器执行特定操作(例如创建、检索、更新或删除资源)的请求之后,服务器便会执行该操作并发送响应,此响应的格式通常为所指定资源的表示法。
在 Google 的 RESTful API 中,客户端会使用 HTTP 动词(例如 POST
、GET
、PUT
或 DELETE
)指定操作。它通过以下形式的全局唯一 URI 来指定资源:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
由于所有 API 资源都具有 HTTP 可访问的唯一 URI,因此 REST 启用了数据缓存,而且经过优化以与网络的分布式基础架构一起使用。
您可能会发现 HTTP 1.1 标准文档中的方法定义十分有用;这些定义中包含了 GET
、POST
、PUT
和 DELETE
的规范。
Blogger API 中的 REST
受支持的 Blogger 操作直接映射到 REST HTTP 动词,如 Blogger API 操作中所述。
Blogger API URI 的具体格式为:
https://www.googleapis.com/blogger/v3/users/userId https://www.googleapis.com/blogger/v3/users/self https://www.googleapis.com/blogger/v3/users/userId/blogs https://www.googleapis.com/blogger/v3/users/self/blogs https://www.googleapis.com/blogger/v3/blogs/blogId https://www.googleapis.com/blogger/v3/blogs/byurl https://www.googleapis.com/blogger/v3/blogs/blogId/posts https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId https://www.googleapis.com/blogger/v3/blogs/blogId/pages https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId
Blogger API 参考文档中总结了所使用的 URI 以及 API 中每种受支持的操作的结果。
示例
列出通过身份验证的用户有权访问的博客:
GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY
从 code.blogger.com 博客(博文 ID 为 3213900)上获取博文:
GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY
JavaScript 中的 REST
您可以通过使用 callback
查询参数和提供回调函数,从 JavaScript 调用 Blogger API。
当浏览器加载脚本时,回调函数便会执行,响应也会提供给回调函数。通过这种方法,您可以编写显示 Blogger 数据的丰富应用,而无需服务器端代码。
以下示例从您将 API 密钥替换为 YOUR-API-KEY 后,从 code.blogger.com 博客中检索博文。
<html> <head> <title>Blogger API Example</title> </head> <body> <div id="content"></div> <script> function handleResponse(response) { document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content; } </script> <script src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script> </body> </html>
数据格式
JSON
JSON(JavaScript 对象表示法)是一种与语言无关的常见数据格式,可通过简单的文本来表示任意数据结构。如需了解详情,请参阅 json.org。