My favorites | 中文(简体) | Sign in

开发人员指南

通过 Google AJAX 供稿 API,您可以下载仅使用 JavaScript 的任意公共 Atom 或 RSS 供稿,因此您可以轻松地混搭供稿、您的内容及其他 API(例如 Google 地图 API)。对于 Flash 和其他非 Javascript 环境,该 API 将显示一个原始 RESTful 界面新增!,该界面会返回 JSON 编码结果。大多数语言和运行时都可轻松处理这些结果。

目录

读者

此文档适用于熟悉 JavaScript 编程和面向对象编程概念的用户。您可以在网络上找到许多 JavaScript 教程

简介

通过 Google AJAX 供稿 API,您可以下载仅使用 JavaScript 的任意公共 Atom 或 RSS 供稿,因此您可以轻松地混搭供稿、您的内容及其他 API(例如 Google 地图 API)。请参考以下程序作为一个简单示例。

JavaScript 和 XMLHttpRequest 使用 同源策略 (SOP)。使用该策略,脚本可以访问同一主机(其中提供 HTML 格式的包含页面)中的数据,但是不能访问其他主机的数据。这可以保护用户免受某些类型的脚本攻击,但同时也使许多开发人员无法编写基于 AJAX 的混搭程序。Google AJAX 供稿 API 针对网络上可用的特定类型的内容的限制提供了简单的解决方案:联合供稿。有关 Google AJAX 供稿 API 如何保障用户安全的更多详细信息,请参考以下安全注意事项

Google AJAX 供稿 API 的“Hello, World”

查看简单的实例是开始学习此 API 的最简单方法。以下实例可以下载 Digg RSS 供稿并向用户显示供稿条目标题:

<html>
  <head>
    <script type="text/javascript" src="http://www.google.com/jsapi?key=YOUR_KEY_HERE"></script>
    <script type="text/javascript">

    google.load("feeds", "1");

    function initialize() {
      var feed = new google.feeds.Feed("http://www.digg.com/rss/index.xml");
      feed.load(function(result) {
        if (!result.error) {
          var container = document.getElementById("feed");
          for (var i = 0; i < result.feed.entries.length; i++) {
            var entry = result.feed.entries[i];
            var div = document.createElement("div");
            div.appendChild(document.createTextNode(entry.title));
            container.appendChild(div);
          }
        }
      });
    }
    google.setOnLoadCallback(initialize);

    </script>
  </head>
  <body>
    <div id="feed"></div>
  </body>
</html>

您可以下载此示例来进行编辑并调试,但您必须使用自己的 Google API 密钥来替换文件中的密钥。

在您的网页上包含 Google AJAX 供稿 API

要在您的网页上包含 Google AJAX 供稿 API,您必须包含 Google AJAX API 脚本标签并调用 google.load("feeds", "1")

<script type="text/javascript" src="http://www.google.com/jsapi?key=YOUR_KEY_HERE"></script>
<script type="text/javascript">
  google.load("feeds", "1");
</script>

第一个脚本标签会载入 google.load 函数,它使您可以载入各个 Google API。google.load("feeds", "1") 会载入 1 版的供稿 API。目前 Google AJAX 供稿 API 为 1 版,但是将来可能会推出新版本。有关详细信息,请参考以下版本管理讨论

载入 API 需要两个步骤,因为 Google 将要移植到新的 AJAX API 载入模型,从而使得在您的网页上包含多个 Google API 更加轻松。订阅 Google AJAX API 博客以便在我们开始推出此新的 AJAX API 载入机制时,您可以得到通知。

JSON 和 XML 结果格式

Google AJAX 供稿 API 以 JSON 和 XML 两种格式返回供稿。默认情况下,API 以 JSON 格式返回供稿。

Google AJAX 供稿 API JSON 格式是原始供稿经简化的规范化版本。它可以将 titledescriptionsummary 等 Atom 和 RSS 属性映射为一组普通的 JSON 属性,因此您可以采用相同的方式访问 Atom 和 RSS 供稿。例如,JSON 结果格式可以将 RSS 属性 description 作为 JSON 属性 content 返回,就像 Atom 属性一样。同样地,RSS 元素 pubDate 将作为 JSON 属性 publishedDate 返回以使结果与 Atom 供稿一致。如果您只想访问标准 RSS 和 Atom 元素,则 JSON 结果格式将很有用,并且您无需担心供稿格式之间的差异。有关信息,请参见下面的 JSON 示例JSON 结果格式规范

