אזהרה: המסמך הזה הוצא משימוש. למידע על מתן הרשאה לאפליקציות ל-Android באמצעות OAuth 2.0, ניתן לעיין מסמכי התיעוד בנושא הרשאה לשירותי Android Play.
במסמך הזה מוסבר איך להשתמש ב-Tasks API עם OAuth 2.0 ב-Android. במאמר מוסברים מנגנוני ההרשאות לקבלת גישה ל-Google Tasks של המשתמש, ואיך אפשר להכין את האובייקט service של Tasks API באפליקציה ל-Android.
כדי שהאפליקציה ל-Android תוכל להשתמש ב-Tasks API, צריך לבצע כמה שלבים:
- בוחרים את חשבון Google של המשתמש
- קבלת אסימון גישה מסוג OAuth 2.0 מ-AccountManager ל-Tasks API
- זיהוי הפרויקט והגדרת אובייקט השירות של Tasks
- ביצוע קריאות ל-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-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.
כדי להשתמש ב-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) תציג את תיבת הדו-שיח של בורר החשבונות.
תהליך ההרשאה של Google APIs ב-Android
עכשיו, לאחר שהמשתמש בחר חשבון, אנחנו יכולים לבקש מ-AccountManager להנפיק אסימון גישה מסוג OAuth 2.0 עבור Task API. כדי לעשות זאת, מפעילים את השיטה AccountManager.getAuthToken(). במהלך הקריאה ל-AccountManager.getAuthToken(), AccountManager.getAuthToken() יטפל ביצירת הקשר עם נקודת הקצה להרשאה של ממשקי ה-API של Google. לאחר ש-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);
כפי שכבר ידוע לך, ב-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 הצגת המשימות, המקבילה לקריאה בלבד של Tasks API היקף: 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. כדי לעשות זאת:
- יצירת פרויקט או שימוש בפרויקט קיים
- כדי להפעיל את Tasks API בפרויקט, מחליפים את המצב של המתג של Tasks API למצב מופעל.
- ניתן למצוא את מפתח ה-API בקטע גישה ל-API > גישה פשוטה ל-API > מפתח API
מפתח ה-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
לא לשכוח להוסיף את הרשאת הגישה לאינטרנט למניפסט של האפליקציה ל-Android, אחרת הבקשות שצוינו למעלה לנקודות הקצה של Tasks API ייכשלו:
<uses-permission android:name="android.permission.INTERNET" />
אפליקציה לדוגמה
לאחרונה הוספנו דוגמה חדשה לספריית הלקוח של Google APIs למאגר הדוגמאות של Java, כדי לעזור לכם להתחיל לעבוד עם Tasks API ו-OAuth 2.0 ב-Android. הדוגמה היא אפליקציה פשוטה אך פעילה ל-Android, שמבקשת הרשאה להשתמש ב-Tasks API ולהציג את המשימות של רשימת המשימות המוגדרת כברירת מחדל ב-ListView.
כדי להפעיל את הדוגמה, אתם צריכים לפעול לפי ההוראות האלה, ואם אתם רוצים לשלוח משוב או שאלות אתם יכולים לשלוח שאלות בפורום של Google Tasks API.