开发者指南：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 数据 API 访问公开和私有 Feed。公开 Feed 不需要任何身份验证，但会处于只读状态。如果您想修改博客，您的客户端需要先进行身份验证，然后才能请求不公开 Feed。

JavaScript 客户端库使用 AuthSub 身份验证系统。如需大致了解如何使用 Google Data 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 系统会将浏览器发送回网络客户端的网址，同时传递身份验证令牌。
  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 错误，您的函数会收到一个标准 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() 的相关信息），请参阅将“AuthSub”身份验证与 JavaScript 客户端库搭配使用文档。

返回页首