بدء سريع لواجهة Drive API للمطورين

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

1. إنشاء رمز Drive

افتح وكلاء الذكاء الاصطناعي وAPI → الرموز → إنشاء رمز. امنح الرمز اسما واضحا مثل drive-report-uploader. حدد فقط النطاقات المطلوبة لسير عملك.

استخدم في هذا الدليل:

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

لا تضف نطاقات الحذف النهائي في أول تكامل. احتفظ بالحذف الدائم في رمز صيانة منفصل.

انسخ الرمز فور إنشائه. يعرض TrekMail النص الصريح مرة واحدة ولا يخزن سوى تجزئة آمنة.

2. ضبط عنوان URL الأساسي والرمز

export TREKMAIL_BASE_URL="https://trekmail.net"
export TREKMAIL_API_TOKEN="tm_live_your_token"

يستخدم كل طلب ترويسة bearer نفسها:

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. سرد مساحات Drive المتاحة

curl -s "$TREKMAIL_BASE_URL/api/v1/drive/spaces" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN"

تتضمن الاستجابة Drive الحساب وأي مساحات Drive لصناديق البريد يسمح للرمز برؤيتها. استخدم account للإشارة إلى Drive الحساب في الأمثلة التالية.

4. إنشاء مجلد

يجب أن تتضمن عمليات الكتابة مفتاح عدم تكرار. إذا أعادت الشبكة محاولة الطلب، يمكن لـ TrekMail إعادة النتيجة الأصلية بدلا من إنشاء نسخ مكررة.

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/folders" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: folder-$(date +%s)" \
  -d '{"name":"API Uploads","color":"#2563eb"}'

احفظ معرّف المجلد المعاد.

5. رفع ملف

تفصل REST API بين التفاوض على الرفع ونقل الملف. ابدأ أولا:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/uploads:initiate" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-report-001" \
  -d '{"name":"report.pdf","size_bytes":123456,"folder_id":42,"client_mime":"application/pdf"}'

يعيد TrekMail تعليمات الرفع. أرسل البايتات إلى عنوان URL المعاد، ثم استدع:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/uploads/{FILE_ID}:complete" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

إذا كنت تستخدم MCP، ففضّل drive_file_upload. تجمع الأداة خطوات البدء والنقل والإكمال والإلغاء.

6. إنشاء رابط مشاركة

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-report-001" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

عنوان URL العام المعاد هو المرة الوحيدة التي يظهر فيها رمز الرابط الخام. احفظه الآن إذا كنت ستحتاج إلى إرساله لاحقا.

7. التحقق من مسار التدقيق

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

قائمة تحقق للإنتاج

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