常见问题解答

概览

1. 什么是 Google Data API？
2. 我要提出功能请求或报告 bug。我应该在哪里发布？
3. 我应该在哪里就特定 API 提出问题？
4. 什么是 JSON？
5. 我必须使用 XML 吗？是否有其他数据格式可供选择？
6. 为什么要使用 REST？
7. 您有没有关于常见问题的提示或简短的示例代码？
8. Gmail 是否提供 Data API？

身份验证

9. 每个 Data API 在 ClientLogin 中的服务名称是什么？
10. 当用户从应用中退出账号时，是否需要通知 API 服务器？
11. ClientLogin 身份验证令牌是否具有过期日期？
12. 我对 Google 账号有一般性问题。Where should I go?
13. 如何向 API 进行身份验证？
14. 我应该为 AuthSub/OAuth 1 范围参数使用什么值？
15. AuthSub 令牌有不同的类型吗？令牌会过期吗？
16. ClientLogin 与 AuthSub/OAuth 1 之间的主要区别是什么？
17. 我可以在第三方 Web 应用中使用 ClientLogin 身份验证吗？
18. 什么是人机识别系统？
19. 如何生成人机识别系统验证？
20. 我应该在 Web 应用中使用 ClientLogin 吗？
21. 使用 AuthSub/OAuth 1 时，如何获取用户的用户名？
22. 如何将 OAuth 1 与 Google Data API 客户端库搭配使用？
23. 如何将 AuthSub 与 Google Data API 客户端库搭配使用？
24. 如何将 ClientLogin 与 Google Data API 客户端库搭配使用？

客户端库

25. Google 支持哪些编程语言的客户端库？
26. 如何报告某个 Google Data 客户端库的 bug 或提出功能请求？
27. 如何在客户端库中启用调试选项？
28. 在哪里可以找到客户端库类的参考文档？

问题排查

29. 有哪些实用的 HTTP 调试工具？
30. 如何在 Java 客户端库中获取 HTTP 日志记录信息？
31. 如何在 .NET 客户端库中获取 HTTP 日志记录信息？
32. 如何从 Google 数据 Feed 中启用 gzip 编码？
33. 使用 PHP 客户端时，为什么会看到“无法连接到 sslv2”错误？
34. 如何获取描述 Feed 的 Atom 服务文档？

---

概览

什么是 Google Data API？

Google Data API 是一种基于 Google Data 协议的 API。Google Data 协议基于 Atom 1.0 和 RSS 2.0 联合格式，以及 Atom 发布协议 (APP)。

Google Data 协议通过使用标准中内置的扩展机制，以各种方式扩展了这些标准。Feed 符合 Atom 或 RSS 联合格式。发布模型符合 Atom 发布协议。

该协议还提供了一个用于 Feed、查询和结果的通用模型。 您可以使用它向任何 Data API 发送查询和更新。

我要提出功能请求或报告 bug。我应该在何处发布？

请查看我们的问题跟踪器。 找到您的功能请求，为其加注星标以表示支持，并接收有关其状态的最新动态。

我应该在哪里就特定 API 提出问题？

如果您的问题未在此处列出，或者您想进一步了解相关信息，可以加入针对每种 Google Data API 的讨论组：

• G Suite（请参阅 G Suite 系列中的各个 API）
• 基础
• Blogger
• 日历
• 代码搜索
• 通讯录
• Google 协作平台
• 电子表格
• 文档 列表
• 联合登录 / OpenID
• 财务
• 健康
• Picasa 线上相册
• 网站站长工具
• YouTube

什么是 JSON？

JSON 是指 JavaScript 对象表示法。

JSON 是一种轻量级数据交换格式，其简单性使其在 Web 开发者中得到广泛使用。它易于读写；您可以使用任何编程语言对其进行解析，并且其结构直接映射到大多数编程语言中使用的数据结构。

详细了解将 JSON 与 Google Data API 搭配使用。

我是否必须使用 XML？是否有其他数据格式可供选择？

Google Data API 的默认数据格式为 XML，以 Atom Feed 的形式呈现。不过，在请求 Feed 时，您可以使用 alt 查询参数指定其他格式。

• alt=rss
  响应数据以 RSS Feed 的格式返回。
