开发者指南：JavaScript

Blogger Data API 允许客户端应用以 Google Data API Feed 的形式查看和更新 Blogger 内容。

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

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

目录

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

受众

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

有关 Blogger 数据 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 数据 API 访问公开 Feed 和不公开 Feed。 公开 Feed 不需要任何身份验证，但它们是只读的。如果您想修改博客，那么您的客户端需要先进行身份验证，然后才能请求不公开 Feed。

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

AuthSub 代理身份验证

需要向 Google 帐号对用户进行身份验证的 Web 应用会使用 AuthSub 代理身份验证。网站运营商和客户端代码无法访问 Blogger 用户的用户名和密码；客户端会获取特殊的 AuthSub 令牌，这些令牌使客户端能够代表特定用户执行操作。

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

  1. 客户端应用调用该客户端库提供的 google.accounts.user.login() 方法，并向其传递一个“范围”值，该值指示要使用的 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() 是您的函数。如果出现 init 错误，函数就会收到标准错误对象；您可以随意使用该对象执行任何操作。

在您通过调用 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() 的信息，请参阅将 AuthSub 与 JavaScript 客户端库配合使用文档。

返回页首