此页面由 Cloud Translation API 翻译。

Blogger JSON API：使用入门

重要提示：我们将于 2024 年 9 月 30 日停止支持 v2.0 JSON API。为了确保功能继续正常运行，请将依赖于 v2.0 JSON API 的应用更新为最新的 API 版本。如需获取最新版本，请使用左侧导航栏中的链接。

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

简介

本文档适用于想要编写可与 Blogger JSON API 交互的应用的开发者。

Blogger JSON API 扩展了 Blogger Data API 的 2.0 版。如果您想以 JSON 格式（而非 XML 格式）从 Blogger 检索数据，请使用 Blogger JSON API。如果您想以 XML 格式检索数据，请使用 Blogger Data API。

此版本的 Blogger JSON API 目前是只读的；不过，我们计划添加读写功能以及其他功能。欢迎随时在 Blogger 帮助论坛中申请其他功能。

前期准备

获取 Google 账号

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

熟悉 Blogger

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

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

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

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

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

Blogger JSON API 背景知识

Blogger 概念

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

博客：该 API 的根概念。博客包含博文和页面。这是博客元信息（例如博客名称和说明）的容器。
博文：博文是博客作者创建的可发布内容。此类信息应及时发布，反映作者目前希望向世界发布的内容。我们理解，随着时间的推移，博文内容会过时，相关性也会降低。
评论：博文作者以外的用户可以通过评论对作者所写的内容做出回应。从砖块到花束，应有尽有。
网页：网页是放置静态内容（例如个人简介信息或与用户联系的方式）的位置。这类信息通常是不会经常更改的永恒性信息。
用户：用户是指与 Blogger 互动的人，无论是作为作者、管理员还是仅作为读者。对于公开博客，读者可以是匿名的，但对于私享博客，读者必须由 Blogger 标识。

Blogger JSON API 数据模型

资源是指具有唯一标识符的单个数据实体。Blogger JSON API 可对以下五种类型的资源执行操作：

博客资源：表示博客。
Posts 资源：表示博文；每个 Posts 资源都是 Blogs 资源的子项。
“评论”资源：表示特定帖子的评论；每个“评论”资源都是“帖子”资源的子资源。
“Pages”资源：表示静态网页；每个“Pages”资源都是“Blogs”资源的子资源。
Users 资源：表示非匿名用户。此属性用于标识网页、帖子或评论的作者。

“Blogs”资源有两个子资源类型：“网页”和“帖子”。
帖子资源可以有评论资源子项。 — 资源关系概览

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

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

Blogger JSON API 操作

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

操作	说明	REST HTTP 映射
list	列出集合中的所有资源。	集合 URI 上的 `GET`。
get	获取特定资源。	资源 URI 上的 `GET`。

下表显示了每种资源类型支持的方法。对私人博客执行的所有列出和获取操作都需要身份验证。

资源类型	支持的方法
	list	get
博客	是	是
帖子	是	是
注释	是	是
页面	是	是
用户数	否	是

调用样式

调用 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 JSON API 中的 REST

受支持的 Blogger 操作直接映射到 REST HTTP 动词，如 Blogger JSON API 操作中所述。

Blogger JSON API URI 的具体格式如下：

https://www.googleapis.com/blogger/v2/users/userId
https://www.googleapis.com/blogger/v2/users/self
https://www.googleapis.com/blogger/v2/users/userId/blogs
https://www.googleapis.com/blogger/v2/users/self/blogs

https://www.googleapis.com/blogger/v2/blogs/blogId/posts
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v2/blogs/blogId/pages
https://www.googleapis.com/blogger/v2/blogs/blogId/pages/pageId

Blogger JSON API 参考文档总结了 API 中支持的每项操作所用的 URI 及其结果的完整说明。

下面是 Blogger JSON API 中此机制运作方式的几个示例。

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

GET https://www.googleapis.com/blogger/v2/users/self/blogs?key=YOUR-API-KEY

获取 code.blogger.com 博客（博客 ID 为 3213900）上的帖子：

GET https://www.googleapis.com/blogger/v2/blogs/3213900?key=YOUR-API-KEY

JavaScript 中的 REST

您可以使用 callback 查询参数和回调函数，通过 JavaScript 使用 REST 调用 Blogger JSON API。这样一来，您无需编写任何服务器端代码，即可编写用于显示 Blogger 数据的丰富应用。

以下示例会从 code.blogger.com 博客检索一篇博文（在您将 YOUR-API-KEY 替换为 API 密钥后）。

<html>
  <head>
    <title>Blogger JSON 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/v2/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

数据格式

JSON

JSON（JavaScript 对象表示法）是一种与语言无关的常见数据格式，可通过简单的文本来表示任意数据结构。如需了解详情，请参阅 json.org。