• alt=json 或 alt=json-in-script
  返回 Atom Feed 的 XML 结构的 JSON 表示形式。JSON 的另一个好处是，它更易于在 JavaScript 客户端代码中“解析”。目前，使用 JSON 仅作为只读选项提供。不过，将 JavaScript 客户端库与 Blogger、Contacts 或 Calendar 服务搭配使用时，既可以读取数据，也可以写入数据。

  详细了解如何请求和使用 JSON Feed。

• alt=atom-in-script
  与 alt=json-in-script 类似，但结果以 Atom XML 字符串（而非 JSON）的形式返回。
• alt=rss-in-script
  与 alt=atom-in-script 类似，但结果以 RSS XML 字符串的形式返回，而不是 Atom。

如需详细了解替代格式，请参阅 Google 数据参考指南。

您为何使用 REST？

REST 简单、轻量、可扩缩，并且非常适合表示和公开数据。

是否提供常见问题的相关提示或简短的示例代码？

您应浏览 Google Data API 提示博客，以获取有关使用客户端库和发出原始请求的帮助。

Gmail 是否有 Data API？

不能，但您可以将 Gmail 的 Atom Feed 与 AuthSub 或 OAuth 1 搭配使用，以请求对用户未读邮件的只读访问权限。范围应设置为 https://mail.google.com/mail/feed/atom/。一个查询示例：

GET https://mail.google.com/mail/feed/atom/

如果您有兴趣管理自己的邮件，Gmail 还支持 IMAP/POP。

---

身份验证

在 Google Data API 文档中，“OAuth”是指 OAuth 1；如需了解 OAuth 2.0 的详细信息，请参阅各个 API 的文档。

在 ClientLogin 中，每个 Data API 的服务名称是什么？

“服务名称”是 ClientLogin 身份验证系统用于标识 Google 服务的简短字符串。

Google API	服务名称
Google Analytics Data API	analytics
G Suite API （网域信息和管理）	apps
Google Sites Data API	jotspot
Blogger Data API	blogger
Book Search Data API	print
日历数据 API	cl
Google Code Search Data API	codesearch
Contacts Data API	cp
Content API for Shopping	structuredcontent
Documents List Data API	writely
Finance Data API	finance
Gmail Atom Feed	mail
Health Data API	health weaver（H9 沙盒）
Maps Data API	local
Picasa 线上相册 Data API	lh2
Sidewiki Data API	annotateweb
Spreadsheets Data API	wise
Webmaster Tools API	sitemaps
YouTube Data API	youtube

如需详细了解 ClientLogin 请求中使用的其他参数，请参阅 ClientLogin 文档。

当用户退出应用时，是否需要通知 API 服务器？

不需要，当用户从应用中退出时，无需通知 Google Data API。不过，如果您的应用不再需要使用已签发的 AuthSub 令牌，则应撤消该令牌。

ClientLogin 身份验证令牌是否有过期日期？

ClientLogin 令牌自签发之日起最多可使用 2 周，但此限制因服务而异，可能会更短。

我有一个关于 Google 账号的常见问题。我应该去哪里？

访问 Google 账号帮助中心。

如何向 API 进行身份验证？

您的 HTTP 请求必须包含一个授权标头，其中包含通过使用 ClientLogin、AuthSub 或 OAuth 1 获取的令牌。

我应该为 AuthSub/OAuth 1 范围参数使用什么值？

AuthSub 和 OAuth 1 需要 scope 参数来标识您的应用将有权访问哪些 Google 服务。如需了解 OAuth 2.0 的详细信息，请参阅特定 API 的文档。

Google API	ClientLogin 服务名称
Google Analytics Data API	https://www.google.com/analytics/feeds/
Google Sites Data API	http(s)://sites.google.com/feeds/
Blogger Data API	http://www.blogger.com/feeds/
Book Search Data API	http://www.google.com/books/feeds/
日历数据 API	http(s)://www.google.com/calendar/feeds/
Contacts Data API	http(s)://www.google.com/m8/feeds/
Content API for Shopping	https://www.googleapis.com/auth/structuredcontent
Documents List Data API	http(s)://docs.google.com/feeds/
Finance Data API	http://finance.google.com/finance/feeds/
Gmail Atom Feed	https://mail.google.com/mail/feed/atom/
Health Data API	https://www.google.com/health/feeds/ https://www.google.com/h9/feeds/（H9 沙盒）
Google Maps Data API	http://maps.google.com/maps/feeds/
Picasa 线上相册 Data API	http://picasaweb.google.com/data/
Portable Contacts API	http://www-opensocial.googleusercontent.com/api/people
Sidewiki Data API	http://www.google.com/sidewiki/feeds/
Spreadsheets Data API	http(s)://spreadsheets.google.com/feeds/
Webmaster Tools API	http://www.google.com/webmasters/tools/feeds/
YouTube Data API	http://gdata.youtube.com

AuthSub 令牌有不同的类型吗？令牌会过期吗？

AuthSub 令牌有两种类型。第一个是单次使用的令牌，通过“token”查询参数呈现给您的 Web 应用。此令牌在首次用于其签发服务时或在兑换为会话令牌时失效。

会话令牌不会过期，除非通过用户或 AuthSubRevokeToken API 调用显式撤消令牌。只有当原始 AuthSubRequest 网址将 session=1 指定为查询参数时，单次使用令牌才能换取会话令牌。

ClientLogin 与 AuthSub/OAuth 1 之间的主要区别是什么？

AuthSub 专为 Web 应用而设计。它可确保用户凭据直接从用户的 Web 浏览器安全地发送到 Google 的服务器，而不是通过第三方网站发送。

ClientLogin 适用于安装型桌面应用。它要求请求应用代表用户向 Google 传输用户凭据。

请参阅 Google Account Authentication API 的相关文档。

我可以在第三方 Web 应用中使用 ClientLogin 身份验证吗？

在第三方 Web 应用中使用 ClientLogin 是可以接受的，但强烈建议不要这样做。根据最佳实践，Web 应用绝不应要求用户提供登录凭据（这可能会受到窥探）。相反，应用应在服务器端存储用户凭据，并拥有一个始终用于向 Google 进行身份验证的“服务账号”。

什么是人机识别系统？

人机识别系统（区分计算机与人的完全自动化的公共图灵测试）是一种问答式测试，用于确定用户是否是真人。该术语已由卡内基梅隆大学注册为商标。如需了解更多详情，请参阅 Wikipedia。 我们已在 ClientLogin 中实现 CAPTCHA。

如何生成人机识别系统验证？

系统会使用专有算法来确定在身份验证期间何时需要进行 CAPTCHA 挑战。使用无效凭据反复尝试进行身份验证通常会生成 CAPTCHA 验证。

我应该在 Web 应用中使用 ClientLogin 吗？

否，ClientLogin 应由用户自有硬件上安装的应用使用。 在 Web 应用中使用 ClientLogin API 是不安全的，强烈建议不要这样做。

在使用 AuthSub/OAuth 1 时，如何获取用户的用户名？

由于您仅从 Google 获得一个用于授予用户 Feed 访问权限的令牌，因此您可能不知道用户的用户名。如果想要使用的 Feed 网址包含用户名，这可能会造成问题。在这种情况下，您可以使用特殊用户名 default 来表示“我正在使用的身份验证令牌所对应的用户”。

如何将 OAuth 1 与 Google Data API 客户端库搭配使用？

请参阅文章将 OAuth 1 与 Google Data API 客户端库搭配使用。

如何将 AuthSub 与 Google Data API 客户端库搭配使用？

请参阅将 AuthSub 与 Google Data API 客户端库搭配使用一文。

如何将 ClientLogin 与 Google Data API 客户端库搭配使用？

请参阅将 ClientLogin 与 Google Data API 客户端库搭配使用一文。

---

客户端库

哪些编程语言的客户端库受 Google 支持？

Java、.NET、Python 和 Objective-C 客户端库由 Google 提供官方支持。此外，我们的合作伙伴 Zend 还编写了一个 PHP 客户端库。使用这些库，您可以构建 Google Data 协议请求、将其发送到服务，并处理服务器响应。此外，还有一个 JavaScript 客户端库，目前仅支持 Blogger、Google 日历和 Google 通讯录。

如果您使用 Java、.Net、Python 或 Objective-C 以外的语言编写客户端库，并希望与 Data API 开发者社区分享，请在 Google Data API 讨论组中发帖。我们期待收到您的宝贵意见！

如何报告某个客户端库的 bug 或提出功能请求？

如需报告客户端库的 bug 或提出功能请求，请访问以下位置：

