警告:本頁面說明 Google 的舊版 API (即 Google Data API);該 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 資訊頁面螢幕截圖](https://developers.google.cn/static/gdata/images/phpinfo.png?authuser=19&hl=zh-tw)
螢幕擷圖顯示 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 安裝程式。
- 選擇與最新版 PHP 相對應的 PHP 安裝程式選項 (位於 Windows 二進位檔部分),然後允許下載。
- 開啟安裝程式,然後按照安裝精靈的指示操作。
- 精靈提示您時,請選擇系統上安裝的網路伺服器,讓伺服器能夠與 PHP 搭配運作。
- 按照上一節列出的步驟檢查安裝狀態。
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 的一部分,但您不必另外下載整個架構,因為我們將這些套件分別納入獨立的下載項目。
- 下載 Google Data 用戶端程式庫檔案。(在該網頁中搜尋「Google Data API」)。
- 解壓縮下載的檔案。建議您建立四個子目錄:
demos
— 範例應用程式documentation
:用戶端程式庫檔案的說明文件library
:實際的用戶端程式庫來源檔案。tests
:適用於自動化測試的單元測試檔案。
- 將
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 安裝檢查工具輸出螢幕截圖](https://developers.google.cn/static/gdata/images/install_checker_ok.png?authuser=19&hl=zh-tw)
如果你看到錯誤 (如下方的螢幕截圖所示),請務必按照上述指示操作。可能是因為缺少擴充功能,或是您的路徑設定可能有誤。請注意,您可能需要重新啟動伺服器,變更才會生效。只有在實際修改 php.ini
檔案時,才適用這個選項。以下螢幕截圖顯示 include_path
已設為 /path/to/nowhere
:
![PHP 安裝檢查工具輸出螢幕截圖](https://developers.google.cn/static/gdata/images/install_checker_error.png?authuser=19&hl=zh-tw)
注意:請注意,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 開發人員指南:
由於 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
檔案後,請按照下列步驟附加到路徑中。
- 使用您偏好的文字編輯器開啟
php.ini
檔案。 - 找出參照 PHP 路徑的那一行,該路徑的開頭應為
include_path
。 - 將您儲存 Zend Framework 的路徑附加到現有的位置清單,並為您的 OS 指定新分隔符 (在 Unix 類似系統上為
:
,在 Windows 上則為;
)。類似 Unix 系統的正確路徑看起來會像這樣:/path1:/path2:/usr/local/lib/php/library
Windows 上的程式碼看起來會像這樣:\path1;\path2;\php\library
- 儲存並關閉檔案。
注意:在 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 的連結。
- 新增「提示與解決方案」附錄。