تحذير: تم إيقاف هذا المستند نهائيًا. للحصول على معلومات حول تفويض تطبيقات Android باستخدام OAuth 2.0، يُرجى الاطّلاع على مستندات تفويض "خدمات Android Play"
يشرح هذا المستند كيفية استخدام واجهة برمجة تطبيقات "مهام Google" مع OAuth 2.0 على نظام التشغيل Android. ويوضّح هذا الدليل آليات التفويض للحصول على إذن بالوصول إلى "مهام Google" لدى المستخدم وكيفية الاستعداد لاستخدام عنصر خدمة "مهام Google" في تطبيق Android.
لكي يستخدم تطبيق Android واجهة برمجة تطبيقات "مهام Google" يجب إجراء عدة خطوات، يجب:
- اختيار حساب Google للمستخدم
- الحصول على رمز دخول OAuth 2.0 من AccountManager لواجهة برمجة تطبيقات المهام
- تحديد مشروعك وإعداد عنصر خدمة "مهام Google"
- إجراء اتصالات بواجهة برمجة تطبيقات "مهام Google"
استيراد مكتبة عملاء 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
عليك استيراد حاوية "مهام Google" الخاصة بـ "مهام Google":
استيراد الملحقات (كل جزء من google-api-java-client-1.4.1-beta.zip):
- كومونز-كودك-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 الحسابات التي سجّلتها في بيئتك، وهي الحسابات المُدرجة ضمن الإعدادات >. الحسابات المزامنة. وعلى وجه التحديد، تعالج الخدمة مسار التفويض، ويمكنها إنشاء رموز مميّزة للتفويض تكون مطلوبة للوصول إلى البيانات باستخدام واجهات برمجة التطبيقات.
لتتمكّن من استخدام AccountManager للحصول على الحسابات وطلب الرموز المميّزة للتفويض، عليك إضافة الأذونات التالية في بيان تطبيق Android:
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />
يمكنك استخدام AccountManager للحصول على حساب Google الذي تريد الوصول إلى "مهام Google" له. لا يدير 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 في واجهة برمجة تطبيقات المهام. ويتم ذلك من خلال استدعاء الطريقة AccountManager.getAuthToken(). أثناء استدعاء AccountManager.getAuthToken() لـ AccountManager.getAuthToken() سيتم الاهتمام بالاتصال بنقطة نهاية تفويض Google APIs. عندما يسترد 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: عند إعداد 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 الخاصة والتي يسهل على الإنسان قراءتها في واجهة برمجة تطبيقات "مهام Google". يعادل استخدام نطاق OAuth 2.0. على سبيل المثال، يمكنك استخدام:
String AUTH_TOKEN_TYPE = "Manage your tasks";
يمكنك أيضًا استخدام العنوان البديل AUTH_TOKEN_TYPE. عرض المهام الذي يعادل قراءة "مهام Google" في واجهة برمجة التطبيقات للقراءة فقط النطاق: oauth2:https://www.googleapis.com/auth/tasks.readonly.
أثناء استدعاء AccountManager.getAuthToken() خلال استدعاء AccountManager.getAuthToken()، سيتحقّق مما إذا كان تطبيقك لديه الإذن بالوصول إلى واجهة برمجة تطبيقات "مهام Google". إذا لم يتم تفويض تطبيقك حتى الآن، سيتم بدء نشاط عن طريق مدير الحساب الذي يعرض مربع حوار التفويض للمستخدم حتى يتمكن من السماح أو رفض تطبيقك لاستخدام واجهة برمجة تطبيقات المهام في حسابه.
إذا رفض المستخدم وصول تطبيقك إلى واجهة برمجة تطبيقات "مهام Google"، سيتم طرح الأمر OperationCanceledException أثناء استدعاء future.getResult() . يجب التعامل مع هذا الإجراء برفق على سبيل المثال من خلال طلب اختيار الحساب مرة أخرى أو عرض رسالة تتضمّن زرًا لمنح الإذن بالوصول مرة أخرى.
تحديد تطبيقك وإعداد كائن خدمة Tasks API
الآن بعد أن حصل تطبيقك على تفويض للوصول إلى واجهة برمجة تطبيقات "مهام Google" وتم منحه رمز الدخول، ستحتاج أيضًا إلى مفتاح واجهة برمجة التطبيقات الذي تحتاج إلى الحصول عليه من مشروع في وحدة التحكم في Google APIs حيث إنه إلزامي لإجراء طلبات البيانات من واجهة برمجة تطبيقات "مهام Google". لإجراء ذلك، يُرجى اتّباع الخطوات التالية:
- إنشاء مشروع أو استخدام مشروع حالي
- يمكنك تفعيل واجهة برمجة تطبيقات "مهام Google" في مشروعك من خلال تبديل مفتاح واجهة برمجة تطبيقات "مهام Google" إلى تفعيل.
- يمكن العثور على مفتاح واجهة برمجة التطبيقات في الوصول إلى واجهة برمجة التطبيقات > الوصول البسيط إلى واجهة برمجة التطبيقات > مفتاح واجهة برمجة التطبيقات
يكون مفتاح واجهة برمجة التطبيقات إلزاميًا لأنّه يحدّد تطبيقك، وبالتالي يسمح لواجهة برمجة التطبيقات بخصم الحصة واستخدام قواعد الحصص المحدَّدة لمشروعك. يجب تحديد مفتاح واجهة برمجة التطبيقات في كائن خدمة "مهام Google":
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 صالحًا لفترة زمنية معيّنة فقط، لذا يجب الحصول على رمز جديد عند انتهاء صلاحيته. هناك طريقتان للتعامل مع هذا الأمر:
- اطلب accessToken إلى AccountManager في كل مرة تقدّم فيها طلبات من خلال واجهة برمجة التطبيقات. يُعدّ هذا الحل مقبولاً لأنّ AccountManager يخزّن الرمز المميّز مؤقتًا.
- واصِل استخدام accessToken إلى أن تظهر لك رسالة الخطأ 403، حيث تطلب حينها رمزًا مميّزًا جديدًا إلى AccountManager.
معالجة "مهام Google" من خلال واجهة برمجة التطبيقات
في هذه المرحلة، يجب أن يكون لديك كائن خدمة "مهام Google" تم إعداده بالكامل ويمكنك استخدامه لطلب بحث عن واجهة برمجة التطبيقات وفقًا لدليل مطوّر واجهة برمجة تطبيقات المهام، على سبيل المثال:
// Getting all the Task lists
List
لا تنسَ إضافة إذن الوصول إلى الإنترنت إلى بيان تطبيق Android، وإلا سيتعذّر تنفيذ الطلبات الواردة أعلاه إلى نقاط نهاية واجهة برمجة تطبيقات "مهام Google":
<uses-permission android:name="android.permission.INTERNET" />
نموذج تطبيق
أضفنا مؤخرًا نموذجًا جديدًا إلى مكتبة برامج Google APIs لمستودع نماذج Java لمساعدتك في بدء استخدام Tasks API وOAuth 2.0 على Android. النموذج هو تطبيق Android بسيط ولكنه يعمل بكامل طاقته، ويطلب إذنًا لاستخدام واجهة برمجة تطبيقات "مهام Google" وعرض مهام قائمة المهام التلقائية في شكل ListView.
اتّبِع هذه التعليمات لبدء تنفيذ النموذج، ولا تتردد في نشر ملاحظاتك أو أسئلتك في منتدى Google Tasks API.