دمج 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.

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

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

تفويض بيانات اعتماد لتطبيق كمبيوتر

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

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

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

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > تطبيق كمبيوتر.
  4. في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google Cloud 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

    صادِق على تطبيقك من خلال تشغيل Google Picker.

  • مربّع حوار تسجيل الدخول باستخدام حساب Google والأذونات

    سجِّل الدخول باستخدام حساب Google وامنح الأذونات المطلوبة.

  • واجهة اختيار ملفات Google Drive داخل أداة Picker

    تصفَّح ملفات Google Drive في Google Picker واختَر العنصر المطلوب.

  • شاشة تأكيد إدراج الملف التي تعرض الزر "إدراج"

    أكِّد اختيارك وانقر على "إدراج" لإضافة الملف إلى تطبيقك.

دمج 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.

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

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

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

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

لعرض 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، وهي قائمة بمعرّفات الملفات المحدّدة مفصولة بفواصل.