Use o Amazon S3 como uma unidade PowerShell

Aplica-se a: AWS.Tools.S3 5.0.288 e versões posteriores. O provedor do drive S3 e seus cmdlets vêm no AWS.Tools.S3 módulo, que é executado no Windows PowerShell 5.1 e PowerShell 7+ (Windows, Linux, macOS).

O PowerShell drive S3 permite que você monte o armazenamento Amazon S3 como um drive e trabalhe com ele da mesma forma que você trabalha com um disco local. Depois de montar uma unidade, o provedor apresenta compartimentos e prefixos como pastas e objetos como arquivos. Os comandos de navegação comuns funcionam diretamente no S3Set-Location, incluindoGet-ChildItem,Get-Content,Set-Content, e. Remove-Item

Este tópico aborda a instalação, montagem, navegação, transferência de conteúdo e desmontagem, além da credencial, da região e do comportamento de segurança da unidade S3.

Pré-requisitos

A importação do módulo registra um PowerShell provedor chamado. AWS.S3 Você pode confirmar que ele está disponível:

Get-PSProvider AWS.S3

Monte uma unidade

Use Mount-S3PSDrive para criar uma unidade. O -Name parâmetro se torna o nome da unidade em cada caminho (por exemplo, -Name S3 fornece caminhos comoS3:/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:/

Exemplo de saída:

   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 você já definiu os padrões de sessão com Set-AWSCredential eSet-DefaultAWSRegion, poderá montar sem outros parâmetros:

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

Mount-S3PSDriveé um invólucro fino sobre o PowerShell embutidoNew-PSDrive. Se preferir, você pode criar o drive diretamente e passar os mesmos parâmetros de credencial e região:

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

Por padrão, não Mount-S3PSDrive produz nenhuma saída. Adicione -PassThru se quiser o PSDriveInfo objeto de volta.

Como as credenciais e a região são resolvidas

Um drive S3 autentica e seleciona uma região exatamente como os cmdlets do S3: primeiro os parâmetros explícitos, depois os padrões da sessão definidos por Set-AWSCredential e, em seguida, o perfilSet-DefaultAWSRegion, o ambiente e as fontes de metadados da instância das cadeias padrão do SDK. Para ver a ordem de resolução completa, consulte Usando AWS credenciais Especifique a AWS região para o Ferramentas da AWS para PowerShell e.

Se nada abastecer uma região, a unidade volta paraus-east-1. A região com a qual você monta é apenas a região inicial: uma única unidade pode alcançar grupos em todas as regiões (consulteAcesse buckets em todas as regiões a partir de um único drive).

Um perfil incorreto ou um bucket ou prefixo ausente falha emMount-S3PSDrive. Alguns erros de permissão podem não aparecer até você acessar um objeto.

Navegue pelo Amazon S3 como uma unidade local

Depois de montar a unidade, navegue com os comandos comuns da PowerShell unidade. O S3 não tem pastas reais, mas o provedor apresenta prefixos como pastas para que você possa navegar por elas da mesma maneira.

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

Exemplo de saída:

   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

O preenchimento de tabulação funciona para compartimentos, prefixos e objetos, então você pode completar um caminho sem inserir nomes completos.

Get-ChildItemretorna cada item como um objeto que expõeName, TypeSize, e LastModified propriedades. Essas propriedades permitem que as listagens sejam direcionadas diretamente para comandos como Where-Object e. Sort-Object Typeé um dosBucket,Folder, ouObject. Pastas e baldes não têm tamanho.

# 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

Outros comandos de navegação também funcionam na unidade:

# 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)

Com-Recurse, a chave de um item Name é em relação ao prefixo (portanto, ele pode conter/), e o mesmo nome de folha pode aparecer em prefixos diferentes. Quando você precisar identificar um item listado de forma inequívoca (por exemplo, para encaminhá-lo adiante), use its PSPath em vez de. 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

Leia objetos do S3

Get-Contentbaixa um objeto. Por padrão, ele retorna o texto linha por linha. Adicione -Raw para retornar o objeto inteiro como uma única string. Ambos Get-Content e Set-Content suporte -Encoding para texto e -AsByteStream conteúdo binário.

# 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

Para objetos não textuais, use -AsByteStream para obter os bytes brutos. Em um caminho do S3, isso funciona tanto no PowerShell 7+ quanto no Windows PowerShell 5.1 porque o provedor do S3 fornece o parâmetro. Somente os arquivos locais diferem por edição (consulteA leitura de bytes do arquivo local difere de acordo com a edição). Para controlar a decodificação de texto, adicione -Encoding com qualquer um dos nomes de PowerShell codificação padrão (UTF8,, UTF8BOM UnicodeASCII, e assim por diante). O padrão é UTF-8 sem um BOM, em ambos Get-Content Set-Content e.

# 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-Contenttambém aceita -PartSize definir o tamanho da parte de download de várias partes, em bytes, entre o mínimo de 5 MiB e o máximo de 5 GiB do S3. Ele é espelhado -PartSizeSet-Content, o que define o tamanho da peça de upload (consulteCarregue objetos muito grandes).

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

Escrever objetos no S3

Set-Contentcarrega (e sobrescreve) um objeto.

# 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

Os uploads têm as seguintes opções:

Você pode cancelar um upload a qualquer momento com Ctrl+C. Nada é confirmado até que o upload seja concluído, portanto, o cancelamento não deixa um objeto parcialmente escrito no lugar do antigo.

Carregue objetos muito grandes

Cada upload por meio da unidade é um upload de várias partes, e o S3 limita um upload de várias partes a 10.000 partes. Com o tamanho de peça padrão de 5 MiB que limita um único objeto a cerca de 48 GiB e um upload após o limite, o limite fica sem peças e falha. Para fazer upload de algo maior, aumente -PartSize para que seja pelo menosobject 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 são parâmetros de destino do S3. Use-os com um caminho de destino S3 explícito (como no exemplo anterior), não com um objeto de destino vinculado ao pipeline.

-PartSizeaceita um valor entre o mínimo de 5 MiB do S3 e o máximo de 5 GiB. No máximo de 5 GiB, 10.000 peças cobrem o maior objeto suportado pelo S3 (5 TiB).

Copiar objetos entre o S3 e o disco local

A cópia no S3 com não Copy-Item é suportada (consulteOperações suportadas e não suportadas). Para mover dados entre seu disco local e o S3, canalize o conteúdo por Get-Content e. Set-Content

Para dados binários, leia e grave os bytes com exatidão. Um caminho do S3 é usado -AsByteStream em ambas PowerShell as edições; somente o lado local é diferente, conforme descrito em. A leitura de bytes do arquivo local difere de acordo com a edição

# 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

A leitura de bytes do arquivo local difere de acordo com a edição

A segmentação de um arquivo local usa PowerShell o FileSystem provedor embutido, e esse provedor não tem -AsByteStream no Windows PowerShell 5.1 (chegou em PowerShell 6). Em vez disso-Encoding Byte, use lá. Essa é uma limitação 5.1, não algo que o drive S3 controla; um caminho S3 -AsByteStream assume as duas edições.

Para S3-to-S3 cópias do lado do servidor, use o cmdlet. Copy-S3Object

Excluir objetos e prefixos

Remove-Itemexclui um único objeto. É necessário excluir um prefixo (uma pasta com conteúdo)-Recurse, o que remove tudo abaixo dele em lotes.

# 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

Se Remove-Item as solicitações dependem do que você almeja:

Use as PowerShell opções nativas para visualizar ou bloquear uma exclusão:

# 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

Você não pode excluir um bucket inteiro pela unidade porque as operações do ciclo de vida do bucket estão fora do escopo. Use Remove-S3Bucket em vez disso.

Defina o escopo de uma unidade para um bucket ou prefixo

Monte com -Root para confinar uma unidade a um balde ou a um prefixo dentro de um balde. A raiz da unidade, então, é esse local, e a navegação fica confinada abaixo dela.

# 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/

A raiz já deve existir. Um bucket ou prefixo inexistente falha na montagem. Como os caminhos relativos não podem subir acima da raiz (..são bloqueados pelo motor), uma montagem com escopo oferece uma visão focada dos dados de exatamente um projeto.

Acesse buckets em todas as regiões a partir de um único drive

Uma única unidade montada pode alcançar baldes em todas as regiões. Na primeira vez que você toca em um bucket, o provedor consulta sua região e encaminha as chamadas subsequentes para o endpoint correto automaticamente. Você não precisa de uma unidade separada para cada região.

# 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

Definir uma classe de armazenamento padrão

Defina uma classe de armazenamento padrão para toda a unidade no momento da montagem com. -StorageClass Cada upload por meio desse drive usa a classe especificada, a menos que um específico a Set-Content substitua pela sua própria. -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

Desmontar uma unidade

Use Dismount-S3PSDrive (uma embalagem sobreRemove-PSDrive) para remover uma unidade. Mude para outro local primeiro, porque PowerShell não removerá uma unidade que seja sua localização atual.

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

Operações suportadas e não suportadas

Use a unidade para navegar e mover o conteúdo do objeto. O ciclo de vida do bucket e as operações de cópia do lado do servidor permanecem com os cmdlets dedicados do S3.

Compatível

Sem compatibilidade

Os comandos não suportados falham com uma mensagem que nomeia o comando e aponta para a alternativa - por exemplo, "não Copy-Item é suportado pela unidade S3. Use Copy-S3Object ou canalize Get-Content para Set-Content.” Os *-ItemProperty comandos são a exceção, conforme descrito na tabela anterior.

Referência de comando

Para ver a lista completa de parâmetros de Mount-S3PSDrive e Dismount-S3PSDrive, consulte a Referência de Ferramentas da AWS para PowerShell cmdlets.

Em um caminho do S3, a unidade também adiciona parâmetros Get-Content dinâmicos aos Set-Content quais a PowerShell documentação desses cmdlets não abrange:

Solução de problemas

“Não é possível desmontar a unidade porque ela está em uso.”

A unidade S3 é a localização atual. Mude para um local em outra unidade, como$HOME, e execute Dismount-S3PSDrive novamente.

A montagem falha com “a raiz não foi encontrada ou não está acessível”.

O bucket ou prefixo in -Root não existe. Verifique o nome (e a região, se o bucket estiver em um que suas credenciais não usem como padrão). Uma falha na credencial produz um erro diferente, não essa mensagem de “não acessível”. Um erro de permissão na raiz pode não aparecer até que você acesse um objeto, portanto, uma montagem bem-sucedida não garante que você possa ler todos os caminhos abaixo dele.

A exclusão de um prefixo não vazio trava em um script.

Isso acontece quando você exclui um prefixo não vazio sem. -Recurse O PowerShell mecanismo gera uma solicitação de confirmação porque o prefixo tem filhos (o comportamento do contêiner tem filhos do provedor do sistema de arquivos). Um host não interativo não pode responder ao prompt, então o comando é bloqueado.

Passe -Recurse para excluir o conteúdo do prefixo sem solicitar, ou confirme interativamente para continuar. (não -Force é consultado pelo caminho de exclusão da unidade, portanto, não tem efeito aqui.)

“Um objeto que acabei de trocar fora da unidade ainda mostra o anúncio antigo.”

Os anúncios são armazenados em cache brevemente (cerca de um segundo) para manter a navegação rápida. As alterações feitas por meio da unidade aparecem imediatamente. As alterações feitas por outra ferramenta aparecem depois que o cache curto expira.

“Uma chave contém uma barra invertida.”

Se a unidade pode endereçar uma chave que contém uma barra invertida depende do sistema operacional, pois a unidade aceita o separador de caminho nativo da plataforma: