Object Storage Service PutObject API - Object Storage Service - Centro de documentación de Alibaba Cloud

Utilice la API PutObject para cargar un archivo en un bucket de Object Storage Service (OSS). El tamaño máximo de un archivo que se puede cargar en una sola operación es de 5 GB.

Sintaxis de la solicitud

PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Notas de uso

El tamaño máximo de un archivo que se puede cargar en una sola operación es de 5 GB. Para cargar un archivo mayor a 5 GB, utilice la función de carga multiparte.
Cuando carga un archivo con el mismo nombre que uno existente, el archivo existente se sobrescribe de forma predeterminada y se devuelve un código de estado 200 OK. Puede establecer un parámetro para evitar sobreescrituras y así prevenir la pérdida accidental de archivos importantes.
OSS utiliza una estructura de almacenamiento plana y no cuenta con directorios como un sistema de archivos tradicional. Puede simular una estructura de carpetas mediante la creación de un objeto vacío que termine con una barra diagonal (/).

Permissions

Una cuenta de Alibaba Cloud tiene permisos completos de forma predeterminada. Sin embargo, un usuario de Resource Access Management (RAM) o un rol de RAM bajo dicha cuenta no tiene permisos hasta que la cuenta de Alibaba Cloud o un administrador se los otorga mediante un RAM Policy o un Bucket Policy.

API	Action	Descripción
PutObject	`oss:PutObject`	Carga un objeto.
	`oss:PutObjectTagging`	Obligatorio si especifica etiquetas de objeto mediante el encabezado `x-oss-tagging` al cargar un objeto.
	`kms:GenerateDataKey`	Obligatorio si el encabezado `X-Oss-Server-Side-Encryption: KMS` se establece en `KMS` al cargar un objeto.
	`kms:Decrypt`

Versioning

En un bucket con el control de versiones habilitado, OSS genera automáticamente un ID de versión único para cada nuevo objeto. Este ID se devuelve en el encabezado de respuesta x-oss-version-id.

En un bucket con el control de versiones suspendido, el ID de versión de un nuevo objeto es null. OSS garantiza que solo exista una versión null de un objeto.

Parámetros de solicitud

