警告：本頁面說明 Google 的舊版 API (即 Google Data API)；該 API 只與 Google Data API 目錄中列出的 API 相關，其中許多 API 已由新版 API 取代。如需特定新的 API 的相關資訊，請參閱新 API 的說明文件。如要瞭解如何使用新版 API 授權要求，請參閱 Google 帳戶驗證與授權。

Google Data API 團隊 Jojo Hartmann
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 的一部分，但也可另外下載。它與其他用戶端程式庫類似，也是開放原始碼的設計，而且設計簡單又有效率，可讓您快速開始處理專案。

安裝前

您的開發機器或網路伺服器可能已安裝 PHP，因此第一步就是確認事實，並確認 PHP 版本夠新，足以用於用戶端程式庫。最簡便的做法是將新檔案放入伺服器的可網路存取目錄，在檔案中輸入下列資訊：

<?php phpinfo(); ?>

然後，請設定適當的權限，並且透過瀏覽器前往其位置，確認可以透過網路存取。如果已安裝 PHP 伺服器且伺服器能夠顯示 PHP 網頁，畫面應該會如以下螢幕截圖所示：

螢幕擷圖顯示 PHP 資訊頁面。此表展示了已安默的 PHP 版本（在本例中為 5.2.6），以及已添加的擴展（在“配置命令”部分中）和 PHP 的內部配置文件的位置（在“加電配置文件”部分）。如果顯示的頁面未顯示，或者您的 PHP 版本低於 5.1.4，則需要安裝或升級您的 PHP 版本。或者，您可以略過下一節，繼續安裝 PHP 用戶端程式庫。

附註：如果您可以存取指令列，且打算使用 PHP 執行指令列指令碼，請參閱本文的指令列 PHP 一節。

安裝 PHP

安裝作業會因平台而異，因此請務必按照特定平台的操作說明安裝。在深入探討之前，值得注意的是，包含 Apache 網路伺服器、MySQL 資料庫以及 PHP 資料庫的預先安裝套件也越來越受歡迎。Windows、Mac OS X 和 Linux 還有 XAMPP 專案。Mac OS X 使用者也可以選擇使用 MAMP 專案。這兩種套件都支援 PHP 中的 OpenSSL (這是與已驗證的動態消息互動的必要項目)，

如果您是按照以下步驟安裝 PHP，請確定你已安裝並啟用 OpenSSL 支援功能。詳情請參閱 PHP 網站的 OpenSSL 部分。以下各節著重於自行安裝 PHP。

Windows 使用者

如要在 Windows 上安裝或升級 PHP，最簡單的方法是使用 PHP 下載頁面提供的 PHP 安裝程式。

1. 選擇與最新版 PHP 相對應的 PHP 安裝程式選項 (位於 Windows 二進位檔部分)，然後允許下載。
2. 開啟安裝程式，然後按照安裝精靈的指示操作。
3. 精靈提示您時，請選擇系統上安裝的網路伺服器，讓伺服器能夠與 PHP 搭配運作。
4. 按照上一節列出的步驟檢查安裝狀態。

Mac OS X

PHP X 已納入 PHP，但是在使用之前，請先升級至最新版的 PHP。如要升級，您可以安裝多種免費二進位套件，或自行編譯。詳情請參閱 PHP 說明文件，瞭解 Mac OS X 的安裝方式。

安裝或設定 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 架構的一部分，但也可作為獨立版本下載。如果您已安裝 Zend Framework 版本 (1.6 以上版本)，可以略過安裝，因為內含 Google Data 用戶端程式庫。不過，請確認您使用的是最新的架構，可確保您擁有所有最新功能及錯誤修正。

下載完整架構不僅可讓您存取 Google Data 用戶端程式庫，還能存取其餘架構。用戶端程式庫本身會使用幾個其他類別，屬於整個 Zend Framework 的一部分，但您不必另外下載整個架構，因為我們將這些套件分別納入獨立的下載項目。

1. 下載 Google Data 用戶端程式庫檔案。(在該網頁中搜尋「Google Data API」)。
2. 解壓縮下載的檔案。建議您建立四個子目錄：
   • demos — 範例應用程式
   • documentation：用戶端程式庫檔案的說明文件
   • library：實際的用戶端程式庫來源檔案。
   • tests：適用於自動化測試的單元測試檔案。
3. 將 library 資料夾的位置新增到 PHP 路徑中 (請參閱下一節)

檢查並確認您可以存取用戶端程式庫檔案

最後一個步驟是，您可以參照建立專案所用的目錄，納入 PHP 用戶端程式庫檔案並納入其中。方法是在 PHP 設定檔 (php.ini) 中設定 include_path 變數。當您發出 require 或 include 陳述式並將外部類別、程式庫或檔案提取至目前的指令碼時，include_path 變數包含 PHP 會分析的目錄位置，與 Java 中的 import 陳述式類似。您必須將用戶端程式庫檔案的位置附加到 include_path 中已設定的項目。這有兩種做法 (以下將詳細說明這兩種方法)：

• 透過指令列在 php.ini 設定檔中永久設定 include_path 指令；您必須具備殼層權限與寫入權限。
• 在「按目錄」層級設定 include_path 路徑變數 — 需要 Apache 網路伺服器和建立 .htaccess 檔案的能力。
• 您可以使用 set_include_path() 函式，以動態方式設定指令碼中的 include 路徑；您可以在每個 .php 檔案中動態設定。

如果您擁有 php.ini 檔案的殼層存取權和寫入權限 (也可以在本機電腦上編寫程式碼)，只要按照「附錄 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 手冊。

如果您沒有伺服器的殼層存取權，但無法修改或建立 .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 安裝檢查工具

如要檢查 include 路徑設定是否正確，您可以執行 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 使用 Proxy 伺服器一文。您也可以參考這些說明文章，瞭解如何在 Linux 上安裝 XAMPP 及在 Windows 上安裝 XAMPP。除了上述文章外，請務必前往 Google Data API Tips 網誌查看 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 的路徑附加到現有的位置清單，並為您的 OS 指定新分隔符 (在 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 的指令列公用程式可稱為「命令列解譯器」。有了這個公用程式，您就可以透過指令列執行 php 指令碼。在某些情況下，如果您是在本機執行 PHP，並希望能夠快速測試某些指令碼，這個方法就非常實用。在您的伺服器上，當然需要殼層存取權。值得注意的是，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 建立連線。如果收到下列與下列內容類似的錯誤訊息，您可能需要透過安全的 Proxy 建立 HTTPS 連線：

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

您的主機供應商應提供要使用的 Proxy 伺服器實際位址資訊。下列程式碼片段展示如何將自訂 Proxy 設定與 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 = 'foo@example.com';
$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 的連結。
• 新增「提示與解決方案」附錄。