使用 Java 用戶端程式庫

本文說明如何使用 Java 用戶端程式庫傳送 Google Data API (簡稱「GData」) 查詢，以及解讀傳回的回應。

Google 提供多種程式設計語言的用戶端程式庫，可與具有資料 API 的服務互動。您可以使用這些程式庫建構 GData 要求、傳送至服務，並接收回應。

本文提供使用 Java 用戶端程式庫的一般資訊，以及常見用途的範例。

如要使用這個用戶端程式庫，您必須執行 Java 1.5。

下載 Java 用戶端程式庫。

本指南的範例是指 Google Calendar API，但本指南並非使用 Calendar API 的正確或最新指南。如要瞭解如何搭配特定服務的 Data API 使用 Java 用戶端程式庫，請參閱該服務的專屬說明文件。舉例來說，如果您使用 Google 日曆，請參閱「Google 日曆資料 API 開發人員指南」。

目錄

  1. 觀眾
  2. 資料模型總覽
  3. 教學課程和範例
    1. 建構及執行用戶端
    2. 要求提供動態消息
    3. 插入新項目
    4. 要求特定項目
    5. 搜尋項目
    6. 依類別查詢
    7. 更新項目
    8. 刪除項目
  4. 參考資料

觀眾

本文適用於想編寫可與 GData 服務互動的用戶端應用程式的 Java 程式設計師。

本文假設您瞭解 Google Data APIs 通訊協定背後的一般概念。並假設您瞭解如何使用 Java 程式設計。

如要瞭解用戶端程式庫提供的類別和方法，請參閱 Java 用戶端程式庫 API 參考資料 (Javadoc 格式)。

建議依序閱讀本文，因為每個範例都以先前的範例為基礎。

資料模型總覽

Java 用戶端程式庫會使用一組類別，代表 Google Data API 使用的元素。舉例來說，Feed 類別對應於 <atom:feed> 元素，其中包含建立項目、取得及設定各種子元素值等方法。此外，還有對應 <atom:entry> 元素的 Entry 類別。Google Data API 中定義的每個元素不一定都有自己的類別，詳情請參閱參考說明文件。

這個程式庫可以自動剖析 Atom 內容，並將 Atom 元素的值放入適當的物件。舉例來說，getFeed 方法會取得動態饋給、剖析動態饋給，並傳回含有結果值的 Feed 物件。

如要將動態消息或項目傳送至服務，請建立 Feed 或 Entry 物件，然後呼叫程式庫方法 (例如 insert 方法)，自動將物件轉換為 XML 並傳送。

您也可以自行剖析及/或產生 XML，最簡單的方法是使用適當的第三方程式庫，例如 Rome。

如同 Google Data API 的 XML 語法可擴充，對應的物件模型也可擴充。舉例來說，用戶端程式庫會提供與 Google Data 命名空間中定義的元素對應的類別。

教學課程和範例

以下範例說明如何使用 Java 用戶端程式庫傳送各種 Data API 要求。

為使這些範例更具體，我們將說明如何與特定服務 (Google 日曆) 互動。我們會指出 Google 日曆與其他 Google 服務的不同之處，協助您調整這些範例，以便用於其他服務。如要進一步瞭解 Google 日曆，請參閱 Google Calendar Data API 說明文件。

建構及執行用戶端

如要編譯本文件中的範例，請使用下列匯入陳述式：

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

要求動態消息

如「Google 日曆資料 API」文件所述，您可以將下列 HTTP 要求傳送至日曆，要求日曆動態消息：

GET http://www.google.com/calendar/feeds/userID/private/full

當然，您必須將 userID 替換成使用者的電子郵件地址；詳情請參閱 Google 日曆文件。您可以改用與 Google 日曆互動的特殊預設網址 (如 Google 日曆文件所述)，但本文將使用包含使用者 ID 的私人完整動態饋給網址。

您也必須提供適當的驗證資訊。這個範例與 Google 日曆文件中的第一個範例主要有以下差異：(1) 這個範例包含驗證，以及 (2) 這個範例使用較通用的 GoogleService 類別，而非 Calendar 專用的 CalendarService 類別。

請注意，我們在此使用的驗證系統 (稱為「已安裝應用程式的 Google 驗證」) 僅適用於已安裝的用戶端應用程式 (例如電腦版用戶端)，不適用於網頁應用程式。如要進一步瞭解驗證，請參閱「Google 帳戶驗證」說明文件。

如要使用 Java 用戶端程式庫要求日曆動態消息，請針對電子郵件地址為「liz@gmail.com」且密碼為「mypassword」的使用者，使用下列程式碼：

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

GoogleService 類別代表用戶端與 GData 服務的連線 (含驗證)。使用用戶端程式庫將查詢傳送至服務的一般程序包含下列步驟：

  1. 取得或建構適當的網址。
  2. 如果您要將資料傳送至服務 (例如插入新項目)，請使用用戶端程式庫類別將原始資料轉換為物件。(如果您只是要求動態饋給，則不適用這個步驟，如本例所示)。
  3. 建立新的 GoogleService 執行個體，設定服務名稱 (例如日曆的 "cl") 和應用程式名稱 (格式為 companyName-applicationName-versionID)。
  4. 設定適當的憑證。
  5. 向用戶端程式庫指出動態饋給將使用的擴充功能，以便程式庫正確剖析傳回的動態饋給。
  6. 呼叫方法來傳送要求並接收任何結果。

setUserCredentials 方法會指定使用者 ID 和密碼，您的用戶端會代表該使用者傳送查詢。本文範例使用「已安裝應用程式的驗證」驗證系統；如要進一步瞭解驗證系統，請參閱 Google 帳戶驗證說明文件。

