نظرة المطورين إلى API الخاصة بخدمة TrekMail Drive

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

أتمتة Drive جزء من TrekMail REST API v1. وهي تستخدم رموز bearer واستجابات JSON وحماية التكرار الآمن حيث يدعمها endpoint، ومسار التدقيق نفسه المعروض ضمن وكلاء الذكاء الاصطناعي وAPI ← سجل التدقيق. يحتوي نموذج أذونات Drive على 11 نطاقا، منها نطاقات منفصلة لكلمات مرور أجهزة المزامنة. تتطور كتالوجات endpoints وأدوات MCP، لذلك استخدم قائمة الأدوات التي يتم إرجاعها واستجابات API لمعرفة السطح المتاح حاليا لرمزك المميز.

ما يمكنك أتمتته

تشمل مهام Drive API المعتادة:

• رفع التقارير الشهرية إلى Drive الخاص بالحساب.
• إنشاء مجلد للعميل وإضافة ملفات ومشاركة رابط تنزيل واحد.
• السماح لوكيل بالبحث في مساحات Drive الخاصة بصناديق البريد وتلخيص ما تغير.
• نقل الملفات القديمة إلى مجلد أرشيف.
• استعادة الملفات من المهملات بعد عملية تنظيف غير مقصودة.
• قراءة حالة إضافة Drive قبل تحذير مستخدم من أن مساحة التخزين أوشكت على الامتلاء.

تركز API على الملفات عن قصد. فهي لا تحل محل لوحة معلومات الفوترة ولا تعرض تغييرات الدفع أو الاشتراك.

Drive الخاص بالحساب وDrive الخاص بصندوق البريد

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

تحدد طلبات API الهدف باستخدام معامل space:

account       # Account Drive
mailbox:42    # mailbox-personal Drive for mailbox ID 42
123           # internal Drive space ID, if your integration stores it

يمكن تقييد الرموز المميزة بصناديق بريد محددة. إذا اقتصر الرمز على صندوق البريد 42، فستعيد طلبات صندوق البريد 99 استجابة شبيهة بعدم العثور بدلا من كشف وجود صندوق البريد الآخر.

المصادقة وعنوان URL الأساسي

استخدم رمز عمليات في ترويسة Authorization:

Authorization: Bearer tm_live_your_token

توجد endpoints الخاصة بخدمة Drive ضمن:

https://trekmail.net/api/v1/drive

أنشئ الرموز من وكلاء الذكاء الاصطناعي وAPI ← الرموز المميزة. اختر نطاقات Drive التي يحتاج إليها مسار عملك فقط.

نطاقات Drive الأحد عشر

عمليات الرفع والملفات الكبيرة

تستخدم عمليات الرفع نمطا من خطوتين. أولا تحجز API الحصة وتعيد تعليمات الرفع. ثم يرسل عميلك وحدات بايت الملف إلى عنوان URL للرفع. وأخيرا، تضع API علامة اكتمال على عملية الرفع. يمكن للملفات الكبيرة استخدام الرفع متعدد الأجزاء وتحديث عناوين URL للأجزاء إذا انتهت صلاحية عملية نقل طويلة.

بالنسبة إلى معظم وكلاء الذكاء الاصطناعي، تكون أداة MCP المسماة drive_file_upload أسهل من استدعاء endpoints منخفضة المستوى للرفع مباشرة. فهي تتولى اكتشاف حجم الملف والرفع والإكمال والإلغاء عند الفشل بأمر واحد.

روابط المشاركة

تنشئ روابط المشاركة عناوين URL عامة لتنزيل الملفات الفردية. وهي مفيدة عندما يكون الملف أكبر من أن يرسل بالبريد الإلكتروني أو عندما ينبغي أن يكون الوصول قابلا للإلغاء. عيّن تاريخ انتهاء وحدا للتنزيل كلما أمكن. لا تتم إعادة الرمز الخام للرابط إلا مرة واحدة عند الإنشاء، لذلك خزّن عنوان URL الذي تم إرجاعه فورا إذا كان مسار عملك يحتاج إليه.

أمان الحذف والحذف النهائي

تنقل عمليات الحذف العادية الملفات والمجلدات إلى المهملات. تظل العناصر قابلة للاستعادة حتى تتم استعادتها أو حذفها نهائيا أو إزالتها وفقا لقواعد الاحتفاظ في المنتج. تتطلب عمليات الحذف الدائم نطاقات الحذف النهائي وينبغي عزلها في رمز مميز منفصل.

حدود إضافة Drive

يمكن للوكلاء قراءة حالة إضافة Drive وسعرها ومعاينة إلغائها باستخدام drive:addon:read. لا يتوفر شراء إضافة Drive أو تغيير سعتها أو إلغاؤها من خلال أدوات الكتابة في REST أو MCP. تظل هذه الإجراءات داخل لوحة المعلومات حتى تبقى فوترة التخزين مسارا مقصودا يتحكم فيه المستخدم.