OSS admite encabezados de solicitud HTTP estándar como Cache-Control, Expires, Content-Encoding, Content-Disposition y Content-Type. Si establece estos encabezados de solicitud, sus valores se aplican automáticamente cuando se descarga el archivo.

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Authorization	String	No	OSS qn6q:77Dv**	Indica que la solicitud ha sido autenticada y autorizada. Para obtener más información sobre cómo calcular el valor de Authorization, consulte Include a signature in the header. El encabezado Authorization suele ser obligatorio. Sin embargo, no necesita incluir este encabezado si incluye la firma en la URL. Para obtener más información, consulte Include a signature in the URL. Valor predeterminado: ninguno
Cache-Control	String	No	no-cache	Especifica el comportamiento de caché cuando se descarga un objeto. Valores válidos: no-cache: La caché debe revalidarse con el servidor de origen antes de servir el contenido. no-store: No se almacena el objeto en caché. public: Cualquier caché puede almacenar el objeto. private: El objeto se almacena en caché únicamente en el cliente. max-age=<seconds>: Periodo de validez de la caché en segundos. Disponible solo en HTTP 1.1. Valor predeterminado: ninguno
Content-Disposition	String	No	attachment	Especifica cómo se muestra el objeto. Valores válidos: Content-Disposition:inline: Muestra el objeto en el navegador. Content-Disposition:attachment: Descarga el objeto con su nombre original. Content-Disposition:attachment; filename="yourFileName": Descarga el objeto con un nombre de archivo personalizado. yourFileName es el nombre de archivo personalizado, por ejemplo, example.jpg. Al descargar objetos como archivos adjuntos, tenga en cuenta lo siguiente: Nota Si el nombre del objeto contiene caracteres especiales como asteriscos () o barras diagonales (/), es posible que el nombre del archivo descargado se escape. Por ejemplo, si descarga `example`.jpg a su computadora local, `example*.jpg` podría escaparse como `example_.jpg`. Para evitar nombres de archivo ilegibles debido a caracteres no ASCII, codifíquelos en formato URL. Por ejemplo, para descargar el objeto `Test.txt` con su nombre original `Test.txt`, establezca el encabezado Content-Disposition en `attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename=UTF-8''%E6%B5%8B%E8%AF%95.txt`, lo cual se deriva de `"attachment;filename="+URLEncoder.encode("Test","UTF-8")+".txt;filename=UTF-8''"+URLEncoder.encode("Test","UTF-8")+".txt"`. La visualización previa o la descarga de un objeto como archivo adjunto depende del momento de creación del bucket, del momento de activación de OSS y del tipo de nombre de dominio. Para obtener más información, consulte What do I do if an image object is downloaded as an attachment but cannot be previewed when I access the image object by using its URL? Valor predeterminado: ninguno
Content-Encoding	String	No	identity	Declara el códec del objeto. Debe especificar el códec real del objeto; de lo contrario, podrían producirse errores de análisis sintáctico o de descarga en el cliente. Si el objeto no está codificado, deje este encabezado vacío. Valores válidos: identity (predeterminado): Sin compresión ni codificación. gzip: Codificado con el algoritmo LZ77 y CRC de 32 bits. compress: Codificado con el algoritmo LZW. deflate: Codificado con zlib y el algoritmo deflate. br: Codificado con el algoritmo Brotli. Valor predeterminado: ninguno
Content-MD5	String	No	eB5eJF1ptWaXm4bijSPyxw==	Se utiliza para comprobar la integridad del contenido del mensaje. Content-MD5 es un valor generado por el algoritmo MD5. Si establece este encabezado, OSS calcula el hash Content-MD5 del cuerpo del mensaje y verifica su consistencia. Para obtener más información, consulte How to calculate Content-MD5. Para garantizar la integridad de los datos, OSS proporciona varios métodos para verificar el hash MD5 de los datos. Para realizar la verificación MD5 mediante Content-MD5, agregue el encabezado Content-MD5 a la solicitud. Valor predeterminado: ninguno
Content-Length	String	No	344606	Tamaño del cuerpo del mensaje HTTP que se transferirá, en bytes. Si el valor del encabezado Content-Length es menor que el tamaño real de los datos transferidos en el cuerpo de la solicitud, OSS crea el objeto de todas formas. Sin embargo, el tamaño del objeto será igual al definido en Content-Length y los datos excedentes se descartarán.
Expires	String	No	Wed, 08 Jul 2015 16:57:01 GMT	Especifica la fecha de caducidad del objeto. Para obtener más información, consulte RFC2616. Valor predeterminado: ninguno
x-oss-forbid-overwrite	String	No	false	Especifica si se debe sobrescribir un objeto con el mismo nombre durante una operación PutObject. Si el bucket de destino tiene el control de versiones habilitado o suspendido, el encabezado de solicitud x-oss-forbid-overwrite no surte efecto. Esto significa que un objeto con el mismo nombre puede sobrescribirse. Si no especifica x-oss-forbid-overwrite o establece x-oss-forbid-overwrite en false, un objeto con el mismo nombre puede sobrescribirse. Si establece x-oss-forbid-overwrite en true, un objeto con el mismo nombre no puede sobrescribirse. Establecer el encabezado de solicitud x-oss-forbid-overwrite afecta el rendimiento de QPS. Si muchas operaciones (QPS>1000) requieren el encabezado de solicitud x-oss-forbid-overwrite, póngase en contacto con el soporte técnico para evitar impactos en sus operaciones comerciales. Valor predeterminado: false
x-oss-server-side-encryption	String	No	AES256	Especifica el método de cifrado del lado del servidor cuando crea un objeto. Valores válidos: AES256, KMS, Si especifica este encabezado, se devuelve en el encabezado de respuesta. OSS cifra y almacena el objeto cargado. Cuando descarga el objeto, el encabezado de respuesta incluye x-oss-server-side-encryption y su valor se establece en el algoritmo de cifrado del objeto.
x-oss-server-side-encryption-key-id	String	No	9468da86-3509-4f8d-a61e-6eab1eac****	ID de la clave maestra del cliente (CMK) gestionada por KMS. Este encabezado solo es válido cuando x-oss-server-side-encryption se establece en KMS.
x-oss-object-acl	String	No	default	Especifica los permisos de acceso del objeto cuando se crea en OSS. Valores válidos: default: El objeto hereda los permisos de acceso del bucket. private: El objeto es un recurso privado. Solo el propietario del objeto y los usuarios autorizados tienen permisos de lectura y escritura sobre el objeto. Otros usuarios no pueden acceder al objeto. public-read: El objeto es un recurso de lectura pública. Solo el propietario del objeto y los usuarios autorizados tienen permisos de lectura y escritura sobre el objeto. Otros usuarios solo tienen permisos de lectura. Utilice este permiso con precaución. public-read-write: El objeto es un recurso de lectura y escritura públicas. Todos los usuarios tienen permisos de lectura y escritura sobre el objeto. Utilice este permiso con precaución. Para obtener más información sobre los permisos de acceso, consulte Object ACL.
x-oss-storage-class	String	No	Standard	Especifica la clase de almacenamiento del objeto. Para un bucket de cualquier clase de almacenamiento, si especifica este parámetro al cargar un objeto, el objeto se almacena en la clase especificada. Por ejemplo, si establece x-oss-storage-class en Standard al cargar un objeto en un bucket de Infrequent Access (IA), el objeto se almacena como un objeto Standard. Valores válidos: Standard: Standard IA: Infrequent Access Archive: Archive Storage ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Importante Si desea cargar una gran cantidad de objetos, especificar directamente la clase de almacenamiento Deep Cold Archive para los objetos que se van a cargar genera altas tarifas de solicitudes PUT. Le recomendamos que primero especifique la clase de almacenamiento Standard para los objetos al cargarlos y luego utilice lifecycle rules para convertirlos a la clase de almacenamiento Deep Cold Archive y así reducir las tarifas de solicitudes PUT. Para obtener más información, consulte Storage classes.
x-oss-meta-*	String	No	x-oss-meta-location	Cuando utiliza la API PutObject, los parámetros con el prefijo x-oss-meta- se consideran metadatos definidos por el usuario, como `x-oss-meta-location`. Un objeto puede tener varios de estos parámetros, pero el tamaño total de todos los metadatos no puede superar los 8 KB. Los metadatos admiten guiones (-), números y letras minúsculas (a-z). Las letras mayúsculas se convierten a minúsculas. No se admiten otros caracteres, incluidos los guiones bajos (_).
x-oss-tagging	String	No	TagA=A&TagB=B	Especifica etiquetas para el objeto en formato clave-valor. Puede establecer varias etiquetas al mismo tiempo, como `TagA=A&TagB=B`. Nota La clave y el valor deben estar codificados en formato URL. La clave es obligatoria, pero el valor es opcional. Por ejemplo, puede establecer las etiquetas del objeto en `TagA&TagB=B`.

