Tài liệu này mô tả cách sử dụng thư viện ứng dụng Java để gửi các truy vấn Google Data API ("GData") và diễn giải các phản hồi được trả về.
Google cung cấp một bộ thư viện ứng dụng bằng nhiều ngôn ngữ lập trình để tương tác với các dịch vụ có API dữ liệu. Khi sử dụng các thư viện này, bạn có thể tạo yêu cầu GData, gửi yêu cầu đó đến một dịch vụ và nhận phản hồi.
Tài liệu này cung cấp một số thông tin chung về cách sử dụng thư viện ứng dụng Java, cùng với một bộ ví dụ về các trường hợp sử dụng phổ biến.
Để sử dụng thư viện ứng dụng này, bạn phải chạy Java 1.5.
Tải thư viện ứng dụng Java xuống.
Các ví dụ trong hướng dẫn này đề cập đến API Lịch Google, nhưng hướng dẫn này không phải là hướng dẫn chính xác hoặc mới nhất về cách sử dụng API Lịch. Để biết thông tin về cách sử dụng thư viện ứng dụng Java với Data API của một dịch vụ cụ thể, hãy xem tài liệu dành riêng cho dịch vụ đó. Ví dụ: nếu bạn đang làm việc với Lịch, hãy đọc Hướng dẫn dành cho nhà phát triển API Dữ liệu Lịch.
Nội dung
Đối tượng
Tài liệu này dành cho những lập trình viên Java muốn viết các ứng dụng có thể tương tác với các dịch vụ GData.
Tài liệu này giả định rằng bạn hiểu những ý tưởng chung đằng sau giao thức API Dữ liệu của Google. Phần này cũng giả định rằng bạn biết cách lập trình bằng Java.
Để biết thông tin tham khảo về các lớp và phương thức do thư viện ứng dụng cung cấp, hãy xem tài liệu tham khảo về API thư viện ứng dụng Java (ở định dạng Javadoc).
Bạn nên đọc tài liệu này theo thứ tự; mỗi ví dụ đều dựa trên các ví dụ trước đó.
Tổng quan về mô hình dữ liệu
Thư viện ứng dụng Java sử dụng một nhóm các lớp để biểu thị các phần tử mà Google Data API sử dụng. Ví dụ: có một lớp Feed (Nguồn cấp dữ liệu) tương ứng với phần tử <atom:feed>; lớp này có các phương thức để tạo một mục, nhận và đặt giá trị của nhiều phần tử con, v.v. Ngoài ra còn có lớp Entry, tương ứng với phần tử <atom:entry>. Không phải phần tử nào được xác định trong Google Data API cũng có lớp riêng; để biết thông tin chi tiết, hãy xem tài liệu tham khảo.
Thư viện này có thể tự động phân tích cú pháp nội dung Atom và đặt các giá trị của phần tử Atom vào các đối tượng thích hợp. Ví dụ: phương thức getFeed nhận một nguồn cấp dữ liệu, phân tích cú pháp và trả về một đối tượng Nguồn cấp dữ liệu có các giá trị kết quả.
Để gửi một nguồn cấp dữ liệu hoặc mục nhập đến một dịch vụ, bạn tạo một đối tượng Nguồn cấp dữ liệu hoặc Mục nhập, sau đó gọi một phương thức thư viện (chẳng hạn như phương thức insert) để tự động dịch đối tượng thành XML và gửi đối tượng đó.
Bạn có thể tự phân tích cú pháp và/hoặc tạo XML nếu muốn; cách dễ nhất để làm việc đó là sử dụng một thư viện thích hợp của bên thứ ba, chẳng hạn như Rome.
Tương tự như cú pháp XML của Google Data API có thể mở rộng, mô hình đối tượng tương ứng cũng có thể mở rộng. Ví dụ: thư viện ứng dụng cung cấp các lớp tương ứng với các phần tử được xác định trong không gian tên Dữ liệu của Google.
Hướng dẫn và ví dụ
Các ví dụ sau đây minh hoạ cách gửi nhiều yêu cầu API dữ liệu bằng thư viện ứng dụng Java.
Để cụ thể hơn, những ví dụ này cho thấy cách tương tác với một dịch vụ cụ thể: Lịch Google. Chúng tôi sẽ chỉ ra những điểm khác biệt giữa Lịch và các dịch vụ khác của Google để giúp bạn điều chỉnh những ví dụ này cho phù hợp với các dịch vụ khác. Để biết thêm thông tin về Lịch, hãy xem tài liệu về Google Calendar Data API.
Tạo và chạy ứng dụng
Để biên dịch các ví dụ trong tài liệu này, bạn cần sử dụng các câu lệnh nhập sau:
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;
Yêu cầu nguồn cấp dữ liệu
Như mô tả trong tài liệu API Dữ liệu Lịch Google, bạn có thể yêu cầu một nguồn cấp dữ liệu Lịch bằng cách gửi yêu cầu HTTP sau đến Lịch:
GET http://www.google.com/calendar/feeds/userID/private/full
Tất nhiên, bạn phải thay thế userID bằng địa chỉ email của người dùng; hãy xem tài liệu Lịch để biết thông tin chi tiết. Thay vào đó, bạn có thể sử dụng URL mặc định đặc biệt để tương tác với Lịch (như mô tả trong tài liệu Lịch), nhưng trong tài liệu này, chúng ta sẽ sử dụng URL nguồn cấp dữ liệu riêng tư đầy đủ có chứa mã nhận dạng người dùng.
Bạn cũng phải cung cấp phương thức xác thực phù hợp. Điểm khác biệt chính giữa ví dụ này và ví dụ đầu tiên trong tài liệu Lịch là (1) ví dụ này bao gồm cả quy trình xác thực và (2) ví dụ này sử dụng lớp GoogleService chung hơn thay vì lớp CalendarService dành riêng cho Lịch.
Xin lưu ý rằng hệ thống xác thực mà chúng ta đang sử dụng ở đây (được gọi là "Xác thực của Google cho các ứng dụng đã cài đặt") chỉ phù hợp để sử dụng trong các ứng dụng khách đã cài đặt (chẳng hạn như ứng dụng khách dành cho máy tính), chứ không phù hợp để sử dụng trong các ứng dụng web. Để biết thêm thông tin về quy trình xác thực, hãy xem tài liệu Xác thực tài khoản Google.
Để yêu cầu một nguồn cấp dữ liệu Lịch bằng thư viện ứng dụng Java, đối với người dùng có địa chỉ email "liz@gmail.com" và mật khẩu "mypassword", hãy sử dụng mã sau:
// 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);
Lớp GoogleService biểu thị một kết nối ứng dụng (có xác thực) với dịch vụ GData. Quy trình chung để gửi truy vấn đến một dịch vụ bằng thư viện ứng dụng bao gồm các bước sau:
- Lấy hoặc tạo URL phù hợp.
- Nếu bạn đang gửi dữ liệu đến một dịch vụ (ví dụ: nếu bạn đang chèn một mục mới), hãy chuyển đổi dữ liệu thô thành các đối tượng bằng cách sử dụng các lớp thư viện ứng dụng. (Bước này không áp dụng nếu bạn chỉ yêu cầu một nguồn cấp dữ liệu, như chúng ta đang làm trong ví dụ này.)
- Tạo một thực thể
GoogleServicemới, đặt tên dịch vụ (chẳng hạn như"cl"cho Lịch) và tên ứng dụng của bạn (dưới dạngcompanyName-applicationName-versionID). - Đặt thông tin đăng nhập phù hợp.
- Cho thư viện ứng dụng biết những tiện ích mà nguồn cấp dữ liệu sẽ sử dụng, để thư viện có thể phân tích cú pháp chính xác các nguồn cấp dữ liệu được trả về.
- Gọi một phương thức để gửi yêu cầu và nhận mọi kết quả.
Phương thức setUserCredentials chỉ định mã nhận dạng và mật khẩu của người dùng mà thay mặt cho người đó, ứng dụng khách của bạn đang gửi truy vấn. Các ví dụ trong tài liệu này sử dụng hệ thống xác thực "Xác thực cho các ứng dụng đã cài đặt"; để biết thêm thông tin về hệ thống xác thực, hãy xem tài liệu Xác thực Tài khoản Google.
Sau khi thiết lập thông tin đăng nhập, bạn cho biết nguồn cấp dữ liệu sẽ sử dụng những tiện ích nào bằng cách gọi phương thức declareExtensions. Trong trường hợp này, chúng ta đang nói rằng nguồn cấp dữ liệu là nguồn cấp dữ liệu Sự kiện, do đó, nguồn cấp dữ liệu này sẽ sử dụng các tiện ích do loại Sự kiện xác định.
Để yêu cầu toàn bộ nguồn cấp dữ liệu, bạn gọi phương thức getFeed. Phương thức này lấy một URL và trả về toàn bộ nguồn cấp dữ liệu có tại URL đó. Chúng tôi sẽ hướng dẫn cách gửi các truy vấn cụ thể hơn ở phần sau của tài liệu này.
Giống như các phương thức khác của lớp GoogleService, getFeed xử lý việc xác thực và chuyển hướng khi cần.
Chèn một mục mới
Để tạo một sự kiện mới trên lịch, bạn có thể sử dụng mã sau:
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);Sau khi đặt URL, chúng ta sẽ tạo một đối tượng EventEntry; EventEntry được lấy từ lớp cơ sở trừu tượng BaseEntry, đây cũng là lớp mẹ cho lớp Entry, đại diện cho một phần tử <atom:entry>.
Lớp EventEntry đại diện cho một loại Sự kiện; để biết thêm thông tin, hãy xem tài liệu về Các loại. Đối với các dịch vụ không phải là Lịch, bạn có thể chỉ định mục được trả về cho một đối tượng Entry thay vì một đối tượng EventEntry.
Tiêu đề mục nhập là TextConstruct, một lớp chứa văn bản ở nhiều dạng (văn bản thuần tuý, HTML hoặc XHTML). Nội dung của mục được biểu thị bằng một đối tượng Content, một lớp có thể chứa văn bản thuần tuý hoặc các dạng nội dung khác, bao gồm cả XML và dữ liệu nhị phân. (Tuy nhiên, phương thức setContent cũng có thể chấp nhận TextConstruct.)
Mỗi tác giả được biểu thị bằng tên, URI và địa chỉ email. (Trong ví dụ này, chúng ta sẽ bỏ qua URI.) Bạn thêm tác giả vào một mục nhập bằng cách gọi phương thức getAuthors().add của mục nhập đó.
Chúng ta đang sử dụng cùng một đối tượng GoogleService mà chúng ta đã tạo trong ví dụ trước. Trong trường hợp này, phương thức cần gọi là insert, phương thức này sẽ gửi một mục đến URL chèn đã chỉ định.
Dịch vụ này trả về mục mới tạo, có thể chứa các phần tử bổ sung do máy chủ tạo, chẳng hạn như URL chỉnh sửa cho mục đó.
Mã trạng thái HTTP được trả về dưới dạng ngoại lệ.
Đoạn mã trên tương đương với việc gửi POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (với phương thức xác thực phù hợp) và cung cấp một mục nhập dưới dạng loại Sự kiện.
Yêu cầu một mục cụ thể
Đoạn mã sau đây cho phép bạn yêu cầu mục cụ thể mà bạn đã chèn trong ví dụ trước.
Trong bối cảnh của loạt ví dụ này, việc truy xuất mục đó không thực sự cần thiết, vì Lịch đã trả về mục được chèn; nhưng bạn có thể áp dụng kỹ thuật tương tự bất cứ khi nào bạn biết URI cho một mục.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
Mục nhập được chèn có một phương thức, getSelfLink, trả về một đối tượng Link bao gồm URL của mục nhập. Lớp Link có một phương thức getHref trả về URL dưới dạng String. Từ đó, chúng ta có thể tạo một đối tượng URL.
Sau đó, chúng ta chỉ cần gọi phương thức getEntry của dịch vụ để lấy mục nhập.
Xin lưu ý rằng chúng ta đưa EventEntry.class làm tham số cho getEntry, cho biết rằng chúng ta đặc biệt mong đợi dịch vụ này trả về một Sự kiện thay vì chỉ một mục nhập đơn giản. Đối với các dịch vụ không phải là Lịch, bạn có thể chỉ cần truyền Entry.class.
Đoạn mã trên tương đương với việc gửi GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID đến Lịch, có xác thực thích hợp.
Tìm kiếm mục
Để truy xuất kết quả khớp đầu tiên từ một cụm từ tìm kiếm toàn văn, hãy sử dụng mã sau:
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();
}Ví dụ này bắt đầu bằng cách tạo một đối tượng Query, chủ yếu bao gồm một URL cùng với các tham số truy vấn được liên kết. Mỗi tham số truy vấn GData tiêu chuẩn đều có một phương thức setter. Bạn cũng có thể đặt các tham số truy vấn tuỳ chỉnh cho một dịch vụ cụ thể bằng phương thức addCustomParameter.
Sau khi tạo Query, chúng ta sẽ truyền đối tượng này đến phương thức query của dịch vụ. Phương thức này sẽ trả về một nguồn cấp dữ liệu chứa kết quả truy vấn. Một phương pháp thay thế là tự tạo URL (bằng cách thêm các tham số truy vấn vào URL nguồn cấp dữ liệu), rồi gọi phương thức getFeed, nhưng phương thức query cung cấp một lớp trừu tượng hữu ích để bạn không phải tự tạo URL.
Phương thức getEntries của nguồn cấp dữ liệu trả về danh sách các mục trong nguồn cấp dữ liệu; getEntries().size trả về số lượng mục trong nguồn cấp dữ liệu.
Trong trường hợp này, nếu truy vấn trả về bất kỳ kết quả nào, chúng ta sẽ chỉ định kết quả khớp đầu tiên cho một đối tượng Entry. Sau đó, chúng ta dùng phương thức getTitle().getPlainText của lớp Entry để truy xuất tiêu đề của mục và chuyển đổi tiêu đề đó thành văn bản.
Đoạn mã trên tương đương với việc gửi GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis đến Lịch.
Truy vấn theo danh mục
Lưu ý: Lịch Google không liên kết nhãn với sự kiện, nên ví dụ này không hoạt động với Lịch.
Để truy xuất một nguồn cấp dữ liệu bao gồm tất cả các mục khớp với nội dung tìm kiếm toàn văn trước đó và nằm trong một danh mục cụ thể hoặc có một nhãn cụ thể, hãy sử dụng mã sau:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);Tất nhiên, lớp Category đại diện cho một danh mục sẽ được dùng trong bộ lọc danh mục. Lớp Query.CategoryFilter có thể chứa nhiều danh mục, nhưng trong trường hợp này, chúng ta đang tạo một bộ lọc chỉ có một danh mục.
Sau đó, chúng ta thêm bộ lọc đó vào cụm từ tìm kiếm hiện có, cụm từ này vẫn chứa chuỗi truy vấn toàn văn bản trong ví dụ trước.
Chúng ta lại dùng phương thức query để gửi truy vấn đến dịch vụ.
Nếu Lịch cho phép tìm kiếm theo danh mục, thì mã trên sẽ tương đương với việc gửi GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis đến Lịch.
Đang cập nhật một mục
Để cập nhật một mục hiện có, hãy sử dụng mã sau. Trong ví dụ này, chúng ta sẽ thay đổi tiêu đề của mục đã truy xuất trước đó từ văn bản cũ ("Tennis with Darcy") thành "Important meeting" (Cuộc họp quan trọng).
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Trước tiên, chúng ta đặt một tiêu đề mới cho mục mà chúng ta đã tìm nạp trước đó. Sau đó, chúng ta sẽ lấy URL chỉnh sửa cho mục nhập bằng phương thức getEditLink. Sau đó, chúng ta gọi phương thức update của dịch vụ để gửi mục nhập đã cập nhật.
Dịch vụ này trả về mục đã cập nhật, bao gồm cả một URL mới cho phiên bản mới của mục này. (Để biết thêm thông tin về các phiên bản mục nhập, hãy xem phần Đồng thời lạc quan trong tài liệu tham khảo về giao thức.)
Đoạn mã trên tương đương với việc gửi PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID đến dịch vụ, cùng với mục mới (ở định dạng Atom) để thay thế mục ban đầu.
Xoá một mục
Để xoá mục đã cập nhật, hãy dùng mã sau:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
URL dùng để xoá giống với URL chỉnh sửa, vì vậy ví dụ này rất giống với ví dụ trước, ngoại trừ việc chúng ta đang gọi phương thức delete thay vì update.
Đoạn mã trên tương đương với việc gửi DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID đến dịch vụ.
Tài liệu tham khảo
Để biết thông tin tham khảo về các lớp và phương thức do thư viện ứng dụng cung cấp, hãy xem tài liệu tham khảo về API thư viện ứng dụng Java (ở định dạng Javadoc).