Usa Amazon S3 come unità PowerShell

Si applica a: AWS.Tools.S3 5.0.288 e versioni successive. Il provider di unità S3 e i relativi cmdlet sono inclusi nel AWS.Tools.S3 modulo, che funziona su Windows PowerShell 5.1 e PowerShell 7+ (Windows, Linux, macOS).

L' PowerShell unità S3 ti consente di montare lo storage Amazon S3 come unità e di utilizzarlo nello stesso modo in cui lavori con un disco locale. Dopo aver montato un'unità, il provider presenta bucket e prefissi come cartelle e oggetti come file. I comandi di navigazione più comuni funzionano direttamente con S3, tra cuiSet-Location,Get-ChildItem, Get-Content e. Set-Content Remove-Item

Questo argomento riguarda l'installazione, il montaggio, la navigazione, il trasferimento e lo smontaggio dei contenuti, oltre alle credenziali, alla regione e al comportamento di sicurezza dell'unità S3.

Prerequisiti

L'importazione del modulo registra un provider denominato. PowerShell AWS.S3 Puoi confermare che è disponibile:

Get-PSProvider AWS.S3

Montare un'unità

Mount-S3PSDriveUsare per creare un'unità. Il -Name parametro diventa il nome dell'unità in ogni percorso (ad esempio, -Name S3 fornisce percorsi similiS3:/amzn-s3-demo-bucket/reports/index.txt).

# Mount an S3: drive using a named profile and Region
Mount-S3PSDrive -Name S3 -ProfileName my-profile -Region us-east-1
# List buckets
Get-ChildItem S3:/

Output di esempio:

   Type     LastModified              Size Name
   ----     ------------              ---- ----
   Bucket   2026-06-02 09:14:03            amzn-s3-demo-app-logs
   Bucket   2026-01-08 16:47:51            amzn-s3-demo-reports

Se hai già impostato i valori predefiniti della sessione con Set-AWSCredential eSet-DefaultAWSRegion, puoi eseguire il montaggio senza altri parametri:

Set-AWSCredential -ProfileName my-profile
Set-DefaultAWSRegion us-west-2
Mount-S3PSDrive -Name S3

Mount-S3PSDriveè un involucro sottile rispetto a quello integrato. PowerShell New-PSDrive Se preferisci, puoi creare direttamente l'unità e passare le stesse credenziali e i parametri della regione:

New-PSDrive -Name S3 -PSProvider AWS.S3 -Root '' -Scope Global -ProfileName my-profile -Region us-east-1

Per impostazione predefinita non Mount-S3PSDrive produce alcun output. Aggiungi -PassThru se vuoi riavere l'PSDriveInfooggetto.

Come vengono risolte le credenziali e la regione

Un'unità S3 autentica e seleziona una regione esattamente come fanno i cmdlet S3: prima i parametri espliciti, poi i valori predefiniti di sessione impostati da e, quindi il profilo, l'ambiente Set-AWSCredential e le fonti di metadati delle istanze delle Set-DefaultAWSRegion catene predefinite dell'SDK. Per Utilizzo delle AWS credenziali Specificare la AWS regione per AWS Strumenti per PowerShell l'ordine di risoluzione completo, vedere e.

Se nulla rifornisce una regione, l'unità ricade suus-east-1. La regione che utilizzi è solo la regione di partenza: una singola unità può raggiungere i bucket tra le regioni (vediAccedi ai bucket tra le regioni da un'unica unità).

Un profilo errato o un bucket o prefisso mancante non funziona. Mount-S3PSDrive Alcuni errori di autorizzazione potrebbero non essere visualizzati finché non si accede a un oggetto.

Naviga in Amazon S3 come un'unità locale

Dopo aver montato l'unità, naviga con i comandi più comuni dell' PowerShell unità. S3 non ha cartelle reali, ma il provider presenta i prefissi come cartelle in modo da poterle navigare nello stesso modo.

# Change into a bucket, then a prefix
Set-Location S3:/amzn-s3-demo-reports/2026
# List the current location
Get-ChildItem

Output di esempio:

   Type     LastModified              Size Name
   ----     ------------              ---- ----
   Folder                                  q1
   Folder                                  q2
   Object   2026-03-31 18:02:11      48210 summary.txt

# List a path without changing location
Get-ChildItem S3:/amzn-s3-demo-bucket/reports/2026

Il completamento tramite tabulazione funziona per bucket, prefissi e oggetti, quindi puoi completare un percorso senza inserire nomi completi.

Get-ChildItemrestituisce ogni elemento come oggetto che esponeName,Type, Size e proprietà. LastModified Queste proprietà consentono agli elenchi di reindirizzarsi direttamente a comandi come Where-Object eSort-Object. Typeè uno deiBucket,Folder, oObject. Le cartelle e i secchi non hanno dimensioni.

