常见问题解答

概览

1. 什么是 Google Data API？
2. 我有功能请求或错误报告，我应该在哪里发布？
3. 我应该在哪里询问有关特定 API 的问题？
4. 什么是 JSON？
5. 我必须使用 XML 吗？还有其他数据格式吗？
6. 为何要使用 REST？
7. 对于常见问题，您是否有任何提示或简短的示例代码？
8. Gmail 有数据 API 吗？

身份验证

9. 每个 Data API 在 StreetView 中的服务名称是什么？
10. 如果用户退出应用，是否需要通知 API 服务器？
11. StreetView 身份验证令牌有失效日期吗？
12. 我有一个关于 Google 帐号的常见问题。我该怎么做？
13. 如何通过 API 进行身份验证？
14. 我应该为 AuthSub/OAuth 1 范围参数使用什么值？
15. 有不同类型的 AuthSub 令牌吗？令牌会过期吗？
16. StreetView 与 AuthSub/OAuth 1 的主要区别是什么？
17. 我可以在第三方 Web 应用中使用 EGL 身份验证吗？
18. 什么是人机识别系统？
19. 如何生成人机识别系统验证？
20. 我是否应在 Web 应用中使用 Paging？
21. 在使用 AuthSub/OAuth 1 时，如何找到用户的用户名？
22. 如何将 OAuth 1 与 Google Data API 客户端库搭配使用？
23. 如何将 AuthSub 与 Google Data API 客户端库搭配使用？
24. 如何在 Google Data API 客户端库中使用 Paging？

客户端库

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

问题排查

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

---

概览

什么是 Google 数据 API？

Google 数据 API 是基于 Google 数据协议的 API。Google 数据协议基于 Atom 1.0 和 RSS 2.0 整合格式，以及 Atom 发布协议 (APP)。

Google 数据协议使用标准中内置的扩展机制，以多种方式扩展这些标准。Feed 符合 Atom 或 RSS 联合格式。发布模型符合 Atom 发布协议的要求。

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

我有功能请求或错误报告，我应该在哪里发布？

查看我们的问题跟踪器。 查找您的功能请求并为其加注星标，即可添加支持并接收有关其状态的更新。

应在何处询问有关特定 API 的问题？

如果本文未列出您遇到的问题，或者您希望进一步澄清，我们提供了各 Google Data API 专用的论坛：

• G Suite（请参阅 G Suite 系列中的各个 API）
• Base
• 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、通讯录或 Google 日历服务结合使用可以读取和写入数据。

  详细了解如何请求和使用 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 的文档。

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

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

Google API	服务名称
Google Analytics（分析）Data API	analytics
G Suite API （域名信息与管理）	apps
Google 协作平台数据 API	jotspot
Blogger 数据 API	blogger
Book Search Data API	print
日历数据 API	cl
Google 代码搜索数据 API	codesearch
联系人数据 API	cp
Content API for Shopping	structuredcontent
文档列表数据 API	writely
财经数据 API	finance
Gmail Atom Feed	mail
健康数据 API	health weaver（H9 沙盒）
Google 地图数据 API	local
Picasa 线上影集数据 API	lh2
边栏评注数据 API	annotateweb
电子表格数据 API	wise
网站站长工具 API	sitemaps
YouTube Data API	youtube

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

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

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

StreetView 身份验证令牌有失效日期吗？

一个 Paging 令牌自发出之日起可以持续 2 周，但此限额因服务而异，可以更短。

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

请访问 Google 帐号帮助中心。

如何向 API 进行身份验证？

您的 HTTP 请求必须包含 Authorization 标头，其中包含使用 StreetView、AuthSub 或 OAuth 1 获得的令牌。

我应该为 AuthSub/Oauth 1 范围参数指定什么值？

AuthSub 和 OAuth 1 需要 scope 参数才能确定您的应用可以访问哪些 Google 服务。如需详细了解 OAuth 2.0，请参阅所用 API 对应的文档。

