دمج Google Picker في تطبيقات أجهزة الكمبيوتر والأجهزة الجوّالة

يوضّح هذا المستند كيفية دمج Google Picker في تطبيقات الكمبيوتر والأجهزة الجوّالة باستخدام Google Picker API.

تتيح Google Picker API للمستخدمين اختيار ملفات Google Drive أو تحميلها. يمكن للمستخدمين منح الإذن لتطبيق الكمبيوتر أو تطبيق الأجهزة الجوّالة أو تطبيق الويب بالوصول إلى بياناتهم على Drive، ما يوفّر طريقة آمنة ومصرّح بها للتفاعل مع ملفاتهم.

الميزات

يتضمّن Google Picker عدة ميزات:

• مظهر مشابه لواجهة مستخدم Google Drive UI
• عدّة طرق عرض تعرض معاينات وصورًا مصغّرة لملفات Drive
• طرق عرض تمت فلترتها مسبقًا ولا تعرض سوى أنواع ملفات معيّنة (مثل ملفات PDF أو الصور) أو مجلدات معيّنة
• إعادة توجيه إلى Google Picker ضمن علامة تبويب جديدة في المتصفّح التلقائي للمستخدم لفتح Google Picker API في صفحة عميل، استخدِم Google Picker API لتطبيقات الويب بدلاً من ذلك.

يُرجى العِلم أنّه على الرغم من إمكانية اختيار الملفات وتحميلها باستخدام Google Picker، لا يسمح للمستخدمين بتنظيم الملفات أو نقلها أو نسخها من مجلد إلى آخر. لإدارة الملفات، عليك استخدام Google Drive API أو واجهة مستخدم Drive.

المتطلبات الأساسية

يجب أن تلتزم التطبيقات التي تستخدم Google Picker بجميع بنود الخدمة الحالية. الأهم من ذلك هو تحديد هويتك بشكل صحيح في طلباتك.

يجب أن يكون لديك أيضًا مشروع على Google Cloud.

إعداد البيئة

لبدء استخدام Google Picker API، عليك إعداد بيئتك.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

• في Google Cloud Console، فعِّل Google Picker API.

  تفعيل واجهة برمجة التطبيقات

إعداد المصادقة والتفويض

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر لبروتوكول OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد على خوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.

السماح ببيانات اعتماد لتطبيق كمبيوتر

لإنشاء معرّف عميل لبروتوكول OAuth 2.0، اتّبِع الخطوات التالية:

1. في Google API Console، انتقِل إلى "القائمة" menu > منصة مصادقة Google > العملاء.

   الانتقال إلى "العملاء"

2. انقر على إنشاء عميل.
3. انقر على نوع التطبيق > تطبيق كمبيوتر.
4. في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google API Console.
5. انقر على إنشاء.

   تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن "معرّفات عملاء OAuth 2.0".

لكي تحصل التطبيقات على إذن الوصول إلى الملفات التي تم منحها سابقًا، عليك اتّباع الخطوات التالية:

1. عليك الحصول على رمز OAuth 2.0 مميز باستخدام النطاق drive.file أو drive أو drive.readonly باتّباع هذه التعليمات: استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs. لمزيد من المعلومات عن النطاقات، يُرجى الاطّلاع على اختيار نطاقات Google Drive API.

2. مرِّر رمز OAuth 2.0 المميز إلى Drive API لقراءة الملفات وتعديلها التي سبق أن منح المستخدم إذن الوصول إليها.

السماح ببيانات اعتماد لتطبيق الأجهزة الجوّالة

لإنشاء معرّف عميل لبروتوكول OAuth 2.0، اتّبِع الخطوات الواردة ضمن السماح ببيانات اعتماد لتطبيق الأجهزة الجوّالة.

السماح ببيانات اعتماد لتطبيق الويب

لإنشاء معرّف عميل لبروتوكول OAuth 2.0، اتّبِع الخطوات الواردة ضمن السماح ببيانات اعتماد لتطبيق الويب.

عرض Google Picker

