Blogger API：使用入门

本文档将介绍如何开始使用 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。