Para obtener más información, consulte Common Response Headers.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
Content-MD5	String	1B2M2Y8AsgTpgAmY7PhC****	Hash MD5 del archivo cargado. Importante El hash MD5 es el hash del archivo obtenido después de que el cliente completa la carga, no el hash MD5 del cuerpo de la respuesta.
x-oss-hash-crc64ecma	String	316181249502703****	Valor CRC-64 del archivo cargado.
x-oss-version-id	String	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	ID de versión del archivo. Este encabezado de respuesta se devuelve únicamente cuando el archivo se carga en un bucket con el control de versiones habilitado.

Para obtener más información, consulte Common Response Headers.

Ejemplos

Carga simple

Ejemplo de solicitud

PUT /test.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
Connection: keep-alive
Content-Type: text/plain
Date: Tue, 04 Dec 2018 15:56:37 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Transfer-Encoding: chunked

Ejemplo de respuesta

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 04 Dec 2018 15:56:38 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
ETag: "D41D8CD98F00B204E9800998ECF8****"
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
x-oss-server-time: 7

Establecer la clase de almacenamiento

Ejemplo de solicitud

PUT /oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Cache-control: no-cache 
Expires: Fri, 28 Feb 2012 05:38:42 GMT 
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
[344606 bytes of object data]

Ejemplo de respuesta

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB30443962F9A
ETag: "A797938C31D59EDD08D86188F6D5B872"

