警告：本頁面介紹的是 Google 的舊版 API (Google Data API)，僅適用於Google Data API 目錄中列出的 API，其中許多 API 都已由新版 API 取代。如需特定新 API 的相關資訊，請參閱該 API 的說明文件。如要瞭解如何使用較新的 API 授權要求，請參閱「Google 帳戶驗證和授權」。
影片：觀看 Trevor Johns 逐步說明如何安裝用戶端程式庫、程式庫架構，以及程式碼逐步解說。
2008 年 10 月更新 (原作者為 Daniel Holevoet)
- 簡介
- 安裝前
- 安裝 PHP
- 安裝 Google Data 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)，以及已啟用的擴充功能 (位於「Configure Command」部分)，還有 PHP 內部設定檔的位置 (位於「Loaded Configuration File」部分)。如果未顯示該頁面，或 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 安裝程式。
- 選擇與最新版 PHP 相對應的 PHP 安裝程式選項 (位於 Windows 二進位檔部分)，並允許下載。
- 開啟安裝程式，然後按照安裝精靈的指示操作。
- 精靈提示時，請選擇系統上安裝的網路伺服器，以便設定伺服器與 PHP 搭配運作。
- 按照上述章節的步驟檢查安裝作業。
Mac OS X
OS 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 Framework 的一部分，但也可以下載獨立版本。如果已安裝 Zend Framework (1.6 以上版本)，則可略過安裝程序，因為 Google Data Client Library 隨附於 Zend Framework。不過，請務必使用最新版架構，確保能使用所有最新功能並修正錯誤，因此通常建議您這麼做。
下載完整架構後，您不僅能存取 Google 資料用戶端程式庫，還能存取架構的其餘部分。用戶端程式庫本身會使用完整 Zend Framework 的其他幾個類別，但我們已將這些類別併入獨立下載項目，因此您不必下載整個架構。
- 下載 Google Data Client Library 檔案。(在該頁面中搜尋「Google Data APIs」)。
- 將下載的檔案解壓縮。應建立四個子目錄：
demos- 範例應用程式documentation- 用戶端程式庫檔案的說明文件library：實際的用戶端程式庫來源檔案。tests- 自動化測試的單元測試檔案。
- 將
library資料夾的位置新增至 PHP 路徑 (請參閱下一節)
檢查是否可以存取用戶端程式庫檔案
最後一個步驟是確認您可以從建構專案的目錄參照及納入 PHP 用戶端程式庫檔案。方法是在 PHP 的設定檔 (php.ini) 中設定 include_path 變數。當您發出 require 或 include 陳述式，將外部類別、程式庫或檔案拉入目前的指令碼時，PHP 會查看 include_path 變數中的多個目錄位置，類似於 Java 中的 import 陳述式。您必須將用戶端程式庫檔案的位置附加至 include_path 中已設定的內容。您可以透過下列兩種方式達成此目的 (詳情請見下文)：
- 從指令列在
php.ini設定檔中永久設定include_path指令，這需要 Shell 存取權和寫入權限。 - 在「每個目錄」層級設定
include_path路徑變數，這需要 Apache 網路伺服器，以及建立.htaccess檔案的能力。 - 使用
set_include_path()函式在指令碼中動態設定包含路徑，可在每個 .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 安裝檢查程式
如要確認包含路徑是否設定正確，可以執行 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 執行這些範例。其餘範例可透過指令列和網頁瀏覽器執行。如要在瀏覽器中查看這些檔案，請將檔案放在您用來提供網頁的任何目錄中。這些範例應可讓您基本瞭解如何編寫及執行 Google Data 應用程式，但如果您想進一步瞭解，還有其他資源可供好奇的程式設計師參考。
注意：如要查看線上網頁式範例，請前往 googlecodesamples.com 尋找 PHP 應用程式。
其他資源
如要尋找用戶端程式庫中類別的相關資訊，最好的方法是前往 Zend Framework 網站上的 API 參考指南。請務必從下拉式選單中選取 Zend_Gdata 套件。
此時您應該已準備就緒，可以開始編寫程式碼。現在就開始撰寫出色的應用程式吧！期待看到您的成果！
您可以找到下列服務的 PHP 開發人員指南：
由於 PHP 用戶端程式庫是開放原始碼專案，因此會持續新增更多 API 的支援。每項服務都有專屬支援群組，請參閱常見問題條目，查看可用的支援群組清單。
如需 API 呼叫的疑難排解說明，請參閱使用網路流量擷取工具偵錯 API 要求，以及搭配 Google Data API 使用 Proxy 伺服器。此外，您也可以參閱這篇文章，瞭解如何在 Linux 上安裝 XAMPP，或參閱這篇文章，瞭解如何在 Windows 上安裝 XAMPP。除了這些文章，也請務必查看 Google Data API 提示網誌上關於 PHP 用戶端程式庫的文章。
附錄 A：在 php.ini 設定檔中編輯 PHP 路徑
PHP 路徑是變數，其中包含 PHP 在載入期間尋找其他程式庫時搜尋的位置清單。如要讓 PHP 載入及存取電腦或伺服器上的 Google Data PHP 用戶端程式庫檔案，必須將這些檔案放在 PHP 知道的位置。或者，您必須將檔案位置附加至 PHP 路徑。請注意，變更 php.ini 檔案通常需要重新啟動伺服器。如要隨時確認 include_path 變數的目前值，請前往稍早討論的 PHP 資訊頁面。在第一個表格中尋找「已載入的設定檔」儲存格，並在右側欄中找出路徑。
注意：如果您發現自己是透過指令列使用 PHP，可能需要修改其他路徑變數。請務必參閱附錄 B：透過指令列使用 PHP。
找到 php.ini 檔案後，請按照下列步驟將其附加至路徑。
- 使用偏好的文字編輯器開啟
php.ini檔案。 - 找出參照 PHP 路徑的行，開頭應為
include_path。 - 將儲存 Zend Framework 的路徑附加至現有的位置清單，並在新的路徑前加上作業系統的指定分隔符號 (Unix 類系統為
:，Windows 為;)。在類 Unix 系統上，正確路徑看起來會像這樣：/path1:/path2:/usr/local/lib/php/library
\path1;\path2;\php\library
- 儲存並關閉檔案。
注意：在 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 網站所述。如要修正這個問題，請確認 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 伺服器實際位址資訊。下列程式碼片段示範如何搭配 PHP 用戶端程式庫使用自訂 Proxy 設定：
// 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 的連結。
- 新增「提示和解答」附錄。