如果您使用 setResultFormat 指定了 XML 结果格式,Google AJAX 供稿 API 会返回完整的供稿 XML(而不是 JSON 结果)。可以通过浏览器中内置的标准 XML DOM 功能访问 XML 文档。如果您更愿意使用 JSON 的 DOM 函数或者需要访问供稿中的扩展元素(例如 digg:diggCount),则 XML 结果格式将很有用。有关信息,请参见下面的 XML 示例XML 结果格式规范

还可以同时使用 JSON 属性和 XML 文档从规范化的属性中获益以及访问 XML 扩展元素。请参考以下组合的 XML/JSON 实例,该实例使用 JSON 属性访问供稿中的所有条目,而使用 XML DOM 获取供稿中的自定义 Digg digg:diggVotes 元素。

API 更新

google.load 的第二个参数是所用的 Google AJAX 供稿 API 的版本。目前 Google AJAX 供稿 API 为 1 版,但是将来可能会推出新版本。

如果在将来对该 API 进行了重大更新,我们将更改版本号并在 Google 代码AJAX API 讨论组上发布通知。更新后,我们会同时支持两个版本至少一个月,以便您可以移植代码。

Google AJAX 供稿 API 团队将使用最新的错误修正和性能改进来定期更新该 API。这些错误修正程序应当只会提高性能并修正错误,但是也可能会意外地使某些 API 客户端无法正常工作。请使用 AJAX API 讨论组报告此类问题。

实例

基本知识

此例可以下载单个供稿并向用户显示每个条目的标题。

var feed = new google.feeds.Feed("http://www.digg.com/rss/index.xml");
feed.load(function(result) {
  if (!result.error) {
    var container = document.getElementById("feed");
    for (var i = 0; i < result.feed.entries.length; i++) {
      var entry = result.feed.entries[i];
      var div = document.createElement("div");
      div.appendChild(document.createTextNode(entry.title));
      container.appendChild(div);
    }
  }
});

查看示例 (helloworld.html)

JSON 结果格式

此例与上述简单实例类似,但是它将显示由 Google AJAX 供稿 API 提供的大多数规范 JSON 属性。有关信息,请参考 JSON 结果格式规范

var feed = new google.feeds.Feed("http://www.digg.com/rss/index.xml");
feed.load(function(result) {
  if (!result.error) {
    var container = document.getElementById("feed");
    for (var i = 0; i < result.feed.entries.length; i++) {
      var entry = result.feed.entries[i];
      var attributes = ["title", "link", "publishedDate", "contentSnippet"];
      for (var j = 0; j < attributes.length; j++) {
        var div = document.createElement("div");
        div.appendChild(document.createTextNode(entry[attributes[j]]));
        container.appendChild(div);
      }
    }
  }
});

查看示例 (json.html)

XML 结果格式

以下实例显示了如何通过 XML DOM(而不是使用由 Google AJAX 供稿 API 返回的 JSON 结果)访问 RSS 和 Atom 供稿。访问两种供稿的不同之处在于,RSS 实例使用 RSS 元素(例如 item),而 Atom 实例使用 Atom 元素(例如 entry)。

第一个实例通过 XML DOM 直接访问 RSS 供稿。在此实例中,我们利用 Google AJAX 供稿 API 中包含的 getElementsByTagNameNS 访问 Digg 供稿中的 diggCount 扩展元素,从而可以在输出中的标题旁边显示投票数。

var feed = new google.feeds.Feed("http://www.digg.com/rss/index.xml");
feed.setResultFormat(google.feeds.Feed.XML_FORMAT);
feed.load(function(result) {
  var container = document.getElementById("feed");
  if (!result.error) {
    var items = result.xmlDocument.getElementsByTagName("item");
    for (var i = 0; i < items.length; i++) {
      var titleElement = items[i].getElementsByTagName("title")[0];
      var title = titleElement.firstChild.nodeValue;

      var votesElement = google.feeds.getElementsByTagNameNS(items[i], "http://digg.com/docs/diggrss/", "diggCount")[0];
      var votes = votesElement.firstChild.nodeValue;

      var div = document.createElement("div");
      div.appendChild(document.createTextNode(title + " (" + votes + " votes)"));
      container.appendChild(div);
    }
  }
});