設定憑證後，請呼叫 declareExtensions 方法，指明動態饋給要使用的擴充功能。在本例中，我們表示動態饋給是「活動」動態饋給，因此會使用「活動類型」定義的擴充功能。

如要要求整個動態消息，請呼叫 getFeed 方法，這個方法會採用網址，並傳回該網址中找到的整個動態消息。本文稍後會說明如何傳送更具體的查詢。

與 GoogleService 類別的其他方法一樣，getFeed 會視需要處理驗證和重新導向。

插入新項目

如要建立新的日曆活動，可以使用下列程式碼：

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

設定網址後，我們會建構 EventEntry 物件；EventEntry 是衍生自抽象基本類別 BaseEntry，也是 Entry 類別的父項類別，代表 <atom:entry> 元素。

EventEntry 類別代表事件種類，詳情請參閱種類文件。如果是日曆以外的服務，您可能會將傳回的項目指派給 Entry 物件，而非 EventEntry 物件。

項目標題是 TextConstruct，這個類別會以各種形式 (純文字、HTML 或 XHTML) 保存文字。項目內容以 Content 物件表示，這個類別可保留純文字或其他形式的內容，包括 XML 和二進位資料。(但 setContent 方法也可以接受 TextConstruct)。

每位作者都會以名稱、URI 和電子郵件地址表示。(在本範例中，我們省略了 URI)。如要將作者新增至項目，請呼叫項目的 getAuthors().add 方法。

我們使用在上一個範例中建立的相同 GoogleService 物件。在這種情況下，要呼叫的方法是 insert，這個方法會將項目傳送至指定的插入網址。

服務會傳回新建立的項目，其中可能包含其他伺服器產生的元素，例如項目的編輯網址。

HTTP 狀態碼會以例外狀況的形式傳回。

上述程式碼等同於傳送 POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (須通過適當驗證)，並以 Event 類別的形式提供項目。

要求特定項目

您可以使用下列程式碼，要求先前範例中插入的特定項目。

在本系列範例中，由於日曆已傳回插入的項目，因此其實不需要擷取該項目；但只要知道項目的 URI，就能套用相同技術。

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

插入的項目具有 getSelfLink 方法，可傳回包含項目網址的 Link 物件。Link 類別有一個 getHref 方法，會以 String 形式傳回網址，我們可以從中建立網址物件。

接著，我們只需要呼叫服務的 getEntry 方法即可取得項目。

請注意，我們將 EventEntry.class 做為參數提供給 getEntry，表示我們特別希望服務傳回 Event，而不只是純粹的項目。如果是日曆以外的服務，您可能只需要傳遞 Entry.class。

上述程式碼等同於將 GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID 傳送至 Google 日曆，並完成適當的驗證。

搜尋項目

如要從全文搜尋中擷取第一個相符項目，請使用下列程式碼：

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

這個範例首先會建構 Query 物件，其中大部分是網址和相關聯的查詢參數。每個標準 GData 查詢參數都有 setter 方法。您也可以使用 addCustomParameter 方法，為特定服務設定自訂查詢參數。

建構 Query 後，我們會將其傳遞至服務的 query 方法，該方法會傳回含有查詢結果的動態消息。另一種做法是自行建構網址 (將查詢參數附加至動態饋給網址)，然後呼叫 getFeed 方法，但 query 方法提供實用的抽象層，因此您不必自行建構網址。

動態饋給的 getEntries 方法會傳回動態饋給中的項目清單；getEntries().size 則會傳回動態饋給中的項目數。

在本例中，如果查詢傳回任何結果，我們會將第一個相符結果指派給 Entry 物件。接著，我們使用 Entry 類別的 getTitle().getPlainText 方法擷取項目的標題，並轉換為文字。

上述程式碼等同於將 GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis 傳送至 Google 日曆。

依類別查詢

注意：Google 日曆不會將標籤與活動建立關聯，因此這個範例不適用於日曆。

如要擷取動態消息，其中包含與先前全文搜尋相符的所有項目，且這些項目屬於特定類別或具有特定標籤，請使用下列程式碼：

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

當然，Category 類別代表要用於類別篩選器的類別。Query.CategoryFilter 類別可以包含多個類別，但在這個情況下，我們只會建構一個類別的篩選器。

接著，我們將該篩選器新增至現有查詢，其中仍包含上一個範例中的全文查詢字串。

我們再次使用 query 方法將查詢傳送至服務。

如果日曆允許類別搜尋，上述程式碼就等同於將 GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis 傳送至日曆。

更新項目

如要更新現有項目，請使用下列程式碼。在這個範例中，我們將先前擷取的項目標題從舊文字「Tennis with Darcy」變更為「Important meeting」。

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

首先，我們為先前擷取的項目設定新標題。然後，我們使用 getEditLink 方法取得項目的編輯網址。接著，我們會呼叫服務的 update 方法，傳送更新後的項目。

服務會傳回更新後的項目，包括這個項目新版本的網址。(如要進一步瞭解項目版本，請參閱通訊協定參考文件的「樂觀並行」一節。)

上述程式碼大致等同於將 PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID 連同新項目 (Atom 格式) 送至服務，以取代原始項目。

刪除項目

如要刪除更新後的項目，請使用下列程式碼：

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

用於刪除的網址與編輯網址相同，因此這個範例與上一個範例非常相似，但我們呼叫的是 delete 方法，而不是 update。

上述程式碼大致等同於將 DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID 傳送至服務。

參考資料

如要瞭解用戶端程式庫提供的類別和方法，請參閱 Java 用戶端程式庫 API 參考資料 (Javadoc 格式)。

返回頁首