Uso de comandos alto nivel (s3) con la AWS CLI - AWS Command Line Interface

Uso de comandos alto nivel (s3) con la AWS CLI

En este tema se describe alguno de los comandos que puede utilizar para administrar los buckets y los objetos de Simple Storage Service (Amazon S3) a través de comandos aws s3 en AWS CLI. Para ver los comandos que no se tratan en este tema y ejemplos de comandos adicionales, consulte los comandos de ‎aws s3 en la Referencia de AWS CLI.

Los comandos de aws s3 de alto nivel simplifican la administración de objetos de Amazon S3. Estos comandos le permiten administrar el contenido de Amazon S3 dentro de sí mismo y con directorios locales.

Requisitos previos

Para ejecutar los comandos de s3, necesitará:

  • AWS CLI instalada, consulte Instalación o actualización de la versión más reciente de AWS CLI para obtener más información.

  • AWS CLI configurada, consulte Fundamentos de configuración para obtener más información. El perfil que utilice debe tener permisos que permitan las operaciones que AWS realizó por los ejemplos.

  • Comprenda estos términos de Amazon S3:

    • Bucket: una carpeta de Amazon S3 de nivel superior.

    • Prefijo: una carpeta de Amazon S3 en un bucket.

    • Objeto: cualquier artículo alojado en un bucket de Amazon S3.

Antes de comenzar

En esta sección se describen algunas cosas que hay que tener en cuenta antes de utilizar los comandos de aws s3.

Cargas de objetos grandes

Cuando utiliza comandos aws s3 para cargar objetos grandes en un bucket de Amazon S3, la AWS CLI automáticamente realiza una carga multiparte. Los errores de carga no pueden reanudarse cuando se usan estos comandos de aws s3.

Si la carga multiparte falla debido a que se agota el tiempo de espera, o si canceló en forma manual en la AWS CLI, la AWS CLI detiene la carga y limpia los archivos que se han creado. Este proceso puede tardar varios minutos.

Si el proceso de carga o limpieza multiparte se cancela por un comando de cierre o un error del sistema, los archivos creados permanecen en el bucket de Amazon S3. Para limpiar la carga multiparte, utilice el comando s3api abort-multipart-upload.

Propiedades de archivo y etiquetas en copias multiparte

Cuando se utiliza la versión 1 de la AWS CLI de comandos en el espacio de nombres de aws s3 para copiar un archivo de una ubicación de bucket de Amazon S3 a otra ubicación de bucket de Amazon S3, y esa operación utiliza la copia multiparte, no se copian propiedades de archivo del objeto fuente en el objeto de destino.

De forma predeterminada, los comandos de la versión 2 de la AWS CLI del espacio de nombres de s3 que realizan copias multiparte transfieren todas las etiquetas y el siguiente conjunto de propiedades del origen a la copia de destino: content-type, content-language, content-encoding, content-disposition, cache-control, expires y metadata.

Esto puede dar lugar a llamadas de la API de AWS adicionales al punto de enlace de Amazon S3 que no se habrían realizado si hubiera utilizado la versión 1 de la AWS CLI. Estos pueden incluir: HeadObject, GetObjectTagging y PutObjectTagging.

Si necesita cambiar este comportamiento predeterminado en los comandos de la versión 2 de la AWS CLI, utilice el parámetro --copy-props para especificar una de las siguientes opciones:

  • predeterminada: el valor predeterminado. Especifica que la copia incluye todas las etiquetas asociadas al objeto de origen y las propiedades abarcadas por el parámetro --metadata-directive utilizado para copias no multiparte: content-type, content-language, content-encoding, content-disposition, cache-control, expires y metadata.

  • directiva de metadatos: especifica que la copia incluye solo las propiedades abarcadas por el parámetro --metadata-directive utilizado para copias no multiparte. No copia ninguna etiqueta.

  • ninguno: especifica que la copia no incluye ninguna de las propiedades del objeto fuente.

Cree un bucket

Utilice el comando s3 mb para crear un bucket. Los nombres de los buckets deben ser globalmente únicos (únicos en todo Amazon S3) y deben ser compatibles con DNS.

Los nombres de los buckets pueden contener minúsculas, números, guiones y puntos. Los nombres de los buckets solo pueden empezar y terminar con una letra o número, y no pueden contener un punto junto a un guion u otro punto.

Sintaxis

$ aws s3 mb <target> [--options]

En el siguiente ejemplo se crea el bucket s3://bucket-name.

$ aws s3 mb s3://bucket-name

Lista de buckets y objetos

Para mostrar los buckets, carpetas u objetos, utilice el comando ‎s3 ls. El uso del comando sin destino u opciones muestra todos los buckets.

Sintaxis

$ aws s3 ls <target> [--options]

Para ver algunas opciones comunes que se pueden utilizar con este comando y ejemplos, consulte Opciones utilizadas con frecuencia para los comandos s3. Para ver una lista completa de las opciones ‎disponibles, consulte s3 ls‎ en la Referencia de los comandos de AWS CLI.

En el siguiente ejemplo se enumeran todos los buckets de Amazon S3.

$ aws s3 ls 2018-12-11 17:08:50 my-bucket 2018-12-14 14:55:44 my-bucket2

El siguiente comando muestra todos los objetos y prefijos de un bucket. En este resultado de ejemplo, el prefijo example/ tiene un archivo llamado MyFile1.txt.

$ aws s3 ls s3://bucket-name PRE example/ 2018-12-04 19:05:48 3 MyFile1.txt

Para filtrar la salida por un prefijo específico, inclúyalo en el comando. El siguiente comando muestra los objetos en bucket-name/example/ (es decir, los objetos que estén en bucket-name filtrados por el prefijo example/).

$ aws s3 ls s3://bucket-name/example/ 2018-12-06 18:59:32 3 MyFile1.txt

Eliminar buckets

Para eliminar un bucket, utilice el comando s3 rb.

Sintaxis

$ aws s3 rb <target> [--options]

En el siguiente ejemplo se quita el bucket s3://bucket-name.

$ aws s3 rb s3://bucket-name

De forma predeterminada, el bucket debe estar vacío para que la operación se realice correctamente. Para eliminar un bucket que no esté vacío, debe incluir la opción --force. Si utiliza un bucket versionado que contenga objetos eliminados previamente, pero que se conservan, este comando no le permitirá eliminar el bucket. En primer lugar, debe eliminar todo el contenido.

El siguiente ejemplo elimina todos los objetos y los prefijos en el bucket, luego elimina el bucket.

$ aws s3 rb s3://bucket-name --force

Eliminar objetos

Para eliminar objetos en un bucket o en el directorio local, utilice el comando s3 rm.

Sintaxis

$ aws s3 rm <target> [--options]

Para ver algunas opciones comunes que se pueden utilizar con este comando y ejemplos, consulte Opciones utilizadas con frecuencia para los comandos s3. Para ver una lista completa de opciones, consulte s3 rm‎ en la Referencia de los comandos de AWS CLI.

En el siguiente ejemplo se elimina filename.txt de s3://bucket-name/example.

$ aws s3 rm s3://bucket-name/example/filename.txt --recursive

En el siguiente ejemplo se eliminan todos los objetos de s3://bucket-name/example utilizando la opción --recursive.

$ aws s3 rm s3://bucket-name/example --recursive

Mover objetos

Use el comando s3 mv para mover objeto‎s de un bucket o un directorio local.

Sintaxis

$ aws s3 mv <source> <target> [--options]

Para ver algunas opciones comunes que se pueden utilizar con este comando y ejemplos, consulte Opciones utilizadas con frecuencia para los comandos s3. Para ver una lista completa de las opciones ‎disponibles, consulte s3 mv‎ en la Referencia de los comandos de AWS CLI.