Google API	Paging 服务名称
Google Analytics（分析）Data API	https://www.google.com/analytics/feeds/
Google 协作平台数据 API	http(s)://sites.google.com/feeds/
Blogger 数据 API	http://www.blogger.com/feeds/
Book Search Data API	http://www.google.com/books/feeds/
日历数据 API	http(s)://www.google.com/calendar/feeds/
联系人数据 API	http(s)://www.google.com/m8/feeds/
Content API for Shopping	https://www.googleapis.com/auth/structuredcontent
文档列表数据 API	http(s)://docs.google.com/feeds/
财经数据 API	http://finance.google.com/finance/feeds/
Gmail Atom Feed	https://mail.google.com/mail/feed/atom/
健康数据 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 线上影集数据 API	http://picasaweb.google.com/data/
便携式通讯录 API	http://www-opensocial.googleusercontent.com/api/people
边栏评注数据 API	http://www.google.com/sidewiki/feeds/
电子表格数据 API	http(s)://spreadsheets.google.com/feeds/
网站站长工具 API	http://www.google.com/webmasters/tools/feeds/
YouTube Data API	http://gdata.youtube.com

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

有两种 AuthSub 令牌。第一种是通过“令牌”查询参数向您的 Web 应用提供的一次性令牌。此令牌第一次在颁发时或用于交换会话令牌时到期。

会话令牌不会过期，除非用户或 AuthSubRevokeToken API 调用明确撤消了该令牌。只有在原始 AuthSubRequest 网址将 session=1 指定为查询参数时，才能用一次性令牌交换会话令牌。

StreetView 与 AuthSub/OAuth 1 的主要区别是什么？

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

Paging 适用于已安装的桌面应用。它要求发出请求的应用代表用户向 Google 传输用户凭据。

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

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

可以在第三方 Web 应用中使用 Paging，但强烈建议不要这样做。根据最佳做法，Web 应用绝不能要求用户提供登录凭据（这可能很容易遭到窥探）。相反，应用应在服务器端存储用户凭据，并具有始终用于向 Google 进行身份验证的“服务帐号”。

什么是人机识别系统？

人机识别系统（区分计算机与人的完全自动化的公共图灵测试）是一种质询-响应测试，用于确定用户是否为真人。该字词是卡内基梅隆大学的商标。如需了解详情，请参阅维基百科。 我们已在 StreetView 中实现了人机识别系统验证。

如何生成验证码验证？

使用专有算法确定在身份验证期间需要人机识别系统质询。如果使用错误的凭据重复尝试身份验证，通常会产生人机识别系统质询。

是否应在 Web 应用中使用 Paging？

不可以，IAB 应该由用户拥有的硬件上使用的已安装应用。 在 Web 应用中使用 EGL 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 客户端库结合使用一文。

如何将 Paging 与 Google Data API 客户端库结合使用？

请参阅将 Paging 与 Google Data API 客户端库结合使用一文。

---

客户端库

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

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

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

如何报告其中一个客户端库的错误或功能请求？

可以在以下位置报告客户端库的 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 调试工具？

下面列出了许多工具，但您可能还需要阅读 The Wire: Network Capture Tools for API Developers 一文，其中详细介绍了 WireShark 和 Fiddler 的示例。

Wireshark

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

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 数据 API 接收经过 gzip 编码的响应，您必须执行以下两项操作：设置“Accept-Translation”标头并修改您的用户代理，使其包含字符串“gzip”。格式正确的标头示例：

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

为什么在使用 PHP 客户端时会看到“无法连接到 sslv2”错误？

作为一项预防措施，自 2009 年 7 月起，我们开始在我们的服务器上停用 SSLv2。不幸的是，2007 年 7 月之前发布的 PHP 客户端库（1.0.0 及更低版本）中存在一个 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 服务文档。注意：只有版本 2 的 Google Data API 将返回符合 AtomPub 服务文档语法的服务文档。Google Data API 版本 1 仍将返回服务文档，但该版本基于早期的 AtomPub 草稿规范（这两个版本之间存在语法和命名空间方面的变化）。