查看示例 (xml.html)

第二个实例通过 XML DOM 直接访问 Atom 供稿。在本例中,我们再次利用 Google AJAX 供稿 API 中包含的 getElementsByTagNameNS 访问 Google Base 供稿中的元素。

var feed = new google.feeds.Feed("http://www.google.com/base/feeds/snippets");
feed.setResultFormat(google.feeds.Feed.XML_FORMAT);
feed.load(function(result) {
  var container = document.getElementById("feed");
  if (!result.error) {
    var entries = google.feeds.getElementsByTagNameNS(result.xmlDocument, "http://www.w3.org/2005/Atom", "entry");
    for (var i = 0; i < entries.length; i++) {
      var titleElement = google.feeds.getElementsByTagNameNS(entries[i], "http://www.w3.org/2005/Atom", "title")[0];
      var title = titleElement.firstChild.nodeValue;

      var priceElement = google.feeds.getElementsByTagNameNS(entries[i], "http://base.google.com/ns/1.0", "price")[0];
      var price = priceElement.firstChild.nodeValue;

      var div = document.createElement("div");
      div.appendChild(document.createTextNode(title + " (" + price + ")"));
      container.appendChild(div);
    }
  }
});

查看示例 (atomxml.html)

组合的 JSON/XML 结果格式

本例重新进行了上述 XML 实例的输出,但是结合了 JSON 结果格式的使用和对 XML DOM 的访问。我们使用由 Google AJAX 供稿 API 返回的 JSON 数据结构反复访问供稿中的所有元素,并且使用每个 JSON 结果中特殊的 xmlNode 指针访问与该条目对应的 XML DOM 中的元素。我们使用该 XML 元素和 getElementsByTagNameNS 访问 diggCount 扩展元素,从而使我们可以访问该 Digg 文章的投票数。

var feed = new google.feeds.Feed("http://www.digg.com/rss/index.xml");
feed.setResultFormat(google.feeds.Feed.MIXED_FORMAT);
feed.load(function(result) {
  if (!result.error) {
    var container = document.getElementById("feed");
    for (var i = 0; i < result.feed.entries.length; i++) {
      var entry = result.feed.entries[i];
      var votesElement = google.feeds.getElementsByTagNameNS(entry.xmlNode, "http://digg.com/docs/diggrss/", "diggCount")[0];
      var votes = votesElement.firstChild.nodeValue;

      var div = document.createElement("div");
      div.appendChild(document.createTextNode(entry.title + " (" + votes + "votes)"));
      container.appendChild(div);
    }
  }
});

查看示例 (jsonxml.html)

FeedControl新增!

本例使用较高级别的 google.feeds.FeedControl 类显示一个供稿集合。该类与 AJAX 搜索 API 的搜索控件层 GSearchControl 类似。本例创建了一个 FeedControl 类,向该类添加了两个供稿,然后通知该供稿控件进行绘制。

<html>
  <head>
    <script  type="text/javascript" src="http://www.google.com/jsapi?key="YOUR-KEY"></script>
    <script type="text/javascript">

      google.load("feeds", "1");

      function initialize() {
        var feedControl = new google.feeds.FeedControl();
        feedControl.addFeed("http://www.digg.com/rss/index.xml", "Digg");
        feedControl.addFeed("http://feeds.feedburner.com/Techcrunch", "TechCrunch");
        feedControl.draw(document.getElementById("feedControl"));
      }
      google.setOnLoadCallback(initialize);

    </script>
  </head>

  <body>
    <div id="feedControl">Loading</div>
  </body>
</html>

查看示例 (feedcontrol.html)

发现供稿新增!

以下两个示例分别使用了全局方法 google.feeds.findFeedsgoogle.feeds.lookupFeed,根据搜索字词来发 供 以及查找与标准网页相关联的供稿。