En el siguiente ejemplo se mueven todos los objetos de s3://bucket-name/example a s3://my-bucket/.

$ aws s3 mv s3://bucket-name/example s3://my-bucket/

En el siguiente ejemplo se mueve un archivo local del directorio de trabajo actual al bucket de Amazon S3 con el comando de s3 cp.

$ aws s3 mv filename.txt s3://bucket-name

En el siguiente ejemplo se mueve un archivo del bucket de Amazon S3 a su directorio de trabajo actual, donde ./ especifica su directorio de trabajo actual.

$ aws s3 mv s3://bucket-name/filename.txt ./

Copia de objetos

‎Use el comando s3 cp para copiar objetos de un bucket o un directorio local.

Sintaxis

$ aws s3 cp <source> <target> [--options]

Puede usar el parámetro guión para el streaming de archivos a la entrada estándar (stdin) o salida estándar (stdout).

aviso

Si está utilizando PowerShell, el shell podría alterar la codificación de un CRLF o agregar un CRLF a la entrada o salida canalizada, o a la salida redirigida.

El comando s3 cp utiliza la siguiente sintaxis para cargar una secuencia de archivos desde stdin hasta un bucket especificado.

Sintaxis

$ aws s3 cp - <target> [--options]

El comando s3 cp utiliza la siguiente sintaxis para descargar una secuencia de archivos de Amazon S3 para stdout.

Sintaxis

$ aws s3 cp <target> [--options] -

Para ver algunas opciones comunes que se pueden utilizar con este comando y ejemplos, consulte Opciones utilizadas con frecuencia para los comandos s3. Para ver una lista completa de opciones, consulte s3 cp en ‎la Referencia de los comandos de AWS CLI.

El siguiente ejemplo copia todos los registros de s3://bucket-name/example a s3://my-bucket/.

$ aws s3 cp s3://bucket-name/example s3://my-bucket/

En el siguiente ejemplo se copian un archivo local del directorio de trabajo actual en el bucket de Amazon S3 con els3 cpcomando.

$ aws s3 cp filename.txt s3://bucket-name

En el siguiente ejemplo se copia un archivo de su bucket de Amazon S3 en su directorio de trabajo actual, donde ./ especifica su directorio de trabajo actual.

$ aws s3 cp s3://bucket-name/filename.txt ./

En el siguiente ejemplo se utiliza la repetición para transmitir el texto “hola mundo” al archivo s3://bucket-name/filename.txt.

$ echo "hello world" | aws s3 cp - s3://bucket-name/filename.txt

En el ejemplo siguiente se transmite el archivo s3://bucket-name/filename.txt a stdout y se imprime el contenido en la consola.

$ aws s3 cp s3://bucket-name/filename.txt - hello world

En el siguiente ejemplo se transmiten los contenidos de s3://bucket-name/pre a stdout, se utiliza el comando bzip2 para comprimir los archivos y se carga el nuevo archivo comprimido llamado key.bz2 a s3://bucket-name.

$ aws s3 cp s3://bucket-name/pre - | bzip2 --best | aws s3 cp - s3://bucket-name/key.bz2

Sincronización de objetos

‎El comando s3 sync sincroniza el contenido de un bucket y un directorio o los contenidos de dos buckets. Normalmente, s3 sync copia archivos u objetos que estén desactualizados o que falten entre el origen y el destino. Sin embargo, también puede introducir la opción --delete para quitar archivos u objetos desde el destino que no se encuentran en el origen.

Sintaxis

$ aws s3 sync <source> <target> [--options]

Para ver algunas opciones comunes que se pueden utilizar con este comando y ejemplos, consulte Opciones utilizadas con frecuencia para los comandos s3. Para ver una lista completa de opciones, consulte s3 sync‎ en la Referencia de los comandos de AWS CLI.

