Tài liệu này mô tả cách sử dụng thư viện ứng dụng Java để gửi truy vấn API Dữ liệu Google ("GData") và diễn giải 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 tập hợp các ví dụ về cách 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ụ của hướng dẫn này tham chiếu đến API Lịch Google, nhưng hướng dẫn này không phải là hướng dẫn mới hoặc chính xác 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 API dữ liệu của một dịch vụ cụ thể, hãy xem tài liệu dành riêng cho từng 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 người xem
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 khách có thể tương tác với dịch vụ GData.
Tài liệu này giả định rằng bạn hiểu các ý 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 trong 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 API về thư viện ứng dụng Java (ở định dạng Javadoc).
Tài liệu này được thiết kế để đọc theo thứ tự; mỗi ví dụ được xây dựng 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 tập hợp các lớp để đại diện cho các thành phần mà API dữ liệu của Google sử dụng. Ví dụ: có một lớp 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ập, nhận và đặt giá trị của nhiều phần tử phụ, v.v. Ngoài ra còn có một lớp Mục nhập, tương ứng với phần tử <atom:entry>. Không phải phần tử nào được xác định trong API dữ liệu của Google 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 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 phù 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 nguồn cấp dữ liệu đó và trả về một đối tượng Nguồn cấp dữ liệu có giá trị thu được.
Để gửi nguồn cấp dữ liệu hoặc mục nhập cho một dịch vụ, bạn tạo đố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 sang XML và gửi đối tượng đó.
Bạn có thể phân tích cú pháp và/hoặc tự tạo XML nếu muốn; cách dễ nhất để làm việc này là sử dụng một thư viện thích hợp của bên thứ ba như Rome.
Cũng giống như cú pháp XML của API Dữ liệu Google có thể mở rộng, mô hình đối tượng tương ứ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 của Google Data.
Hướng dẫn và ví dụ
Các ví dụ sau đây minh họa cách gửi nhiều yêu cầu API dữ liệu bằng cách sử dụng thư viện ứng dụng Java.
Để giúp họ 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 các 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ề API Dữ liệu Lịch Google.
Xây dựng 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ư được mô tả trong tài liệu API dữ liệu của Lịch Google, bạn có thể yêu cầu nguồn cấp dữ liệu Lịch bằng cách gửi yêu cầu HTTP sau đây đế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; xem tài liệu Lịch để biết thêm 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ư được mô tả trong tài liệu Lịch), nhưng trong tài liệu này, chúng tôi sẽ sử dụng URL nguồn cấp dữ liệu đầy đủ riêng tư, có chứa mã nhận dạng người dùng.
Bạn cũng phải cung cấp thông tin 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 việc 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 tôi đang sử dụng ở đây (được gọi là "Xác thực Google cho các ứng dụng đã cài đặt") chỉ thích hợp để sử dụng trong các ứng dụng đã cài đặt như ứng dụng cho máy tính chứ không phải để sử dụng trong các ứng dụng web. Để biết thêm thông tin về việc xác thực, hãy xem tài liệu về 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 cách sử dụng thư viện ứng dụng Java, đối với một 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 thể hiện kết nối máy khách (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ụ sử dụng thư viện ứng dụng bao gồm các bước sau:
- Nhận hoặc tạo URL thích 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 nhập mới), thì 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ư 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ạngcompanyName-applicationName-versionID). - Đặt thông tin xác thực phù hợp.
- Cho thư viện khách biết phần mở rộng mà nguồn cấp dữ liệu sẽ sử dụng để thư viện có thể phân tích cú pháp nguồn cấp dữ liệu được trả về một cách chính xác.
- 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 thay mặt cho khách hàng 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 ứ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 đặt thông tin đăng nhập, bạn chỉ định những tiện ích mà nguồn cấp dữ liệu sẽ sử dụng bằng cách gọi phương thức declareExtensions. Trong trường hợp này, chúng tôi sẽ nói rằng nguồn cấp dữ liệu là một Nguồn cấp dữ liệu sự kiện và do đó, nó sẽ sử dụng những phần mở rộng được xác định theo Loại sự kiện.
Để yêu cầu toàn bộ nguồn cấp dữ liệu, bạn cần gọi phương thức getFeed. Phương thức này sẽ 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ẽ hiển thị cách gửi 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 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, cũng là lớp mẹ cho lớp Entry, đại diện cho 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ề Loại. Đối với các dịch vụ không phải Lịch, bạn có thể chỉ định mục nhập được trả về cho đối tượng Entry thay vì đối tượng EventEntry.
Tiêu đề nhập là một 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 nhập vào đượ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ả dữ liệu XML và 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 trình bày dưới dạng tên, URI và địa chỉ email. (Trong ví dụ này, chúng ta sẽ bỏ URI.) Bạn có thể thêm tác giả vào một mục bằng cách gọi phương thức getAuthors().add của mục đó.
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 gọi là insert sẽ gửi một mục đến URL chèn được 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ệ.
Mã trên tương đương với việc gửi POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (bằng 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ục nhập cụ thể
Mã sau đây cho phép bạn yêu cầu mục nhập cụ thể mà bạn đã chèn vào ví dụ trước.
Trong ngữ cảnh của chuỗi ví dụ này, việc truy xuất mục nhập đó không thực sự cần thiết vì Lịch đã trả về mục nhập được chèn; nhưng kỹ thuật tương tự có thể được áp dụng bất cứ khi nào bạn biết URI cho một mục nhập.
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ề đối tượng Link có chứa 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 đố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.
Lưu ý rằng chúng tôi cung cấp EventEntry.class dưới dạng một thông số cho getEntry, cho biết rằng chúng tôi đặc biệt mong đợi dịch vụ trả về một Sự kiện thay vì chỉ là 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 chỉ cần chuyển Entry.class.
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, với quy trình xác thực phù hợp.
Đang tìm kiếm các mục nhập
Để truy xuất kết quả phù hợp đầu tiên từ tìm kiếm toàn bộ văn bả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, trong đó chủ yếu bao gồm một URL và các tham số truy vấn liên quan. Mỗi tham số truy vấn GData chuẩn có một phương thức setter. Bạn cũng có thể đặt tham số truy vấn tuỳ chỉnh cho một dịch vụ cụ thể bằng cách sử dụng phương thức addCustomParameter.
Sau khi tạo Query, chúng ta chuyển phương thức 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 một URL (thêm các tham số truy vấn vào URL của nguồn cấp dữ liệu) rồi gọi phương thức getFeed, nhưng phương thức query sẽ 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 nhập trong nguồn cấp dữ liệu; getEntries().size trả về số lượng mục nhập 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 đối tượng Entry. Sau đó, chúng ta sử dụng phương thức getTitle().getPlainText của lớp Entry để truy xuất tiêu đề của mục nhập và chuyển đổi nó thành văn bả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 các 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 nguồn cấp dữ liệu bao gồm tất cả mục nhập khớp với tìm kiếm toàn bộ văn bản trước đó và nằm trong danh mục cụ thể hoặc có 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 sẽ đại diện cho một danh mục được sử 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 sẽ tạo một bộ lọc chỉ có một danh mục.
Sau đó, chúng tôi thêm bộ lọc đó vào truy vấn hiện tại, vẫn chứa chuỗi truy vấn văn bản đầy đủ từ ví dụ trước.
Chúng ta một lần nữa sử 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 danh mục, 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.
Cập nhật một mục
Để cập nhật một mục hiện có, hãy dùng mã sau. Trong ví dụ này, chúng tôi sẽ thay đổi tiêu đề của mục nhập đã truy xuất trước đó từ văn bản cũ ("Quần vợt với Darcy") thành "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 tiêu đề mới cho mục nhập đã 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 cách sử dụ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 cập nhật.
Dịch vụ sẽ trả về mục nhập được cập nhật, kể cả URL mới cho phiên bản mới của mục nhập này. (Để biết thêm thông tin về các phiên bản nhập liệu, hãy xem phần Tính năng đồng thời tối ưu trong tài liệu tham khảo về giao thức.)
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 nhập mới (ở định dạng Atom) để thay thế mục nhập ban đầu.
Xoá một mục
Để xoá mục đã cập nhật, hãy sử dụng mã sau:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
URL cần xoá cũng giống như URL chỉnh sửa, vì vậy, ví dụ này rất giống với URL trước đó, chỉ khác là chúng đ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ụ.
Tham chiếu
Để 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 API về thư viện ứng dụng Java (ở định dạng Javadoc).