開始使用 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 依附元件，但為了避免建構錯誤，最好只取得所有內容。請選擇您偏好的作業系統：Windows、Mac OS X 或 Linux。

安裝 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.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("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，但建議您參考 Eclipse 或 NetBeans 等熱門的工具。以下是一些可能有用的連結：

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