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 các ứng dụng Android sử dụng OAuth 2.0, vui lòng xem Tài liệu về việc uỷ quyền cho Dịch vụ Android 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 để truy cập vào Google Tasks của người dùng cũng như cách bạn có thể thiết lập Đối tượng dịch vụ API Tasks trong ứng dụng Android của mình.
Để ứng dụng Android của bạn sử dụng 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
- Nhận mã truy cập OAuth 2.0 từ AccountManager cho Task API
- Xác định dự án và thiết lập Đối tượng dịch vụ Tasks
- Thực hiện lệnh gọi đến API Tasks
Nhập thư viện ứng dụng của Google
Các mẫu mà bạn thấy trong tài liệu này dùng thư viện ứng dụng API của Google cho Java. Bạn cần thêm các tệp jar sau vào ứng dụng Android của mình. Để làm vậy, hãy đặt các tệp được liệt kê dưới đây 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 để tìm các phiên bản mới khi tài liệu này trở nên cũ hơn.
Nhập các tệp jar của thư viện ứng dụng API của Google và các tiện ích Android tương ứng (tất cả các phần của 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ả các phần của 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 trên Android
Kể từ Android 2.0, AccountManager sẽ quản lý những 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ể, công cụ này xử lý quy trình uỷ quyền và có thể tạo mã thông báo uỷ quyền cần thiết để truy cập vào 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ể 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ý các tài khoản Google mà còn quản lý các tài khoản từ các nhà cung cấp khác. Do đó, bạn cần yêu cầu cụ thể Tài khoản Google bằng cách sử dụng mã bên dưới:
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 đi kèm với một 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 về tài khoản họ muốn sử dụng bằng một 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 đổi/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 trình chọn tài khoản.
Quy trình uỷ quyền API của Google trên Android
Bây giờ, người dùng đã chọn một tài khoản, chúng ta có thể yêu cầu AccountManager cấp mã truy cập OAuth 2.0 cho API Tác vụ. 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 AccountManager.getAuthToken(), hãy gọi AccountManager sẽ đảm nhận việc liên hệ với điểm cuối uỷ quyền API Google. Khi AccountManager đã truy xuất mã thông báo uỷ quyền, trình quản lý 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 dành cho OAuth 2.0. Bạn chỉ cần thêm tiền tố cho phạm vi của API mà bạn muốn truy cập bằng oauth2: khi đặt NATIVE_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 AUTH_TOKEN_TYPE sẽ hiển thị trong hộp thoại ủy quyền dưới dạng tên của sản phẩm Google bạn muốn truy cập. Để giải quyết vấn đề này, có một bí danh đặc biệt (mà con người có thể đọc được) AUTH_TOKEN_TYPE cho API Tasks. Các hàm 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 công việc của bạn tương đương với quyền chỉ có thể đọc của API Tasks phạm vi: oauth2:https://www.googleapis.com/auth/tasks.readonly.
Trong quá trình AccountManager.getAuthToken(), hãy gọi AccountManager, ứng dụng sẽ kiểm tra xem ứng dụng của bạn đã được cấp 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, thì Hoạt động sẽ được AccountManager khởi động. Hộp thoại này sẽ hiển thị 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 để dùng API Tasks trên tài khoản của họ.
Nếu người dùng từ chối quyền truy cập của ứng dụng vào API Tasks, thì OperationCanceledException sẽ được gửi trong lệnh gọi future.getResult(). Bạn nên xử lý dễ dàng, chẳng hạn như bằng cách yêu cầu chọn lại tài khoản hoặc hiển thị thông báo có nút để cấp lại quyền truy cập.
Xác định ứng dụng của bạn và thiết lập Đối tượng dịch vụ API Tasks
Giờ đây, ứng dụng của bạn đã được cấp quyền truy cập vào API Tasks và ứng dụng đã được cấp mã truy cập. Bạn cũng cần có Khoá API mà bạn cần nhận được từ dự án trong Bảng điều khiển API của Google vì điều này là bắt buộc để thực hiện các lệnh gọi API Tasks. Để thực hiện, 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 Tasks API trên dự án của bạn bằng cách BẬT nút API Tasks
- Bạn có thể tìm thấy Khoá API tại Quyền truy cập API > Truy cập API đơn giản > Khoá API
Khoá API là bắt buộc vì mã này xác định ứng dụng của bạn, từ đó 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ụ 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ỉ có hiệu lực trong một khoảng thời gian nhất định. Do đó, bạn sẽ phải nhận một mã mới khi mã này hết hạn. Có 2 cách để xử lý vấn đề này:
- Yêu cầu một accessToken cho AccountManager mỗi khi bạn đưa ra yêu cầu thông qua API. Vì AccountManager lưu mã thông báo vào bộ nhớ đệm, nên giải pháp này được chấp nhận.
- Tiếp tục sử dụng accessToken của bạn cho đến khi bạn gặp lỗi 403. Tại thời điểm đó, bạn yêu cầu mã thông báo mới vào AccountManager.
Thao tác với Tasks thông qua API
Tại thời điểm này, bạn cần có một Đối tượng dịch vụ API Tasks được thiết lập đầy đủ. Bạn có thể dùng Đối tượng này để truy vấn API theo Hướng dẫn dành cho nhà phát triển về 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 của bạn. Nếu không, các yêu cầu nêu trên đến các điểm cuối của API Tasks sẽ không thực hiện được:
<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 Thư viện ứng dụng API của Google cho kho lưu trữ mẫu 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 uỷ quyền để sử dụng API Tasks và hiển thị các công việc của danh sách công việc mặc định trong ListView.
Hãy làm theo hướng dẫn sau để chạy mẫu này 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 về API Google Tasks.