开发者指南：JavaScript

借助 Blogger Data API，客户端应用可以以 Google Data API Feed 的形式查看和更新 Blogger 内容。

您的客户端应用可以使用 Blogger Data API 创建新的博文、修改或删除现有博文，以及查询符合特定条件的博文。

除了介绍 Blogger Data API 功能的一些背景信息外，本文档还提供了使用 JavaScript 客户端库进行基本 Data API 交互的示例。如果您有兴趣详细了解该库使用的底层协议，请参阅本开发者指南的“协议”部分。

目录

  1. 观众
  2. 使用条款
  3. 支持的环境简介
  4. 使用入门
    1. 创建 Blogger 账号
    2. 获取库
  5. 对 Blogger 服务进行身份验证
    1. AuthSub 代理身份验证

受众群体

本文档适用于想要编写可与 Blogger 交互的 JavaScript 客户端应用的程序员。该部分提供了一系列使用 JavaScript 客户端库进行基本 Data API 交互的示例。

如需了解 Blogger Data API 参考信息，请参阅协议参考指南。本文档假定您了解 Google Data API 协议背后的一般概念，以及 JavaScript 客户端库使用的模型和控制流。此外还假定您知道如何使用 JavaScript 编程。

如需有关客户端库提供的类和方法的参考信息，请参阅 JavaScript 客户端库 API 参考文档。

本文档应按顺序阅读；每个示例都基于之前的示例构建。

使用条款

您同意在使用 JavaScript 客户端库时遵守 《Google JavaScript 客户端库使用条款》。

支持的环境简介

目前，我们仅支持在浏览器的网页中运行的 JavaScript 客户端应用。目前支持的浏览器包括 Firefox 1.5 及更高版本，以及 Internet Explorer 6.0 及更高版本。

JavaScript 客户端库会处理与服务器的所有通信。如果您是经验丰富的 JS 开发者，可能会想：“但同源政策怎么办？”借助 JavaScript 客户端库，您的客户端可以从任何网域发送 Google Data API 请求，同时仍遵守浏览器安全模型。

使用入门

在编写 JavaScript 客户端应用之前，您需要进行一些设置来获取该库。

创建 Blogger 账号

您可能需要注册一个 Blogger 账号以进行测试。Blogger 使用 Google 账号，因此如果您已经拥有 Google 账号，则无需再做任何准备。

获取库

客户端必须先从服务器请求客户端库代码，然后才能使用客户端库。

首先，在 HTML 文档的 <head> 部分使用 <script> 标记提取 Google AJAX API 加载器：

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

如需在提取加载器后获取 Google Data API 客户端库，请在 JavaScript 设置代码中使用以下代码行，该代码行必须从 HTML 文档的 <head> 部分（或从在 HTML 文档的 <head> 部分使用 <script> 标记包含的 JavaScript 文件）调用：

google.load("gdata", "1.x");

google.load() 的第二个参数是 JavaScript 客户端库的请求版本号。我们的版本编号方案以 Google Maps API 所用的方案为蓝本。以下是可能的版本号及其含义：

"1"
主要版本 1 的倒数第二个修订版。
"1.x"
主要版本 1 的最新修订版。
"1.s"
主要版本 1 的最新稳定修订版。我们会根据从开发者那里收到的反馈，偶尔将某个版本的客户端库声明为“稳定”。但是，该版本可能并不具有最新的功能。
"1.0"、"1.1”等
库的特定版本，具有指定的主要版本号和次要版本号。

调用 google.load() 后，您必须告知加载器等待网页加载完成，然后再调用您的代码：

google.setOnLoadCallback(getMyBlogFeed);

其中，getMyBlogFeed() 是本文档后面部分将要定义的函数。请使用此方法，而不是将 onload 处理程序附加到 <body> 元素。

向 Blogger 服务进行身份验证

您可以使用 Blogger Data API 访问公开和私密 Feed。公开 Feed 不需要任何身份验证，但只能读取。如果您想修改博客，则客户端需要先进行身份验证，然后才能请求私密 Feed。

JavaScript 客户端库使用 AuthSub 身份验证系统。如需详细了解如何使用 Google Data API 进行常规身份验证，请参阅身份验证文档。

AuthSub 代理身份验证

