Blogger API：使用入门

本文档介绍了如何开始使用 Blogger API。

前期准备

获取 Google 账号

确保您已设置 Google 账号。我们建议您使用单独的 Google 账号进行开发和测试，以防意外丢失数据。如果您已有测试账号，则无需再做任何操作；您可以访问 Blogger 界面来设置、修改或查看测试数据。

熟悉 Blogger

如果您不熟悉 Blogger 的相关概念，请先阅读本文档并试用界面，然后再开始编码。本文档假定您熟悉 Blogger、网络编程概念和网络数据格式。

了解如何授权请求和标识您的应用

当您的应用请求不公开的数据时，该请求必须经过有权访问相应数据并且已经过身份验证的用户授权。

当您的应用请求公开的数据时，该请求不需要经过授权，但需要附带身份识别标记，如 API 密钥。

如需了解如何授权请求和使用 API 密钥，请参阅“使用 API”文档中的授权请求和标识您的应用。

Blogger API 背景信息

Blogger 概念

Blogger 基于以下五个基本概念构建：

博客：API 的根概念。博客包含帖子和页面。这是博客元信息（例如博客名称和说明）的容器。
帖子：博文是博客作者创建的可发布内容。此信息旨在及时反映作者当前希望向世界发布的内容。我们知道，随着时间的推移，博文内容会过时，相关性也会降低。
评论：评论是博客帖子作者以外的人对作者所写内容发表看法的地方。从积木到鲜花，应有尽有。
页面：页面用于展示静态内容，例如个人简介信息或联系用户的方式。这类信息通常是不会过时且不会经常更改的信息。
用户：用户是指与 Blogger 进行互动的人员，无论是作为作者、管理员还是仅仅作为读者。对于公开博客，读者可以是匿名身份，但对于非公开博客，读者必须通过 Blogger 进行身份验证。

Blogger API 数据模型

资源是指具有唯一标识符的单个数据实体。Blogger JSON API 基于五种类型的资源运行：

Blogs 资源：表示博客。
Posts 资源：表示一篇博文；每个 posts 资源都是 blogs 资源的子资源。
评论资源：表示对特定帖子的评论；每个评论资源都是帖子资源的子资源。
Pages 资源：表示静态网页；每个 pages 资源都是 blogs 资源的子资源。
Users 资源：表示非匿名用户。用于标识网页、帖子或评论的作者。

博客资源有两个子资源类型：网页和帖子。
帖子资源可能包含评论资源子项。 — 资源之间关系的概览

Blogger API 数据模型基于资源组（称为集合）：

博客合集: 博客集合包含用户有权访问的所有博客。<span="apicollection">您可以按用户列出博客，也可以按 ID 检索单个博客。</span="apicollection">
帖子合集: “帖子集合”包含特定博客资源中的所有帖子资源。
评论集合: 评论集合包含特定帖子资源中的所有评论资源。
网页集合: 网页集合包含特定博客资源中的所有网页资源。
用户集合: 用户集合包含 Blogger 上的所有用户资源，因此无法列出。用户可以通过 ID 或使用标识符 self 检索自己的 users 资源（但无法检索其他用户的）。

Blogger API 操作

您可以在 Blogger API 中对集合和资源调用多种不同的方法，如下表中所述。

操作	说明	REST HTTP 映射
list	列出集合中的所有资源。	集合 URI 的 `GET`。
get	获取特定资源。	针对资源 URI 的 `GET`。
getByUrl	通过网址查找并获取资源。	`GET`，并将网址作为参数传入。
getByPath	通过查找资源路径来获取资源。	`GET`，并将 Path 作为参数传入。
listByUser	列出用户拥有的资源。	`GET` 在用户拥有的集合上。
search	根据查询参数搜索资源。	搜索网址中的 `GET`，查询内容以参数形式传递。
insert	在集合中创建资源。	集合 URI 的 `POST`。
delete	删除资源。	针对资源 URI 的 `DELETE`。
patch	使用 Patch 语义更新资源。	针对资源 URI 的 `PATCH`。
update	更新资源。	针对资源 URI 的 `PUT`。

下表显示了每种资源类型支持的方法。对私密博客执行的所有 list 和 get 操作都需要进行身份验证。

资源类型	支持的方法
	list	get	getByUrl	getByPath	listByUser	搜索	insert	删除	patch	更新
博客	否	是	是	否	是	否	否	否	否	否
帖子	是	是	否	是	否	是	是	是	是	是
注释	是	是	否	否	否	否	否	否	否	否
页面	是	是	否	否	否	否	否	否	否	否
用户数	否	是	否	否	否	否	否	否	否	否

调用样式

调用 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 参考文档总结了 API 中支持的各项操作所用的 URI 和结果的完整说明。

示例

列出已通过身份验证的用户有权访问的博客：

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 数据，而无需服务器端代码。

以下示例在您将 YOUR-API-KEY 替换为自己的 API 密钥后，从 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。

Blogger API：使用入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。