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

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

تفعيل Drive API

قبل استخدام Google APIs، يجب تفعيلها في مشروع على 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 Workspace.	فتح عنوان 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.

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

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

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