Collegare un client compatibile con S3

Collega il client S3 a https://api.dosya.dev/s3 usando indirizzamento con percorso, regione us-east-1 e la coppia di credenziali S3 associata a una chiave API dosya. Il contenitore è un ID dello spazio di lavoro, non il nome visualizzato. Il gateway espone file ordinari; amministrazione dei contenitori AWS e funzioni di immutabilità non sono supportate.

Prima di iniziare

Scegli lo spazio di lavoro e apri Integrazioni → S3. Impostazioni di connessione mostra Endpoint, Region e Bucket dello spazio attuale. Se la pagina indica Il tuo ruolo non consente di usare il gateway S3, chiedi accesso S3 a proprietario o amministratore prima di configurare il client. I permessi del ruolo per elencare, caricare, scaricare ed eliminare si applicano separatamente.

Puoi usare S3 sul piano gratuito entro le quote di spazio e download. La creazione di chiavi API è limitata a tre per utenti effettivamente gratuiti e 20 in totale. Un limite esplicito di chiave o ruolo può restringere dimensione file, byte giornalieri scaricati, richieste al minuto o trasferimenti attivi. Il protocollo è esente dai limiti del piano su numero di richieste e simultaneità; l’esenzione non elimina restrizioni esplicite o limiti di traffico in uscita.

Passaggi: genera la coppia corretta

1. Apri Profilo → Chiavi API → Crea una chiave API. Inserisci un nome in A cosa serve?. Per questa prova di elenco, caricamento e download scegli Accesso completo; Sola lettura consente esplorazione e download ma rifiuta caricamenti, mentre Solo caricamento non può elencare o scaricare oggetti.
2. In Restrizioni e scadenza scegli Solo quelli che scelgo per Protocolli, seleziona Gateway S3 e vincola Spazio di lavoro previsto. Scegli una scadenza breve e controlla indirizzi, orari e limiti d’uso adatti al client. Scegli cartella… può rendere una cartella la radice del client.
3. Scegli Genera la chiave. Salva la chiave API dos_… completa se ti serve anche quella credenziale: viene mostrata solo alla creazione. Il client S3 richiede una coppia separata, non questo valore.
4. Espandi la riga della chiave salvata. In Credenziali S3 scegli Attiva. Nella finestra Credenziali S3 copia ID chiave di accesso, Chiave di accesso segreta, Indirizzo del servizio e Regione prima di Fatto. L’ID di accesso inizia con DOSYA; il segreto generato ha 40 caratteri. Conservalo nell’archivio protetto del client.

Lo screenshot mostra le restrizioni della chiave API, non la successiva finestra del segreto S3. S3 Attive · mostra può mostrare di nuovo l’ID, ma sostituisce il segreto con La chiave segreta non può essere recuperata. Per sostituirla, revoca e ricrea la chiave. Abilitare due volte la stessa chiave viene rifiutato con S3 credentials already exist for this API key. Delete and recreate to regenerate. Se perdi il segreto serve una nuova coppia e chiave; aggiorna i client dipendenti e revoca la vecchia chiave. La revoca è irreversibile e rifiuta sia la chiave sia la coppia S3; non elimina i file salvati.

Passaggi: inserisci le impostazioni

Campo client	Valore dosya
Indirizzo del servizio compatibile S3	https://api.dosya.dev/s3
Regione	us-east-1
Firma / autenticazione	AWS Signature Version 4
Chiave di accesso	ID DOSYA… generato
Chiave segreta	Segreto S3 associato, mai la chiave API dos_…
Indirizzamento	Con percorso (forcePathStyle: true nell’SDK AWS per JavaScript)
Contenitore	ID esatto dello spazio copiato da Integrazioni → S3, per esempio ws_example

Non inserire il contenitore nel nome host. Un oggetto con chiave checks/sample.txt si trova in /s3/ws_example/checks/sample.txt e appare come sample.txt dentro checks in File. S3 non aggiunge la raccolta WebDAV All: All/sample.txt indicherebbe invece una cartella ordinaria. Copia gli ID esattamente anche se lo spazio è stato rinominato.

Una chiave limitata a una cartella mantiene l’ID del contenitore dello spazio, ma risolve ogni chiave oggetto relativamente alla cartella di riferimento. Se è Projects, checks/sample.txt raggiunge Projects/checks/sample.txt; non anteporre ancora Projects. La limitazione dell’appartenenza si interseca con quella della chiave. La chiave non può raggiungere una gerarchia più ampia di quella del membro, un altro spazio vincolato o una cartella nel cestino. Gli elementi nascosti al proprietario della chiave o al suo ruolo sono esclusi salvo il permesso hide_files, che consente di vederli; la chiave non aggira tali regole.

Passaggi: verifica un trasferimento di prova