Habilitar el control de versiones

Ejemplo de solicitud

PUT /test HTTP/1.1
Content-Length: 362149
Content-Type: text/html
Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:53:24 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 02:53:24 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5CAC0A3DB7AEADE01700****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
ETag: "4F345B1F066DB1444775AA97D5D2****"

Códigos de error

Código de error	Código de estado HTTP	Descripción
MissingContentLength	411	El encabezado de la solicitud no utiliza codificación por fragmentos o no se ha establecido el parámetro Content-Length.
InvalidEncryptionAlgorithmError	400	El valor especificado para x-oss-server-side-encryption no es válido. Valores válidos: AES256, KMS, .
AccessDenied	403	El usuario no cuenta con los permisos de acceso obligatorios para el bucket especificado al agregar el objeto.
NoSuchBucket	404	El bucket especificado no existe al momento de agregar el objeto.
InvalidObjectName	400	El nombre del objeto no es válido. Esto puede deberse a que no se especificó el nombre, excede el límite de longitud o contiene caracteres inválidos.
InvalidArgument	400	Este error puede devolverse por las siguientes razones: El tamaño del objeto que se va a agregar supera los 5 GB. El valor de un parámetro como x-oss-storage-class no es válido.
RequestTimeout	400	Se especificó Content-Length, pero no se envió ningún cuerpo de mensaje, o bien el cuerpo enviado es menor que el tamaño indicado. En este caso, el servidor espera hasta que la solicitud agote su tiempo de espera.
Bad Request	400	Si especifica Content-MD5 en la solicitud, OSS calcula el hash MD5 de los datos enviados y lo compara con el valor de Content-MD5 de la solicitud. Si ambos valores no coinciden, se devuelve este error.
KmsServiceNotEnabled	403	Especificó KMS para x-oss-server-side-encryption, pero no ha adquirido previamente un paquete de KMS.
FileAlreadyExists	409	Posibles causas: El encabezado de la solicitud incluye `x-oss-forbid-overwrite=true` para evitar la sobreescritura de un archivo con el mismo nombre, pero ya existe un archivo con ese nombre en el bucket. La función de espacio de nombres jerárquico está habilitada para el bucket y ya existe un directorio con el mismo nombre en el nivel actual.
FileImmutable	409	Este error se devuelve si intenta eliminar o modificar datos en un bucket que se encuentra en estado protegido.

Métodos de integración

SDK

Los SDK correspondientes a la API PutObject en distintos lenguajes son los siguientes:

Java

Python V2

Go V2

C++

PHP V2

C

.NET

Android

iOS

Node.js

Browser.js

Ruby

Harmony
Interfaz de línea de comandos ossutil

Para consultar el comando de ossutil correspondiente a la API PutObject, consulte put-object.

Preguntas frecuentes

¿Cómo modifico los metadatos de un archivo cargado?

Puede modificar los metadatos del archivo mediante la consola de OSS, ossbrowser, los SDK en diversos lenguajes, la interfaz de línea de comandos ossutil o la API REST. Por ejemplo, puede cambiar el Content-Type de application/octet-stream a image/jpeg. Para obtener más información, consulte Manage object metadata.

¿Por qué no funciona el encabezado Expires que configuré?

Prioridad de los encabezados de caché

Si configura tanto Expires como Cache-Control, Cache-Control tiene mayor prioridad. Si Cache-Control incluye una directiva de almacenamiento en caché, como max-age=3600, es posible que se ignore el encabezado Expires.

Expires Configuración incorrecta

El valor del encabezado Expires debe ser una fecha futura en formato GMT. El siguiente código muestra un ejemplo de cómo configurar este encabezado con el SDK de Node.js:

const OSS = require('ali-oss');

// Create an OSS client instance.
const client = new OSS({
  // Replace yourregion with the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the bucket name.
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Expires header set successfully.');
  } catch (error) {
    console.error('Error setting Expires header:', error);
  }
}

// Set the absolute expiration time for the cached content.
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);

Java	Python V2	Go V2	C++	PHP V2
C	.NET	Android	iOS	Node.js
Browser.js	Ruby	Harmony