開始使用 Google Data Java 用戶端程式庫

Stephanie Liu,Google Data API 團隊
2007 年 9 月
  1. 說明
  2. 安裝依附元件
    1. Windows
    2. Mac OS X
    3. Linux
  3. 安裝 Google Data 用戶端程式庫
  4. 執行範例
  5. 建構您自己的應用程式
  6. 結語
  7. 附錄:設定環境變數

簡介

以不熟悉的 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 依附元件,但為了避免建構錯誤,最好只取得所有內容。請選擇您偏好的作業系統:WindowsMac OS XLinux

安裝 Google Data 用戶端程式庫

  1. 前往 http://code.google.com/p/gdata-java-client/downloads/list
  2. 下載最新版本的用戶端程式庫 (gdata-src.java-1.x.x.java.zip) 和範例 (gdata-samples.java-1.x.x.java.zip)。
  3. 將用戶端程式庫來源解壓縮到您的電腦。
  4. 前往 gdata/java/build-src/build.properties 並開啟檔案。
  5. 編輯外部依附元件,指向本機電腦上的 .jar 檔案位置。
  6. 注意:在 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.usernamesample.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("root@gmail.com", "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("root@gmail.com", "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/root@gmail.com/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,但建議您參考 EclipseNetBeans 等熱門的工具。以下是一些可能有用的連結:

如果您在使用任何 API 時搭配 Java 用戶端程式庫使用 API 有任何疑問,可以在 API 專屬的論壇中發文提問。