Utilice Amazon S3 como PowerShell unidad

Se aplica a: AWS.Tools.S3 5.0.288 y versiones posteriores. El proveedor de la unidad S3 y sus cmdlets se incluyen en el AWS.Tools.S3 módulo, que se ejecuta en Windows PowerShell 5.1 y PowerShell 7+ (Windows, Linux, macOS).

La PowerShell unidad S3 le permite montar el almacenamiento de Amazon S3 como una unidad y trabajar con ella del mismo modo que trabaja con un disco local. Tras montar una unidad, el proveedor presenta los cubos y prefijos como carpetas y los objetos como archivos. Los comandos de navegación más comunes funcionan directamente contra S3, comoSet-Location, Get-ChildItem Get-ContentSet-Content, y. Remove-Item

Este tema trata sobre la instalación, el montaje, la navegación, la transferencia de contenido y el desmontaje, además de las credenciales, la región y el comportamiento de seguridad de la unidad S3.

Requisitos previos

Al importar el módulo, se registra un proveedor llamado. PowerShell AWS.S3 Puede confirmar que está disponible:

Get-PSProvider AWS.S3

Monta una unidad

Se usa Mount-S3PSDrive para crear una unidad. El -Name parámetro se convierte en el nombre de la unidad en cada ruta (por -Name S3 ejemplo, muestra rutas 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:/

Código de salida de ejemplo:

   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

Si ya ha establecido los valores predeterminados de sesión con Set-AWSCredential ySet-DefaultAWSRegion, puede montarla sin ningún otro parámetro:

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

Mount-S3PSDrivees un envoltorio delgado sobre el incorporado. PowerShell New-PSDrive Si lo prefiere, puede crear la unidad directamente y pasar los mismos parámetros de credenciales y regiones:

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

De forma predeterminada, no Mount-S3PSDrive produce ninguna salida. -PassThruAñádalo si quiere recuperar el PSDriveInfo objeto.

Cómo se resuelven las credenciales y la región

Una unidad S3 autentica y selecciona una región exactamente como lo hacen los cmdlets de S3: primero los parámetros explícitos, luego los valores predeterminados de sesión establecidos por Set-AWSCredential ySet-DefaultAWSRegion, a continuación, las fuentes de metadatos de perfil, entorno e instancia de las cadenas predeterminadas del SDK. Para ver el orden de resolución completo, consulte y. Uso de AWS credenciales Especifique la AWS región para el Herramientas de AWS para PowerShell

Si nada abastece a una región, la unidad recurre aus-east-1. La región con la que montas es solo la región inicial: una sola unidad puede llegar a grupos de distintas regiones (consultaAccede a sitios de distintas regiones desde un solo viaje).

Si un perfil es incorrecto o si falta un bucket o un prefijo, se produce un error en. Mount-S3PSDrive Es posible que algunos errores de permisos no aparezcan hasta que accedas a un objeto.

Navegue por Amazon S3 como si fuera una unidad local

Tras montar la unidad, navegue con los comandos habituales de la PowerShell unidad. S3 no tiene carpetas reales, pero el proveedor presenta los prefijos en forma de carpetas para que puedas navegar por ellas de la misma manera.

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

Código de salida de ejemplo:

   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

La función de completar pestañas funciona con grupos, prefijos y objetos, por lo que puede completar una ruta sin tener que introducir los nombres completos.

Get-ChildItemdevuelve cada elemento como un objeto que expone Name TypeSize, y propiedades. LastModified Estas propiedades permiten que los listados se canalicen directamente a comandos como Where-Object ySort-Object. Typees uno deBucket,Folder, oObject. Las carpetas y los cubos no tienen ningún tamaño.

# 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

Otros comandos de navegación también funcionan en la unidad:

# 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 clave de un elemento Name es su clave relativa al prefijo (por lo que puede contener/), y el mismo nombre de hoja puede aparecer bajo diferentes prefijos. Cuando necesites identificar un elemento de la lista de forma inequívoca (por ejemplo, para canalizarlo), usa su en lugar de. 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

Lee objetos de S3

Get-Contentdescarga un objeto. De forma predeterminada, devuelve el texto línea por línea. Agregue -Raw para devolver todo el objeto como una sola cadena. Get-ContentTanto como Set-Content soporte -Encoding para texto como -AsByteStream para contenido 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

En el caso de objetos que no sean de texto, -AsByteStream utilícelo para obtener los bytes sin procesar. En una ruta S3, esto funciona tanto en Windows PowerShell 7 o más como en Windows PowerShell 5.1 porque el proveedor de S3 proporciona el parámetro. Solo los archivos locales varían según la edición (consulteLa lectura de los bytes de un archivo local varía según la edición). Para controlar la decodificación del texto, añádalo -Encoding con cualquiera de los nombres de PowerShell codificación estándar (UTF8UTF8BOMUnicodeASCII,,,, etc.). El valor predeterminado es UTF-8 sin una lista de materiales, tanto en Get-Content Y. 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-Contenttambién acepta -PartSize establecer el tamaño de la parte de descarga multiparte, en bytes, entre el mínimo de 5 MiB de S3 y el máximo de 5 GiB. Se duplica -PartSizeSet-Content, lo que establece el tamaño de la parte de carga (consulte). Sube objetos muy grandes

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

Escribe objetos en S3

Set-Contentcarga (y sobrescribe) un 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

Las subidas tienen las siguientes opciones:

Puedes cancelar una subida en cualquier momento con Ctrl+C. No se confirma nada hasta que finalice la subida, por lo que la cancelación no deja un objeto a medio escribir en lugar del anterior.

Sube objetos muy grandes

Todas las subidas a través de la unidad se cargan en varias partes, y S3 limita las subidas en varias partes a 10 000 partes. Con un tamaño de pieza predeterminado de 5 MiB, un único objeto queda limitado a unos 48 GiB, y si se sube más de ese límite, se quedan sin partes y se produce un error. Para subir algo más grande, sube el volumen de -PartSize forma que tenga al menos: 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

-PartSizey -StorageClass son parámetros de destino de S3. Utilícelos con una ruta de destino de S3 explícita (como en el ejemplo anterior), no con un objeto de destino vinculado a una canalización.

-PartSizeacepta un valor entre el mínimo de 5 MiB de S3 y el máximo de 5 GiB. Con un máximo de 5 GiB, 10 000 partes cubren el objeto más grande que admite S3 (5 TiB).

Copie objetos entre S3 y el disco local

No Copy-Item se admite la copia dentro de S3 con (consulteOperaciones compatibles y no compatibles). Para mover datos entre el disco local y S3, canalice el contenido a través Get-Content de Set-Content Y.

En el caso de los datos binarios, lea y escriba los bytes con exactitud. Se utiliza una ruta S3 -AsByteStream en ambas PowerShell ediciones; solo difiere el lado local, como se describe enLa lectura de los bytes de un archivo local varía según la edición.

# 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 lectura de los bytes de un archivo local varía según la edición

La segmentación PowerShell de un archivo local utiliza el FileSystem proveedor integrado, que no tiene -AsByteStream en Windows PowerShell 5.1 (llegó en PowerShell 6). Úsalo -Encoding Byte allí en su lugar. Se trata de una limitación de la versión 5.1, no algo que controle la unidad S3; -AsByteStream en ambas ediciones se utiliza una ruta S3.

Para las S3-to-S3 copias del lado del servidor, utilice el Copy-S3Object cmdlet.

Elimine objetos y prefijos

Remove-Itemelimina un único objeto. Eliminar un prefijo (una carpeta con contenido) requiere-Recurse, lo que elimina por lotes todo lo que esté debajo del prefijo.

# 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

El hecho de Remove-Item que las solicitudes dependan del objetivo al que se dirija:

Usa los PowerShell conmutadores nativos para previsualizar o borrar una imagen:

# 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

No puedes eliminar un depósito completo de la unidad porque las operaciones del ciclo de vida del depósito están fuera de alcance. En su lugar, use Remove-S3Bucket.

Limita una unidad a un bucket o prefijo

Se monta con -Root para confinar una unidad a un depósito o con un prefijo dentro de un depósito. Por lo tanto, la raíz de la unidad es esa ubicación y la navegación se limita a ella.

# 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 raíz ya debe existir. Un bucket o un prefijo inexistentes no se montan. Como las rutas relativas no pueden superar la raíz (están .. bloqueadas por el motor), una montura con ámbito específico te permite ver exactamente los datos de un proyecto.

Accede a sitios de distintas regiones desde un solo viaje

Una sola unidad montada puede llegar a grupos de distintas regiones. La primera vez que tocas un bucket, el proveedor busca su región y dirige automáticamente las llamadas subsiguientes al punto final correcto. No necesitas una unidad diferente para cada región.

# 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

Establece una clase de almacenamiento predeterminada

Establezca una clase de almacenamiento predeterminada para toda la unidad en el momento del montaje con. -StorageClass Todas las subidas a través de esa unidad utilizan la clase especificada, a menos que una clase específica la Set-Content sustituya por la suya propia. -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

Desmonta una unidad

Dismount-S3PSDriveUtilícela (una envolturaRemove-PSDrive) para extraer una unidad. Cambia primero a otra ubicación, porque PowerShell no se eliminará una unidad que esté en tu ubicación actual.

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

Operaciones compatibles y no compatibles

Utilice la unidad para explorar y mover el contenido de los objetos. Las operaciones de copia del ciclo de vida del bucket y del lado del servidor se mantienen en manos de los cmdlets S3 dedicados.

Soportado

No admitido

Los comandos no compatibles fallan y aparecen un mensaje en el que se indica el nombre del comando y se indica la alternativa (por ejemplo, «no Copy-Item es compatible con la unidad S3). Copy-S3ObjectUtilízalo o canaliza Get-Content hacia Set-Content». Los *-ItemProperty comandos son la excepción, tal y como se describe en la tabla anterior.

Referencia de los comandos

Para ver la lista completa de parámetros de Mount-S3PSDrive y Dismount-S3PSDrive, consulte la referencia de Herramientas de AWS para PowerShell cmdlets.

En una ruta S3, la unidad también agrega parámetros dinámicos Set-Content que no se Get-Content incluyen en la PowerShell documentación de esos cmdlets:

Resolución de problemas

«No se puede desmontar la unidad porque está en uso».

La unidad S3 es la ubicación actual. Cambie a una ubicación de otra unidad, por ejemplo$HOME, y Dismount-S3PSDrive vuelva a ejecutarla.

El montaje falla y dice: «No se encontró la raíz o no se puede acceder a ella».

El bucket o el prefijo in -Root no existen. Comprueba el nombre (y la región, si el bucket está en uno en el que tus credenciales no estén configuradas de forma predeterminada). Un error en las credenciales produce un error diferente, no este mensaje de «no se puede acceder a ella». Es posible que un error de permiso en la raíz no aparezca hasta que accedas a un objeto, por lo que un montaje correcto no garantiza que puedas leer todas las rutas que se encuentran debajo de él.

La eliminación de un prefijo que no esté vacío se bloquea en un script.

Esto ocurre cuando se elimina un prefijo que no esté vacío sin. -Recurse El PowerShell motor lanza un mensaje de confirmación porque el prefijo contiene elementos secundarios (es decir, el comportamiento del proveedor del sistema de archivos según el cual el contenedor tiene elementos secundarios). Un host no interactivo no puede responder a la solicitud, por lo que el comando se bloquea.

Pase -Recurse para eliminar el contenido del prefijo sin preguntar, o confirme de forma interactiva para continuar. (no -Force aparece en la ruta de eliminación de la unidad, por lo que no tiene ningún efecto en este caso).

«Un objeto que acabo de cambiar fuera de la unidad sigue mostrando la lista anterior».

Los listados se almacenan en caché brevemente (alrededor de un segundo) para que la navegación sea más rápida. Los cambios realizados a través de la unidad aparecen inmediatamente. Los cambios realizados por otra herramienta aparecen cuando caduca la caché corta.

«Una clave contiene una barra invertida».

El hecho de que la unidad pueda direccionar una clave que contenga una barra invertida depende del sistema operativo, ya que la unidad acepta el separador de rutas nativo de la plataforma: