Cảnh báo: Tài liệu này không còn được dùng nữa. Để biết thông tin về cách uỷ quyền cho ứng dụng Android bằng OAuth 2.0, vui lòng xem tài liệu về Uỷ quyền Dịch vụ Google Play.
Tài liệu này giải thích cách sử dụng API Tasks với OAuth 2.0 trên Android. Tài liệu này mô tả các cơ chế uỷ quyền để có quyền truy cập vào Google Tasks của người dùng và cách bạn có thể sử dụng Đối tượng dịch vụ API Tasks trong ứng dụng Android.
Để ứng dụng Android của bạn sử dụng được API Tasks, bạn cần thực hiện một số bước sau:
- Chọn Tài khoản Google của người dùng
- Lấy mã truy cập OAuth 2.0 từ AccountManager cho API Task
- Xác định dự án và thiết lập service Object (đối tượng dịch vụ) của Tasks
- Gọi API Tasks
Nhập thư viện ứng dụng của Google
Các mẫu bạn sẽ thấy trong tài liệu này sử dụng thư viện ứng dụng API của Google dành cho Java. Bạn sẽ cần thêm các tệp jar sau vào ứng dụng Android. Để thực hiện việc này, hãy đặt các tệp jar được liệt kê bên dưới vào thư mục /assets ở thư mục gốc của ứng dụng Android. Ngoài ra, hãy kiểm tra các phiên bản mới khi tài liệu này cũ đi.
Nhập các tệp jar thư viện ứng dụng Google API và các tiện ích Android của thư viện đó (tất cả đều thuộc google-api-java-client-1.4.1-beta.zip):
- google-api-client-1.4.1-beta.jar
- google-api-client-extensions-android2-1.4.1-beta.jar
- google-api-client-googleapis-1.4.1-beta.jar
- google-api-client-googleapis-extensions-android2-1.4.1-beta.jar
Nhập tệp jar dành riêng cho Tasks:
Nhập phần phụ thuộc (tất cả đều thuộc google-api-java-client-1.4.1-beta.zip):
- commons-codec-1.3.jar
- gson-1.6.jar
- guava-r09.jar
- httpclient-4.0.3.jar
- httpcore-4.0.1.jar
- jackson-core-asl-1.6.7.jar
- jsr305-1.3.9.jar
Tài khoản Google trong Android
Kể từ Android 2.0, AccountManager quản lý các tài khoản mà bạn đã đăng ký trong môi trường của mình, những tài khoản được liệt kê trong phần Cài đặt > Tài khoản và đồng bộ hoá. Cụ thể, lớp này xử lý luồng uỷ quyền và có thể tạo mã uỷ quyền cần thiết để truy cập dữ liệu bằng API.
Để có thể sử dụng AccountManager để lấy tài khoản và yêu cầu mã thông báo uỷ quyền, bạn cần thêm các quyền sau vào tệp kê khai ứng dụng Android:
<uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.USE_CREDENTIALS" />
Bạn có thể sử dụng AccountManager để lấy Tài khoản Google mà bạn muốn truy cập vào Tasks. AccountManager không chỉ quản lý tài khoản Google mà còn quản lý tài khoản của các nhà cung cấp khác. Do đó, bạn cần yêu cầu cụ thể về Tài khoản Google bằng cách sử dụng mã dưới đây:
AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");Ngoài ra, Thư viện ứng dụng API của Google dành cho Java còn đi kèm với GoogleAccountManager chỉ xử lý các tài khoản Google:
GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity); Account[] accounts = googleAccountManager.getAccounts();
Nếu có nhiều Tài khoản Google trên thiết bị Android, bạn nên nhắc người dùng chọn tài khoản mà họ muốn sử dụng bằng hộp thoại có dạng như sau:
Bạn có thể tạo một hộp thoại như vậy bằng cách sử dụng mã chuyển/trường hợp sau trong phương thức onCreateDialog của hoạt động:
@Override protected Dialog onCreateDialog(int id) { switch (id) { case DIALOG_ACCOUNTS: AlertDialog.Builder builder = new AlertDialog.Builder(this); builder.setTitle("Select a Google account"); final Account[] accounts = accountManager.getAccountsByType("com.google"); final int size = accounts.length; String[] names = new String[[]size]; for (int i = 0; i < size; i++) { names[[]i] = accounts[[]i].name; } builder.setItems(names, new DialogInterface.OnClickListener() { public void onClick(DialogInterface dialog, int which) { // Stuff to do when the account is selected by the user gotAccount(accounts[[]which]); } }); return builder.create(); } return null; }
Việc gọi showDialog(DIALOG_ACCOUNTS) sẽ hiển thị hộp thoại bộ chọn tài khoản.
Quy trình uỷ quyền API của Google trên Android
Giờ đây, khi người dùng đã chọn một tài khoản, chúng ta có thể yêu cầu AccountManager phát hành mã truy cập OAuth 2.0 cho API Task. Bạn có thể thực hiện việc này bằng cách gọi phương thức AccountManager.getAuthToken(). Trong lệnh gọi AccountManager.getAuthToken(), AccountManager sẽ chịu trách nhiệm liên hệ với điểm cuối uỷ quyền API của Google. Khi AccountManager truy xuất mã thông báo uỷ quyền, lớp này sẽ chạy AccountManagerCallback mà bạn đã xác định trong lệnh gọi phương thức:
manager.getAuthToken(account, AUTH_TOKEN_TYPE, null, activity, new AccountManagerCallback<Bundle>() { public void run(AccountManagerFuture<Bundle> future) { try { // If the user has authorized your application to use the tasks API // a token is available. String token = future.getResult().getString(AccountManager.KEY_AUTHTOKEN); // Now you can use the Tasks API... useTasksAPI(token); } catch (OperationCanceledException e) { // TODO: The user has denied you access to the API, you should handle that } catch (Exception e) { handleException(e); } } }, null);
Như bạn có thể đã biết, AccountManager của Android có hỗ trợ thử nghiệm cho OAuth 2.0. Bạn chỉ cần đặt tiền tố cho phạm vi của API mà bạn muốn truy cập bằng oauth2: khi đặt AUTH_TOKEN_TYPE. Vì vậy, đối với API Tasks, bạn có thể sử dụng:
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
Vấn đề khi sử dụng giá trị ở trên làm AUTH_TOKEN_TYPE là chuỗi oauth2:https://www.googleapis.com/auth/tasks sẽ xuất hiện trong hộp thoại uỷ quyền dưới dạng tên của sản phẩm Google mà bạn muốn truy cập. Để giải quyết vấn đề này, các bí danh AUTH_TOKEN_TYPE đặc biệt (có thể đọc được) tồn tại cho API Tasks. Các phạm vi này tương đương với việc sử dụng phạm vi OAuth 2.0. Ví dụ: bạn có thể sử dụng:
String AUTH_TOKEN_TYPE = "Manage your tasks";
Bạn cũng có thể sử dụng bí danh AUTH_TOKEN_TYPE Xem việc cần làm của bạn tương đương với phạm vi chỉ có thể đọc của API Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.
Trong lệnh gọi AccountManager.getAuthToken(), AccountManager sẽ kiểm tra xem ứng dụng của bạn đã được uỷ quyền truy cập vào API Tasks hay chưa. Nếu ứng dụng của bạn chưa được uỷ quyền, AccountManager sẽ khởi động một Hoạt động. Hoạt động này sẽ hiển thị một hộp thoại uỷ quyền cho người dùng để họ có thể Cho phép hoặc Từ chối ứng dụng của bạn sử dụng API Tasks trên tài khoản của họ.
Nếu người dùng từ chối cấp quyền truy cập vào API Tasks cho ứng dụng của bạn, thì một OperationCanceledException sẽ được gửi trong lệnh gọi future.getResult(). Bạn nên xử lý vấn đề đó một cách linh hoạt, chẳng hạn như yêu cầu chọn lại tài khoản hoặc hiển thị thông báo có nút để uỷ quyền truy cập lại.
Xác định ứng dụng và thiết lập Đối tượng dịch vụ API Tasks
Giờ đây, ứng dụng của bạn đã được uỷ quyền truy cập vào API Tasks và đã được cấp mã thông báo truy cập, bạn cũng cần có Khoá API mà bạn cần lấy từ một dự án trong Bảng điều khiển API của Google vì đây là yêu cầu bắt buộc để thực hiện lệnh gọi API Tasks. Để thực hiện việc đó, hãy làm theo các bước sau:
- Tạo dự án hoặc sử dụng dự án hiện có
- Bật API Tasks trên dự án của bạn bằng cách chuyển nút bật/tắt API Tasks sang trạng thái BẬT
- Bạn có thể tìm thấy Khoá API tại Quyền truy cập API > Quyền truy cập API đơn giản > Khoá API
Bạn bắt buộc phải có Khoá API vì khoá này xác định ứng dụng của bạn, do đó cho phép API khấu trừ hạn mức và sử dụng các quy tắc hạn mức được xác định cho dự án của bạn. Bạn cần chỉ định Khoá API trên Đối tượng dịch vụ của Tasks:
useTasksAPI(String accessToken) {
// Setting up the Tasks API Service
HttpTransport transport = AndroidHttp.newCompatibleTransport();
AccessProtectedResource accessProtectedResource = new GoogleAccessProtectedResource(accessToken);
Tasks service = new Tasks(transport, accessProtectedResource, new JacksonFactory());
service.accessKey = INSERT_YOUR_API_KEY;
service.setApplicationName("Google-TasksSample/1.0");
// TODO: now use the service to query the Tasks API
}accessToken chỉ hợp lệ trong một khoảng thời gian nhất định, vì vậy, bạn sẽ phải lấy một mã mới khi mã cũ hết hạn. Có 2 cách để xử lý vấn đề này:
- Yêu cầu accessToken cho AccountManager mỗi khi bạn gửi yêu cầu thông qua API. Vì AccountManager lưu mã thông báo vào bộ nhớ đệm nên bạn có thể chấp nhận giải pháp này.
- Tiếp tục sử dụng accessToken cho đến khi bạn gặp lỗi 403. Tại thời điểm đó, bạn sẽ yêu cầu mã thông báo mới cho AccountManager.
Thao tác với Tasks thông qua API
Tại thời điểm này, bạn đã thiết lập đầy đủ Đối tượng dịch vụ API Tasks. Bạn có thể sử dụng đối tượng này để truy vấn API theo Hướng dẫn dành cho nhà phát triển API Tasks, ví dụ:
// Getting all the Task lists ListtaskLists = service.tasklists.list().execute().items; // Getting the list of tasks in the default task list List tasks = service.tasks.list("@default").execute().items; // Add a task to the default task list Task task = new Task(); task.title = "New Task"; task.notes = "Please complete me"; task.due = "2010-10-15T12:00:00.000Z"; Task result = service.tasks.insert("@default", task).execute();
Đừng quên thêm quyền truy cập Internet vào tệp kê khai ứng dụng Android, nếu không các yêu cầu trên đến các điểm cuối API Tasks sẽ không thành công:
<uses-permission android:name="android.permission.INTERNET" />
Ứng dụng mẫu
Gần đây, chúng tôi đã thêm một mẫu mới vào kho lưu trữ mẫu Thư viện ứng dụng API của Google cho Java để giúp bạn bắt đầu sử dụng API Tasks và OAuth 2.0 trên Android. Mẫu này là một ứng dụng Android đơn giản nhưng hoạt động đầy đủ, yêu cầu cấp quyền sử dụng Tasks API và hiển thị các việc cần làm trong danh sách việc cần làm mặc định trong ListView.
Hãy làm theo hướng dẫn này để chạy mẫu và đừng ngại đăng ý kiến phản hồi hoặc câu hỏi của bạn lên Diễn đàn API Google Tasks.