警告：本文件已淘汰。 如要進一步瞭解如何使用 OAuth 2.0 授權 Android 應用程式，請參閱 Android Play 服務授權說明文件。
本文說明如何在 Android 裝置上搭配 OAuth 2.0 使用 Tasks API。文中說明瞭取得使用者的 Google Tasks 存取權的授權機制，以及在 Android 應用程式中如何準備好使用 Tasks API 服務物件。
如要讓 Android 應用程式使用 Tasks API，必須執行以下步驟：
匯入 Google 用戶端程式庫
本文件中的範例使用 Java 適用的 Google API 用戶端程式庫。您必須將下列 jar 新增至 Android 應用程式，若要這麼做，請將下列 Jar 放在 Android 應用程式根目錄的 /assets 資料夾中。另請注意，隨著這份文件的版本過舊，請檢查是否有新版本。
匯入 Google API 用戶端程式庫 jar 檔案及其 Android 擴充功能 (所有 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
匯入 Tasks 專屬 jar：
匯入依附元件 (所有 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
Android 中的 Google 帳戶
從 Android 2.0 開始，AccountManager 管理您在環境中註冊的帳戶，將列於 設定 > 底下列出的帳戶帳戶與同步處理。具體來說，這項服務會處理授權流程，並產生透過 API 存取資料所需的授權權杖。
如要使用 AccountManager 取得帳戶及要求授權權杖，您必須先在 Android 應用程式資訊清單中新增以下權限：
<uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.USE_CREDENTIALS" />
您可以使用 AccountManager，取得要使用 Tasks 的 Google 帳戶。AccountManager 不僅管理 Google 帳戶，也管理其他供應商的帳戶。因此，您必須使用下方代碼特別申請 Google 帳戶：
AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");
此外，Java 專用 Google API 用戶端程式庫隨附的 GoogleAccountManager 僅可處理 Google 帳戶：
GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity); Account[] accounts = googleAccountManager.getAccounts();
如果 Android 裝置可使用多個 Google 帳戶，應顯示要使用的對話方塊，提示使用者要使用的帳戶：
您可以在活動的 onCreateDialog 方法中使用以下切換/案例程式碼來建構這類對話方塊：
@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;
}
呼叫 showDialog(DIALOG_ACCOUNTS)，會顯示帳戶選擇工具對話方塊。
Android 上的 Google API 授權流程
使用者選取帳戶後，就可以要求 AccountManager 核發 Task API 的 OAuth 2.0 存取權杖。方法是呼叫 AccountManager.getAuthToken() 方法。在 AccountManager.getAuthToken() 呼叫期間，AccountManager 會負責聯繫 Google API 授權端點。AccountManager 擷取授權權杖後，就會執行您在方法呼叫中定義的 AccountManagerCallback：
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);
您可能已經知道 Android AccountManager 已實驗性支援 OAuth 2.0。設定 AUTH_TOKEN_TYPE 時，您只需要在要存取的 API 範圍前方加上 oauth2:，因此，您可以使用 Tasks API：
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
使用上述值做為 AUTH_TOKEN_TYPE 時會發生的問題，是授權對話方塊中的 oauth2:https://www.googleapis.com/auth/tasks 字串會顯示為待存取的 Google 產品名稱。為解決這個問題，我們為 Tasks API 建立了 AUTH_TOKEN_TYPE 別名，方便人類可讀。等同於使用 OAuth 2.0 範圍。例如，您可以使用：
String AUTH_TOKEN_TYPE = "Manage your tasks";
您也可以使用 AUTH_TOKEN_TYPE 別名 檢視您的工作，相當於 Tasks API 唯讀 範圍：oauth2:https://www.googleapis.com/auth/tasks.readonly。
在 AccountManager.getAuthToken() 呼叫期間，AccountManager 會檢查應用程式是否已獲得授權，可存取 Tasks API。如果您的應用程式尚未授權給 AccountManager，該程式會向使用者顯示授權對話方塊，讓使用者「允許」或「拒絕」應用程式透過其帳戶使用 Tasks API。
如果使用者拒絕應用程式存取 Tasks API，系統會在 future.getResult() 呼叫期間擲回 OperationCanceledException。請妥善處理這個問題，例如要求再次選擇帳戶，或是顯示附有再次授權存取按鈕的訊息。
識別應用程式並設定 Tasks API 服務物件
現在您的應用程式已取得 Tasks API 的存取權，並已取得存取權杖。您需要在 Google API 控制台中從專案取得 API 金鑰，因為必須執行 Tasks API 呼叫。步驟如下：
- 建立專案或使用現有專案
- 將 Tasks API 切換為「開啟」，以便在專案中啟用 Tasks API
- API 金鑰可至 API 存取權>Simple API Access >API 金鑰
API 金鑰是識別應用程式的必要條件，因此 API 可扣除配額及使用專案定義的配額規則。您必須在 Tasks service 物件指定 API 金鑰：
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 僅在特定一段時間內有效，因此屆時您必須取得新的憑證。有 2 種方式可以處理這個問題：
- 每次透過 API 發出請求時，都必須向 AccountManager 要求 accessToken。由於 AccountManager 會快取憑證，因此這個解決方案可以接受。
- 繼續使用 accessToken 直到收到 403 錯誤。此時，您可以要求向 AccountManager 索取新的憑證，
透過 API 操控工作
此時，您應該已經擁有完整的 Tasks API 服務物件，可以根據 Tasks API 開發人員指南查詢 API，例如：
// 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();
請記得在 Android 應用程式資訊清單中新增存取網際網路的權限，否則對 Tasks API 端點提出的上述要求將會失敗：
<uses-permission android:name="android.permission.INTERNET" />
應用程式範例
我們最近在 Java 適用的 Google API 用戶端程式庫範例存放區中新增範例，協助您開始在 Android 上使用 Tasks API 和 OAuth 2.0。這個範例是簡單但功能完整的 Android 應用程式，可要求授權使用 Tasks API，並在 ListView 中顯示預設工作清單的工作。
請按照這些操作說明執行範例，也歡迎到 Google Tasks API 論壇張貼意見回饋或提問。