התחלה מהירה עם Drive API למפתחים

מדריך זה מציג את הדרך הבטוחה ביותר מרעיון לשילוב ועד לקריאה פעילה ל-Drive API. תיצרו אסימון בעל הרשאות מצומצמות, תציגו מרחבי Drive, תעלו קובץ אחד ותיצרו קישור שיתוף ציבורי עם תאריך תפוגה.

1. יצירת אסימון Drive

פתחו סוכני AI ו-API → אסימונים → יצירת אסימון. תנו לאסימון שם ברור כמו drive-report-uploader. בחרו רק את טווחי ההרשאה הדרושים לתהליך העבודה.

למדריך זה השתמשו ב:

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

אל תכללו הרשאות מחיקה סופית בשילוב ראשון. שמרו מחיקה קבועה לאסימון תחזוקה נפרד.

העתיקו את האסימון מיד לאחר יצירתו. TrekMail מציג את הערך הגלוי פעם אחת ושומר רק גיבוב מאובטח.

2. הגדרת כתובת הבסיס והאסימון

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 מחזיר הוראות העלאה. שלחו את הבתים לכתובת ההעלאה שהוחזרה, ולאחר מכן קראו ל:

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. בדיקת נתיב הביקורת

פתחו סוכני AI ו-API → יומן ביקורת וסננו לפי אסימון. אתם אמורים לראות יצירת תיקייה, העלאה, השלמה ויצירת קישור שיתוף. זו הדרך המהירה ביותר לוודא שהשילוב משתמש באסימון ובטווחי ההרשאה הצפויים.

רשימת בדיקה לסביבת ייצור

• השתמשו באסימון אחד לכל שילוב.
• העניקו הרשאות קריאה, כתיבה ושיתוף בנפרד; אל תכללו מחיקה סופית בתהליכים יומיומיים.
• הוסיפו תפוגה ומגבלות הורדה לקישורים ציבוריים.
• השתמשו במפתח אידמפוטנטיות כאשר תיעוד נקודת הקצה או מפרט OpenAPI דורשים זאת. בתהליך זה נכללים יצירת תיקייה, התחלת העלאה ויצירת קישור שיתוף.
• בטלו אסימוני בדיקה לאחר הפיתוח.