Todos los productos
Search

Este producto

    Object Storage Service:AppendObject

    Centro de documentos

    Object Storage Service:AppendObject

    Última actualización: Sep 03, 2026

    Carga un objeto mediante la anexión de datos. Los objetos creados con AppendObject son de tipo Appendable, mientras que los objetos cargados con PutObject son de tipo Normal.

    Control de versiones

    Cuando el control de versiones está habilitado o suspendido para un bucket, tenga en cuenta el siguiente comportamiento para los objetos Appendable:

    • Solo puede anexar datos a la versión actual de un objeto Appendable. OSS no crea versiones anteriores para este objeto.

      Una operación PutObject o DeleteObject sobre la versión actual guarda el objeto Appendable como una versión anterior. El objeto ya no admite nuevas anexiones.

    • No se puede ejecutar AppendObject en objetos que no sean de tipo Appendable, como objetos Normal o marcadores de eliminación.

    • Solo se puede crear una nueva versión Appendable cuando el objeto no existe o la versión más reciente es un marcador de eliminación. Establezca position en 0.

    Límites

    • El tamaño máximo de un objeto Appendable es de 5 GB.

    • No se puede utilizar la operación AppendObject en objetos protegidos por un retention policy.

    • Los objetos Appendable no admiten el cifrado del lado del servidor con un CMK ID a través de KMS.

    • El rendimiento de descarga de los objetos Appendable es significativamente menor que el de los objetos Normal o Multipart. Evalúe si esto cumple con sus requisitos.

    Permisos

    De forma predeterminada, una cuenta de Alibaba Cloud tiene permisos completos. Los usuarios RAM o roles RAM bajo una cuenta de Alibaba Cloud no tienen ningún permiso de forma predeterminada. La cuenta de Alibaba Cloud o el administrador de la cuenta deben otorgar permisos de operación a través de RAM policies o Bucket Policy.

    API

    Action

    Descripción

    AppendObject

    oss:PutObject

    Puede llamar a esta operación para cargar un objeto anexándolo a un objeto existente.

    oss:PutObjectTagging

    Al cargar un objeto anexándolo a uno existente, si especifica etiquetas de objeto mediante x-oss-tagging, se requiere este permiso.

    Sintaxis de la solicitud

    POST /ObjectName?append&position=Position HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    Encabezados de solicitud

    Nombre

    Tipo

    Obligatorio

    Ejemplo

    Descripción

    Cache-control

    string

    No

    no-cache

    El comportamiento de caché de la página web para el objeto. Definido en RFC2616.

    Predeterminado: none

    Content-Disposition

    string

    No

    attachment;filename=oss_download.jpg

    El nombre del objeto al descargarse. Definido en RFC2616.

    Predeterminado: none

    Content-MD5

    string

    No

    ohhnqLBJFiKkPSBO1eNaUA==

    Un hash MD5 codificado en Base64 que se utiliza para verificar la integridad del cuerpo del mensaje.

    Calcule el hash MD5 del cuerpo del mensaje (excluyendo encabezados) para producir un valor de 128 bits y luego codifíquelo en Base64.

    Predeterminado: none

    Restricciones: ninguna

    Expires

    string

    No

    Wed, 08 Jul 2015 16:57:01 GMT

    La fecha de caducidad. Definida en RFC2616.

    Predeterminado: none

    x-oss-server-side-encryption

    string

    No

    AES256

    El método de cifrado del lado del servidor.

    Valores válidos:

    • AES256: utiliza claves totalmente administradas por OSS para el cifrado y descifrado (SSE-OSS).

    • KMS: utiliza claves administradas por KMS para el cifrado y descifrado.

    x-oss-object-acl

    string

    No

    private

    La ACL del objeto.

    Valores válidos:

    • default (predeterminado): El objeto hereda la ACL del bucket.

    • private: Solo el propietario y los usuarios autorizados tienen permisos de lectura y escritura sobre el objeto. Otros usuarios no pueden acceder al objeto.

    • public-read: Solo el propietario y los usuarios autorizados pueden leer y escribir el objeto. Otros usuarios tienen acceso de solo lectura. Utilícelo con precaución.

    • public-read-write: Todos los usuarios tienen acceso de lectura y escritura. Utilícelo con precaución.

    Los permisos de acceso se describen en Object ACL.

    x-oss-storage-class

    string

    No

    Standard

    La clase de almacenamiento del objeto.

    Cuando se especifica, el objeto se almacena en esta clase independientemente de la clase de almacenamiento del bucket. Por ejemplo, establecer x-oss-storage-class en Standard dentro de un bucket IA almacena el objeto como Standard.

    Valores válidos:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    Los detalles están disponibles en Storage classes.

    Importante

    • Este encabezado de solicitud solo surte efecto en la primera operación de anexión. No surte efecto en operaciones de anexión posteriores.

    • Los objetos de tipo Appendable no se pueden convertir a la clase de almacenamiento Cold Archive o Deep Cold Archive de ninguna manera.

    x-oss-meta-*

    string

    No

    x-oss-meta-location

    Encabezados de metadatos personalizados. Se aplica solo a la primera operación de anexión. Los parámetros con prefijo x-oss-meta-* se almacenan como metadatos del objeto.

    Límite de tamaño: El total de metadatos no puede superar los 8 KB.

    Reglas de nomenclatura: Solo se permiten guiones (-), dígitos y letras minúsculas (a-z). Las letras mayúsculas se convierten a minúsculas. No se admiten guiones bajos (_).

    x-oss-tagging

    string

    No

    TagA=A

    Etiquetas de objeto en formato clave-valor. Varias etiquetas se separan con signos et (&), como TagA=A&TagB=B.

    Importante

    • Este encabezado de solicitud solo surte efecto en la primera operación de anexión. No surte efecto en operaciones de anexión posteriores.

    • La clave y el valor deben estar codificados en URL. La clave es obligatoria, pero el valor es opcional. Por ejemplo, puede establecer las etiquetas del objeto en TagA&TagB=B.

    Esta operación también admite Common request headers.

    Parámetros de solicitud

    Importante

    Los parámetros append y position forman parte de la CanonicalizedResource y deben incluirse en la firma.

    Nombre

    Tipo

    Obligatorio

    Ejemplo

    Descripción

    append

    string

    Sí

    No aplicable

    Indica una operación AppendObject. Cada llamada actualiza la última hora de modificación del objeto.

    position

    string

    Sí

    0

    El desplazamiento en bytes desde donde comenzar la anexión. Después de cada operación exitosa, x-oss-next-append-position indica la siguiente posición.

    La primera anexión debe establecer position en 0. Las anexiones posteriores deben establecer position en el tamaño actual del objeto. Por ejemplo, si la primera anexión tiene content-length 65536, la segunda debe establecer position en 65536.

    • Cuando position es 0 y no existe ningún objeto con el mismo nombre, la solicitud se comporta como PutObject. Puede establecer encabezados como x-oss-server-side-encryption, que luego se incluye en las respuestas subsiguientes de AppendObject. Para modificar metadatos posteriormente, utilice CopyObject.

    • Anexar contenido de longitud cero en la posición correcta no cambia el estado del objeto.

    Encabezados de respuesta

    Encabezado de respuesta

    Tipo

    Ejemplo

    Descripción

    x-oss-next-append-position

    Entero de 64 bits

    1717

    La posición para la siguiente anexión, igual al tamaño actual del objeto.

    Se devuelve en caso de éxito o cuando ocurre un error 409 debido a una discrepancia de posición.

    x-oss-hash-crc64ecma

    Entero de 64 bits

    3231342946509354535

    El valor CRC de 64 bits del objeto, calculado según el estándar CRC-64/XZ.

    Esta operación también admite Common response headers.

    Cálculo de CRC-64

    Métodos de cálculo compatibles:

    • Cálculo mediante el módulo Boost CRC

      typedef boost::crc_optimal<64, 0x42F0E1EBA9EA3693ULL, 0xffffffffffffffffULL, 0xffffffffffffffffULL, true, true> boost_ecma;