• Java
• JavaScript
• .NET
• PHP
• Python
• Objective-C

发布 bug 后，在相应 API 的开发者论坛中创建一个帖子。

如何在 Google Data API 客户端库中启用调试选项？

如需了解如何使用某些客户端库启用调试，请参阅以下文章：调试 Google Data API 客户端：从程序内部探索流量

在哪里可以找到客户端库类的参考文档？

客户端库	参考指南
Java	Javadoc
JavaScript	JSdoc
.NET	NDoc
PHP	phpDoc
Python	PyDoc

---

问题排查

有哪些实用的 HTTP 调试工具？

下面列出了许多工具，但您可能还想阅读在线：面向 API 开发者的网络捕获工具一文，其中深入介绍了 WireShark 和 Fiddler 的示例。

Wireshark

Wireshark 是一款“网络协议分析器”。它能够捕获网络流量并分析内容。在调试您无法直接访问 HTTP 请求和响应流的库中发生的流量时，此功能非常有用。由于应用与身份验证服务之间的通信使用 SSL 加密，因此无法使用 Wireshark 分析它们之间的流量。Wireshark 还可用于分析使用 tcpdump 等工具捕获的流量。开发者以源代码和 Windows 安装程序的形式提供 Wireshark。第三方软件包适用于许多平台。

Fiddler

Fiddler 是一款“HTTP 调试代理”。如果您能将代码或运行时环境配置为使用代理服务器来处理 HTTP 流量，Fiddler 将位于您的应用和 Google 数据服务之间，让您能够检查流量。Fiddler 2 包含对 SSL 的支持。Fiddler 目前仅适用于 Windows。

cURL

c网址 是一种命令行工具，可执行 HTTP/HTTPS 请求。这对于快速测试与服务的互动非常有用，而无需先在客户端中构建 HTTP 支持。

如何在 Java 客户端库中获取 HTTP 日志记录信息？

Java 客户端库使用 java.util.logging 软件包来启用 HTTP 请求日志记录。这样，您就可以为请求和响应启用标头记录功能，并记录状态代码和请求网址。目前，此功能不会记录完整的请求和响应流。这些日志使用的记录器名称为 com.google.gdata.client.http.HttpGDataRequest。

如果服务器返回错误代码，系统会抛出异常。异常类继承自 com.google.gdata.util.ServiceException，并包含一个名为 getResponseBody() 的公共方法。如需了解详情，请参阅 Javadoc。

如何在 .NET 客户端库中获取 HTTP 日志记录信息？

.NET 库使用 System.Diagnostics 跟踪方法来记录执行路径（如果已启用跟踪）。此外，如果出现错误，系统会抛出 GDataRequestException。该异常包含一个 ResponseString，可用于访问 HTTP 响应的正文。

如何从 Google 数据 Feed 中启用 gzip 编码？

若要从某个 Google Data API 接收 gzip 编码的响应，您必须执行以下两项操作：设置“Accept-Encoding”标头，并修改您的用户代理，使其包含字符串“gzip”。格式正确的标头示例：

User-Agent: my program (gzip)
Accept-Encoding: gzip

使用 PHP 客户端时，为什么会看到“Unable to Connect to sslv2”错误？

自 2009 年 7 月起，我们开始在服务器上停用 SSLv2，以作为一项预防措施来提高安全性。遗憾的是，在 2007 年 7 月之前发布的 PHP 客户端库的早期版本（版本 1.0.0 及更早版本）中存在一个 bug，该 bug 会强制连接使用 SSLv2。当连接到已停用 SSLv2 的服务器时，会导致以下错误：

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

如需更正此错误，请升级到较新版本的 PHP 客户端库，该库可从 http://framework.zend.com/download 下载。

如果您无法升级到较新版本，可以通过向应用添加以下代码来解决此问题，其中 $gdata 是您现有的 Zend_Gdata 实例（或相应的子类）：

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));

如何获取描述 Feed 的 Atom 服务文档？

您可以通过在请求中传递 alt=atom-service 参数来获取 Atom 服务文档。注意：只有 Google Data API 的第 2 版才会返回符合 AtomPub 服务文档语法的服务文档。Google Data API 的版本 1 仍会返回服务文档，但该文档基于较早的 AtomPub 草稿规范（这两个版本之间存在语法和命名空间更改）。