Scaricare un oggetto con un client S3

dosya espone ogni spazio di lavoro tramite un bucket compatibile con S3. L’endpoint è https://api.dosya.dev/s3, la regione di firma è us-east-1 e il nome del bucket è l’ID dello spazio di lavoro mostrato in Integrazioni → S3.

Preparare credenziali e permessi

Il ruolo nello spazio di lavoro deve consentire Gateway S3, accesso ai file e download. Se S3 è negato, la pagina mostra Il tuo ruolo non consente di usare il gateway S3. Un proprietario o amministratore deve modificare il ruolo.

In Profilo → Chiavi API, crea una chiave Solo lettura e limita i protocolli a Gateway S3 se la credenziale serve solo per i download. Associa credenziali S3 alla chiave API. dosya mostra la chiave di accesso segreta una sola volta: copiala in un archivio sicuro delle credenziali al momento della creazione.

Un vincolo allo spazio di lavoro può limitare la credenziale al bucket previsto. È supportata anche una cartella di ancoraggio: diventa / per la vista S3, quindi le chiavi degli oggetti sono relative a essa e i percorsi superiori o adiacenti non sono raggiungibili.

Scegli un nuovo profilo AWS CLI dedicato a questo download. Controlla prima aws configure list-profiles; se dosya-download-test esiste già, usa sempre un altro nome inutilizzato nei comandi seguenti.

Inserisci in modo interattivo l’ID di accesso S3 e il segreto mostrati:

aws configure --profile dosya-download-test

Alle richieste inserisci ID di accesso S3, relativo segreto, us-east-1 e json. Non inserire il segreto come argomento di un comando e non usare una sessione di terminale registrata: la richiesta evita la cronologia della shell ma non garantisce che le credenziali digitate siano nascoste. Per impostazione predefinita AWS CLI salva le credenziali in ~/.aws/credentials e le impostazioni in ~/.aws/config. Sono file locali, non un archivio password cifrato; mantienili privati e fuori da trascrizioni condivise o repository.

Imposta l’indirizzamento path solo per questo profilo:

aws configure set s3.addressing_style path --profile dosya-download-test

Mantieni --profile dosya-download-test in ogni comando remoto affinché la procedura non usi né modifichi il profilo predefinito.

Passaggi

1. Copia l’ID dello spazio di lavoro da Integrazioni → S3 e individua la chiave esatta dell’oggetto elencando un prefisso limitato:

   aws --profile dosya-download-test --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
     s3api list-objects-v2 --bucket WORKSPACE_ID --prefix 'path/to/'

2. Controlla ContentLength dell’oggetto S3 senza scaricarne il contenuto:

   aws --profile dosya-download-test --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
     s3api head-object --bucket WORKSPACE_ID --key 'path/to/object.bin'

3. Scegli un nuovo nome di file locale o crea una copia di sicurezza del percorso attuale. aws s3 cp può sostituire la destinazione locale indicata nel comando.

4. Scarica l’oggetto:

   aws --profile dosya-download-test --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
     s3 cp 's3://WORKSPACE_ID/path/to/object.bin' './object.bin'

5. Confronta il numero di byte locali con ContentLength di head-object. Se la fonte originale ha un checksum attendibile ottenuto separatamente, calcola lo stesso algoritmo in locale e confrontalo; non presumere che ogni ETag S3 sia un hash del contenuto portabile.

Risoluzione dei problemi

• AccessDenied: API key scope 'upload' cannot download files indica che la chiave consente solo il caricamento; crea invece una chiave di sola lettura o con accesso completo.
• AccessDenied: Access denied indica che il ruolo non ha accesso generale ai file. AccessDenied: Download not allowed identifica il permesso separato di download.
• NoSuchBucket indica di solito che l’ID dello spazio di lavoro è errato, la chiave è vincolata altrove o l’utente non appartiene più allo spazio di lavoro.
• NoSuchKey indica che il percorso relativo non corrisponde a un file visibile e attivo. Anche i contenuti nascosti risultano assenti e una chiave vincolata a una cartella deve omettere ogni segmento sopra la cartella di ancoraggio.
• AccessDenied: Object is locked indica che il file o una cartella superiore ha un blocco completo. Lo sblocco personale nell’app web non rende consentito il download tramite richiesta S3.
• SignatureDoesNotMatch richiede di controllare coppia di chiavi di accesso, endpoint e regione di firma us-east-1. Non puoi rigenerare solo il segreto, perché è mostrato una sola volta; se lo perdi, associa una nuova coppia di credenziali S3.
• Un intervallo di byte non soddisfacibile restituisce HTTP 416 con Content-Range: bytes */SIZE; dopo aver controllato la dimensione attuale dell’oggetto, riprova senza l’intervallo non più valido.

Il download è di sola lettura per dosya: non rimuove, sposta o modifica l’oggetto nel cloud. Sostituire un percorso di output locale esistente ha effetto in locale e non è recuperabile da dosya, a meno che non esista un’altra copia locale.

Risultato previsto

AWS CLI termina correttamente, la dimensione del file locale coincide con ContentLength S3 e un checksum noto indipendentemente corrisponde, quando disponibile. L’oggetto di origine resta nello stesso percorso dello spazio di lavoro dosya senza modifiche nel cloud.

Guide correlate

• Connettere un client S3
• Limitare i permessi S3