需要对用户进行 Google 账号身份验证的 Web 应用会使用 AuthSub 代理身份验证。网站运营商和客户端代码无权访问 Blogger 用户的用户名和密码；而是，客户端会获取特殊的 AuthSub 令牌，以便客户端代表特定用户执行操作。

下面简要介绍了基于 Web 的 JavaScript 客户端在身份验证过程中会发生的情况：

  1. 客户端应用调用客户端库提供的 google.accounts.user.login() 方法，并向其传递一个“scope”（范围）值，用于指明要使用的 Google 服务。对于 Blogger，范围为 "http://www.blogger.com/feeds/"。
  2. 客户端库会将浏览器发送到 Google 的“访问权限请求”页面，用户可以在该页面上输入凭据以登录服务。
  3. 如果用户成功登录，AuthSub 系统会将浏览器发送回 Web 客户端的网址，并传递身份验证令牌。
  4. JavaScript 客户端库会将令牌存储在 Cookie 中，并将控制权返回给调用 google.accounts.user.login() 的客户端应用函数。
  5. 当客户端应用随后调用与 Blogger 交互的客户端库方法时，客户端库会自动将令牌附加到所有请求。

注意：为了让 JavaScript 客户端库在网络浏览器中发出经过身份验证的 Blogger 请求，您的网页必须包含与您的网页托管在同一网域中的图片。它可以是任何图片，甚至是单像素透明图片，但网页上必须有图片。如果您不希望图片显示在页面上，可以使用 <img> 标记的 style 属性将图片放置在渲染区域之外。例如 style="position:absolute; top: -1000px;"

下面是用于处理登录的客户端应用代码。我们稍后会从其他代码调用 setupMyService() 函数。

function logMeIn() {
  scope = "http://www.blogger.com/feeds/";
  var token = google.accounts.user.login(scope);
}

function setupMyService() {
  var myService =
    new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
  logMeIn();
  return myService;
}

提示：我们强烈建议您提供登录按钮或其他用户输入机制，以提示用户手动开始登录流程。相反，如果您在加载后立即调用 google.accounts.user.login()，而不等待用户互动，那么用户到达您的网页后首先看到的是 Google 登录页面。如果用户决定不登录，Google 不会将其重定向回您的网页；因此，从用户的角度来看，他们尝试访问您的网页，但被转到了其他位置，而没有被重定向回来。这种情况可能会让用户感到困惑和沮丧。在本文档中的示例代码中，我们将在加载后立即调用 google.accounts.user.login()，以使示例保持简单，但我们不建议在实际客户端应用中采用这种方法。

请注意，您无需对名为 token 的变量执行任何操作；客户端库会跟踪令牌，因此您无需执行任何操作。

注意：创建新的 BloggerService 对象时，客户端库会调用名为 google.gdata.client.init() 的方法，该方法会检查客户端所运行的浏览器是否受支持。如果出现错误，客户端库会向用户显示错误消息。如果您想自行处理此类错误，则可以在创建服务之前明确调用 google.gdata.client.init(handleInitError)，其中 handleInitError() 是您的函数。如果发生初始化错误，您的函数会收到标准的 Error 对象；您可以对该对象执行任何操作。

在您通过调用 google.accounts.user.logout() 撤消令牌之前，令牌将保持有效：

function logMeOut() {
  google.accounts.user.logout();
}

如果您未调用 logout()，则存储令牌的 Cookie 的有效期为两年，除非用户将其删除。该 Cookie 会跨浏览器会话保留，因此用户可以关闭浏览器，然后重新打开并返回您的客户端，并且仍会处于登录状态。

不过，在某些异常情况下，令牌可能会在会话期间失效。如果 Blogger 拒绝令牌，您的客户端应通过调用 logout() 移除包含当前令牌的 Cookie，然后再次调用 login() 来获取新的有效令牌，以处理错误情况。

还有另外两种 AuthSub 方法，在各种情境中都可能对您有用：

  • google.accounts.user.checkLogin(scope) 可告知您浏览器当前是否拥有给定范围的身份验证令牌。
  • google.accounts.user.getInfo() 提供有关当前令牌的详细信息，以供调试使用。

如需详细了解如何使用 JavaScript 与 AuthSub 交互（包括有关令牌管理以及 checkLogin() 和 getInfo() 的信息），请参阅使用 JavaScript 客户端库进行“AuthSub”身份验证一文。

返回页首