第一个示例使用 google.feeds.findFeeds 根据搜索字词动态填充 FeedControl

<html>
  <head>
    <script  type="text/javascript" src="http://www.google.com/jsapi?key="YOUR-KEY"></script>
    <script type="text/javascript">

      google.load("feeds", "1");

      var defaultQuery = 'Official Google Blogs';

      function findFeeds(query) {
        google.feeds.findFeeds(query, feedSearchDone);
      }

      function feedSearchDone(result) {
        var el = document.getElementById('feedControl');

        if (result.error || result.entries.length <= 0) {
          el.innerHTML = 'No Results Found';
          return;
        }

        // Create a feed control
        var feedControl = new google.feeds.FeedControl();

        // Grab top 4..
        for (var i = 0; i < 4; i++) {
          feedControl.addFeed(result.entries[i].url, result.entries[i].title);
        }

        feedControl.setLinkTarget(google.feeds.LINK_TARGET_BLANK);
        feedControl.setNumEntries(2);
        feedControl.draw(el);
      }

      google.setOnLoadCallback(function() {findFeeds(defaultQuery)});

    </script>
  </head>

  <body>
    <div id="feedControl">Loading</div>
  </body>
</html>

查看示例 (findfeeds.html)

第二个示例使用 google.feeds.lookupFeed 为特定用户获取与公共 Flickr 网页相关联的供稿,然后再动态填充幻灯片。

<html>
  <head>
    <script  type="text/javascript" src="http://www.google.com/jsapi?key="YOUR-KEY"></script>
    <script type="text/javascript">

      google.load("feeds", "1");

      var defaultUser = 'dlc0421';

      function newSlideShow(user) {
        showStatus('Resolving feed for ' + user);
        var url = 'http://www.flickr.com/photos/' + user;
        google.feeds.lookupFeed(url, lookupDone);
      }

      function lookupDone(result) {
        if (result.error || result.url == null) {
        showStatus('Could not locate feed for user');
        return;
        }

        showStatus('Found Photo Feed');
        // We need to switch over from Atom to RSS to get Yahoo Media for slideshow..
        var url = result.url.replace('format=atom', 'format=rss_200');
        showSlideShow(url);
      }

      function showSlideShow(url) {
        var options = {
          displayTime: 2500,
          transistionTime: 800,
          scaleImages: true,
          thumbnailTag: 'content',
          linkTarget : google.feeds.LINK_TARGET_BLANK
        };
        new GFslideShow(url, "slideshow", options);
      }

      google.setOnLoadCallback(function() {newSlideShow(defaultUser)});

    </script>
  </head>

  <body>
    <div id="feedControl">Loading</div>
  </body>
</html>

查看示例 (lookup.html)

API 详细信息

支持的供稿格式

Google AJAX 供稿 API 支持以下供稿格式:

发现供稿新增!

Google AJAX 供稿 API 现在可支持其他全局方法 google.feeds.findFeedsgoogle.feeds.lookupFeed,这些全局方法可用来搜索相关的供稿以及查找与基于网址的 HTML 相关联的供稿。

如何抓取供稿

Google AJAX 供稿 API 使用 Feedfetcher 抓取供稿,其还可用于 Google 阅读器Google 个性化主页。有关 Feedfetcher 的详细信息,请参考 Google 网站管理员帮助中心

供稿抓取频率

由于 Google AJAX 供稿 API 使用 Feedfetcher,因此来自 Google AJAX 供稿 API 的供稿数据可能无法始终保持最新状态。Google 供稿抓取器(“Feedfetcher”)不到一小时就从大多数网站中检索一次供稿。某些经常更新的网站刷新次数可能更加频繁。

跨浏览器的 XML 访问

Microsoft Internet Explorer 不支持 DOM Level 2,这意味着它不支持名称空间感知的 DOM 函数(如 getElementsByTagNameNS)。Google AJAX 供稿 API 包含对 getElementsByTagNameNS 的跨浏览器应用,因为这对于使用供稿的网站而言是一项常见的要求。目前,Google AJAX 供稿 API 不包含对其他任何 DOM Level 2 方法的应用。

Flash 和其他非 Javascript 环境新增!

