שימוש ב-Tasks API ב-Android

אזהרה: המסמך הזה הוצא משימוש. למידע על מתן הרשאות לאפליקציות ל-Android באמצעות OAuth 2.0, אפשר לעיין במסמכי העזרה בנושא הרשאות ב-Android Play Services.

במסמך הזה מוסבר איך להשתמש ב-Tasks API עם OAuth 2.0 ב-Android. במאמר מוסבר איך משיגים גישה ל-Google Tasks של משתמש באמצעות מנגנוני הרשאה, ואיך יוצרים אובייקט שירות של Tasks API מוכן לשימוש באפליקציה ל-Android.

כדי שאפליקציית Android שלכם תוכל להשתמש ב-Tasks API, צריך לבצע כמה שלבים:

1. בוחרים את חשבון Google של המשתמש
2. קבלת אסימון גישה מסוג OAuth 2.0 מ-AccountManager ל-Task API
3. זיהוי הפרויקט והגדרת אובייקט השירות של Tasks
4. ביצוע קריאות ל-Tasks API

ייבוא ספריית הלקוח של Google

בדוגמאות שמופיעות במסמך הזה נעשה שימוש בספריית הלקוח של Google APIs ל-Java. צריך להוסיף את קובצי ה-jar הבאים לאפליקציה ל-Android. לשם כך, צריך להציב את קובצי ה-jar המפורטים בהמשך בתיקייה /assets ברמה הבסיסית של האפליקציה ל-Android. כדאי גם לבדוק אם יש גרסאות חדשות ככל שהמסמך הזה נעשה ישן יותר.

מייבאים את קובצי ה-jar של ספריית הלקוח של Google APIs ואת התוספים שלה ל-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

מייבאים את קובץ ה-jar הספציפי ל-Tasks:

• google-api-services-tasks-v1-1.1.0-beta.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

חשבונות Google ב-Android

החל מגרסה 2.0 של Android, ה-AccountManager מנהל את החשבונות שרשומים בסביבה שלכם, החשבונות שמפורטים בקטע הגדרות > חשבונות וסנכרון. באופן ספציפי, הוא מטפל בתהליך ההרשאה ויכול ליצור אסימוני הרשאה שנדרשים כדי לגשת לנתונים באמצעות ממשקי API.

חשבונות שרשומים בסביבת Android

כדי שתוכלו להשתמש ב-AccountManager כדי לקבל חשבונות ולבקש אסימוני הרשאה, עליכם להוסיף את ההרשאות הבאות למניפסט של אפליקציית Android:

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />

אפשר להשתמש ב-AccountManager כדי לקבל את חשבון Google שאליו רוצים לגשת ב-Tasks. AccountManager מנהל לא רק חשבונות Google, אלא גם חשבונות של ספקים אחרים. לכן, תצטרכו לבקש באופן ספציפי חשבונות Google באמצעות הקוד הבא:

AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");

לחלופין, ספריית הלקוח של Google APIs ל-Java כוללת את GoogleAccountManager שמטפל רק בחשבונות Google:

GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity);
Account[] accounts = googleAccountManager.getAccounts();

אם יש יותר מחשבון Google אחד במכשיר Android, צריך לבקש מהמשתמש לבחור את החשבון שבו הוא רוצה להשתמש באמצעות תיבת דו-שיח שיכולה להיראות כך:

תיבת הדו-שיח לבחירת חשבון

אפשר ליצור תיבת דו-שיח כזו באמצעות קוד switch/case הבא בשיטה 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) תציג את תיבת הדו-שיח לבחירת חשבון.

תהליך ההרשאה של Google APIs ב-Android

עכשיו, אחרי שהמשתמש בחר חשבון, אנחנו יכולים לבקש מ-AccountManager להנפיק אסימון גישה מסוג OAuth 2.0 ל-Task API. כדי לעשות זאת, קוראים ל-method‏ AccountManager.getAuthToken(). במהלך הקריאה ל-AccountManager.getAuthToken(), ה-AccountManager יטפל ביצירת הקשר לנקודת הקצה של הרשאה של Google APIs. אחרי ש-AccountManager יאתר את אסימון ההרשאה, הוא יפעיל את AccountManagerCallback שהגדרתם בקריאה ל-method:

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. צריך רק להוסיף את הקידומת oauth2: להיקף של ה-API שאליו רוצים לגשת כשמגדירים את AUTH_TOKEN_TYPE. ל-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 View your tasks, שהוא שווה לעוצמת הגישה לקריאה בלבד של Tasks API: ‏ oauth2:https://www.googleapis.com/auth/tasks.readonly.

