Hướng dẫn dành cho nhà phát triển về Thư viện ứng dụng .NET

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 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 để 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 bộ ví dụ về các cách sử dụng phổ biến của phiên bản C# của thư viện ứng dụng, sau đó là các thông tin khác về cách viết ứng dụng GData. Ở cuối tài liệu này là đường liên kết đến tài liệu tham khảo cho thư viện ứng dụng C#, ở định dạng NDoc.

Để sử dụng thư viện ứng dụng này, bạn cần có thời gian chạy .NET 1.1 và bạn cũng phải cập nhật tất cả các bản vá.

Tải thư viện ứng dụng .NET 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 .NET 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

  1. Đối tượng người xem
  2. Tổng quan về mô hình dữ liệu
  3. Hướng dẫn và ví dụ
  4. Reference

Đối tượng

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 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. Hướng dẫn này cũng giả định rằng bạn biết cách lập trình bằng 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à kiểu dữ liệu 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.

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 cho thấy cách gửi nhiều yêu cầu GData bằng thư viện ứng dụng C#.

Để 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âu lệnh using sau:

using Google.GData.Client;

Yêu cầu nguồn cấp dữ liệu

Như mô tả trong tài liệu Google Calendar Data API, 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 đâ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; 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. 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 C#, đối với người dùng có địa chỉ email "jo@gmail.com" và mật khẩu "mypassword", hãy sử 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 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:

  1. Lấy hoặc tạo URL phù hợp.
  2. 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.)
  3. Tạo một thực thể Service mớ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ạng companyName-applicationName-versionID).
  4. Đặt thông tin đăng nhập phù hợp.
  5. 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 đăng nhập mạng .NET tiêu chuẩn. Thông tin đăng nhập được đặt thà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ề các hệ thống xác thực khác, hãy xem tài liệu 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 gọi phương thức service.Query. Phương thức này lấy một đối tượng FeedQuery 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 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 thiết lập URL, chúng ta sẽ tạo một đối tượng AtomEntry.

Tiêu đề mục nhập là 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 của mục đượ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ả XML và dữ liệu nhị phân.

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 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 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 đó.

Đoạn 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ộ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 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 bạn có thể áp dụng cùng một kỹ thuật 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 đã chèn có một thuộc tính là SelfUri, trả về một đối tượng AtomUri. Đối tượng này có thể dùng phương thức ToString() để tạo một đố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ụ để lấy một đối tượng AtomFeed mới, chỉ có một mục trong bộ sưu tập Entries.

Đoạn 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, có xác thực thích hợp.

Tìm kiếm một mục

Để truy xuất kết quả trùng khớp đầu tiên trong một tìm kiếm toàn văn, hãy sử dụng đoạn 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, 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 thuộc tính.

Sau khi tạo FeedQuery, 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 Query, nhưng phương thức FeedQuery cung cấp một lớp trừu tượng hữu ích để bạn không phải tự tạo URL.

Tập hợp Entries 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; 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 một đối tượng AtomEntry. Sau đó, chúng ta dùng thuộc tính Title của lớp AtomEntry để truy xuất tiêu đề của mục.

Đoạn 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 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:

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 đại diện cho một danh mục sẽ được 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 đ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/jo@gmail.com/private/full/-/by_jo?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ụ sau, 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 Beth") thành "Important meeting" (Cuộc họp quan trọng).

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

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 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ụ 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 v1.)

Đoạn 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 mới (ở định dạng Atom) để thay thế mục ban đầu.

Xoá một mục

Để xoá một mục hiện có, hãy dùng mã sau:

updateEntry.Delete();

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/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 trình bày cách sử dụng Google Data C# API để làm việc với các 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 Google Lịch, nguồn cấp dữ liệu này sẽ chứa nhiều dữ liệu dành riêng cho lịch mà bạn không thể dễ dàng truy cập bằng các đối tượng chuẩn hướng đến 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 tiện ích sau:

using Google.GData.Extensions;
using Google.GData.Calendar;

Không gian tên Extensions xử lý các tiện ích nói chung; không gian tên Calendar 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 tuỳ chỉnh. Bạn có thể xem một ví dụ chi tiết hơn về cách sử dụng các tiện ích đó trong thư mục con /Samples của quá trình cài đặt API C#. Các đối tượng sau đây sẽ được thêm:

EventQuery
Một lớp con của FeedQuery, cho phép bạn đặt 2 thông số tuỳ chỉnh cho dịch vụ Lịch (start-min và start-max).
CalendarService
Một lớp con của dịch vụ, có thể trả về một nguồn cấp dữ liệu sự kiện.
EventFeed
Một lớp con của AtomFeed, hiển thị EventEntries.
EventEntry
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 chi tiết về các lớp đặc biệt đó, hãy xem tài liệu về API và chương trình mẫu.

Tài liệu tham khảo

Để 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.

Trở lại đầu trang