En el siguiente ejemplo se sincroniza el contenido de un prefijo Amazon S3 llamado ruta en el bucket denominado my-bucket con el directorio activo actual.

s3 sync actualiza los archivos que tengan un tamaño o tiempo de modificación diferente que los archivos con el mismo nombre en el destino. La salida muestra las operaciones específica realizadas durante la sincronización. Observe que la operación sincroniza de forma recursiva el subdirectorio MySubdirectory y su contenido con s3://my-bucket/path/MySubdirectory.

$ aws s3 sync . s3://my-bucket/path upload: MySubdirectory\MyFile3.txt to s3://my-bucket/path/MySubdirectory/MyFile3.txt upload: MyFile2.txt to s3://my-bucket/path/MyFile2.txt upload: MyFile1.txt to s3://my-bucket/path/MyFile1.txt

En el siguiente ejemplo, que amplía el anterior, se muestra cómo funciona la opción --delete.

// Delete local file $ rm ./MyFile1.txt // Attempt sync without --delete option - nothing happens $ aws s3 sync . s3://my-bucket/path // Sync with deletion - object is deleted from bucket $ aws s3 sync . s3://my-bucket/path --delete delete: s3://my-bucket/path/MyFile1.txt // Delete object from bucket $ aws s3 rm s3://my-bucket/path/MySubdirectory/MyFile3.txt delete: s3://my-bucket/path/MySubdirectory/MyFile3.txt // Sync with deletion - local file is deleted $ aws s3 sync s3://my-bucket/path . --delete delete: MySubdirectory\MyFile3.txt // Sync with Infrequent Access storage class $ aws s3 sync . s3://my-bucket/path --storage-class STANDARD_IA

Cuando se utiliza la opción --delete, las opciones --exclude y --include pueden filtrar archivos u objetos para eliminarlos durante una operación de s3 sync. En este caso, la cadena del parámetro debe especificar qué archivos se deben excluir o incluir en la eliminación, en el contexto del directorio o bucket de destino. A continuación se muestra un ejemplo.

Assume local directory and s3://my-bucket/path currently in sync and each contains 3 files: MyFile1.txt MyFile2.rtf MyFile88.txt ''' // Sync with delete, excluding files that match a pattern. MyFile88.txt is deleted, while remote MyFile1.txt is not. $ aws s3 sync . s3://my-bucket/path --delete --exclude "path/MyFile?.txt" delete: s3://my-bucket/path/MyFile88.txt ''' // Sync with delete, excluding MyFile2.rtf - local file is NOT deleted $ aws s3 sync s3://my-bucket/path . --delete --exclude "./MyFile2.rtf" download: s3://my-bucket/path/MyFile1.txt to MyFile1.txt ''' // Sync with delete, local copy of MyFile2.rtf is deleted $ aws s3 sync s3://my-bucket/path . --delete delete: MyFile2.rtf

Opciones utilizadas con frecuencia para los comandos s3

Las siguientes opciones se utilizan con frecuencia para los comandos descritos en este tema. ‎Para obtener una lista completa de las opciones que puede utilizar en un comando, consulte el comando específico en guía de referencia de AWS CLI versión 2.

acl

s3 sync y s3 cp pueden utilizar la opción --acl. Esto le permite configurar los permisos de acceso para archivos copiados en Amazon S3. La opción --acl admite los valores private, public-read y public-read-write. Para obtener más información, consulte la sección ACL predefinidas en la Guía del usuario de Amazon Simple Storage Service.

$ aws s3 sync . s3://my-bucket/path --acl public-read
excluya

Cuando utiliza el comando s3 cp, s3 mv, s3 sync o s3 rm, puede filtrar los resultados mediante la opción --exclude o --include. La opción --exclude establece reglas para excluir únicamente objetos del comando y las opciones se aplican en el orden especificado. Esto se muestra en el siguiente ejemplo.

