بنية Drive Sync: عناوين URL والنطاقات والتدقيق

هذا مرجع Drive Sync للمطورين، عند دمج المزامنة مع REST API أو MCP server، أو بناء أدوات فوق TrekMail Drive، أو تدقيق تطبيق واجهة WebDAV للأذونات.

لربط rclone أو Finder فقط، ابدأ بـ نظرة عامة على Drive Sync.

ما هو Drive Sync

Drive Sync هو واجهة WebDAV لـ TrekMail Drive. يمنح تطبيق مزامنة متوافق وصولا إلى ملفات لوحة المعلومات وبريد الويب نفسها باستخدام كلمة مرور جهاز وأذونات محددة.

تستخدم الواجهة طرق WebDAV القياسية عند بادئة ثابتة. يختلف دعم العملاء، لذا اختبر العمليات المطلوبة في مجلد مؤقت قبل ترحيل أو نسخ احتياطي production.

بنية URL

ينشأ URL حسب النشر ويظهر في Sync devices. انسخه ولا تبنه من نطاق لوحة المعلومات. يبدأ المسار بـ /dav/files/:

https://YOUR-DRIVE-HOST/dav/files/

تحت الجذر شجرة حساب وأشجار صناديق بريد. يعتمد ما تفتحه كلمة المرور على ارتباطها بصندوق بريد وعلى أذوناتها معا.

شجرة الحساب كله

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

هذه Account Drive في لوحة المعلومات. كلمة المرور غير المقيدة بصندوق واحد تراها عند امتلاك إذن Account Drive.

شجرة صندوق البريد

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

كلمة المرور المقيدة بصندوق واحد ترى شجرته الشخصية فقط. إذا كان له Drive شخصي وللحساب مجلدات مشتركة، تعرض Shared/ مجلدات الحساب المشتركة مع الجميع.

لا ترى كلمة المرور المقيدة Account Drive أو صندوقا آخر. غير المقيدة تسرد مساحات Drive، لكن كل مسار يتطلب إذن الحساب أو الصندوق المطابق.

إنشاء كلمة مرور جهاز

أنشئها من Sync devices في لوحة المعلومات، أو من بريد الويب للصندوق الحالي. تنشئ لوحة المعلومات كلمة على مستوى الحساب أو تقيدها بصندوق، وبريد الويب يقيدها بالصندوق المسجل.

اختر تسمية واضحة والأذونات المطلوبة فقط، وحدد انتهاء للاتصال المؤقت. يظهر السر مرة واحدة، فاحفظه في التطبيق أو مدير كلمات المرور قبل إغلاق التأكيد.

يمكن إبطالها دون تغيير كلمة دخول TrekMail. تتوقف الكلمة الملغاة أو المنتهية فورا.

الدخول بكلمة مرور جهاز

تستخدم المزامنة HTTP Basic عبر HTTPS. أدخل اسم المستخدم من Sync devices وكلمة الجهاز المنشأة، ولا تستخدم كلمة لوحة TrekMail.

بعد الإبطال أو الانتهاء، يطلب التطبيق بيانات الاعتماد عادة. تفحص حالة الحساب ووصول الصندوق وDrive والأذونات عند كل طلب.

نموذج النطاقات

يستخدم Drive Sync سلاسل REST API نفسها بصيغة drive:{family}:{action}. تنطبق ثمانية على كلمات الأجهزة:

قراءة مسار تحتاج :read المطابق، والإنشاء والتغيير والنقل والنسخ والحذف تحتاج :write. يحدد المسار نوع الوصول، فلا تصل كلمة مقيدة إلى Account Drive أو صندوق آخر.

تعرض Sync devices الأذونات المناسبة للمزامنة فقط. Billing permissions ليست جزءا من كلمة الجهاز.

أذونات Share وpurge

قد تعرض الاستمارة :share و:purge عند استحقاق الحساب. guard مسار WebDAV الحالي يربط عمليات الملفات فقط بـ :read و:write، فلا تفترض أن اختيارهما يضيف أمر رابط أو حذف نهائي في WebDAV.

يتطلب DELETE العادي :write وينقل الملف إلى Trash. لا يوفر WebDAV استبدالا في المكان أو purge نهائيا. استخدم واجهة Drive.

أمان أسماء الملفات

يجب أن تكون الأسماء آمنة عبر الأنظمة. ترفض الأسماء الفارغة وفواصل المسار ومحارف التحكم والمحارف المضللة وما يتعارض بعد تطبيع Windows أو Unicode. الحد 255 محرفا ظاهرا.

عند خطأ التحقق، غير الاسم في التطبيق وحاول مجددا. لا تضع مسارا في اسم الملف للتحايل.

الرفع المجزأ

تستخدم الملفات الصغيرة PUT عاديا. عملاء Nextcloud chunked-upload v2 ينشئون جلسة تحت /dav/uploads/{session-uuid}/ ويرفعون أجزاء مرقمة ثم يستخدمون MOVE للتجميع في الموقع النهائي.

تختلف الحدود حسب النشر والعميل. اعتبر الجلسة الفاشلة أو المنتهية محاولة جديدة. إذا سبق عميل آخر إلى الوجهة، استخدم رد التعارض لاختيار اسم أو تحديث المجلد.

سجل التدقيق

تظهر تغييرات Sync الناجحة في نشاط Drive. تحدد السجل العنصر والإجراء والوقت وكلمة الجهاز، ليحقق المسؤول ويلغي الكلمة ذات الصلة.

يرى عملاء Drive change feed تغييرات WebDAV. إذا طلبت الخدمة مزامنة كاملة، فأعد بناء العرض المحلي من snapshot جديد قبل متابعة cursor المحفوظ.

حدود المعدل

طلبات Drive Sync محدودة لحماية الخدمة والملفات. عند 429 خفض concurrency والتزم بـ Retry-After إن قدم، وجرب عملية صغيرة قبل استئناف المهمة.

التوفر

Drive Sync متاح في production. يلزم وصول Drive، وتعتمد الأذونات على الحساب والصندوق والخطة ومنشئ الكلمة. يستخدم White Label الخدمة نفسها. انسخ URL من Sync devices دائما.

الخطوة التالية

• إعداد المستخدم: نظرة عامة على Drive Sync.
• واجهة إصدار كلمات الأجهزة: Sync devices.
• مكافئات REST API وMCP: نظرة عامة على Drive API ونطاقات وأذونات Drive API.
• نموذج التخزين والحصة: شرح حصص التخزين المجمعة.