Google Data PHP 客户端库使用入门

警告：此页面介绍的是 Google 的旧版 API（即 Google Data API），仅适用于Google Data API 目录中列出的 API，其中许多 API 已被更新的 API 取代。如需了解特定新 API，请参阅相应新 API 的文档。如需了解如何使用较新的 API 授权请求，请参阅 Google 账号身份验证和授权。

视频：观看 Trevor Johns 介绍客户端库安装、库架构和代码演练。

Jochen Hartmann，Google Data API 团队
更新于 2008 年 10 月（最初由 Daniel Holevoet 撰写）

• 简介
• 安装前
• 安装 PHP
  • 在 Windows 上
  • 在 Mac OS X 上
  • 在 Linux 设备上
• 安装 Google Data PHP 客户端库
• 检查以确保您可以访问客户端库文件
  • 运行 PHP 安装检查器
  • 运行示例
• 了解详情
• 附录 A：在 php.ini 配置文件中修改 PHP 路径
• 附录 B：通过命令行使用 PHP
• 附录 C：提示和解答
• 修订历史记录

简介

Google Data PHP 客户端库是一组功能强大的类，可让您与 Google Data API 进行交互。与其他客户端库不同，它作为热门 Zend Framework 的一部分进行打包，但也可以单独下载。与我们的其他客户端库类似，它也是开源的，并且设计得简单高效，可让您快速开始项目。

安装前

您的开发机器或 Web 服务器上可能已安装 PHP，因此第一步是验证这一点，并确保 PHP 版本足够新，可用于客户端库。最简单的检查方法是将新文件放入服务器上可从网络访问的目录中。在文件中输入以下信息：

<?php phpinfo(); ?>

然后，确保通过设置适当的权限可以从网络访问该文件，并在浏览器中前往其位置。如果已安装 PHP 且服务器能够呈现 PHP 网页，您应该会看到类似以下屏幕截图的内容：

此屏幕截图显示了 PHP 信息页面。此页面会显示已安装的 PHP 版本（在本例中为 5.2.6）、已启用的扩展程序（在“配置命令”部分中）以及 PHP 内部配置文件的位置（在“已加载的配置文件”部分中）。如果未显示该页面，或者您的 PHP 版本低于 5.1.4，您需要安装或升级 PHP 版本。否则，您可以跳过下一部分，继续安装 PHP 客户端库。

注意：如果您可以访问命令行，并且计划使用 PHP 运行命令行脚本，请参阅本文的命令行 PHP 部分。

安装 PHP

安装过程因平台而异，因此请务必在安装过程中按照适用于您所用平台的说明操作。在深入探讨之前，值得一提的是，预安装的软件包（也包含 Apache Web 服务器和 MySQL 数据库以及 PHP）越来越受欢迎。对于 Windows、Mac OS X 和 Linux，可以使用 XAMPP 项目。Mac OS X 用户还可以选择使用 MAMP 项目。这两个软件包都支持 PHP 中的 OpenSSL（这是与经过身份验证的 Feed 进行交互所必需的）。

如果您按照以下步骤安装 PHP，请确保您还安装并启用了对 OpenSSL 的支持。如需了解详情，请参阅 PHP 网站的 OpenSSL 部分。以下部分重点介绍如何单独安装 PHP。

在 Windows 上

在 Windows 上安装或升级 PHP 的最简单方法是使用 PHP 下载页面上提供的 PHP 安装程序。

1. 选择与最新版 PHP 对应的 PHP 安装程序选项（在 Windows 二进制文件部分），然后允许下载。
2. 打开安装程序并按照安装向导的说明操作。
3. 当向导提示您时，请选择安装在您系统上的 Web 服务器，以便向导配置该服务器以使用 PHP。
4. 按照上文中概述的步骤检查安装情况。

在 Mac OS X 上

OS X 中包含 PHP，但在使用之前，您应升级到最新版本的 PHP。如需升级，您可以安装多个免费的二进制软件包中的任意一个，也可以自行编译。如需了解详情，请参阅有关 在 Mac OS X 上安装的 PHP 文档页面。

安装或以其他方式设置 OS X 后，请按照本文档安装前部分中列出的步骤检查安装。

在 Linux 上

