警告:這份文件已不適用。如要進一步瞭解如何使用 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 存取資料所需的授權權杖。
您必須在 Android 應用程式資訊清單中新增以下權限,才能使用 AccountManager 取得帳戶及要求授權權杖:
<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 用戶端程式庫隨附只處理 Google 帳戶的 GoogleAccountManager:
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 核發 OAuth 2.0 存取權杖以供 Task API 使用。做法是呼叫 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。如果您的應用程式尚未取得 Activity 授權,由 AccountManager 啟動。該頁面會顯示授權對話方塊,讓使用者能夠「允許」或「拒絕」您的應用程式透過自己的帳戶使用 Tasks API。
如果使用者拒絕您的應用程式存取 Tasks API,系統會在 future.getResult() 呼叫期間擲回 OperationCanceledException。但請謹慎處理這種情況,例如要求重新選擇帳戶,或顯示訊息以再次提供授權按鈕的按鈕。
識別應用程式並設定 Tasks API 服務物件
您的應用程式已獲得存取 Tasks API 的授權,且已取得存取權杖。您還需要在 Google API 控制台中從專案取得 API 金鑰,因為必須進行 Tasks API 呼叫。步驟如下:
- 建立專案或使用現有專案
- 將 Tasks API 切換為「開啟」,以便在專案中啟用 Tasks API
- 如要查看 API 金鑰,請依序點選 [API 存取權] > [簡易 API 存取權] > [API 金鑰]。
由於 API 金鑰可識別您的應用程式,因此必須強制 API 使用您專案定義的配額限制。您必須在 Tasks 服務物件中指定 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 會快取這個解決方案的權杖,因此方法是可接受的。
- 請在收到 403 錯誤時要求 AccountManager 提供新的權杖,否則請繼續使用 accessToken。
透過 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 中顯示預設工作清單的工作。
請按照這些instructions執行範例,歡迎隨時前往 Google Tasks API 論壇張貼意見或問題。