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

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

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

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

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

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

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

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

ייבוא הצנצנת הספציפית ל-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

החל מ-Android 2.0, 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, צריך להציג למשתמש את החשבון שבו הוא רוצה להשתמש בתיבת דו-שיח שתיראה כך:

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

כדי ליצור תיבת דו-שיח כזו, צריך להשתמש בקוד המתג או הרישיות הבא במתודה 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) תציג את תיבת הדו-שיח של Account Chooser.

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

עכשיו, אחרי שהמשתמש בחר חשבון, אנחנו יכולים לבקש מAccountManager להנפיק אסימון גישה מסוג OAuth 2.0 עבור Task API. כדי לעשות זאת, מתבצעת קריאה לשיטה AccountManager.getAuthToken(). במהלך הקריאה ל-AccountManager.getAuthToken(), AccountManager.getAuthToken() יטפל בפנייה לנקודת הקצה להרשאה של 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);

כפי שאולי כבר ידוע לך ל-AccountManager ב-Android יש תמיכה ניסיונית ב-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 שאליו ברצונך לגשת. כדי לעקוף את הבעיה, קיימים כינויי AUTH_TOKEN_TYPE מיוחדים (קריאים לאנשים) ל-Tasks API. הן מקבילות לשימוש בהיקף OAuth 2.0. לדוגמה:

String AUTH_TOKEN_TYPE = "Manage your tasks";

אפשר גם להשתמש בכינוי AUTH_TOKEN_TYPE הצגת המשימות שלך, שמקביל להיקף הקריאה בלבד של ממשק ה-API של Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.

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

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

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

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

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

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

קבלת מפתח ה-API מ-API 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.

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

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

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