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

لعرض تطبيقك في Google Drive عندما ينشئ المستخدم ملفًا أو يفتحه، عليك أولاً إعداد عملية دمج واجهة مستخدم Drive. يجب أيضًا ضبط إعدادات تطبيقك لإدراج تطبيقك في 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.