أتمتة رفع الملفات باستخدام Drive API

تُعد أتمتة الرفع من أكثر عمليات Drive API فائدة. يمكن أن تصل التقارير والفواتير وملفات التصدير وملفات PDF الموقعة ومرفقات الدعم إلى مجلد TrekMail Drive الصحيح بلا نقل يدوي.

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

النطاقات الموصى بها

للرفع إلى Drive الحساب، ابدأ بالنطاقين:

• drive:account:read
• drive:account:write

للرفع إلى Drive صندوق البريد، استخدم:

• drive:mailbox:read
• drive:mailbox:write

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

فحوص ما قبل الرفع

قبل رفع ملف كبير، استدع endpoint ملخص التخزين أو استخدام المساحة. عالج "تجاوز الحصة" كنتيجة عمل عادية لا كتعطل.

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

مسار رفع REST

1. أرسل POST /api/v1/drive/spaces/{space}/uploads:initiate مع اسم الملف وحجمه ومعرّف المجلد الاختياري ونوع MIME.
2. أرسل وحدات بايت الملف إلى عنوان الرفع أو عناوين الرفع متعدد الأجزاء التي أُعيدت.
3. أرسل POST /api/v1/drive/uploads/{file}:complete بعد نجاح النقل.
4. عند فشل النقل، استدع POST /api/v1/drive/uploads/{file}:abort لتحرير الحجز بسرعة.

استخدم Idempotency-Key في طلب البدء الذي يحجز السعة. استخدم مفتاحا ثابتا لكل ملف منطقي مثل invoice-2026-05-001-upload. لا تفترض أن كل endpoint لاحق يعيد نتائج ثابتة؛ احتفظ بمعرّف الملف وافحص حالته قبل إعادة محاولة الإكمال أو إلغاء النقل.

مسار رفع MCP

للوكلاء، فضّل أداة واحدة:

drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)

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

قواعد الأسماء والمجلدات

استخدم أسماء متوقعة ليسهل تصفح Drive لاحقا:

• Reports/2026/05/monthly-summary.pdf
• Clients/Acme/contracts/acme-renewal-2026.pdf
• Invoices/2026/INV-2026-0042.pdf

أضف طابعا زمنيا أو إصدارا للنسخ المتكررة. لا تفقد المعنى برفع final.pdf كل أسبوع.

معالجة الإخفاقات

خطط لهذه الحالات:

بعد الرفع

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