Local directory contains 3 files: MyFile1.txt MyFile2.rtf MyFile88.txt // Exclude all .txt files, resulting in only MyFile2.rtf being copied $ aws s3 cp . s3://my-bucket/path --exclude "*.txt" // Exclude all .txt files but include all files with the "MyFile*.txt" format, resulting in, MyFile1.txt, MyFile2.rtf, MyFile88.txt being copied $ aws s3 cp . s3://my-bucket/path --exclude "*.txt" --include "MyFile*.txt" // Exclude all .txt files, but include all files with the "MyFile*.txt" format, but exclude all files with the "MyFile?.txt" format resulting in, MyFile2.rtf and MyFile88.txt being copied $ aws s3 cp . s3://my-bucket/path --exclude "*.txt" --include "MyFile*.txt" --exclude "MyFile?.txt"
incluir

Cuando utiliza el comando s3 cp, s3 mv, s3 sync o s3 rm, puede filtrar los resultados utilizando la opción --exclude o --include. La opción --include establece reglas para incluir únicamente objetos específicos para el comando y las opciones se aplican en el orden especificado. Esto se muestra en el siguiente ejemplo.

Local directory contains 3 files: MyFile1.txt MyFile2.rtf MyFile88.txt // Include all .txt files, resulting in MyFile1.txt and MyFile88.txt being copied $ aws s3 cp . s3://my-bucket/path --include "*.txt" // Include all .txt files but exclude all files with the "MyFile*.txt" format, resulting in no files being copied $ aws s3 cp . s3://my-bucket/path --include "*.txt" --exclude "MyFile*.txt" // Include all .txt files, but exclude all files with the "MyFile*.txt" format, but include all files with the "MyFile?.txt" format resulting in MyFile1.txt being copied $ aws s3 cp . s3://my-bucket/path --include "*.txt" --exclude "MyFile*.txt" --include "MyFile?.txt"
concesión

Los comandos s3 cp, s3 mv y s3 sync incluyen una opción --grants que puede usar para conceder permisos sobre el objeto a usuarios o grupos específicos. Configure la opción --grants para obtener una lista de permisos mediante la siguiente sintaxis. Reemplace Permission, Grantee_Type y Grantee_ID por sus propios valores.

Sintaxis

--grants Permission=Grantee_Type=Grantee_ID [Permission=Grantee_Type=Grantee_ID ...]

Cada valor contiene los siguientes elementos:

  • Permiso: especifica los permisos concedidos. Se puede establecer en read, readacl, writeacl o full.

  • Tipo de beneficiario: especifica cómo identificar al beneficiario. Se puede establecer en uri, emailaddress o id.

  • Grantee_ID: especifica el beneficiario del permiso según Grantee_Type.

    • uri: URI del grupo. Para obtener más información, consulte la sección ¿Quién es un beneficiario?

    • emailaddress: dirección de correo electrónico de la cuenta.

    • id: ID canónico de la cuenta.

Para obtener más información acerca de cómo controlar el acceso a Amazon S3, consulte la sección de Control de acceso.

En el siguiente ejemplo se copia un objeto en un bucket. Concede permisos read sobre el objeto a todos los usuarios y permisos full (read, readacl y writeacl) a la cuenta asociada con user@example.com.

$ aws s3 cp file.txt s3://my-bucket/ --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers full=emailaddress=user@example.com

También puede especificar una clase de almacenamiento no predeterminada (REDUCED_REDUNDANCY o STANDARD_IA) para los objetos que se cargan en Amazon S3. Para ello, utilice la opción --storage-class.

$ aws s3 cp file.txt s3://my-bucket/ --storage-class REDUCED_REDUNDANCY
recursive

Cuando use esta opción, el comando se ejecuta en todos los objetos o archivos del directorio especificado o con el prefijo indicado. En el siguiente ejemplo se elimina s3://my-bucket/path y todos sus contenidos.

$ aws s3 rm s3://my-bucket/path --recursive

Recursos

referencia de AWS CLI:

Referencia de servicio: