Todos los productos
Search

Este producto

    Object Storage Service:PostObject

    Centro de documentos

    Object Storage Service:PostObject

    Última actualización: Sep 03, 2026

    Invoque la operación PostObject para cargar un objeto en un bucket mediante un formulario HTML.

    Notas de uso

    • La carga mediante formulario HTML requiere el permiso oss:PutObject. Attach a custom policy to a RAM user.

    • Los objetos cargados con PostObject no pueden superar los 5 GB.

    • Una solicitud PostObject requiere permisos de escritura en el bucket. Si la ACL del bucket es public-read-write, no se necesita información de firma. De lo contrario, OSS autentica la firma en la solicitud.

    • A diferencia de PutObject, PostObject utiliza un AccessKey secret para firmar la política. La cadena de firma resultante es el valor del campo de formulario Signature, que OSS autentica.

    • La URL del formulario es el nombre de dominio del bucket sin el nombre del objeto. La línea de solicitud es POST / HTTP/1.1, no POST /ObjectName HTTP/1.1.

    • Si una solicitud POST contiene información de firma en el encabezado o en la URL, OSS no verifica dicha información.

    Control de versiones

    Si el control de versiones está habilitado en el bucket, OSS genera un ID de versión único para el objeto cargado y lo devuelve en el encabezado de respuesta x-oss-version-id.

    Si el control de versiones está suspendido, OSS genera un ID de versión nulo para el objeto cargado y lo devuelve en el encabezado de respuesta x-oss-version-id. Solo se permite un ID de versión nulo por objeto.

    Sintaxis de la solicitud

    POST / HTTP/1.1 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length: ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    Encabezados de la solicitud

    Importante

    • El cuerpo de la solicitud PostObject utiliza codificación multipart/form-data. A diferencia de PutObject, que pasa parámetros en encabezados HTTP, PostObject los pasa como campos de formulario en el cuerpo.

    • PostObject no admite el encabezado x-oss-tagging. Una vez completada la operación PostObject, invoque PutObjectTagging para etiquetar el objeto.

    Nombre

    Tipo

    Obligatorio

    Descripción

    Content-Type

    String

    No

    Tipo de archivo y codificación de la página web, lo cual determina cómo leen los navegadores el archivo.

    El formulario enviado en una operación Post debe estar codificado en formato multipart/form-data. Esto significa que el encabezado Content-Type tiene el formato multipart/form-data;boundary=xxxxxx.

    El límite (boundary) es una cadena aleatoria generada por el formulario. No necesita especificarlo. Los SDK generan este valor automáticamente.

    Esta operación también utiliza Common request headers, como Host y Date.

    Elementos del formulario

    A continuación se describen los elementos del formulario comunes a las firmas V1 y V4. Para obtener información sobre los elementos exclusivos de las firmas V4, consulte V4 signature form. Para obtener información sobre los elementos exclusivos de las firmas V1, consulte V1 signature form.

    Importante

    • El campo file debe ser el último campo del formulario. Los demás campos pueden ir en cualquier orden.

    • La clave de un campo de formulario no puede superar los 8 KB de tamaño, y el valor no puede superar los 2 MB.

    Nombre

    Tipo

    Obligatorio

    Descripción

    Cache-Control

    String

    No

    Comportamiento de caché al descargar el objeto, según se define en RFC 2616.

    Valor predeterminado: none.

    Content-Disposition

    String

    No

    Nombre de descarga del objeto, según se define en RFC 2616.

    Valor predeterminado: none.

    Content-Encoding

    String

    No

    Codificación de contenido del objeto al descargarse, según se define en RFC 2616.

    Valor predeterminado: none.

    Expires

    String

    No

    Tiempo de expiración de la caché, según se define en RFC 2616.

    Valor predeterminado: none.

    policy

    String

    Sí, condicional

    Especifica la validez de los campos del formulario de solicitud. Una solicitud sin el campo policy se trata como anónima y solo puede acceder a buckets public-read-write.

    Valor predeterminado: none.

    Restricción: Obligatorio si el bucket no es public-read-write, o si se proporciona OSSAccessKeyId o Signature.

    Importante

    El formulario y la política deben tener codificación UTF-8. El campo de formulario policy también debe estar codificado en Base64.

    x-oss-server-side-encryption-key-id

    String

    No

    Clave maestra del cliente (CMK) administrada por KMS. Válido únicamente cuando x-oss-server-side-encryption se establece en KMS.

    x-oss-content-type

    String

    No

    Reemplaza el Content-Type que los navegadores agregan automáticamente al campo de formulario file. Este elemento tiene la mayor prioridad para especificar Content-Type.

    Orden de prioridad: x-oss-content-type > Content-Type del campo de formulario file

    Valor predeterminado: none.

    x-oss-forbid-overwrite

    String

    No

    Especifica si se debe sobrescribir un objeto con el mismo nombre durante una operación PostObject.

    Cuando el control de versiones está habilitado o suspendido, x-oss-forbid-overwrite se ignora y los objetos con el mismo nombre pueden sobrescribirse.

    • Si x-oss-forbid-overwrite no se especifica o se establece en false, los objetos con el mismo nombre pueden sobrescribirse.

    • Si x-oss-forbid-overwrite se establece en true, los objetos con el mismo nombre no pueden sobrescribirse.

    El encabezado x-oss-forbid-overwrite reduce las QPS. Si su uso de x-oss-forbid-overwrite supera las 1,000 QPS, póngase en contacto con el soporte técnico.

    x-oss-object-acl

    String

    No

    Permisos de acceso para el objeto cargado.

    Valores válidos:

    • default (predeterminado): Hereda la ACL del bucket.

    • private: Solo el propietario y los usuarios autorizados pueden leer y escribir el objeto.

    • public-read: Todos los usuarios pueden leer el objeto. Solo el propietario y los usuarios autorizados pueden escribirlo. Úselo con precaución.

    • public-read-write: Todos los usuarios pueden leer y escribir el objeto. Úselo con precaución.

    Los permisos de acceso se describen en Object ACL.

    x-oss-storage-class

    String

    No

    Especifica la clase de almacenamiento del objeto.

    Independientemente de la clase de almacenamiento del bucket, el objeto cargado utiliza la clase que usted especifique. Por ejemplo, si establece x-oss-storage-class como Standard para un bucket IA, el objeto se almacena como Standard.

    Valores válidos:

    • Standard: Estándar

    • IA: Acceso poco frecuente

    • Archive: Almacenamiento de archivos

    • ColdArchive: Archivo frío

    • DeepColdArchive: Archivo frío profundo

      Importante

      Si desea cargar una gran cantidad de objetos, especificar directamente la clase de almacenamiento Deep Cold Archive para los objetos a cargar genera altas PUT request fees. 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.

    Storage classes.

    key

    String

    Sí

    Nombre del objeto a cargar. No codifique el nombre. Si el nombre incluye una ruta, como destfolder/example.jpg, OSS crea automáticamente la carpeta correspondiente.

    Valor predeterminado: none.

    success_action_redirect

    String

    No

    URL a la que se redirige al cliente tras una carga exitosa. Si no se especifica, el comportamiento de la respuesta lo determina success_action_status. En caso de error, OSS devuelve un error sin redirigir.

    Valor predeterminado: none.

    success_action_status

    String

    No

    Código de estado HTTP devuelto tras una carga exitosa cuando no se especifica success_action_redirect.

    Valores válidos: 200, 201 y 204 (predeterminado).

    • Si este campo se establece en 200 o 204, OSS devuelve un documento vacío y el código de estado correspondiente.

    • Si este campo se establece en 201, OSS devuelve un archivo XML y el código de estado 201.

    • Si este campo no se establece o se configura con un valor no válido, OSS devuelve un documento vacío y el código de estado 204.

    x-oss-meta-*

    String

    No

    Metadatos definidos por el usuario.

    Valor predeterminado: none.

    Los campos de formulario con prefijo x-oss-meta- se almacenan como metadatos de usuario. Ejemplo: x-oss-meta-location.

    Nota

    Un objeto puede tener varios de estos parámetros, pero el tamaño total de todos los metadatos de usuario no puede superar los 8 KB.

    x-oss-security-token

    String

    No

    Token de seguridad STS. Obligatorio solo al usar STS para construir una URL firmada. Obtenga un token invocando la operación AssumeRole.

    Valor predeterminado: none.

    file

    String

    Sí

    Contenido de archivo o texto. No codifique el contenido. El navegador establece Content-Type según el tipo de archivo, sobrescribiendo su configuración. Solo se puede cargar un archivo por solicitud.

    Valor predeterminado: none.

    Importante

    El campo file debe ser el último campo del formulario.

    Encabezados de respuesta

    Nombre

    Tipo

    Ejemplo

    Descripción

    x-oss-server-side-encryption

    String

    KMS

    Se devuelve si se especifica x-oss-server-side-encryption en la solicitud. Indica el algoritmo de cifrado utilizado.

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    Hash MD5 del archivo.

    Importante

    Este es el hash MD5 del archivo cargado, no el hash MD5 del cuerpo de la respuesta.

    x-oss-hash-crc64ecma

    String

    316181249502703****

    Valor CRC-64 del archivo.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    ID de versión del objeto cargado. Se devuelve únicamente para buckets con control de versiones habilitado.

    Esta operación también devuelve Common response headers, como Date y x-oss-request-id.

    Elementos de respuesta

    Nombre

    Tipo

    Descripción

    PostResponse

    Contenedor

    Contenedor que almacena el resultado de la solicitud Post.

    Nodos secundarios: Bucket, ETag, Key y Location

    Bucket

    String

    Nombre del bucket.

    Nodo principal: PostResponse

    ETag

    String

    ETag del objeto cargado. Para cargas con PostObject, el ETag es un identificador único, pero no es el hash MD5 del contenido. Úselo para comprobar si el contenido ha cambiado.

    Nodo principal: PostResponse

    Location

    String

    URL del objeto recién creado.

    Nodo principal: PostResponse

    Ejemplos

    • Ejemplo de solicitud:

      POST / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 344606
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
/user/a/objectName.txt
--9431149156168
Content-Disposition: form-data; name="success_action_status"
200
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
content_disposition
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
44CF9590006BF252****
--9431149156168
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
--9431149156168
Content-Disposition: form-data; name="Signature"
kZoYNv66bsmc10+dcGKw5x2P****
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
Content-Type: text/plain
abcdefg
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    • Ejemplo de respuesta:

      HTTP/1.1 200 OK