# List the 10 largest objects with the prefix "2026"
Get-ChildItem S3:/amzn-s3-demo-app-logs/2026 -Recurse |
    Where-Object Type -eq 'Object' |
    Sort-Object Size -Descending |
    Select-Object -First 10 Name, Size, LastModified

Sull'unità funzionano anche altri comandi di navigazione:

# Retrieve the single item at an exact path (no children)
Get-Item S3:/amzn-s3-demo-bucket/reports/index.txt
# Test whether a path exists and whether it is a folder or an object
Test-Path S3:/amzn-s3-demo-bucket/reports                              # -> True
Test-Path S3:/amzn-s3-demo-bucket/reports -PathType Container          # -> True (a prefix)
Test-Path S3:/amzn-s3-demo-bucket/reports/index.txt -PathType Leaf     # -> True (an object)

Con-Recurse, la chiave di un elemento Name è relativa al prefisso (quindi può contenere/) e lo stesso nome della foglia può apparire con prefissi diversi. Quando hai bisogno di identificare un elemento elencato in modo inequivocabile (ad esempio, per indirizzarlo in avanti), usa il suo invece di. PSPath Name

# Read each listed object by explicit PSPath
Get-ChildItem S3:/amzn-s3-demo-bucket/prefix | ForEach-Object {
    Get-Content -LiteralPath $_.PSPath -AsByteStream -Raw
}

Get-Content -LiteralPath 'S3:/amzn-s3-demo-bucket/data[2026].csv' -Raw

Legge oggetti da S3

Get-Contentscarica un oggetto. Per impostazione predefinita, restituisce il testo riga per riga. Aggiungi -Raw per restituire l'intero oggetto come una singola stringa. Entrambi Get-Content e Set-Content supporto -Encoding per testo e -AsByteStream contenuto binario.

# Read an object line by line
Get-Content S3:/amzn-s3-demo-reports/2026/summary.txt
# Read the whole object as one string
Get-Content S3:/amzn-s3-demo-reports/2026/summary.txt -Raw

Per oggetti non di testo, usa -AsByteStream per ottenere i byte grezzi. Su un percorso S3 questo funziona sia su PowerShell 7+ che su Windows PowerShell 5.1 perché il provider S3 fornisce il parametro. Solo i file locali differiscono in base all'edizione (vedi). La lettura dei byte dei file locali varia a seconda dell'edizione Per controllare la decodifica del testo, aggiungete -Encoding con uno qualsiasi dei nomi di PowerShell codifica standard (UTF8,UTF8BOM, UnicodeASCII, e così via). L'impostazione predefinita è UTF-8 senza distinta base, su entrambi e. Get-Content Set-Content

# Read raw bytes
Get-Content S3:/amzn-s3-demo-bucket/images/logo.png -AsByteStream -Raw
# Decode as a specific text encoding
Get-Content S3:/amzn-s3-demo-bucket/data/report.csv -Encoding UTF8

Get-Contentaccetta anche -PartSize di impostare la dimensione della parte di download in più parti, in byte, tra il minimo S3 di 5 MiB e il massimo di 5 GiB. Si attivaSet-Content, -PartSize il che imposta la dimensione della parte caricata (vedi). Carica oggetti molto grandi

$bytes = [byte[]]((Get-Content S3:/amzn-s3-demo-bucket/images/logo.png -AsByteStream -Raw) | ForEach-Object { $_ })

Scrivere oggetti in S3

Set-Contentcarica (e sovrascrive) un oggetto.

# Write text
Set-Content S3:/amzn-s3-demo-reports/2026/notes.txt -Value 'Draft complete'
# Write several lines
Set-Content S3:/amzn-s3-demo-bucket/notes/list.txt -Value @('alpha', 'beta', 'gamma')
# Write raw bytes
Set-Content S3:/amzn-s3-demo-bucket/images/logo.png -AsByteStream -Value $bytes

I caricamenti hanno le seguenti opzioni:

Puoi annullare un caricamento in qualsiasi momento con Ctrl+C. Non viene eseguito alcun commit fino al termine del caricamento, quindi l'annullamento non lascia un oggetto scritto a metà al posto di quello precedente.

Carica oggetti molto grandi

Ogni caricamento tramite l'unità è un caricamento in più parti e S3 limita un caricamento in più parti a 10.000 parti. Con la dimensione predefinita delle parti di 5 MiB, un limite massimo per un singolo oggetto è di circa 48 GiB, e un caricamento oltre il limite massimo si esaurisce e fallisce. Per caricare qualcosa di più grande, aumenta -PartSize in modo che sia almeno: object size / 10,000

# Upload a ~200 GiB object with 64 MiB parts (200 GiB / 10,000 = 21 MiB, so 64 MiB is plenty)