تعيد Google Picker API لتطبيقات الكمبيوتر والأجهزة الجوّالة توجيه المستخدم إلى Google Picker ضمن علامة تبويب جديدة في المتصفّح التلقائي للمستخدم. بعد أن يمنح المستخدم إذن الوصول ويختار الملفات ذات الصلة، يعود Google Picker إلى التطبيق الذي تم استدعاؤه من خلال عنوان URL للردّ.

دمج Google Picker في تطبيقك

للسماح للمستخدمين بمنح إذن الوصول إلى ملفات إضافية أو اختيار ملفات لاستخدامها في مسار تطبيقك، اتّبِع الخطوات التالية:

1. اطلب إذن الوصول إلى النطاق drive.file لفتح صفحة الوصول إلى OAuth 2.0 في علامة تبويب متصفّح جديدة باتّباع هذه التعليمات: استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs. لمزيد من المعلومات عن النطاقات، يُرجى الاطّلاع على اختيار نطاقات Google Drive API.

   يُرجى العِلم أنّه لا يُسمح لهذه التطبيقات إلا بالنطاق drive.file ولا يمكن دمجه مع أي نطاق آخر.

2. يقبل عنوان URL لعلامة تبويب المتصفّح الجديدة جميع مَعلمات سلسلة طلبات البحث القياسية لبروتوكول OAuth.

   عليك إلحاق مَعلمتَي عنوان URL‏ prompt وtrigger_onepick بطلب عنوان URL لمنح تفويض OAuth 2.0. يمكنك أيضًا تخصيص Google Picker باستخدام عدة مَعلمات أخرى اختيارية:

   المَعلمة	الوصف	الحالة
   prompt=consent	طلب إذن الوصول إلى الملف	مطلوب
   trigger_onepick=true	تفعيل Google Picker	مطلوب
   allow_multiple=true	السماح للمستخدم باختيار ملفات متعددة إذا كانت القيمة "صحيح"	اختياري
   mimetypes=MIMETYPES	قائمة بأنواع MIME مفصولة بفواصل لفلترة نتائج البحث إذا لم يتم ضبط هذه المَعلمة، ستظهر الملفات لجميع أنواع MIME في طريقة العرض.	اختياري
   file_ids=FILE_IDS	قائمة قيم مفصولة بفاصلة لمعرّفات الملفات لفلترة نتائج البحث إذا لم يتم ضبط هذه المَعلمة، ستظهر جميع الملفات في طريقة العرض.	اختياري
   allow_folder_selection=true	السماح للمستخدم باختيار المجلدات أيضًا إذا كانت القيمة "صحيح"	اختياري

   يوضّح المثال التالي طلب عنوان URL لمنح تفويض OAuth 2.0:

   https://accounts.google.com/o/oauth2/v2/auth? \
   client_id=CLIENT_ID \
   &scope=https://www.googleapis.com/auth/drive.file \
   &redirect_uri=REDIRECT_URI \
   &response_type=code \
   &access_type=offline \
   &prompt=consent \
   &trigger_onepick=true
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • CLIENT_ID: معرّف عميل تطبيقك

   • REDIRECT_URI: المكان الذي يعيد إليه خادم التفويض توجيه متصفّح المستخدم بعد المصادقة الناجحة على سبيل المثال، https://www.cymbalgroup.com/oauth2callback

     يجب أن يكون redirect_uri المحدّد عنوان URL عامًا يستخدم HTTPS. إذا كنت تريد استخدام بروتوكول مخصّص أو عنوان URL للمضيف المحلي لـ redirect_uri، عليك استخدام عنوان URL عام يستخدم HTTPS ثم يعيد التوجيه إلى البروتوكول المخصّص أو عنوان URL للمضيف المحلي.

3. بعد أن يمنح المستخدم إذن الوصول ويختار الملفات ذات الصلة، يعيد OAuth التوجيه إلى redirect_uri المحدّد في الطلب مع إلحاق مَعلمات عنوان URL التالية:

   • picked_file_ids: إذا منح المستخدم إذن الوصول واختار ملفات، ستظهر قائمة بمعرّفات الملفات المحدّدة مفصولة بفواصل.

   • code: رمز الدخول أو رمز التفويض استنادًا إلى مَعلمة response_type التي تم ضبطها في الطلب تتضمّن هذه المَعلمة رمز تفويض جديدًا .

   • scope: النطاقات المضمّنة في الطلب

   • error: إذا ألغى المستخدم الطلب ضمن مسار الموافقة، سيظهر خطأ.

   يوضّح المثال التالي استجابة عنوان URL لمنح تفويض OAuth 2.0:

   https://REDIRECT_URI?picked_file_ids=PICKED_FILE_IDS&code=CODE&scope=SCOPES
   