对于 Flash 开发人员以及需要从其他非 Javascript 环境中访问 Google AJAX 供稿 API 的开发人员,该 API 提供了一个简单的 RESTful 界面。在所有情况下,支持的方法均为 GET,响应格式为 JSON 已编码结果(具有嵌入的状态代码)。使用此界面的应用程序必须遵守所有现有的使用条款。需要特别注意的是要在您的请求中正确标识自己。应用程序必须始终在其请求中包含一个有效且准确的 http 参考标头。此外,我们要求(但不命令)每个请求包含一个有效的 API 密钥。通过提供密钥,您的应用程序可以向我们提供辅助的识别机制,这在我们需要联系您以纠正问题时会很有用。

熟悉此界面最简单的方法便是亲自实践。请使用命令行工具 curlwget 执行以下命令:

curl -e http://www.my-ajax-site.com \
        'http://ajax.googleapis.com/ajax/services/feed/load?q=http%3A%2F%2Fwww.digg.com%2Frss%2Findex.xml&v=1.0'

此命令将为 /ajax/services/feed/loadDigg.com 供稿 () 执行一次供稿载入 (q=http%3A%2F%2Fwww.digg.com%2Frss%2Findex.xml)。响应具有 Content-Typetext/javascript; charset=utf-8。从以下响应中您可看到,responseDataJSON 结果格式文档中所描述的属性是相同的。有关如何通过 REST API 来实现前面部分中所描述的各种访问方法的详细信息,请参见到基本网址的表格映射方法

{"responseData": {
 "feed": {
  "title": "Digg",
  "link": "http://digg.com/",
  "author": "",
  "description": "Digg",
  "type": "rss20",
  "entries": [
   {
    "title": "The Pirate Bay Moves Servers to Egypt Due to Copyright Laws",
    "link": "http://digg.com/tech_news/The_Pirate_Bay_Moves_Servers_to_Egypt_Due_to_Copyright_Laws",
    "author": "",
    "publishedDate": "Mon, 31 Mar 2008 23:13:33 -0700",
    "contentSnippet": "Due to the new copyright legislation that are going ...",
    "content": "Due to the new copyright legislation that are going to take...",
    "categories": [
    ]
   },
   {
    "title": "Millions Dead/Dying in Recent Mass-Rick-Rolling by YouTube.",
    "link": "http://digg.com/comedy/Millions_Dead_Dying_in_Recent_Mass_Rick_Rolling_by_YouTube",
    "author": "",
    "publishedDate": "Mon, 31 Mar 2008 22:53:30 -0700",
    "contentSnippet": "Click on any \u0022Featured Videos\u0022. When will the insanity stop?",
    "content": "Click on any \u0022Featured Videos\u0022. When will the insanity stop?",
    "categories": [
    ]
   },
   ...
  ]
 }
}
, "responseDetails": null, "responseStatus": 200}

除此响应格式以外,该协议还支持标准的 JSON-P 样式的回调,可通过指定 callback 参数来触发这类回调。此参数存在时,会将 JSON 对象作为参数传递到指定的回调中。

curl -e http://www.my-ajax-site.com \
        'http://ajax.googleapis.com/ajax/services/feed/load?q=http%3A%2F%2Fwww.digg.com%2Frss%2Findex.xml&v=1.0&callback=foo'

此命令执行与先前的载入相同的供稿载入,但已更改为传递 callback。正确使用此参数后,将会在响应中返回 Javascript 调用(而不是返回 JSON 对象),JSON 对象会通过 results 参数传递。

foo({"responseData": {
 "feed": {
  "title": "Digg",
  "link": "http://digg.com/",
  "author": "",
  "description": "Digg",
  "type": "rss20",
  "entries": [
   {
    "title": "The Pirate Bay Moves Servers to Egypt Due to Copyright Laws",
    "link": "http://digg.com/tech_news/The_Pirate_Bay_Moves_Servers_to_Egypt_Due_to_Copyright_Laws",
    "author": "",
    "publishedDate": "Mon, 31 Mar 2008 23:13:33 -0700",
    "contentSnippet": "Due to the new copyright legislation that are going ...",
    "content": "Due to the new copyright legislation that are going to take...",
    "categories": [
    ]
   },
   {
    "title": "Millions Dead/Dying in Recent Mass-Rick-Rolling by YouTube.",
    "link": "http://digg.com/comedy/Millions_Dead_Dying_in_Recent_Mass_Rick_Rolling_by_YouTube",
    "author": "",
    "publishedDate": "Mon, 31 Mar 2008 22:53:30 -0700",
    "contentSnippet": "Click on any \u0022Featured Videos\u0022. When will the insanity stop?",
    "content": "Click on any \u0022Featured Videos\u0022. When will the insanity stop?",
    "categories": [
    ]
   },
   ...
  ]
 }
}
, "responseDetails": null, "responseStatus": 200})