uint64_t do_boost_crc(const char* buffer, int length)
{
    boost_ecma crc;
    crc.process_bytes(buffer, length);
    return crc.checksum();
}

    • Cálculo mediante Python crcmod

      import crcmod
do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693, initCrc=0, xorOut=0xffffffffffffffff, rev=True)
print(do_crc64(b"123456789"))

    Operaciones relacionadas

    Otra operación

    Descripción de la relación

    PutObject

    PutObject sobre un objeto Appendable existente lo sobrescribe y cambia su tipo a Normal.

    HeadObject

    HeadObject sobre un objeto Appendable devuelve x-oss-next-append-position, x-oss-hash-crc64ecma y x-oss-object-type (establecido en Appendable).

    GetBucket (ListObjects)

    GetBucket lista objetos Appendable con Type establecido en Appendable.

    Ejemplos

    • Ejemplo de solicitud

      POST /oss.jpg?append&position=0 HTTP/1.1 
Host: oss-example.oss.aliyuncs.com 
Cache-control: no-cache 
Expires: Wed, 08 Jul 2015 16:57:01 GMT 
x-oss-storage-class: Archive
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Wed, 08 Jul 2015 06:57:01 GMT 
Content-Type: image/jpg 
Content-Length: 1717 
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e  
[1717 bytes of object data]

      Ejemplo de respuesta

      HTTP/1.1 200 OK
Date: Wed, 08 Jul 2015 06:57:01 GMT
ETag: "0F7230CAA4BE94CCBDC99C550000****"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-hash-crc64ecma: 14741617095266562575
x-oss-next-append-position: 1717
x-oss-request-id: 559CC9BDC755F95A6448****

    • Ejemplo de solicitud con control de versiones

      Cuando el control de versiones está habilitado, la respuesta de AppendObject incluye x-oss-version-id, que especifica el ID de versión del objeto actual.

      POST /example?append&position=0 HTTP/1.1 
Host: versioning-append.oss.aliyuncs.com 
Date: Tue, 09 Apr 2019 03:59:33 GMT
Content-Length: 3
Content-Type: application/octet-stream
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
Date: Tue, 09 Apr 2019 03:59:33 GMT
ETag: "2776271A4A09D82CA518AC5C0000****"
Connection: keep-alive
Content-Length: 0  
Server: AliyunOSS
x-oss-version-id: CAEQGhiBgIC_k6aV5RgiIGI3YTY2ZmMzYWJlMzQ3YjM4YTljOTk5YjUyZGF****
x-oss-hash-crc64ecma: 3231342946509354535
x-oss-next-append-position: 47
x-oss-request-id: 5CAC18A5B7AEADE01700****

    SDKs

    SDKs para esta operación:

    Interfaz de línea de comandos ossutil

    Utilice el comando append-object en ossutil.

    Códigos de error

    Código de error

    Código de estado HTTP

    Descripción

    ObjectNotAppendable

    409

    Se llamó a AppendObject sobre un objeto que no es de tipo Appendable.

    PositionNotEqualToLength

    409

    • El valor de position no coincide con la longitud actual del objeto.

      Utilice el encabezado de respuesta x-oss-next-append-position para reintentar. Las solicitudes concurrentes aún podrían fallar con este error.

    • Cuando position es 0, la solicitud solo tiene éxito si no existe ningún objeto Appendable con el mismo nombre o si el existente tiene longitud 0. De lo contrario, se devuelve este error.

    InvalidArgument

    400

    Los valores de parámetros como x-oss-storage-class y x-oss-object-acl no son válidos.

    FileImmutable

    409

    El bucket se encuentra en estado protegido y no permite la eliminación ni la modificación.

    KmsServiceNotEnabled

    403

    Se especificó el cifrado KMS, pero Key Management Service (KMS) no está habilitado en la consola.