Blogger JSON API：使用入门

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

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

目录

  1. 简介
  2. 准备工作
    1. 获取 Google 账号
    2. 熟悉 Blogger
    3. 了解如何授权请求并识别您的应用
  3. Blogger JSON API 背景
    1. Blogger 概念
    2. Blogger JSON API 数据模型
    3. Blogger JSON API 操作
  4. 调用样式
    1. REST
  5. 数据格式
    1. JSON

简介

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

Blogger JSON API 扩展了 Blogger Data API 2.0 版。如果你想从 Blogger 中检索 JSON 格式的数据，而不是 XML 格式，那么可以使用 Blogger JSON API。如果您希望检索 XML 格式的数据，请使用 Blogger 数据 API。

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

前期准备

获取 Google 账号

确保您已设置 Google 帐号。我们建议您使用一个单独的 Google 帐号进行开发和测试，以防止数据意外丢失。如果您已经拥有测试帐号，说明一切准备就绪；您可以访问 Blogger 界面，设置、修改或查看您的测试数据。

熟悉 Blogger

如果您不熟悉 Blogger 的概念，请在开始编码之前阅读本文档并练习使用界面。本文档假定您熟悉 Blogger、网络编程概念和网络数据格式。

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

当您的应用请求私密数据时，该请求必须由有权访问相应数据且经过身份验证的用户授权。

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

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

Blogger JSON API 背景

Blogger 概念

Blogger 的构建基于五个基本概念：

  • 博客：API 的根概念。博客包含博文和页面。这是博客元信息（如“博客名称和说明”）的容器。
  • 博文：博文是博客作者创建的可发布项。这些信息应及时反映作者想要向全世界发布的内容。众所周知，随着时间的推移，博文的内容会变得越来越陈旧，并且变得不那么相关。
  • 评论：评论是博文作者以外的用户对作者所写内容作出回应的位置。从砖块到花束，应有尽有。
  • 网页：网页用于存储静态内容，例如传记信息或与用户联系的方式。这些信息通常具有时效性，不会经常更改。
  • 用户：用户是指与 Blogger 互动的人，可以是作者、管理员，也可以是读者。公开博客的读者可能是匿名的，但私密博客的读者必须以 Blogger 的身份加以标识。

Blogger JSON API 数据模型

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

  • 博客资源：代表博客。
  • Posts 资源：表示帖子；每个帖子资源都是 Blogs 资源的子级。
  • 评论资源：表示对特定帖子的评论；每个评论资源都是帖子资源的子级。
  • 网页资源：表示静态网页；每个网页资源都是 Blogs 资源的子级。
  • Users 资源：表示非匿名用户。用于标识网页、帖子或评论的作者。
Blogs 资源有两个子资源类型，即页面和帖子。帖子资源可能包含评论资源子级。
资源之间的关系概览

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

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

Blogger JSON API 操作

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

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

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

资源类型
支持的方法
列表 获取
博客 是 是
帖子 是 是
注释 是 是
页面 是 是
用户数 否 是

调用样式

调用 API 的方法有以下几种：

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

下面几个示例展示了它在 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

您可以通过 JavaScript 中的 REST（借助 callback 查询参数和回调函数）调用 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。