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

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

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

قبل استخدام 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.