ossutil cp - Upload files and directories to OSS - Object Storage Service

Cargue archivos o directorios locales a un bucket de OSS con el comando cp. Este comando admite la carga simple, la carga reanudable, la carga por lotes y la carga incremental. Además, ofrece opciones para los metadatos del objeto, la clase de almacenamiento y la ACL.

Funcionamiento

El comando cp selecciona el método de carga según el tamaño del archivo:

Carga simple: se utiliza cuando el archivo es más pequeño que el umbral de carga reanudable (valor predeterminado: 100 MB, configurable con --bigfile-threshold).
Carga reanudable: se utiliza cuando el archivo alcanza o supera dicho umbral. Las cargas interrumpidas dejan partes en el bucket. Elimine estas partes periódicamente para evitar costos de almacenamiento. Puede delete parts manualmente o configurar lifecycle rules para eliminarlas automáticamente.

Nota

A partir de ossutil v1.6.16, puede usar ossutil como nombre del binario en todos los sistemas operativos compatibles. En versiones anteriores, debe usar el nombre del binario específico de su sistema operativo. Para obtener más información, consulte ossutil command reference.

Permisos

Una cuenta de Alibaba Cloud tiene todos los permisos de forma predeterminada. Los usuarios y roles de RAM no tienen permisos predeterminados y requieren autorización mediante una RAM policy o un bucket policy.

Acción de API	Descripción
`oss:PutObject`	Carga un objeto.
`oss:PutObjectTagging`	Obligatorio solo cuando se configuran etiquetas de objeto durante la carga.
`kms:GenerateDataKey`	Obligatorio solo cuando se usa el cifrado del lado del servidor de Key Management Service (KMS).
`kms:Decrypt`

Sintaxis del comando

ossutil cp file_url cloud_url [options]

Parámetros y opciones:

Parámetro	Descripción
file_url	Ruta del archivo local. Si el origen es un directorio, la ruta debe terminar con un separador de ruta (`/` o `\`). Por ejemplo, `/localfolder/examplefile.txt` en un sistema Linux o `D:\localfolder\examplefile.txt` en un sistema Windows.
cloud_url	Ruta del objeto, con el formato `oss://bucket[/prefix]`. Ejemplo: `oss://examplebucket/examplefile.txt`.
-r, --recursive	Carga archivos y subdirectorios de forma recursiva. Sin esta opción, solo se procesa el objeto especificado.
-f --force	Fuerza la ejecución de la operación sin solicitar confirmación.
-u, --update	Carga únicamente si el objeto de destino no existe o es más antiguo que el archivo de origen.
--maxupspeed	Velocidad máxima de carga en KB/s. Valor predeterminado: 0 (sin límite).
--enable-symlink-dir	Carga los subdirectorios vinculados. Esta opción está deshabilitada de forma predeterminada.
--disable-all-symlink	Ignora todos los enlaces simbólicos durante la carga.
--disable-ignore-error	No ignora los errores durante las operaciones por lotes.
--only-current-dir	Carga solo los archivos del directorio de origen especificado e ignora sus subdirectorios.
--bigfile-threshold	Umbral de tamaño para iniciar una carga reanudable. Unidad: bytes. Valor predeterminado: 100 MB Valores válidos: de 0 a 9223372036854775807
--part-size	Tamaño de cada parte en bytes. De forma predeterminada, ossutil lo calcula según el tamaño del archivo. Intervalo: de 1 a 9223372036854775807
--checkpoint-dir	Directorio donde se guardan los registros de la carga reanudable. De forma predeterminada, ossutil crea el directorio `.ossutil_checkpoint` y lo elimina tras completar la carga. Si especifica un directorio personalizado, asegúrese de que se pueda eliminar.
--encoding-type	Codificación de los nombres de archivo. Establezca el valor url para codificar los nombres de archivo con URL. No se aplica ninguna codificación de forma predeterminada.
--include	Incluye todos los archivos que cumplen las condiciones especificadas. Para obtener más información sobre la sintaxis y ver ejemplos, consulte Batch upload files that meet specified conditions.
--exclude	Excluye todos los archivos que cumplen las condiciones especificadas. Para obtener más información sobre la sintaxis y ver ejemplos, consulte Batch upload files that meet specified conditions.
--meta	Metadatos del archivo. Incluyen encabezados HTTP estándar y metadatos definidos por el usuario, que comienzan con `x-oss-meta-`. Los metadatos deben tener el formato `header:value#header:value`. Ejemplo: `Cache-Control:no-cache#Content-Encoding:gzip`. Para obtener más información sobre los metadatos compatibles con OSS, consulte Manage object metadata.
--acl	Lista de control de acceso (ACL) del archivo. Valores válidos: default (predeterminado): la ACL del objeto es igual a la ACL del bucket. private: solo el propietario del bucket puede leer y escribir los objetos del bucket. Otros usuarios no pueden acceder a los objetos. public-read: solo el propietario del bucket puede escribir en los objetos del bucket. Otros usuarios, incluidos los anónimos, pueden leerlos. Esto puede provocar filtraciones de datos y cargos inesperadamente altos. Si usuarios malintencionados escriben información ilegal en los objetos, sus derechos e intereses legítimos podrían verse afectados. No configure este permiso salvo en escenarios especiales. public-read-write: cualquier persona, incluidos los usuarios anónimos, puede leer y escribir los objetos del bucket. Esto puede provocar filtraciones de datos y cargos inesperadamente altos. Tenga precaución al configurar este permiso.
--snapshot-path	Directorio para las instantáneas de carga. En cargas posteriores, ossutil lee este directorio para ejecutar cargas incrementales.
--disable-crc64	Deshabilita la validación de datos CRC-64. Está habilitada de forma predeterminada.
--disable-dir-object	Omite la creación de objetos de directorio durante la carga.
--payer	Método de pago. Establezca el valor requester para cobrar al solicitante las tarifas de tráfico y de solicitudes.
--tagging	Etiquetas que se agregan durante la carga. Formato: `TagkeyA=TagvalueA&TagkeyB=TagvalueB....`.
-j, --jobs	Tareas simultáneas para operaciones con varios archivos. Valor predeterminado: 3. Valores válidos: de 1 a 10000.
--parallel	Tareas simultáneas para operaciones con un solo archivo. Valores válidos: de 1 a 10000. Si no se establece, se determina automáticamente según el tipo de operación y el tamaño del archivo.
--start-time	Marca de tiempo UNIX. Se ignoran los objetos cuya última actualización sea anterior a esta hora. Nota Solo ossutil 1.7.18 y versiones posteriores admiten este parámetro. Para obtener más información sobre cómo actualizar, consulte update (Upgrade ossutil).
--end-time	Marca de tiempo UNIX. Se ignoran los objetos cuya última actualización sea posterior a esta hora. Nota Si especifica tanto `start-time` como `end-time`, el comando de copia se ejecuta solo para los archivos modificados por última vez entre las horas de inicio y fin especificadas. Solo ossutil 1.7.18 y versiones posteriores admiten este parámetro. Para obtener más información sobre cómo actualizar la versión, consulte update (Upgrade ossutil).

Para obtener más información sobre otras opciones comunes de este comando, consulte Common options.

Ajuste -j, --jobs y --parallel para optimizar el rendimiento. De forma predeterminada, ossutil calcula el paralelismo según el tamaño del archivo. En transferencias por lotes de archivos grandes, la concurrencia real equivale a jobs × parallel.

Si la computadora tiene recursos limitados (ancho de banda, memoria o CPU), reduzca la concurrencia a 100 o menos. Auméntela si los recursos están subutilizados.
Una concurrencia excesiva puede degradar el rendimiento o causar errores EOF. Ajuste -j, --jobs y --parallel según los recursos de su computadora. Comience con valores bajos y auméntelos gradualmente hasta encontrar el valor óptimo.

Ejemplos

Estos ejemplos usan Linux. Ajuste las rutas según su sistema operativo. Los ejemplos asumen lo siguiente:

Nombre del bucket: examplebucket
Directorio de OSS: desfolder/
Directorio local: localfolder/
Archivo local: examplefile.txt

Cargar un solo archivo

Cargue un archivo a un directorio. Si no se especifica un nombre de objeto, se usa el nombre original del archivo.
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
Cargue un solo archivo y use la opción --meta para establecer los metadatos del archivo. Los metadatos deben tener el formato header:value#header:value....
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
```

Cargas por lotes

Cargar solo los archivos de una carpeta
Agregue la opción -r al comando cp para cargar solo los archivos de una carpeta local a una ruta específica de OSS.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
Cargar archivos de una carpeta y especificar una marca de tiempo

Cargue archivos de una carpeta local a una ruta específica de OSS. Los archivos deben haberse modificado entre las 10:09:18 (UTC+8) del 31 de octubre de 2023 y las 12:55:58 (UTC+8) del 31 de octubre de 2023.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
Cargar una carpeta y los archivos que contiene

Use la opción -r del comando cp para cargar una carpeta local y sus archivos. OSS crea un objeto de 0 KB terminado en / para cada subdirectorio, pero no para la carpeta en sí. Para crear un objeto de carpeta, use el comando mkdir (create directories).
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
Cargar una carpeta y omitir los archivos existentes

Para reintentar una carga por lotes con errores, use --update (o -u) para omitir los archivos ya cargados y ejecutar una carga incremental:
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

Cargar solo los archivos del directorio actual e ignorar los subdirectorios

ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

Cargar sin generar un objeto para el directorio

En OSS, los directorios se simulan mediante objetos de 0 KB terminados en /. Use --disable-dir-object para omitir la creación de estos objetos. La estructura de directorios sigue apareciendo en la consola de OSS, pero desaparece cuando se eliminan todos los archivos que contiene.
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
```

Cargar archivos de un subdirectorio vinculado

ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r

Ignorar todos los subarchivos y subdirectorios vinculados durante una carga

ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

De forma predeterminada, el comando cp sigue los enlaces simbólicos y carga el contenido del archivo al que apunta el enlace, en lugar del enlace mismo.

Por ejemplo, link.txt es un enlace simbólico que apunta a source.txt:
```
ossutil cp link.txt oss://examplebucket/
```
Después de la carga, el contenido del objeto en OSS coincide con el de source.txt. El comportamiento es el mismo para cargas de un solo archivo y para cargas recursivas de directorios (-r).

Las opciones --disable-all-symlink y --enable-symlink-dir solo están disponibles en ossutil 1.x. En ossutil 2.x, la herramienta sigue los enlaces simbólicos de forma predeterminada y no ofrece ninguna opción para deshabilitar este comportamiento.

Cargar por lotes archivos que cumplen condiciones específicas

Use --include y --exclude para filtrar archivos durante una carga por lotes.

Las opciones --include y --exclude admiten los siguientes formatos:

Asterisco (*): coincide con cualquier cantidad de caracteres. Por ejemplo, *.txt coincide con todos los archivos TXT.
Signo de interrogación (?): coincide con un solo carácter. Por ejemplo, abc?.jpg coincide con todos los archivos JPG cuyo nombre es "abc" seguido de un solo carácter, como abc1.jpg.
[secuencia]: coincide con cualquier carácter de la secuencia. Por ejemplo, abc[1-5].jpg coincide con los archivos llamados abc1.jpg to abc5.jpg.
[!secuencia]: coincide con cualquier carácter fuera de la secuencia. Por ejemplo, abc[!0-7].jpg coincide con los archivos cuyo nombre no es abc0.jpg to abc7.jpg.

Una regla puede contener varias condiciones de inclusión y exclusión. ossutil las evalúa de izquierda a derecha. Para un archivo llamado test.txt, distintos órdenes de reglas producen resultados diferentes.

Regla 1: --include "*test*" --exclude "*.txt" . Cuando la regla coincide con --include "*test*", el resultado indica que test.txt cumple la condición. Cuando la regla continúa evaluando --exclude "*.txt", test.txt se excluye porque su nombre contiene .txt. El resultado final es que test.txt no cumple las condiciones.
Regla 2: --exclude "*.txt" --include "*test*". El archivo test.txt se excluye por la regla --exclude "*.txt". Sin embargo, la regla --include "*test*" incluye después test.txt porque su nombre contiene "test". Como resultado, test.txt se incluye.
Regla 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" . Primero, la regla --include "*test*" incluye test.txt. Luego, la regla --exclude "*.txt" excluye test.txt. Por último, la regla --include "te?t.txt" incluye test.txt. Por lo tanto, test.txt se incluye.

Importante

No puede especificar un formato de directorio en las condiciones. Por ejemplo, --include "/usr/test/.jpg" no es compatible.

A continuación se muestran algunos ejemplos:

Cargar todos los archivos con formato TXT

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r

Cargar todos los archivos cuyo nombre contenga abc y que no tengan formato JPG ni TXT

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

Limitar la velocidad de carga

Use --maxupspeed para limitar la velocidad de carga en KB/s. Ejemplos:

Cargar un archivo y establecer el límite de velocidad en 1 MB/s

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024

Cargar una carpeta y establecer el límite de velocidad en 1 MB/s

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

Cargar y establecer etiquetas de objeto

Use --tagging para establecer etiquetas de objeto durante la carga. Separe varias etiquetas con el signo &. Ejemplo:

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&..."

Object tagging.

Cargar y especificar una clase de almacenamiento

Use --meta para establecer la clase de almacenamiento durante la carga. Valores válidos:

Standard: Standard
IA: Infrequent Access
Archive: Archive Storage
ColdArchive: Cold Archive
DeepColdArchive: Deep Cold Archive

Si no se especifica ninguna clase de almacenamiento, el objeto hereda la clase de almacenamiento del bucket. Para obtener más información, consulte 存储类型.

A continuación se muestran ejemplos de cómo cargar un archivo y especificar una clase de almacenamiento:

Cargar un solo archivo y establecer su clase de almacenamiento en Infrequent Access

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA

Cargar una carpeta y establecer la clase de almacenamiento de sus archivos en Standard

ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

Cargar y especificar una ACL

Use --acl para establecer la ACL del archivo cargado. Valores válidos:

default: hereda la ACL del bucket (predeterminado)
private: private
public-read: public-read
public-read-write: acceso público de lectura y escritura

A continuación se muestran algunos ejemplos:

Cargar un solo archivo y establecer su ACL en private

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private

Cargar una carpeta y establecer la ACL de sus archivos en public-read

ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

Cargar y especificar un método de cifrado

Especifique un método de cifrado del lado del servidor durante la carga. Ejemplos:

Cargar un archivo y especificar SSE-OSS como método de cifrado y AES256 como algoritmo de cifrado

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256

Cargar un archivo y especificar SSE-KMS como método de cifrado y no especificar un ID de CMK
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS
```
El cifrado KMS genera una pequeña tarifa por uso de claves. KMS pricing.

Cargar un archivo y especificar SSE-KMS como método de cifrado y un ID de CMK

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

Para obtener más información sobre el cifrado del lado del servidor, consulte Server-side encryption.

Cargar y generar instantáneas

Con --snapshot-path, ossutil registra el lastModifiedTime de los archivos cargados y lo usa para omitir los archivos sin cambios en cargas posteriores, lo que acelera las cargas incrementales por lotes. Asegúrese de que ningún otro usuario modifique los objetos correspondientes entre cargas. --snapshot-path es ideal para cargas por lotes de gran tamaño. Ejemplo:

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path

Importante

ossutil no elimina automáticamente las instantáneas de la carpeta snapshot-path. Elimine periódicamente las instantáneas innecesarias de la carpeta snapshot-path.
La E/S de las instantáneas añade sobrecarga. Para lotes pequeños, buenas condiciones de red u objetos compartidos, use --update para las cargas incrementales.
Puede usar las opciones --update y --snapshot-path al mismo tiempo. Primero, ossutil revisa la información de snapshot-path para determinar si omite un archivo. Si el archivo no se omite según la instantánea, ossutil usa la opción --update para decidir si lo omite.

Cargar y configurar pay-by-requester

ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

Cargas entre cuentas o entre regiones

Use las opciones comunes -e, -i y -k para cargar un archivo local a un bucket de otra región o de otra cuenta de Alibaba Cloud.

Nota

Especifique el endpoint que corresponde a la región del bucket. Para obtener más información, consulte Regions and endpoints.

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret