ארכיטקטורת Drive Sync: כתובות, היקפים וביקורת

זהו מסמך למפתחים על Drive Sync, לשילוב גישת סנכרון לצד REST API או MCP server, בניית כלים על TrekMail Drive או ביקורת אכיפת ההרשאות של WebDAV.

לחיבור rclone או Finder בלבד, התחילו בסקירת Drive Sync.

מהו Drive Sync

Drive Sync הוא ממשק WebDAV ל-TrekMail Drive. יישום תואם מקבל גישה לאותם קבצים שבלוח הבקרה ובדואר הרשת, עם סיסמת התקן והרשאות נבחרות.

הממשק משתמש בשיטות WebDAV רגילות בקידומת קבועה. התמיכה משתנה בין לקוחות, לכן בדקו פעולות בתיקייה זמנית לפני העברת production או גיבוי.

מבנה URL

כתובת Drive נוצרת עבור הפריסה ומופיעה ב-Sync devices. העתיקו אותה ואל תבנו אותה מדומיין לוח הבקרה. הנתיב מתחיל ב-/dav/files/:

https://YOUR-DRIVE-HOST/dav/files/

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

עץ כלל החשבון

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

זהו Account Drive בלוח הבקרה. סיסמה שאינה מוגבלת לתיבה אחת יכולה לראותו עם הרשאת Account Drive.

עץ מוגבל לתיבת דואר

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

סיסמה המוגבלת לתיבה אחת רואה רק את העץ האישי שלה. אם יש גישת Drive אישית ותיקיות משותפות, Shared/ מציגה את תיקיות החשבון המשותפות לכולן.

היא אינה רואה Account Drive או תיבה אחרת. סיסמה ללא הגבלה יכולה למנות מרחבי Drive, אך כל נתיב עדיין דורש הרשאת חשבון או תיבה תואמת.

יצירת סיסמת התקן

צרו אותה דרך Sync devices בלוח הבקרה או בדואר הרשת לתיבה הנוכחית. לוח הבקרה יוצר סיסמת חשבון או מגביל לתיבה; דואר הרשת יוצר רק לתיבה המחוברת.

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

אפשר לבטל בלי לשנות סיסמת TrekMail רגילה. סיסמה מבוטלת או שפג תוקפה מפסיקה מיד.

כניסה עם סיסמת התקן

הסנכרון משתמש ב-HTTP Basic מעל HTTPS. הזינו שם משתמש מ-Sync devices ואת סיסמת ההתקן. אל תשתמשו בסיסמת לוח הבקרה.

לאחר ביטול או תפוגה היישום מבקש שוב פרטים. מצב החשבון, גישת תיבה ו-Drive וההרשאות נבדקים בכל בקשה.

מודל היקפים

Drive Sync משתמש באותן מחרוזות כמו REST API בתבנית drive:{family}:{action}. שמונה חלות על סיסמאות התקן:

קריאה דורשת :read, ויצירה, שינוי, העברה, העתקה או מחיקה דורשות :write. הנתיב קובע חשבון או תיבה, ולכן סיסמה מוגבלת אינה מגיעה ל-Account Drive או לתיבה אחרת.

Sync devices מציג רק הרשאות המתאימות לסנכרון. Billing permissions אינן חלק מהסיסמה.

הרשאות Share ו-purge

הטופס עשוי להציג :share ו-:purge לפי זכאות. WebDAV route guard הנוכחי ממפה פעולות רק ל-:read ו-:write, לכן בחירתן אינה מוסיפה פקודת קישור או מחיקה לצמיתות ב-WebDAV.

DELETE רגיל דורש :write ומעביר ל-Trash. WebDAV אינו מספק החלפה במקום או purge לצמיתות. השתמשו בממשק Drive.

בטיחות שמות קבצים

שמות חייבים להיות בטוחים במערכות שונות. שמות ריקים, מפרידי נתיב, תווי בקרה, תווים מטעים ושמות שמתנגשים אחרי נרמול Windows או Unicode נדחים. עד 255 תווים גלויים.

בשגיאת אימות, שנו שם ביישום ונסו שוב. אל תעקפו באמצעות נתיב בשם.

העלאות בחלקים

קבצים קטנים משתמשים ב-PUT. לקוחות Nextcloud chunked-upload v2 יוצרים הפעלה תחת /dav/uploads/{session-uuid}/, מעלים חלקים ממוספרים ומשתמשים ב-MOVE להרכבה ביעד.

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

נתיב ביקורת

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

לקוחות Drive change feed רואים שינויי WebDAV. אם נדרש סנכרון מלא, בנו תצוגה מקומית מ-snapshot חדש לפני המשך עם cursor שמור.

מגבלות קצב

בקשות מוגבלות להגנה. בעת 429, הפחיתו concurrency, כבדו Retry-After אם סופק ונסו פעולה קטנה לפני חידוש המשימה.

זמינות

Drive Sync זמין ב-production. נדרשת גישת Drive וההרשאות תלויות בחשבון, בתיבה, בתוכנית וביוצר. White Label משתמש באותו שירות. העתיקו URL מ-Sync devices.

מה הלאה

• הגדרת משתמש: סקירת Drive Sync.
• ממשק הנפקת סיסמאות: Sync devices.
• מקבילות REST API ו-MCP: סקירת Drive API והיקפים והרשאות Drive API.
• מודל אחסון ומכסות: הסבר על מכסות אחסון משותפות.