Architettura Drive Sync: URL, scope e audit

Questo è il riferimento per sviluppatori dedicato a Drive Sync. Se stai integrando l’accesso di sincronizzazione con l’API REST o il server MCP, creando strumenti basati su TrekMail Drive o verificando come l’interfaccia WebDAV applica i permessi, questa è la pagina giusta.

Se vuoi soltanto collegare rclone o Finder a Drive, inizia dalla panoramica di Drive Sync.

Che cos’è Drive Sync

Drive Sync è un’interfaccia WebDAV per TrekMail Drive. Consente a un’app di sincronizzazione compatibile di accedere agli stessi file visibili nella dashboard e nella webmail, con una password dispositivo dedicata e i permessi selezionati.

L’interfaccia utilizza metodi WebDAV standard sotto un prefisso fisso. Il supporto varia tra i client, quindi prova le operazioni necessarie con una cartella eliminabile prima di usare il client per una migrazione o un backup di produzione.

Struttura degli URL

L’URL di Drive viene generato per la distribuzione e mostrato in Sync devices. Copia questo URL invece di costruirne uno dal dominio della dashboard. Il percorso inizia con /dav/files/:

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

Sotto questa radice si trovano un albero dell’account e gli alberi delle caselle. Ciò che una password può aprire dipende sia dall’associazione alla casella sia dai permessi selezionati:

Albero dell’intero account

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

Questo è l’Account Drive della dashboard. Una password non limitata a una singola casella può vedere questo albero se dispone di un permesso Account Drive.

Albero limitato a una casella

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

Quando una password dispositivo è limitata a una casella, può vedere solo l’albero personale di quella casella. Se la casella dispone dell’accesso al Drive personale e l’account contiene cartelle condivise, la raccolta Shared/ mostra le cartelle dell’account condivise con tutte le caselle.

Una password limitata a una casella non può vedere Account Drive o un’altra casella. Una password senza limite di casella può elencare gli spazi Drive dell’account, ma ogni percorso richiede comunque il permesso corrispondente dell’account o della casella.

Creare una password dispositivo

Puoi creare una password da Sync devices nella dashboard oppure, per la casella che stai usando, dalla webmail. La dashboard può creare una password per l’intero account o limitarla a una casella. La webmail crea una password solo per la casella con cui hai effettuato l’accesso.

Scegli un’etichetta chiara, seleziona solo i permessi necessari all’app e imposta una scadenza se la connessione è temporanea. Il segreto viene mostrato una sola volta. Salvalo nell’app o in un gestore di password prima di chiudere la schermata di conferma.

Puoi revocare una password dispositivo in qualsiasi momento senza cambiare la normale password di accesso a TrekMail. Una password revocata o scaduta smette immediatamente di funzionare.

Accedere con una password dispositivo

La sincronizzazione utilizza HTTP Basic su HTTPS. Inserisci il nome utente visualizzato in Sync devices e la password dispositivo generata. Non usare la password della dashboard TrekMail in un’app di sincronizzazione.

Se la password viene revocata o scade, normalmente l’app richiede nuovamente le credenziali. Lo stato dell’account, l’accesso alla casella, l’accesso a Drive e i permessi selezionati vengono verificati a ogni richiesta.

Modello degli scope

Drive Sync usa le stesse stringhe di scope dell’API REST, nel formato drive:{family}:{action}. Questi sono gli otto scope applicabili alle password dispositivo:

La lettura di un percorso richiede il relativo permesso :read. Per creare, modificare, spostare, copiare o eliminare occorre :write. Il percorso determina se l’app richiede l’accesso all’account o alla casella, quindi una password limitata a una casella non può raggiungere Account Drive o un’altra casella.

La schermata Sync devices offre soltanto permessi appropriati per un’app di sincronizzazione. I permessi di fatturazione non fanno parte di una password dispositivo.

Permessi di condivisione ed eliminazione definitiva

Il modulo della password dispositivo può mostrare i permessi :share e :purge quando l’account ne ha diritto. L’attuale protezione delle route WebDAV associa le operazioni sui file soltanto a :read e :write, quindi non presumere che la selezione di uno di questi permessi aggiunga a WebDAV un comando per creare link condivisi o eliminare definitivamente.

In WebDAV, un normale DELETE richiede :write e sposta il file nel cestino. WebDAV non consente di sostituire un file nella stessa posizione né di eseguire un’eliminazione definitiva. Per queste operazioni usa l’interfaccia Drive.

Sicurezza dei nomi dei file

I nomi di file e cartelle devono essere sicuri su sistemi operativi diversi. Vengono rifiutati nomi vuoti, separatori di percorso, caratteri di controllo, caratteri ingannevoli nei nomi e nomi che entrerebbero in conflitto dopo la normalizzazione Windows o Unicode. I nomi possono contenere fino a 255 caratteri visibili.

Se un’app riceve un errore di convalida, rinomina l’elemento nell’app e riprova. Non cercare di aggirare l’errore inserendo un percorso nel nome di un file.

Caricamenti in blocchi

I file piccoli possono usare un normale PUT. I client che supportano il flusso di caricamento in blocchi v2 di Nextcloud possono creare una sessione di caricamento sotto /dav/uploads/{session-uuid}/, caricare blocchi numerati e poi usare MOVE per assemblare il file nella destinazione finale.

I limiti di caricamento possono variare in base alla distribuzione e al client. Considera una sessione non riuscita o scaduta come un nuovo tentativo di caricamento. Se un altro client crea prima la destinazione, usa la risposta di conflitto per scegliere un nuovo nome o aggiorna la cartella prima di riprovare.

Registro di audit

Le modifiche completate correttamente tramite Sync compaiono nella cronologia delle attività di Drive. Il record identifica l’elemento interessato, l’azione, l’ora e la password dispositivo utilizzata, consentendo a un amministratore di esaminare modifiche impreviste e revocare la password pertinente.

I client che usano il feed delle modifiche di Drive possono vedere le modifiche effettuate tramite WebDAV. Se il servizio richiede una risincronizzazione completa, ricostruisci la vista locale da uno snapshot aggiornato prima di proseguire con il cursore salvato.

Limiti di frequenza

Le richieste Drive Sync sono soggette a limiti per proteggere il servizio e i tuoi file. Se un client riceve 429, riduci la concorrenza, rispetta Retry-After quando viene fornito e riprova una piccola operazione prima di riprendere il lavoro.

Disponibilità

Drive Sync è disponibile in produzione. Gli account devono avere accesso a Drive e i permessi disponibili per le password dispositivo dipendono comunque dall’account, dalla casella, dal piano e dalla persona che crea la password. I clienti White Label usano lo stesso servizio Drive Sync. Copia sempre l’URL corrente da Sync devices invece di costruirlo.

Passaggi successivi

• Per la configurazione destinata agli utenti finali, consulta la panoramica di Drive Sync.
• Per l’interfaccia della dashboard che genera password dispositivo, consulta Sync devices.
• Per gli equivalenti di queste operazioni nell’API REST e in MCP, consulta la Panoramica dell’API Drive e Scope e permessi dell’API Drive.
• Per il modello di archiviazione e quote condiviso dalla sincronizzazione con tutte le altre funzioni, consulta Spiegazione delle quote di archiviazione aggregate.