4. يجب أن تبدّل التطبيقات رمز التفويض من الخطوة 3 برمز OAuth 2.0 مميز جديد. لمزيد من المعلومات، يُرجى الاطّلاع على تبديل رمز التفويض برموز التجديد والدخول والدخول.

5. يمكن للتطبيقات بعد ذلك استخدام معرّفات الملفات من مَعلمة عنوان URL في الخطوة 3 ورمز OAuth 2.0 المميز الذي تم الحصول عليه في الخطوة 4 لاستدعاء Drive API. لمعرفة المزيد، يُرجى الانتقال إلى نظرة عامة على Google Drive API.

استخدام Google Picker مع تطبيقات Android

يمكنك أيضًا استخدام Google Picker في تطبيقات Android للأجهزة الجوّالة.

السماح ببيانات اعتماد لتطبيق الأجهزة الجوّالة

لاستخدام Google Picker في تطبيق Android، عليك السماح لـ المستخدمين باستخدام OAuth 2.0، على غرار تطبيقات الكمبيوتر. لمعرفة التفاصيل عن مصادقة Android، يُرجى الاطّلاع على السماح بالوصول إلى بيانات مستخدمي Google data.

لعرض Google Picker أثناء عملية السماح، أنشِئ AuthorizationRequest واستخدِم مَعلمة المورد PICKER_OAUTH_TRIGGER في العنصر AuthorizationRequest.ResourceParameter.

عند إنشاء AuthorizationRequest:

• استخدِم النطاق drive.file.

• استدعِ setOptOutIncludingGrantedScopes على true للتأكّد من أنّ الرمز المميّز الذي يتم عرضه مخصّص للنطاق drive.file فقط وليس لأي نطاقات تم منحها سابقًا.

• اضبط الحقل AuthorizationRequest.Prompt على CONSENT لطلب موافقة المستخدم حتى إذا تم منحها من قبل.

• يمكنك اختياريًا استخدام عامل التشغيل "أو" (|) على مستوى البت لضبط حقل AuthorizationRequest.Prompt أيضًا على SELECT_ACCOUNT للسماح للمستخدم باختيار حساب قبل عرض طلب الموافقة.

استدعاء Google Picker

على غرار تطبيقات الكمبيوتر، يمكنك تخصيص Google Picker باستخدام عدة مَعلمات اختيارية:

• PICKER_ALLOW_MULTIPLE: يسمح للمستخدمين باختيار ملفات متعددة.
• PICKER_MIMETYPES: يقبل قائمة بأنواع MIME مفصولة بفواصل لفلترة نتائج البحث. إذا لم يتم ضبط هذه المَعلمة، ستظهر الملفات لجميع أنواع MIME في طريقة العرض.
• PICKER_FILE_IDS: يقبل قائمة قيم مفصولة بفاصلة لمعرّفات الملفات لفلترة نتائج البحث. إذا لم يتم ضبط هذه المَعلمة، ستظهر جميع الملفات في طريقة العرض.
• PICKER_ALLOW_FOLDER_SELECTION: يسمح للمستخدمين باختيار المجلدات أيضًا.

لمزيد من المعلومات عن المَعلمات الاختيارية في تطبيقات الكمبيوتر، يُرجى الاطّلاع على عرض Google Picker.

بعد أن يمنح المستخدم إذن الوصول ويختار الملفات ذات الصلة، يتم عرض العنصر getTokenResponseParams لمورد AuthorizationResult. إذا منح المستخدم إذن الوصول، يحتوي هذا العنصر على القيمة picked_file_ids، وهي قائمة بمعرّفات الملفات المحدّدة مفصولة بفواصل.

مواضيع ذات صلة

• اختيار نطاقات Google Drive API