Tài liệu này mô tả cách sử dụng thư viện ứng dụng .NET để gửi các truy vấn API Dữ liệu Google ("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 để tương tác với các dịch vụ hỗ trợ GData, bằng nhiều ngôn ngữ lập trình. 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 tập hợp các ví dụ về cách sử dụng phổ biến của phiên bản C# của thư viện ứng dụng, theo sau là thông tin khác về cách viết ứng dụng khách GData. Ở cuối tài liệu này là một đường liên kết đến tài liệu tham khảo về thư viện ứng dụng khách C#, ở định dạng NDoc.
Để sử dụng thư viện ứng dụng này, bạn cần thời gian chạy .NET 1.1 và bạn cũng nên cập nhật tất cả bản vá.
Tải thư viện ứng dụng .NET 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 .NET 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 C# 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 C#.
Tổng quan về mô hình dữ liệu
Thư viện ứng dụng C# cung cấp một tập hợp các lớp tương ứng với các phần tử và loại dữ liệu 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.
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 GData bằng thư viện ứng dụng C#.
Để 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âu lệnh sau bằng cách sử dụng câu lệnh:
using Google.GData.Client;
Yêu cầu nguồn cấp dữ liệu
Như mô tả trong tài liệu về API dữ liệu 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. 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 nguồn cấp dữ liệu Lịch bằng thư viện ứng dụng C#, cho người dùng có địa chỉ email "jo@gmail.com" và mật khẩu "mypassword", hãy dùng mã sau:
// Create a query and service object:
FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");
// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");
// Tell the service to query:
AtomFeed calFeed = service.Query(query);
Lớp Service đại diệ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ể
Servicemớ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.
- 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 service.setUserCredentials đặt thuộc tính service.Credentials bằng một đối tượng thông tin xác thực Mạng .NET tiêu chuẩn.
Thông tin xác thực được đặt thành mã và mật khẩu của người dùng mà khách hàng của bạn đang gửi truy vấn thay mặt cho họ. 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ề các hệ thống xác thực khác, hãy xem tài liệu về Xác thực tài khoản Google.
Để yêu cầu toàn bộ nguồn cấp dữ liệu, bạn cần gọi phương thức service.Query. Phương thức này sẽ lấy đối tượng FeedQuery và trả về toàn bộ nguồn cấp dữ liệu 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 Service, Query xử lý việc xác thực và chuyển hướng khi cần.
Chèn một mục mới
Để chèn một mục vào nguồn cấp dữ liệu Lịch, bạn có thể sử dụng mã sau:
AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March";
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth";
entry.Content.Content = "Meet for a quick lesson.";
Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");
// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);
Sau khi đặt URL, chúng ta sẽ tạo một đối tượng AtomEntry.
Tiêu đề nhập là một AtomTextConstruct, 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 AtomContent, 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.
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 thêm đối tượng AtomAuthor vào bộ sưu tập Authors của mục đó.
Chúng ta đang sử dụng cùng một đối tượng Service 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ên tương đương với việc gửi POST http://www.google.com/calendar/feeds/jo@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.
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 đượ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 URL của một mục nhập.
FeedQuery singleQuery = new FeedQuery(); singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); AtomFeed newFeed = service.Query(singleQuery); AtomEntry retrievedEntry = newFeed.Entries[0];
Mục nhập được chèn có một thuộc tính SelfUri, trả về một đối tượng AtomUri mà có thể dùng phương thức ToString() để tạo đối tượng URI mới.
Sau đó, chúng ta chỉ cần gọi phương thức Query của dịch vụ để nhận đối tượng AtomFeed mới, chỉ với một mục nhập trong bộ sưu tập entry (Mục nhập).
Mã trên tương đương với việc gửi GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID đến Lịch, với quy trình xác thực phù hợp.
Đang tìm mục nhập
Để truy xuất kết quả phù hợp đầu tiên trong một tìm kiếm toàn bộ văn bản, hãy sử dụng mã sau:
FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis";
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
AtomEntry firstMatchEntry = myResultsFeed.Entries[0];
String myEntryTitle = firstMatchEntry.Title.Text;
}
Ví dụ này bắt đầu bằng cách tạo một đối tượng FeedQuery, 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 đều có một thuộc tính.
Sau khi tạo FeedQuery, 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 Query, nhưng phương thức FeedQuery 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.
Bộ sưu tập Entries của nguồn cấp dữ liệu sẽ trả về danh sách các mục trong nguồn cấp dữ liệu; Entries.Count 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 đối tượng AtomEntry. Sau đó, chúng ta sẽ sử dụng thuộc tính Title của lớp AtomEntry để truy xuất tiêu đề của mục.
Mã trên tương đương với việc gửi GET http://www.google.com/calendar/feeds/jo@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:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);
Tất nhiên, lớp AtomCategory sẽ đại diện cho một danh mục được sử dụng trong bộ lọc danh mục. Lớp QueryCategory 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/jo@gmail.com/private/full/-/by_jo?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ụ sau, chúng tôi sẽ thay đổi tiêu đề của mục đã truy xuất trước đó từ văn bản cũ ("Quần vợt có Beth") thành "Cuộc họp quan trọng".
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
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 chỉ cần gọi phương thức Upate để gửi mục nhập đã cập nhật đến dịch vụ.
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 truy cập, 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 phiên bản 1.)
Mã ở trên tương đương với việc gửi PUT http://www.google.com/calendar/feeds/jo@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ột mục hiện có, hãy dùng mã sau:
updateEntry.Delete();
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/jo@gmail.com/private/full/entryID đến dịch vụ.
Làm việc với nguồn cấp dữ liệu Lịch Google
Các ví dụ trên nêu rõ cách sử dụng API C# của Google Data để làm việc với nguồn cấp dữ liệu GData chung. Tuy nhiên, khi bạn làm việc với một nguồn cấp dữ liệu Lịch Google, thì nguồn cấp dữ liệu chứa nhiều dữ liệu theo lịch cụ thể không truy cập được bằng cách sử dụng các đối tượng tiêu chuẩn hướng Atom trong thư viện API cơ sở. Để giúp bạn tương tác với những nguồn cấp dữ liệu đó, chúng tôi cung cấp các phần mở rộng sau:
using Google.GData.Extensions; using Google.GData.Calendar;
Không gian tên của phần mở rộng xử lý các phần mở rộng nói chung; không gian tên Lịch cho phép bạn truy cập vào một dịch vụ lịch, nguồn cấp dữ liệu và đối tượng truy vấn tùy chỉnh. Bạn có thể tìm thấy một ví dụ chi tiết hơn về cách các tiện ích đó được sử dụng trong thư mục con /Samples của quy trình cài đặt API C#. Các đối tượng sau đây được thêm:
- Truy vấn sự kiện
- Một lớp con của FeedQuery, cho phép bạn đặt hai tham số tùy chỉnh cho dịch vụ Lịch (start-min và start-max).
- Dịch vụ Lịch
- Một lớp con dịch vụ có thể trả về nguồn cấp dữ liệu sự kiện.
- Nguồn cấp dữ liệu sự kiện
- Một lớp con của AtomFeed, hiển thị EventEntries.
- Mục sự kiện
- Một lớp con của AtomEntry, có các thuộc tính bổ sung liên quan đến dữ liệu lịch.
Để biết thêm thông tin về các lớp đặc biệt đó, hãy xem tài liệu về API và chương trình mẫu.
Tham chiếu
Để biết thông tin tham khảo về thư viện ứng dụng C#, hãy xem tài liệu tham khảo.