عندما يختار المستخدم ملفًا وينقر على عنصر القائمة "فتح باستخدام" في واجهة مستخدم Drive، يعيد Drive توجيه المستخدم إلى عنوان URL الخاص بالتطبيق والمحدّد في ضبط عملية الدمج مع واجهة مستخدم Drive.
إذا وضعت علامة في المربّع "استيراد" عند إعداد عملية دمج واجهة مستخدم Drive، يمكن للمستخدم اختيار مجموعة من الملفات الخاصة بالتطبيق وملفات Google Workspace لفتحها. عند ضبط عملية دمج واجهة مستخدم Drive، يتم تحديد الملفات الخاصة بالتطبيق في الحقلَين "أنواع MIME التلقائية" و"امتدادات الملفات التلقائية"، بينما يتم تحديد ملفات Google Workspace في الحقلَين "أنواع MIME الثانوية" و "امتدادات الملفات الثانوية".
بالنسبة إلى كل ملف يريد المستخدم فتحه، يتحقّق Drive من أنواع MIME مقارنةً بأنواع MIME التلقائية والثانوية التي حدّدتها:
بالنسبة إلى أنواع MIME المحدّدة في الحقل "أنواع MIME التلقائية"، يتم تمرير معرّف الملف إلى تطبيقك. وللحصول على معلومات حول كيفية التعامل مع الملفات الخاصة بالتطبيق، راجِع مقالة التعامل مع عنوان URL مفتوح للمستندات الخاصة بالتطبيق.
بالنسبة إلى أنواع MIME المحدّدة في حقل "أنواع MIME الثانوية"، تعرض واجهة مستخدم Drive مربّع حوار يسأل المستخدم عن نوع الملف الذي يريد تحويل ملف Google Workspace إليه. على سبيل المثال، إذا اخترت ملفًا بتنسيق "مستندات Google" في واجهة مستخدم Drive واقترح حقل "أنواع MIME الثانوية" أنّ تطبيقك يتوافق مع text/plain أو application/pdf، ستسأل واجهة مستخدم Drive المستخدم عمّا إذا كان يريد التحويل إلى "نص عادي" أو PDF.
للحصول على معلومات حول كيفية التعامل مع ملفات Google Workspace، يُرجى الاطّلاع على التعامل مع عنوان URL مفتوح لمستندات Google Workspace. للاطّلاع على قائمة بمستندات Google Workspace وتنسيقات تحويل أنواع MIME، يُرجى الاطّلاع على تصدير أنواع MIME لمستندات Google Workspace.
التعامل مع طلب فتح عنوان URL لمستندات خاصة بالتطبيق
كما هو موضّح في إعداد عملية دمج لواجهة مستخدم Drive، يتلقّى تطبيقك متغيّرات النموذج التي تتضمّن معلومات تتيح لتطبيقك فتح الملف. يتلقّى تطبيقك مجموعة تلقائية من متغيّرات النموذج
ضمن المَعلمة state
. في ما يلي
معلومات state
تلقائية لعنوان URL خاص بتطبيق معيّن:
{
"ids": ["ID"],
"resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
"action":"open",
"userId":"USER_ID"
}
يتضمّن هذا الناتج القيم التالية:
- ID: معرّف المجلد الرئيسي
- RESOURCE_KEYS: قاموس JSON لمعرّفات الملفات التي تم ربطها بمفاتيح الموارد الخاصة بها.
-
open
: الإجراء الذي يتم تنفيذه القيمة هيopen
عند استخدام Open URL. - USER_ID: رقم تعريف الملف الشخصي الذي يحدّد المستخدم بشكل فريد.
يجب أن يتّخذ تطبيقك إجراءً بشأن هذا الطلب باتّباع الخطوات التالية:
- تأكَّد من أنّ الحقل
action
يتضمّن القيمةopen
وأنّ الحقلids
متوفّر. - استخدِم القيمة
userId
لإنشاء جلسة جديدة للمستخدم. لمزيد من المعلومات عن المستخدمين الذين سجّلوا الدخول، اطّلِع على المستخدمون والأحداث الجديدة. - استخدِم طريقة
files.get
للتحقّق من الأذونات وجلب البيانات الوصفية للملف وتنزيل محتوى الملف باستخدام قيمID
. - إذا تم ضبط
resourceKeys
في الطلب، اضبط عنوان الطلبX-Goog-Drive-Resource-Keys
. لمزيد من المعلومات حول مفاتيح الموارد، يُرجى الاطّلاع على الوصول إلى الملفات التي تتم مشاركتها باستخدام رابط من خلال مفاتيح الموارد.
يتم ترميز المَعلمة state
باستخدام ترميز عنوان URL، لذا يجب أن يتعامل تطبيقك مع أحرف الإلغاء
ويحلّلها بتنسيق JSON.
التعامل مع عنوان URL مفتوح لمستندات Google Workspace
كما هو موضّح في إعداد عملية دمج لواجهة مستخدم Drive، يتلقّى تطبيقك مجموعة تلقائية من متغيّرات النموذج ضمن المَعلمة state
. state
المعلومات التلقائية
لفتح عنوان URL في Google Workspace هي:
{
"exportIds": ["ID"],
"resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
"action":"open",
"userId":"USER_ID"
}
يتضمّن هذا الناتج القيم التالية:
- EXPORT_ID: قائمة بأرقام تعريف الملفات مفصولة بفواصل يتم تصديرها (يتم استخدامها فقط عند فتح مستندات Google المضمّنة).
- RESOURCE_KEYS: قاموس JSON لمعرّفات الملفات التي تم ربطها بمفاتيح الموارد الخاصة بها.
-
open
: الإجراء الذي يتم تنفيذه القيمة هيopen
عند استخدام Open URL. - USER_ID: رقم تعريف الملف الشخصي الذي يحدّد المستخدم.
يجب أن يتّخذ تطبيقك إجراءً بشأن هذا الطلب باتّباع الخطوات التالية:
تأكَّد من أنّ هذا الطلب يهدف إلى فتح ملف من خلال رصد كلّ من القيمة
open
في الحقلstate
ووجود الحقلexportIds
.استخدِم طريقة
files.get
للتحقّق من الأذونات واسترداد البيانات الوصفية للملفات وتحديد نوع MIME باستخدام قيمEXPORT_ID
.حوِّل محتوى الملف باستخدام الطريقة
files.export
. يوضّح نموذج الرمز التالي كيفية تصدير مستند Google Workspace إلى نوع MIME المطلوب.إذا تم ضبط
resourceKey
في الطلب، اضبط عنوان الطلبX-Goog-Drive-Resource-Keys
. لمزيد من المعلومات حول مفاتيح الموارد، يُرجى الاطّلاع على الوصول إلى الملفات التي تتم مشاركتها باستخدام رابط من خلال مفاتيح الموارد.Java
Python
Node.js
PHP
عرض الملفات المحوَّلة كملفات للقراءة فقط أو عرض مربّع حوار يتيح للمستخدم حفظ الملف بنوع الملف الجديد
يتم ترميز المَعلمة state
باستخدام ترميز عنوان URL، لذا يجب أن يتعامل تطبيقك مع أحرف الإلغاء
ويحلّلها بتنسيق JSON.
المستخدمون والأحداث الجديدة
يجب أن تتعامل تطبيقات Drive مع جميع أحداث "فتح باستخدام" على أنّها عمليات تسجيل دخول محتملة. قد يكون لدى بعض المستخدمين حسابات متعددة، لذا قد لا يتطابق معرّف المستخدم في المَعلمة state
مع الجلسة الحالية. إذا كان معرّف المستخدم في المَعلمة state
لا يتطابق مع الجلسة الحالية، عليك إنهاء الجلسة الحالية لتطبيقك وتسجيل الدخول بصفتك المستخدم المطلوب.
مواضيع ذات صلة
بالإضافة إلى فتح تطبيق من واجهة مستخدم Google Drive، يمكن للتطبيقات عرض أداة اختيار ملفات لاختيار المحتوى من داخل التطبيق. لمزيد من المعلومات، اطّلِع على Google Picker.