במהלך הקריאה ל-AccountManager.getAuthToken(), ה-AccountManager יבדוק אם לאפליקציה יש הרשאה לגשת ל-Tasks API. אם האפליקציה שלכם עדיין לא אושרה, ה-AccountManager יתחיל פעילות שבה יוצג למשתמש תיבת דו-שיח לאישור, כדי שהוא יוכל לאפשר או לדחות את האפשרות של האפליקציה להשתמש ב-Tasks API בחשבון שלו.

תיבת דו-שיח להרשאה

אם המשתמש ידחה את הגישה של האפליקציה ל-Tasks API, תופיע OperationCanceledException במהלך הקריאה ל-future.getResult(). כדאי לטפל בכך בצורה נעימה, למשל על ידי בקשה לבחור שוב את החשבון או הצגת הודעה עם לחצן לאישור הגישה מחדש.

זיהוי האפליקציה והגדרת אובייקט השירות של Tasks API

עכשיו, אחרי שהאפליקציה קיבלה הרשאה לגשת ל-Tasks API וקיבלתם לה אסימון גישה, אתם צריכים גם מפתח API. מפתח ה-API הזה מחייב כדי לבצע קריאות ל-Tasks API, וצריך לקבל אותו מפרויקט במסוף Google APIs. כדי לעשות זאת:

1. יצירת פרויקט או שימוש בפרויקט קיים
2. מפעילים את Tasks API בפרויקט על ידי החלפת המצב של המתג של Tasks API למצב מופעל.
3. מפתח ה-API נמצא בקטע גישת API > גישה פשוטה ל-API > מפתח API

אחזור מפתח ה-API מ-APIs Console

מפתח ה-API הוא חובה, כי הוא מזהה את האפליקציה שלכם, ולכן מאפשר ל-API לנכות מכסה ולהשתמש בכללי המכסה שהוגדרו לפרויקט. צריך לציין את מפתח ה-API באובייקט השירות של 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 תקף רק למשך פרק זמן מסוים, כך שתצטרכו לקבל אסימון חדש כשפג התוקף שלו. יש 2 דרכים לטפל בבעיה הזו:

• מבקשים accessToken מ-AccountManager בכל פעם ששולחים בקשות דרך ה-API. מכיוון שהאסימון מאוחסן במטמון של AccountManager, הפתרון הזה מקובל.
• ממשיכים להשתמש ב-accessToken עד שמופיעה הודעת השגיאה 403. בשלב הזה מבקשים אסימון חדש מ-AccountManager.

מניפולציה של משימות דרך ה-API

בשלב הזה, אובייקט השירות של Tasks API אמור להיות מוגדר במלואו, ותוכלו להשתמש בו כדי לשלוח שאילתות ל-API בהתאם למדריך למפתחים של Tasks API. לדוגמה:

// Getting all the Task lists
List taskLists = 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" />

אפליקציה לדוגמה

לאחרונה הוספנו דוגמה חדשה למאגר הדוגמאות של ספריית הלקוח של Google APIs ל-Java, כדי לעזור לכם להתחיל להשתמש ב-Tasks API וב-OAuth 2.0 ב-Android. הדוגמה היא אפליקציית Android פשוטה שפועלת באופן מלא. היא מבקשת הרשאה לשימוש ב-Tasks API ומציגה את המשימות של רשימת המשימות שמוגדרת כברירת מחדל ב-ListView.

הצגת המשימות ברשימת המשימות שמוגדרת כברירת מחדל ב-ListView

פועלים לפי ההוראות האלה כדי להפעיל את הדוגמה, ואל תהססו לפרסם משוב או שאלות בפורום של Google Tasks API.