Adición de un objeto
Funciones
La operación AppendObject agrega datos al final de un objeto en un bucket especificado. Si no hay ningún objeto con nombre en el bucket, se crea un nuevo objeto.
El objeto creado mediante la operación AppendObject es un objeto anexable y el objeto cargado mediante la operación de PUT es un objeto normal.
Los objetos cargados deben almacenarse en bucket. Solo los usuarios que tienen el permiso de escritura para un bucket pueden subir objetos al bucket. El nombre de cada objeto del mismo bucket debe ser único.
Para asegurarse de que los datos no se dañen durante la transmisión, puede agregar el parámetro Content-MD5 al encabezado de solicitud. Después de recibir los datos, OBS realiza la verificación MD5 para los datos. Si los datos son incoherentes, OBS devuelve un mensaje de error.
Esta operación le permite especificar el parámetro x-obs-acl al crear un objeto anexable y establecer la política de control de permisos para el objeto.
Esta operación admite la encriptación del lado del servidor.
Relación con otras operaciones
- Si realiza la operación PUT en un objeto anexable existente, el objeto anexable se sobrescribe por el objeto recién cargado y el tipo de objeto cambia a normal. Si se realiza al revés, se produce un error.
- Un objeto anexable se cambiará a un objeto normal después de ser copiado. Un objeto anexable no se puede copiar y guardar como un objeto anexable.
WORM
Si un bucket tiene WORM habilitado, una operación de adición en este bucket fallará, con un error 403.
Restricciones
- El último tiempo de modificación del objeto se actualiza cada vez que se realiza una carga anexada.
- Si se utiliza el modo de encriptación SSE-C en el lado del servidor, la carga anexada es la misma que el segmento de inicialización. En este caso, los encabezados de solicitud tales como x-obs-server-side-encryption deben ser transportados.
- Para la encriptación del lado del servidor (SSE-KMS), el encabezado de solicitud como x-obs-server-side-encryption se especifica solo cuando el archivo se carga por primera vez y no existe ningún objeto con el mismo nombre en el bucket.
- La longitud de cada carga anexada no puede exceder el límite superior (5 GB) de la longitud del objeto.
- El número máximo de escrituras solo anexadas para cada objeto anexable es de 10,000.
- Si la clase de almacenamiento de objetos es COLD (almacenamiento de Archive), no se puede invocar a esta API.
- Si se configura la replicación entre regiones para un bucket, no se puede usar esta operación de API.
- La adición de objetos no está disponible para sistemas de archivos paralelos.
Sintaxis de solicitud
POST /ObjectName?append&position=Position HTTP/1.1 Host: bucketname.obs.region.myhuaweicloud.com Content-Type: application/xml Content-Length: length Authorization: authorization Date: date <Optional Additional Header> <object Content>
Parámetros de solicitud
La solicitud debe especificar parámetros en el mensaje, indicando que la solicitud es para anexar la carga y que debe especificarse la ubicación de carga. Para obtener más información acerca de los parámetros, consulte Tabla 1.
Parámetro |
Descripción |
Obligatorio |
---|---|---|
append |
Indica que el archivo se carga en modo de adición. Tipo: string |
Sí |
position |
Ubicación de la carga anexada Para agregar un objeto, el valor de position debe establecerse en 0 cuando el objeto se carga por primera vez. El valor de position se incluirá en el encabezado x-obs-next-append-position de la respuesta devuelta por el servidor cuando el objeto se cargue correctamente la próxima vez. Tipo: integer |
Sí |
Encabezados de solicitud
Esta solicitud utiliza encabezados comunes. Para obtener más información, véase Tabla 3.
Tabla 2 describe los encabezados de mensaje adicionales que una solicitud puede utilizar cuando se solicita el parámetro position=0.
Esta solicitud puede utilizar el encabezado de solicitud de encriptación del lado del servidor. Para obtener más información, consulte Tabla 3.
Encabezado |
Descripción |
Obligatorio |
---|---|---|
x-obs-acl |
Para la primera adición, el encabezado del mensaje se puede agregar para establecer la política de control de permisos del objeto. Se utilizan las políticas comunes predefinidas, entre ellas: private, public-read, public-read-write. Para obtener más información sobre cada política, consulte la configuración de ACL mediante campos de encabezado en ACLs. Tipo: string Nota: Este encabezado es una política predefinida expresada en una string de caracteres. |
No |
x-obs-grant-read |
Para la primera escritura, puede utilizar este encabezado para conceder a todos los usuarios de una cuenta los permisos para leer el objeto y obtener los metadatos del objeto. Tipo: string |
No |
x-obs-grant-read-acp |
Para la primera escritura, puede utilizar este encabezado para conceder a todos los usuarios de una cuenta el permiso para obtener información de ACL de objeto. Tipo: string |
No |
x-obs-grant-write-acp |
Para la primera escritura, puede utilizar este encabezado para conceder a todos los usuarios de una cuenta el permiso para escribir la ACL del objeto. Tipo: string |
No |
x-obs-grant-full-control |
Para la primera escritura, puede utilizar este encabezado para conceder a todos los usuarios de una cuenta los permisos para leer el objeto, obtener los metadatos del objeto, obtener la información de ACL del objeto y escribir la ACL del objeto. Tipo: string |
No |
x-obs-storage-class |
Para la primera escritura, puede usar este campo de encabezado para configurar la clase de almacenamiento de objetos. Si no utiliza este encabezado, la clase de almacenamiento de objetos es la clase de almacenamiento predeterminada del bucket. Tipo: string Debido a que los objetos de Archive (COLD) no admiten la carga de anexos, los valores configurables son los siguientes: STANDARD (Standard), WARM (Infrequent Access), que distinguen entre mayúsculas y minúsculas. Ejemplo: x-obs-storage-class:STANDARD |
No |
x-obs-meta-* |
Para la primera escritura, puede usar un encabezado que comience con x-obs-meta- para definir metadatos de objeto en una solicitud HTTP. Los metadatos personalizados se devolverán en el encabezado de respuesta cuando recupere o consulte los metadatos del objeto. El tamaño de la solicitud de HTTP sin el cuerpo de la solicitud debe ser igual o menor que 8 KB. Tipo: string Ejemplo: x-obs-meta-test:test metadata |
No |
x-obs-persistent-headers |
Para la primera adición, puede agregar el encabezado x-obs-persistent-headers en una solicitud de HTTP para especificar uno o más encabezados de respuesta definidos por el usuario. Los encabezados de respuesta definidos por el usuario se devolverán en el encabezado de respuesta cuando recupere el objeto o consulte los metadatos del objeto. Tipo: string Formato: x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2)... Nota: Los elementos, como key1 y key2, son encabezados definidos por el usuario. Si contienen caracteres no ASCII o irreconocibles, se pueden codificar mediante URL o Base64. El servidor procesa estos encabezados como cadenas de caracteres, pero no los decodifica. Los elementos, tales como value1 y value2, son los valores de las cabeceras correspondientes. base64_encode indica que el valor se codifica usando Base64. Un encabezado definido por el usuario y su valor codificado en Base64 se conectan usando dos puntos (:) para formar un par clave-valor. Todos los pares clave-valor se separan con una coma (,) y se colocan en el encabezado x-obs-persistent-headers. A continuación, el servidor decodifica el valor cargado. Ejemplo: x-obs-persistent-headers: key1:dmFsdWUx,key2:dmFsdWUy El encabezado devuelto para descargar el objeto u obtener los metadatos del objeto es key1:value1 o key2:value2 respectivamente. Restricciones:
|
No |
x-obs-website-redirect-location |
Si un bucket está configurado con la función de alojamiento de sitios web estático, redirigirá las solicitudes para este objeto a otro objeto en el mismo bucket o a una URL externa. OBS almacena el valor de este encabezado en los metadatos del objeto. Tipo: string Valor predeterminado: ninguno Restricción: el valor debe tener el prefijo de una barra diagonal (/), http://, o https://. La longitud del valor no puede superar los 2 KB. |
No |
x-obs-expires |
Especifica cuándo caduca un objeto. Se mide en días. Una vez que el objeto caduca, se elimina automáticamente. (El cálculo comienza a partir de la última modificación del objeto). Tipo: integer Ejemplo: x-obs-expires:3 |
No |
Encabezado |
Descripción |
Obligatorio |
---|---|---|
x-obs-server-side-encryption |
Indica que se utiliza SSE-KMS. Tipo: string Ejemplo: x-obs-server-side-encryption:kms |
No. Este encabezado es necesario cuando se utiliza SSE-KMS. |
x-obs-server-side-encryption-kms-key-id |
Indica la clave principal cuando se utiliza SSE-KMS. Si no se proporciona este encabezado, se utilizará la clave principal predeterminada. Si no existe una clave principal por defecto, OBS creará una y la usará por defecto. Tipo: string Se admiten los dos formatos siguientes: - regionID:domainID:key/key_id - key_id regionID indica el ID de la región a la que pertenece la clave. domainID indica el ID del tenant al que pertenece la clave. key_id indica el ID de la clave creada en DEW. Ejemplos: - x-obs-server-side-encryption-kms-key-id:region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 - x-obs-server-side-encryption-kms-key-id:4f1cd4de-ab64-4807-920a-47fc42e7f0d0 |
No |
x-obs-server-side-encryption-customer-algorithm |
Indica el algoritmo de encriptación cuando se utiliza SSE-C. Tipo: string Ejemplo: x-obs-server-side-encryption-customer-algorithm:AES256 Restricción: Este encabezado debe usarse junto con x-obs-server-side-encryption-customer-key y x-obs-server-side-encryption-customer-key-MD5. |
No. Este encabezado se requiere cuando se utiliza SSE-C. |
x-obs-server-side-encryption-customer-key |
Indica la clave para cifrar objetos cuando se utiliza SSE-C. Tipo: string Ejemplo: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= Restricciones: Este encabezado es una clave de 256 bits codificada en Base64 y debe usarse junto con x-obs-server-side-encryption-customer-algorithm y x-obs-server-side-encryption-customer-key-MD5. |
No. Este encabezado se requiere cuando se utiliza SSE-C. |
x-obs-server-side-encryption-customer-key-MD5 |
Indica el valor MD5 de la clave de encriptación cuando se utiliza SSE-C. El valor MD5 se utiliza para comprobar si se produce algún error durante la transmisión de la clave. Tipo: string Ejemplo: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restricción: Este encabezado es un valor MD5 de 128 bits codificado en Base64 y debe usarse junto con x-obs-server-side-encryption-customer-algorithm y x-obs-server-side-encryption-customer-key. |
No. Este encabezado se requiere cuando se utiliza SSE-C. |
Elementos de solicitud
Esta solicitud no implica ningún elemento.
Sintaxis de respuesta
1 2 3 4 |
HTTP/1.1 status_code Date: date ETag: etag Content-Length: length |
Encabezados de respuesta
La respuesta a la solicitud utiliza encabezados comunes. Para más detalles, consulte Tabla 1.
La ETag devuelve el valor hash de los datos que se van a cargar, no el valor hash de todo el objeto.
Encabezado |
Descripción |
---|---|
x-obs-version-id |
ID de versión del objeto. Si el control de versiones está habilitado para el bucket, se devolverá el ID de versión del objeto. Tipo: string |
x-obs-server-side-encryption |
Este encabezado se incluye en una respuesta si se utiliza SSE-KMS. Tipo: string Ejemplo: x-obs-server-side-encryption:kms |
x-obs-server-side-encryption-kms-key-id |
Indica el ID de clave principal. Este encabezado se incluye en una respuesta si se utiliza SSE-KMS. Tipo: string Formato: regionID:domainID:key/key_id regionID indica el ID de la región a la que pertenece la clave. domainID indica el ID del tenant al que pertenece la clave. key_id indica el ID de clave utilizado en esta encriptación. Ejemplo: x-obs-server-side-encryption-kms-key-id:region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 |
x-obs-server-side-encryption-customer-algorithm |
Indica un algoritmo de encriptación. Este encabezado se incluye en una respuesta si se utiliza SSE-C. Tipo: string Ejemplo: x-obs-server-side-encryption-customer-algorithm:AES256 |
x-obs-server-side-encryption-customer-key-MD5 |
Indica el valor MD5 de una clave utilizada para cifrar objetos. Este encabezado se incluye en una respuesta si se utiliza SSE-C. Tipo: string Ejemplo: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== |
x-obs-next-append-position |
Indica la posición que se proporcionará para la siguiente solicitud. Tipo: integer |
Elementos de respuesta
Esta respuesta no contiene elementos.
Respuestas de error
- Si la longitud del objeto excede el límite debido a la carga anexada, OBS devuelve 400 Bad Request y el código de error es AppendTooLarge.
- Si el valor de position es diferente de la longitud original del objeto actual, OBS devuelve 409 Conflict y el código de error es PositionNotEqualToLength.
- Si existe un objeto con el mismo nombre de objeto en un bucket y el tipo de objeto no es Appendable, OBS devuelve 409 Conflict y el código de error es ObjectNotAppendable.
- Si el número de veces de escritura de un objeto es superior a 10000, OBS devuelve 409 Conflict y el código de error es ObjectNotAppendable.
- Si la clase de almacenamiento de objetos es COLD (almacenamiento de Archive), no se puede invocar a esta API. Si sigue invocando a esta API, OBS devuelve 409 Conflict con el código de error de ObjectNotAppendable.
- Si se configura la replicación entre regiones para un bucket, no se puede usar esta operación de API. De lo contrario, OBS devuelve 400 Bad Request y el código de error es OperationNotSupported.
Otros errores se incluyen en Tabla 2.
Ejemplo de solicitud: Adjuntar carga
POST /object?append&position=0 HTTP/1.1 Host: examplebucket.obs.region.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT Content-Type: image/jpg Content-Length: 1458 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [1458 bytes of object data]
Ejemplo de respuesta: Adjuntar carga
1 2 3 4 5 6 7 8 |
HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "d41d8cd98f00b204e9800998ecf8427e" Content-Length: 0 Server: OBS x-obs-request-id: 8DF400000163D3F0FD2A03D2D30B0542 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCTjCqTmsA1XRpIrmrJdvcEWvZyjbztdd x-obs-next-append-position: 1458 |
Ejemplo de solicitud: Adjuntar carga (con redirect y un encabezado definido por el usuario utilizado)
El bucket examplebucket existe pero el objeto obj001 no existe. Cree un objeto haciendo la invocación a la API para la operación anexada. Establezca el campo de encabezado de redirección de la siguiente manera: "x-obs-website-redirect-location":"http://www.example.com/", y establezca el campo de encabezado definido por el usuario en: "x-obs-meta-redirect":"redirect". La solicitud es la siguiente:
POST /obj001?append&position=0 HTTP/1.1 Host: examplebucket.obs.region.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT x-obs-website-redirect-location: http://www.example.com/ x-obs-meta-redirect: redirect Content-Length: 6 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [6 bytes of object data]
Ejemplo de respuesta: Adjuntar carga (con redirect y un encabezado definido por el usuario utilizado)
1 2 3 4 5 6 7 8 |
HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "9516dfb15f51c7ee19a4d46b8c0dbe1d" Content-Length: 0 Server: OBS x-obs-request-id: 5DEB00000164A3150AC36F8F0C120D50 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCSrVlTYwsA4p9GEW+LYqotSl5BYDxHfT x-obs-next-append-position: 6 |