دليل API وMCP لروابط مشاركة Drive

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

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

النطاقات المطلوبة

استخدم drive:account:share لملفات Drive الخاصة بالحساب. واستخدم drive:mailbox:share لملفات Drive الخاصة بصندوق البريد. ومن المفيد أيضا منح نطاق للقراءة، لأن معظم مهام سير العمل تحتاج إلى العثور على الملف قبل مشاركته.

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

إنشاء رابط باستخدام REST

curl -s -X POST "https://trekmail.net/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-{FILE_ID}-client-a" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

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

إنشاء رابط باستخدام MCP

drive_share_create(file_id=123, expires_at="2026-06-01T00:00:00Z", max_downloads=25)

اطلب من الوكيل إعادة عنوان URL في إجابته النهائية وذكر تاريخ انتهاء الصلاحية وحد التنزيل.

عرض الروابط وإلغاؤها

استخدم endpoint القائمة أو drive_share_list للاطلاع على الروابط النشطة والسابقة لملف. استخدم الإلغاء عندما يرسل رابط إلى الشخص الخطأ أو عندما يصبح عقد غير صالح أو تنتهي فترة تسليم مؤقتة.

drive_share_revoke(link_id=456)

يسري الإلغاء على الفور. أنشئ رابطا جديدا إذا كان يجب استعادة الوصول.

القيم الافتراضية الموصى بها

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

سلوك الأمان

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

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

سجل التدقيق

يسجل إنشاء روابط المشاركة وإلغاؤها مع هوية رمز API. إذا كان وكيل ينشئ روابط للعملاء، فراجع سجل التدقيق دوريا وبدل الرموز عندما تتغير مسؤوليات الفريق.