根据 Linux 发行版的不同，可能存在内置或易于使用的 PHP 安装设置选项。例如，在 Ubuntu 上，您可以使用软件包管理器，也可以在终端中直接输入以下内容：

sudo apt-get install php5

如果您的 Linux 发行版没有提供打包安装，您必须从源代码进行安装。有关为 Apache 1.3 编译 PHP 和为 Apache 2 编译 PHP 的详细说明。PHP.net 还提供了针对其他服务器的说明。

安装 Google Data PHP 客户端库

现在您已经安装了可正常运行的 PHP 版本，接下来该安装客户端库了。客户端库是开源 Zend Framework 的一部分，但也可以下载独立版本。如果您已安装 Zend Framework（1.6 版或更高版本），则可以跳过安装，因为其中已包含 Google Data Client Library。不过，确保您使用的是最新版本的框架可保证您能使用所有最新功能和 bug 修复，因此通常建议您这样做。

下载完整框架后，您不仅可以访问 Google Data 客户端库，还可以访问框架的其余部分。客户端库本身使用了一些属于完整 Zend Framework 的其他类，但无需下载整个框架，因为我们已将它们捆绑到独立下载中。

1. 下载 Google Data 客户端库文件。（在该页面中搜索“Google Data API”。）
2. 解压缩下载的文件。应创建四个子目录：
   • demos - 示例应用
   • documentation - 客户端库文件的文档
   • library - 实际的客户端库源文件。
   • tests - 用于自动化测试的单元测试文件。
3. 将 library 文件夹的位置添加到您的 PHP 路径（请参阅下一部分）

检查以确保您可以访问客户端库文件

最后一步是确保您可以从构建项目的目录中引用并包含 PHP 客户端库文件。为此，您需要在 PHP 的配置文件 (php.ini) 中设置 include_path 变量。include_path 变量包含许多目录位置，当您发出 require 或 include 语句将外部类、库或文件拉入当前脚本时，PHP 会在这些目录中进行查找，这类似于 Java 中的 import 语句。您需要将客户端库文件的位置附加到 include_path 中已设置的内容。这可以通过两种方式来实现（下文将详细介绍这两种方式）：

• 通过命令行在 php.ini 配置文件中永久设置 include_path 指令 - 需要 shell 访问权限和写入权限。
• 在“每个目录”级别设置 include_path 路径变量 - 需要 Apache Web 服务器和创建 .htaccess 文件的能力。
• 使用 set_include_path() 函数可在脚本中动态设置包含路径，并且可以在每个 .php 文件中动态设置。

如果您拥有对 php.ini 文件的 shell 访问权限和写入权限（或者您是在本地机器上编写代码），只需按照附录 A 中的说明操作即可。如果您使用的是 Apache 网络服务器，并且能够创建 .htaccess 文件，则可以在“每个目录”级别设置 include_path 变量，这意味着您正在处理的目录中的所有文件都能够自动引用客户端库目录。

您可以指定 PHP 配置选项，如以下代码段所示：

# This works for PHP5 in both Apache versions 1 and 2
<IfModule mod_php5.c>
  php_value include_path        ".:/usr/local/lib/php:/path/to/ZendGdata/library"
</IfModule>

注意：如需详细了解如何更改配置设置，请参阅 PHP 手册。

如果您无法通过 shell 访问服务器，也无法修改或创建 .htaccess 文件，则始终可以使用 set_include_path 函数。请注意，您可能已为 include_path 设置了一些值，因此最好按照以下模型附加新值，而不是覆盖整个路径：

$clientLibraryPath = '/path/to/ZendGdata/library';
$oldPath = set_include_path(get_include_path() . PATH_SEPARATOR . $clientLibraryPath);

注意：如需详细了解 set_include_path 函数，请参阅 PHP 手册页面。

运行 PHP 安装检查器

如需验证您的包含路径是否已正确设置，您可以运行 PHP 安装检查器脚本。只需将该文件的内容复制并粘贴到服务器上可从网络访问的目录中的新文件中，然后从浏览器中前往该文件即可。如果您看到类似如下所示的输出，则表示一切都已正确配置，您可以开始使用 PHP 客户端库了：

如果您看到错误（如下面的屏幕截图所示），请务必按照说明操作。您可能缺少扩展程序，或者您的路径可能仍未正确设置。请注意，您可能需要重启服务器才能使更改生效。这仅在您实际修改 php.ini 文件时适用。以下屏幕截图显示，include_path 已设置为 /path/to/nowhere：

