Google Data PHP 客户端库使用入门

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

视频：Trevor Johns 将向您介绍客户端库安装、库架构和代码演示。

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

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

简介

Google 数据 PHP 客户端库是一个功能强大的类集合，可让您与 Google 数据 API 进行交互。与我们的其他客户端库不同，它封装在热门的 Zend Framework 中，但也可以单独下载。与我们的其他客户端库类似，它也是开源的，简单而高效，便于您快速开始自己的项目。

安装前

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

<?php phpinfo(); ?>

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

该屏幕截图显示了 PHP 信息页面。此页面会显示已安装的 PHP 版本（在本例中为 5.2.6），以及已启用的扩展程序（在“Configure Command”部分中）以及 PHP 的内部配置文件的位置（在“Loaded Profile File”部分中）。如果此页面未显示或您的 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 交互所需的 OpenSSL）。

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

在 Windows 上

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

1. 选择与最新版本的 PHP 对应的 PHP 安装程序选项（在 Windows 二进制文件部分），并允许下载该文件。
2. 打开安装程序并按照安装向导的说明操作。
3. 当向导提示您时，请选择您系统中安装的网络服务器，以便将其配置为使用 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 客户端库。不过，请确保您使用的是最新版本的框架，这可以确保您能够获得所有最新的功能和 bug 修复，因此通常建议这样做。

下载完整的框架后，您不仅可以访问 Google 数据客户端库，还能访问框架的其余部分。客户端库本身使用了一些属于完整 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 网络服务器和 .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 Installation Checker 脚本。只需将该文件的内容复制并粘贴到服务器上可通过网络访问的新文件中，然后从浏览器转到该文件即可。如果您看到如下所示的输出，则表明所有配置均已正确，您可以开始使用 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 执行这些示例。其余示例可通过命令行和网络浏览器运行。如果您希望在浏览器中查看这些报告，则应将其放在要用于投放网页的任何目录中。这些示例应该会让您基本了解如何编写和运行 Google 数据应用，但当您准备好进行更多操作后，可以参考一些具有好奇心的程序员的资源。

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

了解详情

如需查找客户端库中的类的相关信息，最好参阅 Zend Framework 网站上的 API 参考指南。请务必从下拉列表中选择 Zend_Gdata 软件包。

此时，您应该已经准备好开始编码了。接下来，编写一些很棒的应用程序。我们期待您的成果！

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

• Blogger
• Google 日历
• Google 文档列表
• YouTube 数据 API

由于 PHP 客户端库是一个开源项目，因此我们会不断支持更多 API。每项服务都有自己的支持论坛，请参阅我们的常见问题解答条目中列出了可用的支持论坛。

如果您在 API 调用方面需要帮助，请参阅相关文章，了解如何使用网络流量捕获工具调试 API 请求以及如何将代理服务器与 Google Data API 搭配使用。还有一些外部文章介绍了如何在 Linux 上安装 XAMPP 以及如何在 Windows 上安装 XAMPP。除了上述所有文章之外，请务必查看 Google Data API 提示博客中关于 PHP 客户端库的博文。

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

PHP 路径是一个变量，其中包含 PHP 在加载期间查找其他库时搜索的位置列表。为了让 PHP 能够加载和访问您的计算机或服务器上的 Google 数据 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 上，访达不允许访问位于系统位置（如 /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 网站中所述。要解决此问题，请确保未在 php.ini 文件中覆盖 XML 处理。请确保从配置文件中移除对 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 的部分移到了附录中，为网络服务器提供了更清晰的 PHP 配置。
• 添加了关于多个 php.ini 配置文件的备注。
• 添加了有关如何动态设置 include_path 的部分。
• 添加了有关安装检查工具脚本的部分。
• 添加了指向在线示例的链接。
• 添加了 XAMPP 和 MAMP 的链接。
• 添加了“提示和解决方案”附录。