1. Elenca il contenitore scelto, preferibilmente tramite ID diretto. La ricerca dei contenitori può essere filtrata agli spazi consentiti; il successo non prova il permesso di caricare.
2. Scegli un nuovo nome sotto un prefisso di prova autorizzato, per esempio checks/s3-first-sample.txt. Carica byte innocui e attendi il risultato. Un nuovo percorso annidato può creare cartelle mancanti se il ruolo lo consente.
3. Aggiorna File in dosya e controlla spazio, percorso relativo alla cartella di riferimento, nome e dimensione. Scarica quella chiave esatta in un file locale separato e confronta contenuto o SHA-256 calcolato localmente.
4. Decidi se conservare checks/s3-first-sample.txt per esaminarlo o eliminare quell’oggetto dal client. Per dismettere la connessione di prova scegli Revoca nella riga dedicata in Profilo → Chiavi API; eliminare solo il profilo locale lascia file cloud e chiave.

PutObject restituisce HTTP 200 con ETag dopo la conferma; GET restituisce byte o un intervallo e l’elenco è XML con fino a 1.000 voci per pagina. Il client deve seguire i token di continuazione. Un ETag non è sempre l’hash del file: gli oggetti multipart usano ETag multipart. Queste operazioni non creano URL pubblici; usa la condivisione dosya per dare accesso senza credenziali.

Operazioni supportate e conseguenze

Il servizio supporta elenco di contenitori e oggetti, HEAD, caricamento, download, copia, eliminazione singola e in blocco, marcatori di cartella e avvio, caricamento, copia, elenco, completamento e annullamento delle parti multipart. L’eliminazione in blocco accetta al massimo 1.000 chiavi e segnala errori per ogni chiave. Le parti multipart vanno da 1 a 10.000 e ciascuna ha massimo 5 GiB; i limiti effettivi di oggetto e spazio possono essere inferiori. Un trasferimento fallito può lasciare un caricamento incompleto: usa l’annullamento del client senza presumere che l’annullamento locale abbia rimosso le parti.

I contenitori corrispondono a spazi di lavoro esistenti. CreateBucket per uno spazio esistente accessibile può restituire 200 per compatibilità, ma non crea uno spazio. Eliminazione contenitori, IAM/ACL AWS, regole del ciclo di vita, CORS configurabile, replica, versioni AWS S3 e Object Lock/conservazione/blocco legale non sono disponibili. Le scritture di configurazione restituiscono 501 NotImplemented; alcune letture restituiscono configurazione vuota o un errore di assenza. Non usare questo servizio per software che richiede garanzie S3 di immutabilità o blocco legale.

Caricare su un percorso esistente crea un’altra versione del file dosya, non un ID versione AWS. Il limite predefinito è 10 versioni; un limite positivo configurato rimuove quelle eccedenti e quelle vecchie di proprietari gratuiti sono soggette a un processo dopo sette giorni. Conserva gli originali per il recupero. Eliminare un oggetto idoneo restituisce 204 anche se era assente; il file esistente va nel cestino e i link vengono revocati. Il cestino occupa spazio fino all’eliminazione definitiva ed è soggetto alla conservazione del proprietario: sette giorni sul piano gratuito, 30 sugli altri. Byte eliminati definitivamente e credenziali revocate non si recuperano riconnettendo il client.

Risoluzione dei problemi

Risultato	Controllo o soluzione
InvalidAccessKeyId / The access key ID does not exist	Verifica l’ID S3; chiavi scadute, revocate e non valide vengono rifiutate.
SignatureDoesNotMatch / The request signature does not match	Controlla segreto associato e indirizzo/percorso firmato esatto; elimina la vecchia richiesta e lascia firmare nuovamente il client.
AccessDenied / This API key is not permitted to use the S3 gateway	Crea una chiave che includa S3 tra i protocolli scelti.
This API key is pinned to a different workspace	Usa l’ID del contenitore copiato corrispondente al vincolo.
This role is not permitted to use the S3 gateway	Il proprietario o amministratore deve controllare l’accesso S3 del ruolo.
Upload not allowed, Creating folders is not allowed o Object is locked	Confronta l’operazione con permessi del ruolo e stato della destinazione.
EntityTooLarge o QuotaExceeded	Controlla dimensione file, spazio e limiti espliciti di chiave e ruolo prima di riprovare.
429 XML SlowDown	Il controllo d’uso di chiave o ruolo ha rifiutato la richiesta o il trasferimento. Leggi il messaggio, rispetta Retry-After se presente e riduci il parallelismo per un rifiuto di simultaneità; una quota in byte richiede rinnovo o modifica autorizzata.
429 JSON {"ok":false,"error":"Too many requests"}	È stato raggiunto il limite indipendente all’ingresso: 600 richieste al minuto per utente o 1.200 per IP. Attendi Retry-After, riduci la frequenza e sfasa i processi sullo stesso utente o IP.

L’autenticazione precede i controlli su protocollo, condizioni e uso della chiave, vincolo allo spazio, appartenenza, cartella di riferimento e ruolo: correggere un rifiuto può rivelarne un altro. Non ampliare una chiave limitata solo per nascondere un altro errore.

Risultato previsto

Il client raggiunge il contenitore copiato con richieste SigV4 a percorso. La destinazione del campione è visibile in File e i byte scaricati separatamente corrispondono all’originale; un nome di connessione salvato o un accesso riuscito senza tale verifica non completano la configurazione.

Guide correlate

• Eseguire l’esempio AWS CLI con un profilo isolato
• Risolvere errori di firma e ora della richiesta
• Impostare le restrizioni di protocollo di una chiave