开发者指南概览

警告:本页面介绍的是 Google 的旧版 API,即 Google 数据 API;它仅与 Google 数据 API 目录中列出的许多 API 相关,其中许多 API 已替换为较新的 API。如需了解特定新 API,请参阅新 API 的文档。如需了解如何使用较新的 API 向请求授权,请参阅 Google 帐号身份验证和授权

Google 的使命是:整合全球信息,供大众使用,使人人受益。这包括使信息在除网络浏览器以外的情境中可访问,并可供 Google 以外的服务访问。

Google 数据协议为外部开发者提供了一种编写新应用的安全方式,让最终用户能够访问和更新许多 Google 产品所存储的数据。外部开发者可以直接使用 Google 数据协议,也可以使用客户端库提供的任何受支持编程语言。

观众

本系列文档适用于任何想要了解 Google 数据协议的人员。即使您只想编写使用特定语言的客户端库的代码,但如果您想了解客户端库的抽象层下面发生的情况,本文档组会很有帮助。

如果您正在寻找特定 API 的开发者指南,请访问 Google 数据协议 API 目录

如果要使用您喜爱的编程语言访问 API,请访问客户端库下载页面。

背景

许多 Google 产品(如 Google 日历和电子表格)都提供基于 Google 数据协议的 API。作为开发者,您可以使用这些 API 编写客户端应用,为最终用户提供访问和操控这些 Google 产品中存储的数据的新方式。

注意:在这些和其他相关文档中,提供 API 的 Google 产品有时被称为“服务”。

如果您编写直接使用 Google 数据协议的代码,它会使用 GETPOST 等 HTTP 请求访问该 API。通过这些请求,Google 产品存储的数据可通过数据 Feed 以无线方式来回传输。数据 Feed 只是包含数据的结构化列表。过去,主要 Feed 格式一直是 AtomPub XML,但现在 JSON 或 JavaScript 对象表示法也可以作为备用格式使用。

如果您不想编写直接发出 HTTP 请求的代码,则可以使用提供的客户端库集中提供的一种编程语言来编写您的客户端应用。执行此操作时,HTTP 请求的详细信息将由客户端库处理;您可以使用客户端库提供的特定语言的方法和类在更概念的级别编写代码。

请参阅特定产品的文档,详细了解您目前使用的 API 或 API 版本可用的特定语言。

协议版本

协议版本 2.0 与协议版本 1.0

第一版 Google 数据协议是在 Atom 发布协议最终确定之前开发的。第二版 Google 数据协议完全符合 AtomPub RFC 5023 标准。

Google 数据协议 2.0 版还支持:

  • HTTP ETag。一种 Web 标准,可帮助您的客户端应用更好地利用 HTTP 缓存。客户端库中支持协议 v2.0 的服务会自动处理 ETag。
  • 部分响应部分更新(实验性)。这些功能可让您发出传输较少数据的请求。通过只请求您真正需要的信息,或者发送仅包含您真正想要更改的数据的更新,您的客户端应用可以更加高效地使用网络、CPU 和内存资源。目前,只有部分产品支持部分响应和部分更新;如需了解特定 API 是否支持,请参阅特定产品的相关文档。

更新应用

如果您使用的 API 是基于最新版本的协议构建的,那么 Protocol v2.0 功能会包含在其文档中。一般而言,我们建议您将客户端应用升级到 API 可用的最新版本。

更新基于客户端库的客户端

如果您的客户端应用使用客户端库(例如 Java 客户端库或 .NET 客户端库),则其中可能包含支持协议 v2.0 功能的 API 版本。要确定这一点,请参阅您所使用的 Google 产品的 API 文档,确定同时满足以下两个条件:

  • 有一个支持 Google 数据协议 v2.0 功能的 API 版本。
  • 您使用的客户端库也支持该 API 版本。

如果客户端库支持,而您想更新现有应用,则只需下载并使用最新版本的客户端库即可。所有代码仍然有效,客户端库会在后台处理协议 v2.0 变更。

更新原始 HTTP 客户端

如果您直接使用 Google 数据协议编写客户端应用,则需要进行以下更改:

  • 非默认版本请求。。为您发送的每个 HTTP 请求添加一个 HTTP 版本标头 (GData-Version: X.0),其中 X 是支持 Google 数据协议 v2.0 功能的 API 版本。或者,在每个请求的网址中添加查询参数 (v=X.0),其中 X 再次是正确的 API 版本。如果您未指定更新版本,默认情况下,您的请求将发送至支持的最低 API 版本。
  • 乐观并发。如果您使用的是支持乐观并发的 API 版本,则可能需要更改更新并删除代码,才能使用 ETag。有关详情,请参阅 Google 数据协议参考文档中的 ETag 部分,并参阅您的客户端应用所用协议的“更新”和“删除”部分。
  • 自行或修改 URI如果客户自行跟踪 Feed 或条目的 URI 或修改 URI,请注意这些 URI 可能已更改。要获取新的 URI,请使用旧 URI 重新请求该项目,但将该请求标记为版本 X 请求 0,其中 X 是支持 Google 数据协议 v2.0 功能的 API 版本。服务器会返回条目的新表示法,包括新的 URI,您可以存储它来替代旧 URI。
  • 命名空间 URI如果您的客户端在本地存储 Google Data Protocol API 命名空间 URI 或对其进行硬编码,则您需要对其进行更新:
    • AtomPub 命名空间(前缀为 app)已从 http://purl.org/atom/app 更改为 http://www.w3.org/2007/app
    • OpenSearch 命名空间(前缀为 openSearch)已从“http://a9.com/-/spec/opensearchrss/1.0/”更改为“http://a9.com/-/spec/opensearch/1.1/”。