2007 年 9 月
簡介
以不熟悉的 API 開始開發工作並不容易,因此本文將逐步說明如何下載並安裝 Google Data API (「GData」) Java 用戶端程式庫。我會逐一說明所有依附元件,並設定您需要的環境變數。您將立即擁有不同的 GData 服務!
您使用 Eclipse 嗎?
請參閱程式設計方面的程式設計:將 Eclipse 與 Google Data API 搭配使用一文。
安裝依附元件
GData Java 用戶端程式庫包含下列外部依附元件。以下各節將說明如何在您偏好的作業系統 (或工作停滯的作業系統) 上安裝這些依附元件。
- JDK (Java Development Kit) 1.5 以上版本
- Apache Ant 1.7 以上版本
- Sun 的 JavaMail API 1.4 以上版本中的 mail.jar
- 使用 Sun.Java 的啟用啟用架構。對媒體專用 API (包括 Document List Data API、Picasa Web Album API 和 YouTube Data API) 而言,這是必要步驟。
- Sun 的 Servlet API 2.3 以上版本中的 Servlet.jar。只有在「sample.authsub」或「sample.gbase.recipe」套件中執行程式碼範例時,才需要使用這個值。
某些範例只需要使用 .jar
依附元件,但為了避免建構錯誤,最好只取得所有內容。請選擇您偏好的作業系統:Windows、Mac OS X 或 Linux。
安裝 Google Data 用戶端程式庫
- 前往 http://code.google.com/p/gdata-java-client/downloads/list。
- 下載最新版本的用戶端程式庫 (
gdata-src.java-1.x.x.java.zip
) 和範例 (gdata-samples.java-1.x.x.java.zip
)。 - 將用戶端程式庫來源解壓縮到您的電腦。
- 前往
gdata/java/build-src/build.properties
並開啟檔案。 - 編輯外部依附元件,指向本機電腦上的
.jar
檔案位置。
注意:在 Windows 中,請務必以反斜線來逸出逸出。例如:
servlet.jar=C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0\\lib\\servlet-api.jar
執行範例
所有可用樣本都位於 gdata-samples.java-1.x.x.java.zip
封存檔的 gdata/java/sample
下。gdata/java/build-samples/build.properties
檔案包含程式庫內範例的所有輸入值。將 sample.credentials.username
和 sample.credentials.password
設為有效的使用者名稱和密碼。我們可以使用 Ant 來建構和執行範例。
開啟命令提示字元並變更為 gdata/java
目錄,然後輸入:
ant -f build-samples.xml sample.calendar.run
您可能會收到一些資訊或警告訊息,但都可以在結尾處尋找 BUILD SUCCESSFUL
訊息!如果沒有收到成功訊息,請參閱疑難排解一節。
輸入:
ant -f build-samples.xml sample.spreadsheet.guidemo.run
如要瞭解如何執行特定範例,請前往 gdata/java/build-samples
並查看該範例的建構檔案。找到 samples run
區段。
疑難排解
如果您的建構失敗,並出現下列錯誤訊息:
BUILD FAILED Target 'core.sample.core.util.build' does not exist in this project. It is used from target 'sample.calendar.build'. Total time: 0 seconds
或者,如果專案中出現必需的錯誤訊息,則可能是舊版的 Ant。輸入 ant -version
,以確定您執行的是 1.7 以上版本。如要取得最新版本的 Ant,請參閱上方的依附元件操作說明。
打造您自己的應用程式
下一個問題是如何建構自己的應用程式。我將透過「Google 日曆」服務完成「Hello, World!」對等程式,呈現基本功能。如需更詳細的資訊,請參閱 Java 用戶端程式庫的開發人員指南,以及個別產品的開發人員指南。
建立名為 CalendarTest.java 的檔案。首先,加入下列匯入陳述式。
import com.google.gdata.client.*; import com.google.gdata.client.calendar.*; import com.google.gdata.data.*; import com.google.gdata.data.acl.*; import com.google.gdata.data.calendar.*; import com.google.gdata.data.extensions.*; import com.google.gdata.util.*; import java.net.*; import java.io.*; import sample.util.*;
此為整個程式 (沒有任何例外狀況處理)。
public class CalendarTest { public static void main(String[] args) { CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0"); myService.setUserCredentials("[email protected]", "pa$$word"); URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full"); CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class); System.out.println("Your calendars:"); System.out.println(); for (int i = 0; i < resultFeed.getEntries().size(); i++) { CalendarEntry entry = resultFeed.getEntries().get(i); System.out.println("\t" + entry.getTitle().getPlainText()); } } }
This little program will request all the calendars you own and display all the titles. It's a little longer than the canonical "Hello, World!" example, but it's very simple once we break it down. The first couple of lines creates a service object and sets the user credentials.
CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0"); myService.setUserCredentials("[email protected]", "pa$$word");
然後設定資源的網址。在這種情況下,您可以向已驗證使用者要求所有日曆的清單。
URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");
以下這行程式碼會在 URL 上執行實際的 GET
指令,並將最終的資訊提供放入一個潮濕的物件中。
CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);
下方的 for
迴圈會疊代每個項目並列印標題。請注意,系統會將標題儲存為 TextConstruct
,因此必須另外呼叫函式才能取得純文字。
for (int i = 0; i < resultFeed.getEntries().size(); i++) { CalendarEntry entry = resultFeed.getEntries().get(i); System.out.println("\t" + entry.getTitle().getPlainText()); }
還有一些基本概念 - 我們來看看一些其他的常見事。下列程式碼片段說明如何建立並插入物件。本例將使用新的日曆活動。
URL postURL = new URL("http://www.google.com/calendar/feeds/[email protected]/private/full"); CalendarEventEntry myEvent = new CalendarEventEntry(); //Set the title and description myEvent.setTitle(new PlainTextConstruct("Pi Day Party")); myEvent.setContent(new PlainTextConstruct("I am throwing a Pi Day Party!")); //Create DateTime events and create a When object to hold them, then add //the When event to the event DateTime startTime = DateTime.parseDateTime("2007-03-14T15:00:00-08:00"); DateTime endTime = DateTime.parseDateTime("2007-03-14T17:00:00-08:00"); When eventTimes = new When(); eventTimes.setStartTime(startTime); eventTimes.setEndTime(endTime); myEvent.addTime(eventTimes); // POST the request and receive the response: CalendarEventEntry insertedEntry = myService.insert(postURL, myEvent);
另一個常見作業是建立查詢。
//Create a new query object and set the parameters Query myQuery = new Query(feedURL); myQuery.setFullTextQuery("Pi"); //Send the request with the built query URL CalendarEventFeed myResultsFeed = myService.query(myQuery, CalendarEventFeed.class); //Take the first match and print the title if (myResultsFeed.getEntries().size() > 0) { CalendarEventEntry firstMatchEntry = new CalendarEventEntry(); myResultsFeed.getEntries().get(0); System.out.println(firstMatchEntry.getTitle().getPlainText()); }
進行偵錯時,另一個實用的作業就是排除原始 XML。您可以在程式庫中使用便利的公用程式。確認已匯入 samples.util.*
。再載入動態消息或項目。
CommonUtils.dump(resultFeed, System.out);
如需更完整的偵錯工具,請參閱我們的偵錯 Google Data API 用戶端:在程式中探索流量一文,瞭解如何在用戶端程式庫中啟用記錄功能。
這可以讓您瞭解使用用戶端程式庫建構應用程式的感覺如何。詳情請參閱結論部分,瞭解每個 Google Data API 提供的開發人員指南。
結語
希望您現在能使用 GData Java 用戶端程式庫建構並執行應用程式!我沒有找到您可以使用的熱門任何 IDE,但建議您參考 Eclipse 或 NetBeans 等熱門的工具。以下是一些可能有用的連結:
- GData Java 用戶端程式庫首頁
- Google Data API 清單
- Java 開發人員指南適用於下列 Google Data API:
- 著色於程式設計:將 Eclipse 與 Google Data API 搭配使用
- Google Data API Java 用戶端 Eclipse 外掛程式
如果您在使用任何 API 時搭配 Java 用戶端程式庫使用 API 有任何疑問,可以在 API 專屬的論壇中發文提問。