x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e 
Date: Fri, 24 Feb 2014 06:03:28 GMT
ETag: "5B3C1A2E053D763E1B002CC607C5****"
Connection: keep-alive
Content-Length: 0
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
Server: AliyunOSS

    SDK

    SDK compatibles:

    Códigos de error

    Código de error

    Código de estado HTTP

    Descripción

    FieldItemTooLong

    400

    El tamaño de la clave del campo de formulario no puede superar los 8 KB, y el tamaño del valor del campo no puede superar los 2 MB.

    InvalidArgument

    400

    Independientemente de la ACL del bucket, si se proporciona OSSAccessKeyId, policy o Signature, los tres son obligatorios. La ausencia de cualquiera de ellos devuelve este error.

    InvalidDigest

    400

    El Content-MD5 en la solicitud no coincide con el hash MD5 calculado por OSS para el cuerpo de la solicitud.

    EntityTooLarge

    400

    El cuerpo de la solicitud supera el límite de tamaño de 5 GB.

    InvalidEncryptionAlgorithmError

    400

    El valor de x-oss-server-side-encryption no es AES256 or KMS.

    IncorrectNumberOfFilesInPOSTRequest

    400

    Una solicitud PostObject solo puede contener un campo de formulario file.

    FileAlreadyExists

    409

    Existe un objeto con el mismo nombre y x-oss-forbid-overwrite está establecido en true.

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption está establecido en KMS, pero no ha adquirido previamente un paquete de KMS.

    FileImmutable

    409

    El bucket está protegido y los datos no pueden eliminarse ni modificarse.

    MethodNotAllowed

    405

    El método de solicitud HTTP no es compatible. Compruebe que el método de solicitud, los encabezados, el protocolo de URL, el nombre de dominio y la ruta sean correctos.

    Política POST

    El campo de formulario policy es una política de seguridad en formato JSON que especifica restricciones para las cargas mediante formularios HTML, incluido el nombre del bucket, el prefijo del objeto, el periodo de validez, los métodos HTTP permitidos, los límites de tamaño de carga y los tipos de contenido.

    Firma POST

    Cada solicitud PostObject debe incluir una firma para la autenticación.

    Preguntas frecuentes

    ¿Qué debo hacer si se devuelve el error "Your proposed upload exceeds the maximum allowed size"?

    • Causa: El tamaño del archivo cargado está fuera del rango especificado por content-length-range.

    • Solución: Utilice content-length-range para especificar los tamaños mínimo y máximo permitidos para el archivo cargado, en bytes. Por ejemplo, para cargar un archivo de 1 GB, puede establecer content-length-range como ["content-length-range", 1, 1073741824].

    Referencias