注意：请注意，PHP 安装检查器会依次检查以下各项：(1) 是否已安装必需的 PHP 扩展程序；(2) include_path 是否指向 PHP 客户端库的目录；(3) 是否可以建立 SSL 连接；最后，是否可以连接到 YouTube Data API。如果特定测试失败，则不会运行其余测试。

现在，客户端库已安装完毕，接下来可以尝试运行示例了。

运行示例

Zend/Gdata 目录的根目录下有一个演示文件夹，其中包含一些示例，可帮助您入门。其中一些示例旨在从命令行（例如 demos/Zend/Gdata/Blogger.php 和 demos/Zend/Gdata/Spreadsheet-ClientLogin.php）运行，您可以使用 php /path/to/example 执行这些示例。其余示例既可通过命令行运行，也可通过 Web 浏览器运行。如果您想在浏览器中查看这些文件，应将它们放置在您用于提供网页的任何目录中。这些示例应该能让您对如何编写和运行 Google Data 应用有一个基本的了解，但如果您想了解更多信息，还有其他资源可供好奇的程序员参考。

注意：如果您有兴趣在线查看基于 Web 的演示，请访问 googlecodesamples.com 并查找 PHP 应用。

了解详情

如需查找有关客户端库中包含的类的信息，最好前往 Zend Framework 网站查看 API 参考指南。请务必从下拉菜单中选择 Zend_Gdata 软件包。

至此，您应该已准备就绪，可以开始编码了。快去编写一些出色的应用吧。我们期待看到您的成果！

您可以找到以下服务的 PHP 开发者指南：

• Blogger
• Google 日历
• Google 文档列表
• YouTube Data API

由于 PHP 客户端库是一个开源项目，因此我们一直在添加对更多 API 的支持。每项服务都有自己的支持群组，请参阅我们的常见问题解答条目，查看可用的支持群组列表。

如果您需要有关 API 调用问题排查方面的帮助，可以参阅有关使用网络流量捕获工具调试 API 请求和将代理服务器与 Google Data API 搭配使用的文章。此外，您还可以找到一些关于在 Linux 上安装 XAMPP 和在 Windows 上安装 XAMPP 的外部文章。除了所有这些文章之外，请务必查看 Google Data API 提示博客上有关 PHP 客户端库的帖子。

附录 A：在 php.ini 配置文件中修改 PHP 路径

PHP 路径是一个变量，其中包含 PHP 在加载期间查找其他库时搜索的位置列表。为了让 PHP 能够加载和访问您机器或服务器上的 Google Data PHP 客户端库文件，您需要将这些文件放置在 PHP 能够识别的位置。或者，您需要将文件的位置附加到 PHP 路径。请注意，对 php.ini 文件的更改通常需要重启服务器。您可以随时前往前面讨论过的 PHP 信息页面，验证 include_path 变量的当前值。在第一个表格中找到“加载的配置文件”单元格，然后在右侧的列中找到相应路径。

注意：如果您发现自己正在从命令行使用 PHP，则可能需要修改其他路径变量。请务必查看附录 B：从命令行使用 PHP。

找到 php.ini 文件后，请按以下步骤操作，将该文件附加到路径中。

1. 在您惯用的文本编辑器中打开 php.ini 文件。
2. 找到引用 PHP 路径的行，该行应以 include_path 开头。
3. 将您存储 Zend Framework 的路径附加到已有的位置列表，并在新路径前面加上您操作系统指定的分隔符（在类 Unix 系统上为 :，在 Windows 上为 ;）。在类 Unix 系统上，正确的路径应如下所示：

   /path1:/path2:/usr/local/lib/php/library

   在 Windows 上，它看起来会像这样：

   \path1;\path2;\php\library

4. 保存并关闭文件。

注意：在 Mac OS X 上，Finder 不允许访问位于系统位置（例如 /etc 目录）中的文件。因此，使用 vi 或 pico 等命令行编辑器修改这些文件可能是最简单的方法。为此，请使用如下命令：pico /path/to/php.ini。

附录 B：通过命令行使用 PHP

