使用 Java 用戶端程式庫

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

Google 提供一組支援多種程式設計語言的用戶端程式庫，可用於與擁有資料 API 的服務互動。透過這些程式庫，您可以建構 GData 要求、將要求傳送至服務以及接收回應。

本文件提供 Java 用戶端程式庫的一些一般資訊，並提供一系列常見用途範例。

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

下載 Java 用戶端程式庫。

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

目錄

  1. 觀眾
  2. 資料模型總覽
  3. 教學課程與範例
    1. 建立並執行用戶端
    2. 要求動態饋給
    3. 插入新項目
    4. 要求特定項目
    5. 搜尋項目
    6. 依類別查詢
    7. 更新項目
    8. 刪除項目
  4. Reference

目標對象

本文件旨在協助 Java 程式設計師撰寫用戶端應用程式，以便與 GData 服務互動。

本文假設您已瞭解 Google Data API 通訊協定背後的一般概念。同時假設您知道如何在 Java 中編寫程式。

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

這份文件是按順序閱讀，每個範例都是以先前的範例為基礎。

資料模型總覽

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

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

如要將資訊提供或項目傳送至服務，請先建立資訊提供或項目，然後呼叫程式庫方法 (如 insert 方法)，自動將物件轉譯為 XML 並傳送。

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

就像 Google Data API 的 XML 語法一樣可以擴充，對應的物件模型也可擴充。例如，用戶端程式庫提供與 Google Data 命名空間中定義的元素相對應的類別。

教學課程與範例

下列範例說明如何使用 Java 用戶端程式庫傳送各種資料 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 Calendar Data API 文件所述，您可以透過傳送 HTTP 要求至 Google 日曆來要求日曆資訊提供：

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

當然，您必須將 userID 替換為使用者的電子郵件地址。詳情請參閱 Google 日曆的文件。您可以改用「Google 日曆」的特殊預設網址 (如 Google 日曆文件中所述) 操作，但是在這份文件中，我們會使用包含使用者 ID 的私人完整資訊提供網址。

您也必須提供適當的驗證機制。這個範例與 Google 日曆文件的第一個範例的主要差別在於：(1) 此範例包含驗證機制，並且 (2) 此範例使用較為一般的 GoogleService 類別，而非日曆專用的 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 例項，設定服務名稱 (例如 Google 日曆的 "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 類別代表事件種類；詳情請參閱 Kinds 文件。如果是日曆以外的服務，您可以將傳回的項目指派給 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 (具備適當驗證機制) 及以事件種類提供項目。

要求特定項目

以下程式碼可讓您要求您在上一個範例中插入的特定項目。

在這個系列的範例中，您不一定要擷取該項目，因為 Google 日曆已經傳回插入的項目，但是只要您知道項目的 URI，就可以套用相同的技巧。

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

插入的項目具有 getSelfLink 方法，可傳回包含該項目網址的 Link 物件。Link 類別的 getHref 方法會傳回 String 網址，我們可以藉此建立網址物件。

接下來，您必須呼叫服務的 getEntry 方法以取得項目。

請注意，我們將 EventEntry.class 做為 getEntry 的參數，指出我們預期服務會傳回事件，而不是單純傳回一個項目。如果是 Google 日曆以外的服務，您可以改為傳送 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 日曆不會為標籤與活動建立關聯，因此這個範例不支援 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 方法將查詢傳送至服務。

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

更新項目

如要更新現有項目，請使用下列程式碼。在這個範例中，我們會將先前擷取的項目標題從舊的文字 (「網球與達西隊」) 變更為「重要會議」。

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 格式)。

返回頁首