تهيئة دمج واجهة مستخدم Drive

لعرض تطبيقك في Google Drive عندما ينشئ المستخدم ملفًا أو يفتحه، عليك أولاً إعداد عملية دمج واجهة مستخدم Drive (UI). يجب أيضًا ضبط الإعدادات لإدراج تطبيقك في Google Workspace Marketplace.

تفعيل Drive API

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

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

إعداد عملية دمج واجهة مستخدم Drive

  1. في وحدة تحكّم Google API، انتقِل إلى رمز القائمة > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات التي تم تفعيلها.

    الانتقال إلى الخدمات وواجهات برمجة التطبيقات المفعّلة

  2. في أسفل لوحة بيانات "واجهات برمجة التطبيقات والخدمات"، انقر على Google Drive API. ستظهر لك صفحة ضبط Google Drive API.
  3. اختَر علامة التبويب دمج واجهة مستخدم Drive.
  4. (اختياري) أدخِل اسمًا في حقل اسم التطبيق. يتم عرض اسم التطبيق للمستخدمين في علامة التبويب "إدارة التطبيقات" في إعدادات Drive.
  5. (اختياري) أدخِل وصفًا قصيرًا مكونًا من سطر واحد في حقل الوصف القصير. يظهر الوصف الموجز للمستخدمين في علامة التبويب "إدارة التطبيقات" في إعدادات Drive.
  6. (اختياري) أدخِل وصفًا كاملاً في حقل الوصف المفصَّل.
  7. حمِّل رمزًا أو أكثر من رموز التطبيقات ليتم عرضها في قائمة المستخدم لتطبيقات Drive المرتبطة وفي قائمة السياقات "فتح باستخدام". يجب أن تكون الأيقونات بتنسيق PNG بخلفية شفافة. قد يستغرق ظهور الرموز في Drive ما يصل إلى 24 ساعة.

  8. لاستخدام عنصر القائمة "فتح باستخدام" في واجهة مستخدم Drive، أدخِل عنوان URL إلى تطبيقك في حقل فتح عنوان URL. يتم استخدام عنوان URL هذا من خلال قائمة السياقات "فتح باستخدام".

    • يجب أن يحتوي عنوان URL هذا على اسم نطاق مؤهل بالكامل، حيث إنّ localhost لا يعمل.
    • يجب أن يتمكّن المستخدمون المعنيّون في تطبيقك من الوصول إلى عنوان URL هذا. إذا كان لديك إصدارات متعددة من التطبيق، مثل واحد للإصدار المتاح للجميع وآخر للإصدار المقيّد للمستخدمين، يجب أن يستخدم كل إصدار عنوان URL فريدًا. يمكنك بعد ذلك إنشاء عمليات إعداد مختلفة للتطبيق لكل إصدار.
    • عليك إثبات ملكية عنوان URL هذا قبل أن تتمكّن من إدراج تطبيقك في Google Workspace Marketplace.
    • يتم تلقائيًا إلحاق معلَمة طلب البحث state بعنوان URL هذا لنقل البيانات من واجهة مستخدم Drive إلى تطبيقك. للحصول على معلومات عن محتوى المعلَمة state، يُرجى الاطّلاع على المَعلمة state.
  9. (اختياري) أدخِل أنواع MIME التلقائية وامتدادات الملفات في حقلي أنواع MIME التلقائية وامتدادات الملفات التلقائية. تمثل أنواع MIME التلقائية وامتدادات الملفات الملفات التي تم تصميم تطبيقك لفتحها بشكل فريد. على سبيل المثال، قد يفتح تطبيقك تنسيقًا مدمجًا لتقسيم الصور وتعديلها. يجب تضمين أنواع الوسائط العادية فقط والتأكد من خلوها من الأخطاء الإملائية والأخطاء الإملائية. إذا لم يفتح تطبيقك سوى ملفات اختصارات أو ملفات تابعة لجهة خارجية، يمكنك ترك نوع MIME فارغًا.

  10. (اختياري) أدخِل أنواع MIME الثانوية وامتدادات الملفات في حقلي أنواع MIME الثانوية وامتدادات الملفات الثانوية. تمثل أنواع MIME الثانوية وامتدادات الملفات الملفات التي يمكن لتطبيقك فتحها، ولكنها ليست خاصة بتطبيقك. على سبيل المثال، قد يكون تطبيقك تطبيقًا لتعديل الصور يفتح صور PNG وJPG. يجب تضمين أنواع الوسائط العادية فقط والتأكد من خلوها من الأخطاء الإملائية والأخطاء الإملائية. إذا لم يفتح تطبيقك سوى ملفات اختصارات أو ملفات تابعة لجهة خارجية، يمكنك ترك نوع MIME فارغًا.

  11. لاستخدام الزر "جديد" في واجهة مستخدم Drive وطلب إنشاء ملف من خلال تطبيقك، ضع علامة في المربّع إنشاء ملفات. يظهر الحقلان عنوان URL الجديد واسم المستند الاختيارية.

    • يجب أن يحتوي عنوان URL هذا على اسم نطاق مؤهل بالكامل، حيث إنّ localhost لا يعمل.
    • يجب إثبات ملكية عنوان URL هذا قبل أن تتمكّن من إدراج تطبيقك في Google Workspace Marketplace.
    • يتم تلقائيًا إلحاق معلَمة طلب البحث state بعنوان URL هذا لنقل البيانات من واجهة مستخدم Drive إلى تطبيقك. للحصول على معلومات عن محتوى المعلَمة state، يُرجى الاطّلاع على المَعلمة state.
  12. أدخِل عنوان URL في حقل عنوان URL الجديد. يستخدم الزر "جديد" عنوان URL هذا لإعادة توجيه المستخدم إلى تطبيقك.

  13. (اختياري) إذا كنت تريد أن يفتح تطبيقك الملفات المتوافقة مع Google Workspace، ضَع علامة في المربّع استيراد.

  14. (اختياري) إذا كان على تطبيقك إدارة الملفات في مساحات التخزين السحابي المشتركة، ضَع علامة في المربّع دعم مساحات التخزين السحابي المشتركة. لمزيد من المعلومات حول طريقة دعم مساحات التخزين السحابي المشتركة في تطبيقك، يُرجى الاطّلاع على تنفيذ الدعم الخاص بمساحة التخزين السحابي المشتركة.

  15. انقر على إرسال.