最后,该协议还支持 callbackcontext 参数。指定了这些网址参数后,响应将作为直接 Javascript 调用与 callback(context, feed, status, details, unused) 的签名一起进行编码。请注意以下命令和响应中的细微差别。

curl -e http://www.my-ajax-site.com \
 'http://ajax.googleapis.com/ajax/services/feed/load?q=http%3A%2F%2Fwww.digg.com%2Frss%2Findex.xml&v=1.0&callback=foo&context=bar'

此命令执行供稿载入并且与先前的载入相同,但是已更改为传递 callbackcontext。正确使用这些参数时,将在响应中返回 Javascript 调用(而不是 JSON 对象),并且通过 feed 参数传递 JSON 对象。

foo('bar', {
 "feed": {
  "title": "Digg",
  "link": "http://digg.com/",
  "author": "",
  "description": "Digg",
  "type": "rss20",
  "entries": [
   {
    "title": "The Pirate Bay Moves Servers to Egypt Due to Copyright Laws",
    "link": "http://digg.com/tech_news/The_Pirate_Bay_Moves_Servers_to_Egypt_Due_to_Copyright_Laws",
    "author": "",
    "publishedDate": "Mon, 31 Mar 2008 23:13:33 -0700",
    "contentSnippet": "Due to the new copyright legislation that are going ...",
    "content": "Due to the new copyright legislation that are going to take...",
    "categories": [
    ]
   },
   {
    "title": "Millions Dead/Dying in Recent Mass-Rick-Rolling by YouTube.",
    "link": "http://digg.com/comedy/Millions_Dead_Dying_in_Recent_Mass_Rick_Rolling_by_YouTube",
    "author": "",
    "publishedDate": "Mon, 31 Mar 2008 22:53:30 -0700",
    "contentSnippet": "Click on any \u0022Featured Videos\u0022. When will the insanity stop?",
    "content": "Click on any \u0022Featured Videos\u0022. When will the insanity stop?",
    "categories": [
    ]
   },
   ...
  ]
 }
}
, 200, null)

代码段新增!

Google AJAX 搜索 API 文档包含一些代码段,演示了如何从 Flash、Java 和 Php 对服务进行访问。代码段的具体语言部分在所有 Google AJAX API 中都是统一的,因此,您无需查看所有这些代码段,请访问此链接查看相关信息。

有关此界面的完整文档,请参考类参考手册

安全注意事项

JavaScript 使用同源策略 (SOP) 防止恶意脚本访问私有用户数据。有关此策略的含义和其他 JavaScript 安全问题的深入讨论,请参考 GWT 应用程序的安全性文章。

Google AJAX 供稿 API 不会向所请求供稿的主机(例如 digg.com)发送任何私有信息。Google 的抓取器 Feedfetcher 可以匿名下载供稿,对于 Google AJAX 供稿 API 提出的所有请求,Google 服务器可以用作该供稿的缓存。Google AJAX 供稿 API 仅提供对公共可访问供稿的访问。

疑难解答

如果您在使用代码时遇到问题:

  • 请确保您的 API 密钥有效。
  • 查找错别字。请注意,JavaScript 语言区分大小写。
  • 使用 JavaScript 调试器。在 Firefox 中,您可以使用 JavaScript 控制台或 FireBug 扩展。在 IE 中,您可以使用 Microsoft 脚本调试器
  • 搜索 AJAX API 讨论组。如果找不到可以解答您问题的帖子,请将您的问题连同演示该问题的网页链接一起发布到该讨论组。