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

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

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

الميزات

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

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

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

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

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

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

إعداد البيئة

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

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

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

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

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

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

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

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

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

  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" واختَر العنصر المطلوب.

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

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

دمج 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 يتوافق مع نوع تطبيقك وإعدادات OAuth. لا يفرض Google Picker أي قيود إضافية.

  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" مع تطبيقات Android

يمكنك أيضًا استخدام "أداة اختيار الملفات من Google" في تطبيقات 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

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

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

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

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