# PowerShell 7+
Get-Content ./huge.bin -AsByteStream -ReadCount 8MB |
    Set-Content S3:/amzn-s3-demo-bucket/archive/huge.bin -AsByteStream -PartSize 64MB

# Windows PowerShell 5.1 (local read uses -Encoding Byte; the S3 write keeps -AsByteStream -PartSize)
Get-Content ./huge.bin -Encoding Byte -ReadCount 8MB |
    Set-Content S3:/amzn-s3-demo-bucket/archive/huge.bin -AsByteStream -PartSize 64MB

-PartSizee -StorageClass sono parametri di destinazione S3. Usali con un percorso di destinazione S3 esplicito (come nell'esempio precedente), non con un oggetto di destinazione associato alla pipeline.

-PartSizeaccetta un valore compreso tra il minimo S3 di 5 MiB e il massimo di 5 GiB. Con un massimo di 5 GiB, 10.000 parti coprono l'oggetto più grande supportato da S3 (5 TiB).

Copia oggetti tra S3 e il disco locale

La copia all'interno di S3 con non Copy-Item è supportata (vedi). Operazioni supportate e non supportate Per spostare i dati tra il disco locale e S3, reindirizza il contenuto tramite e. Get-Content Set-Content

Per i dati binari, leggi e scrivi esattamente i byte. Un percorso S3 viene utilizzato -AsByteStream in entrambe le PowerShell edizioni; solo il lato locale è diverso, come descritto in. La lettura dei byte dei file locali varia a seconda dell'edizione

# Upload a local file (PowerShell 7+; on Windows PowerShell 5.1 the local read uses -Encoding Byte)
Get-Content ./report.csv -AsByteStream -ReadCount 8MB | Set-Content S3:/amzn-s3-demo-bucket/data/report.csv -AsByteStream

# Download to a local file (on Windows PowerShell 5.1 the local write uses -Encoding Byte)
Get-Content S3:/amzn-s3-demo-bucket/data/report.csv -AsByteStream | Set-Content ./report.csv -AsByteStream

La lettura dei byte dei file locali varia a seconda dell'edizione

Il targeting di un file locale utilizza PowerShell il FileSystem provider integrato e tale provider non ne ha -AsByteStream in Windows PowerShell 5.1 (è arrivato nella versione PowerShell 6). Usa invece -Encoding Byte lì. Questa è una limitazione 5.1, non controllata dall'unità S3; un percorso S3 riguarda entrambe le -AsByteStream edizioni.

Per le S3-to-S3 copie sul lato server, utilizzare il Copy-S3Object cmdlet.

Eliminare oggetti e prefissi

Remove-Itemelimina un singolo oggetto. L'eliminazione di un prefisso (una cartella con contenuti) richiede la rimozione in -Recurse batch di tutto ciò che contiene.

# Delete a single object
Remove-Item S3:/amzn-s3-demo-bucket/notes/todo.txt
# Delete a prefix and everything under it
Remove-Item S3:/amzn-s3-demo-bucket/old-logs -Recurse

Il Remove-Item tipo di richiesta dipende dal tipo di destinazione scelto:

Usa gli PowerShell switch nativi per visualizzare in anteprima o bloccare un'eliminazione:

# Preview without deleting
Remove-Item S3:/amzn-s3-demo-bucket/old-logs -Recurse -WhatIf
# Ask for confirmation
Remove-Item S3:/amzn-s3-demo-bucket/notes/todo.txt -Confirm

Non è possibile eliminare un intero bucket dall'unità perché le operazioni relative al ciclo di vita del bucket non rientrano nell'ambito di applicazione. Usare invece Remove-S3Bucket.

Assegna l'ambito di un'unità a un bucket o a un prefisso

Monta con -Root per confinare un'unità in un bucket o un prefisso all'interno di un bucket. La radice dell'unità è quindi quella posizione e la navigazione è limitata al di sotto di essa.

# Mount rooted at a bucket: the drive root lists the bucket's top-level entries
Mount-S3PSDrive -Name Data -Root amzn-s3-demo-bucket -ProfileName my-profile -Region us-east-1
Get-ChildItem Data:/                 # top-level keys in amzn-s3-demo-bucket
Get-Content Data:/reports/index.txt  # -> amzn-s3-demo-bucket/reports/index.txt

# Mount rooted at a bucket + prefix
Mount-S3PSDrive -Name Reports -Root amzn-s3-demo-reports/2026 -ProfileName my-profile -Region us-east-1
Get-ChildItem Reports:/              # contents of amzn-s3-demo-reports/2026/

La radice deve già esistere. Un bucket o un prefisso inesistente non riesce a eseguire il montaggio. Poiché i percorsi relativi non possono superare la radice (..è bloccato dal motore), un montaggio con ambito offre una visione mirata esattamente dei dati di un progetto.

Accedi ai bucket tra le regioni da un'unica unità

Una singola unità montata può raggiungere i bucket in tutte le regioni. La prima volta che tocchi un bucket, il provider cerca la sua regione e indirizza automaticamente le chiamate successive all'endpoint giusto. Non è necessaria un'unità separata per ogni regione.

# Mounted in us-east-1, but this bucket is in us-west-2 and commands work without extra configuration
Mount-S3PSDrive -Name S3 -ProfileName my-profile -Region us-east-1
Get-ChildItem S3:/amzn-s3-demo-west-bucket
Get-Content   S3:/amzn-s3-demo-west-bucket/data/report.csv -Raw

Imposta una classe di archiviazione predefinita

Imposta una classe di archiviazione predefinita a livello di unità al momento del montaggio con. -StorageClass Ogni caricamento tramite quell'unità utilizza la classe specificata a meno che una specifica non la Set-Content sovrascriva con una propria. -StorageClass

# Set all uploads to default to STANDARD_IA
Mount-S3PSDrive -Name Archive -ProfileName my-profile -Region us-east-1 -StorageClass STANDARD_IA
Set-Content Archive:/amzn-s3-demo-bucket/cold/data.txt -Value '...'                        # STANDARD_IA
Set-Content Archive:/amzn-s3-demo-bucket/hot/data.txt  -Value '...' -StorageClass STANDARD # overrides to STANDARD

Smonta un'unità

Usa Dismount-S3PSDrive (un involucro sopraRemove-PSDrive) per rimuovere un'unità. Passa prima a un'altra posizione, perché PowerShell non rimuoverà un'unità che è la tua posizione attuale.

Set-Location $HOME           # or C:\ on Windows
Dismount-S3PSDrive -Name S3

Operazioni supportate e non supportate

Usa l'unità per sfogliare e spostare il contenuto degli oggetti. Il ciclo di vita dei bucket e le operazioni di copia lato server rimangono affidate ai cmdlet S3 dedicati.

Supportata

Non supportata

I comandi non supportati hanno esito negativo e viene visualizzato un messaggio che nomina il comando e punta all'alternativa, ad esempio, "non Copy-Item è supportato dall'unità S3. Usa Copy-S3Object, o reindirizzalo Get-Content a Set-Content». I *-ItemProperty comandi sono l'eccezione, come descritto nella tabella precedente.

Riferimento ai comandi

Per l'elenco completo dei parametri per Mount-S3PSDrive e Dismount-S3PSDrive, vedere il AWS Strumenti per PowerShell Cmdlet Reference.

In un percorso S3, l'unità aggiunge anche parametri dinamici Set-Content che non sono Get-Content inclusi nella PowerShell documentazione di tali cmdlet:

Risoluzione dei problemi

«Impossibile smontare l'unità perché è in uso».

L'unità S3 è la posizione corrente. Passa a una posizione su un'altra unità, ad esempio$HOME, e poi esegui di Dismount-S3PSDrive nuovo.

Il montaggio non riesce con il messaggio «root non è stato trovato o non è raggiungibile».

Il bucket o il prefisso in -Root non esiste. Controlla il nome (e la regione, se il bucket è incluso in uno in cui le tue credenziali non sono predefinite). Un errore di credenziale produce un errore diverso, non questo messaggio «non raggiungibile». Un errore di autorizzazione nella cartella principale potrebbe non apparire finché non si accede a un oggetto, quindi un montaggio riuscito non garantisce la possibilità di leggere tutti i percorsi al suo interno.

L'eliminazione di un prefisso non vuoto si blocca in uno script.

Ciò accade quando si elimina un prefisso non vuoto senza. -Recurse Il PowerShell motore genera una richiesta di conferma perché il prefisso ha figli (il comportamento container-has-children del provider del file system). Un host non interattivo non può rispondere al prompt, quindi il comando si blocca.

Passa -Recurse per eliminare il contenuto del prefisso senza chiedere conferma o conferma in modo interattivo per procedere. (non -Force viene consultato dal percorso di eliminazione dell'unità, quindi non ha alcun effetto qui.)

«Un oggetto che ho appena modificato all'esterno dell'unità mostra ancora il vecchio elenco».

Le inserzioni vengono memorizzate brevemente nella cache (circa un secondo) per mantenere la navigazione veloce. Le modifiche apportate tramite l'unità vengono visualizzate immediatamente. Le modifiche apportate da un altro strumento vengono visualizzate dopo la scadenza della cache breve.

«Una chiave contiene una barra rovesciata».

La capacità dell'unità di indirizzare una chiave che contiene una barra rovesciata dipende dal sistema operativo, poiché l'unità accetta il separatore di percorso nativo della piattaforma: