Drive Sync-architectuur: URL’s, scopes en audit

Dit is de ontwikkelaarsreferentie voor Drive Sync. Deze pagina is bedoeld voor wie synchronisatietoegang naast de REST API of MCP-server integreert, hulpmiddelen bovenop TrekMail Drive bouwt of controleert hoe de WebDAV-interface rechten afdwingt.

Wil je alleen rclone of Finder met Drive verbinden, begin dan bij het overzicht van Drive Sync.

Wat Drive Sync is

Drive Sync is een WebDAV-interface voor TrekMail Drive. Een compatibele synchronisatie-app krijgt hiermee toegang tot dezelfde bestanden die je in het dashboard en webmail ziet, met een eigen apparaatwachtwoord en geselecteerde rechten.

De interface gebruikt standaard WebDAV-methoden onder een vast voorvoegsel. De ondersteuning verschilt per client. Test daarom de benodigde bewerkingen met een wegwerpmap voordat je de client voor een productiemigratie of back-up gebruikt.

URL-indeling

De Drive-URL wordt voor de implementatie gegenereerd en weergegeven onder Sync devices. Kopieer die URL in plaats van er zelf een te maken op basis van je dashboarddomein. Het pad begint met /dav/files/:

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

Onder deze hoofdmap staan een accountstructuur en mailboxstructuren. Wat een wachtwoord kan openen, hangt af van zowel de koppeling aan een mailbox als de geselecteerde rechten:

Structuur voor het hele account

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

Dit is de Account Drive uit het dashboard. Een wachtwoord dat niet tot één mailbox is beperkt, kan deze structuur zien als het een Account Drive-recht heeft.

Structuur beperkt tot een mailbox

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

Wanneer een apparaatwachtwoord tot één mailbox is beperkt, kan het alleen de persoonlijke structuur van die mailbox zien. Als de mailbox toegang tot persoonlijke Drive heeft en het account gedeelde mappen bevat, toont de verzameling Shared/ de accountmappen die met alle mailboxen zijn gedeeld.

Een wachtwoord dat tot één mailbox is beperkt, kan Account Drive of een andere mailbox niet zien. Een wachtwoord zonder mailboxbeperking kan de Drive-ruimten van het account weergeven, maar elk pad vereist nog steeds het bijbehorende account- of mailboxrecht.

Een apparaatwachtwoord maken

Je kunt een wachtwoord maken via Sync devices in het dashboard of, voor de mailbox die je op dat moment gebruikt, via webmail. Het dashboard kan een wachtwoord voor het hele account maken of het tot één mailbox beperken. Webmail maakt alleen een wachtwoord voor de aangemelde mailbox.

Kies een duidelijk label, selecteer alleen de rechten die de app nodig heeft en stel een vervaldatum in als de verbinding tijdelijk is. Het geheim wordt eenmaal getoond. Sla het op in de app of een wachtwoordbeheerder voordat je het bevestigingsscherm sluit.

Je kunt een apparaatwachtwoord op elk moment intrekken zonder je normale TrekMail-aanmeldwachtwoord te wijzigen. Een ingetrokken of verlopen wachtwoord werkt onmiddellijk niet meer.

Aanmelden met een apparaatwachtwoord

Synchronisatie gebruikt HTTP Basic via HTTPS. Voer de gebruikersnaam uit Sync devices en het gegenereerde apparaatwachtwoord in. Gebruik je wachtwoord voor het TrekMail-dashboard niet in een synchronisatie-app.

Als het wachtwoord wordt ingetrokken of verloopt, vraagt de app doorgaans opnieuw om aanmeldgegevens. Bij elke aanvraag worden de accountstatus, mailboxrechten, Drive-toegang en geselecteerde rechten gecontroleerd.

Scopemodel

Drive Sync gebruikt dezelfde scopetekenreeksen als de REST API, in de vorm drive:{family}:{action}. Deze acht zijn van toepassing op apparaatwachtwoorden:

Voor het lezen van een pad is het bijbehorende recht :read vereist. Voor maken, wijzigen, verplaatsen, kopiëren of verwijderen is :write nodig. Het pad bepaalt of de app om account- of mailboxtoegang vraagt. Een wachtwoord dat tot één mailbox is beperkt, kan daarom Account Drive of een andere mailbox niet bereiken.

Het scherm Sync devices biedt alleen rechten die zinvol zijn voor een synchronisatie-app. Factureringsrechten maken geen deel uit van een apparaatwachtwoord.

Rechten voor delen en permanent verwijderen

Het formulier voor apparaatwachtwoorden kan de rechten :share en :purge tonen als het account daar recht op heeft. De huidige WebDAV-routebeveiliging koppelt bestandsbewerkingen alleen aan :read en :write. Ga er dus niet van uit dat een van deze rechten een WebDAV-opdracht voor deellinks of permanent verwijderen toevoegt.

Voor WebDAV vereist een normale DELETE de machtiging :write en wordt een bestand naar de prullenbak verplaatst. WebDAV biedt geen vervanging van een bestand op dezelfde locatie en geen bewerking voor permanent verwijderen. Gebruik hiervoor de Drive-interface.

Veilige bestandsnamen

Bestands- en mapnamen moeten veilig zijn op verschillende besturingssystemen. Lege namen, padscheidingstekens, besturingstekens, misleidende tekens in bestandsnamen en namen die na Windows- of Unicode-normalisatie botsen, worden geweigerd. Namen mogen maximaal 255 zichtbare tekens lang zijn.

Als een app een validatiefout ontvangt, hernoem je het item in de app en probeer je het opnieuw. Probeer de fout niet te omzeilen door een pad in een bestandsnaam te plaatsen.

Uploads in delen

Kleine bestanden kunnen een gewone PUT gebruiken. Clients die de Nextcloud-flow voor uploads in delen v2 ondersteunen, kunnen een uploadsessie onder /dav/uploads/{session-uuid}/ maken, genummerde delen uploaden en vervolgens met MOVE het bestand op de uiteindelijke locatie samenstellen.

Uploadlimieten kunnen per implementatie en client verschillen. Behandel een mislukte of verlopen sessie als een nieuwe uploadpoging. Als een andere client de bestemming eerst maakt, gebruik je de conflictrespons om een nieuwe naam te kiezen of vernieuw je de map voordat je het opnieuw probeert.

Auditregistratie

Geslaagde wijzigingen via Sync verschijnen in de activiteitengeschiedenis van Drive. De registratie vermeldt het betrokken item, de actie, het tijdstip en het gebruikte apparaatwachtwoord. Zo kan een beheerder onverwachte wijzigingen onderzoeken en het betreffende wachtwoord intrekken.

Clients die de Drive-wijzigingsfeed gebruiken, kunnen wijzigingen zien die via WebDAV zijn aangebracht. Als de dienst om een volledige hersynchronisatie vraagt, bouw je de lokale weergave opnieuw op vanuit een recente momentopname voordat je doorgaat met de opgeslagen cursor.

Aanvraaglimieten

Aanvragen aan Drive Sync zijn begrensd om de dienst en je bestanden te beschermen. Als een client 429 ontvangt, verlaag je de gelijktijdigheid, respecteer je Retry-After als dit wordt meegeleverd en probeer je een kleine bewerking opnieuw voordat je de taak hervat.

Beschikbaarheid

Drive Sync is beschikbaar in productie. Accounts hebben Drive-toegang nodig en de beschikbare rechten voor apparaatwachtwoorden blijven afhankelijk van het account, de mailbox, het abonnement en de persoon die het wachtwoord maakt. White Label-klanten gebruiken dezelfde Drive Sync-dienst. Kopieer altijd de actuele URL uit Sync devices in plaats van er zelf een te maken.

Volgende stappen

• Raadpleeg voor installatie door eindgebruikers het overzicht van Drive Sync.
• Raadpleeg voor de dashboardinterface die apparaatwachtwoorden uitgeeft Sync devices.
• Raadpleeg voor de REST API- en MCP-equivalenten van deze bewerkingen het overzicht van de Drive API en Scopes en rechten van de Drive API.
• Raadpleeg voor het opslag- en quotamodel dat synchronisatie met alle andere functies deelt Uitleg over gedeelde opslagquota.