طلب نطاق drive.install

للسماح للتطبيقات بالظهور كخيار في القائمة "فتح باستخدام" أو "جديد"، اطلب دمج نطاق https://www.googleapis.com/auth/drive.install مع واجهة مستخدم Drive. عند طلب هذا النطاق، يتلقى المستخدمون مربع حوار مشابه لما يلي:

مربّع حوار تثبيت واجهة مستخدم Google Drive
الشكل 1. مربّع حوار التثبيت عند استخدام النطاقات لواجهة مستخدم Drive.

لمزيد من المعلومات عن النطاقات التي يمكنك طلبها لتطبيقات Drive، وكيفية طلبها، يُرجى الاطِّلاع على معلومات المصادقة والمصادقة الخاصة بواجهة برمجة التطبيقات.

المعلَمة state

يتم تلقائيًا إلحاق المَعلمة state بكل من "عنوان URL المفتوح" و"عنوان URL الجديد" لتمرير البيانات من واجهة مستخدم Drive إلى تطبيقك. وتحتوي هذه المَعلمة على سلسلة بترميز JSON مع متغيّرات النموذج وبيانات عن الطلب المقدّم إلى تطبيقك. وتعتمد المتغيّرات المضمّنة على نوع عنوان URL المستخدَم (فتح عنوان URL أو عنوان URL الجديد):

متغيّر النموذج الوصف تطبيق عنوان URL
{ids} قائمة مفصولة بفواصل تضم معرّفات الملفات التي يتم فتحها. فتح عنوان URL
{exportIds} قائمة مفصولة بفواصل تضم معرّفات الملفات التي يتم تصديرها (تُستخدم فقط عند فتح مستندات Google المضمَّنة) فتح عنوان URL
{resourceKeys} قاموس JSON لأرقام تعريف الملفات التي تم ربطها بمفاتيح الموارد الخاصة بها فتح عنوان URL
{folderId} رقم تعريف المجلد الرئيسي. عنوان URL جديد
{folderResourceKey} مفتاح المصدر للمجلد الرئيسي. عنوان URL جديد
{userId} رقم تعريف الملف الشخصي الذي يحدِّد المستخدم. فتح عنوان URL وعنوان URL جديد
{action} تمثّل هذه السمة الإجراء الذي يتم تنفيذه. وتكون القيمة open عند استخدام عنوان URL مفتوح أو create عند استخدام عنوان URL جديد. فتح عنوان URL وعنوان URL جديد

تتضمّن المَعلمة state عنوان URL مرمَّز، لذا يجب أن يتعامل تطبيقك مع أحرف الإلغاء ويحلّلها بتنسيق JSON. يمكن للتطبيقات رصد القيمة create في المَعلمة state للتحقّق من طلب إنشاء ملف.

مثال على معلومات الحالة بتنسيق JSON لعنوان URL جديد

معلومات state لعنوان URL جديد هي:

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

مثال على معلومات الحالة في ملف JSON لعنوان URL مفتوح

معلومات state لعنوان URL المفتوح هي:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

تُستخدم المعرفات ومفاتيح الموارد لجلب البيانات الوصفية للملفات وتنزيل محتوى الملف. بعد حصول تطبيقك على رقم تعريف الملف ورمز دخول مميّز، يمكنه التحقّق من الأذونات وجلب البيانات الوصفية للملف وتنزيل محتوى الملف، كما هو موضّح في طريقة files.get.

يجب أن يتمكّن التطبيق المثبّت من إنشاء إجراءات يتم تشغيلها من واجهة مستخدم Drive وإدارتها وفتحها. لمعرفة المزيد من المعلومات، يُرجى الاطّلاع على الزر "جديد" في واجهة مستخدم Drive أو الدمج مع قائمة سياقات "فتح باستخدام" في واجهة مستخدم Drive.