自 PHP 版本 5 起，PHP 中提供了一个命令行实用程序，称为“命令行解释器”的 CLI。使用此实用程序可从命令行运行 PHP 脚本。如果您在本地计算机上运行 PHP，并希望找到快速测试某些脚本的方法，那么此功能可能会很有用。当然，在服务器上，这需要 shell 访问权限。需要注意的一点是，PHP 通常使用两个单独的 php.ini 文件，一个包含在服务器上运行的 PHP 的配置选项，另一个包含 PHP 在从命令行运行时使用的配置。如果您有兴趣运行客户端库中的命令行演示应用，还需要修改命令行 php.ini 文件。

如需找到该文件，请在类 Unix 系统（Mac OS X、Linux 等）上输入以下命令：

php -i | grep php.ini

该命令应导致终端中显示以下信息：

Configuration File (php.ini) Path => /etc/php5/cli
Loaded Configuration File => /etc/php5/cli/php.ini

注意：当然，实际路径位置 (/etc/php...) 在您的系统上可能会有所不同。

附录 C：提示和解答

本部分简要介绍了开发者在使用 PHP 时发现的一些问题以及相应的解决方案。

XAMPP 中的 dom-xml 扩展服务存在问题

PHP 客户端库使用 DOMDocument 类将 XML 请求和响应转换为 PHP 对象。dom-xml 扩展程序可能会导致 XML 处理出现问题，并导致转换不正确。我们的一些开发者发现，使用 XAMPP 时，DOMDocument 构造函数会被旧函数调用替换，如 PHP 网站上所述。如需解决此问题，请确保 XML 处理未在 php.ini 文件中被覆盖。请务必从配置文件中移除对 php_domxml.dll 的引用。

使用客户端库时，请求超时

如果您使用客户端库执行相当大的请求（例如向 YouTube Data API 上传视频），可能需要更改 Zend_Http_Client 类中的 timeout 参数。在实例化期间传递 $config 参数即可轻松实现此目的，该参数会将 timeout 值设置为 10 秒默认值以外的其他值：

// assuming your Zend_Http_Client already exists as $httpClient
// and that you want to change the timeout from the 10 second default to 30 seconds

$config = array('timeout' => 30);
$httpClient->setConfig($config);

某些托管服务提供商不允许从其服务器建立 HTTPS 连接

我们了解到，有些托管服务提供商不允许您从其默认服务器建立 https 连接。如果您收到类似于以下内容的错误消息，则可能需要通过安全代理建立 HTTPS 连接：

Unable to Connect to sslv2://www.google.com:443. Error #110: Connection timed out

您的托管服务提供商应提供有关要使用的代理服务器实际地址的信息。以下代码段演示了如何将自定义代理配置与 PHP 客户端库搭配使用：

// Load the proxy adapter class in addition to the other required classes
Zend_Loader::loadClass('Zend_Http_Client_Adapter_Proxy');

// Configure the proxy connection with your hostname and portnumber
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'your.proxy.server.net',
    'proxy_port' => 3128
);

// A simple https request would be an attempt to authenticate via ClientLogin
$proxiedHttpClient = new Zend_Http_Client('http://www.google.com:443', $config);

$username = '[e-mail]';
$password = 'barbaz';

// The service name would depend on what API you are interacting with, here
// we are using the Google DocumentsList Data API
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;

// Try to perform the ClientLogin authentication using our proxy client.
// If there is an error, we exit since it doesn't make sense to go on.
try {

  // Note that we are creating another Zend_Http_Client
  // by passing our proxied client into the constructor.

  $httpClient = Zend_Gdata_ClientLogin::getHttpClient(
      $username, $password, $service, $proxiedHttpClient);

} catch (Zend_Gdata_App_HttpException $httpException) {

  // You may want to handle this differently in your application
  exit("An error occurred trying to connect to the proxy server\n" .
      $httpException->getMessage() . "\n");

}

修订历史记录

2008 年 10 月 1 日

由 Jochen Hartmann 更新。此更新包含以下更改：

• 通过将引用命令行 PHP 的部分移至附录，使 Web 服务器的 PHP 配置更加清晰。
• 添加了有关多个 php.ini 配置文件的注释。
• 添加了有关如何动态设置 include_path 的部分。
• 添加了有关安装检查器脚本的部分。
• 添加了指向在线示例的链接。
• 添加了 XAMPP 和 MAMP 的链接。
• 添加了“提示和解答”附录。