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

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

تفعيل Drive API

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

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

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

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

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

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

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

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.
   تحذير: تم إيقاف الخيار الذي يتيح عرض شاشة الموافقة المتعلّقة ببروتوكول OAuth 2.0 تلقائيًا. لا تضع علامة في هذا المربّع. يجب أن يبدأ التطبيق جميع طلبات التفويض.

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

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

    ملاحظة: إذا ثبّت المستخدم تطبيقات متعددة من Drive يمكنها فتح ملف، سيتم استخدام آخر تطبيق تم تثبيته إلى أن يختار المستخدم تطبيقًا آخر.

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. عند طلب هذا النطاق، يتلقّى المستخدمون مربّع حوار مشابهًا لما يلي:

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

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

ملاحظة: إذا نشرت تطبيق Drive في Google Workspace Marketplace، يمكن للمستخدمين ومشرفي النطاق البحث عن التطبيق وتثبيته مباشرةً من Google Workspace Marketplace.

المَعلمة 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 عند استخدام Open URL أو create عند استخدام New 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.

ملاحظة: يجب أن تستدعي جميع التطبيقات، بما في ذلك التطبيقات التي تفتح الملفات من الاختصارات والاختصارات التابعة لجهات خارجية، الطريقة files.get للتحقّق من أذونات المستخدم بشأن مستند. يجب أن تحذّر التطبيقات المستخدمين الذين لديهم إذن بالقراءة فقط عند فتح ملف لا يمكنهم تعديله أو حفظه (بدلاً من السماح لهم بقضاء الوقت في التعديل، ثم عرض رسالة خطأ عند الحفظ).

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

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