HeadObject - retrieve object metadata without content download - Object Storage Service

La operación HeadObject recupera los metadatos de un objeto sin devolver su contenido.

Control de versiones

Si llama a HeadObject sin especificar un versionId, se devuelven los metadatos de la versión actual. Si la versión actual es un marcador de eliminación, OSS devuelve 404 NoSuchKey.
Si llama a HeadObject con un versionId específico, se devuelven los metadatos de esa versión. No especifique el versionId de un marcador de eliminación; de lo contrario, OSS devuelve 405 MethodNotAllowed.

Permisos

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

API	Acción	Descripción
HeadObject	`oss:GetObject`	Consulta los metadatos de un objeto.

Sintaxis de la solicitud

HEAD /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Encabezados de solicitud

Nombre	Tipo	Obligatorio	Descripción
If-Modified-Since	String	No	Si la hora especificada es anterior a la hora de modificación real del objeto, OSS devuelve 200 OK con los metadatos del objeto. De lo contrario, OSS devuelve 304 Not Modified. Valor predeterminado: Ninguna
If-Unmodified-Since	String	No	Si la hora especificada es igual o posterior a la hora de modificación real del objeto, OSS devuelve 200 OK con los metadatos del objeto. De lo contrario, OSS devuelve 412 Precondition Failed. Valor predeterminado: Ninguna
If-Match	String	No	Si el ETag especificado coincide con el ETag del objeto, OSS devuelve 200 OK con los metadatos del objeto. De lo contrario, OSS devuelve 412 Precondition Failed. Valor predeterminado: Ninguna
If-None-Match	String	No	Si el ETag especificado no coincide con el ETag del objeto, OSS devuelve 200 OK con los metadatos del objeto. De lo contrario, OSS devuelve 304 Not Modified. Valor predeterminado: Ninguna

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

Encabezados de respuesta

Si el objeto solicitado es un enlace simbólico, los encabezados de respuesta se comportan de la siguiente manera:

Content-Length, ETag, x-oss-storage-class y Content-Md5 corresponden a los metadatos del archivo de objeto.
Last-Modified es la última hora de modificación del enlace simbólico o del archivo de objeto, la que sea posterior.
Los demás encabezados de respuesta indican los metadatos del enlace simbólico.

Nombre	Tipo	Descripción
x-oss-meta-*	String	Los encabezados de metadatos definidos por el usuario establecidos mediante PutObject con el prefijo x-oss-meta- se devuelven en la respuesta.
Encabezados personalizados que no comienzan con x-oss-meta-	String	Los encabezados personalizados que no comienzan con x-oss-meta- (por ejemplo, x-oss-persistent-headers:`key1:base64_encode(value1),key2:base64_encode(value2)...`) establecidos mediante PutObject se devuelven en la respuesta.
x-oss-server-side-encryption	String	Se devuelve si el objeto utiliza cifrado del lado del servidor. El valor indica el algoritmo de cifrado.
x-oss-server-side-encryption-key-id	String	Se devuelve si el objeto utiliza cifrado del lado del servidor basado en KMS. El valor es el ID de clave de KMS.
x-oss-storage-class	String	La clase de almacenamiento del objeto. Valores válidos: Standard, IA, Archive, ColdArchive y DeepColdArchive. Storage classes.
x-oss-object-type	String	El tipo del objeto. Los objetos cargados mediante PutObject o creados mediante CreateDirectory son de tipo Normal. Los objetos cargados mediante AppendObject son de tipo Appendable. Los objetos cargados mediante MultipartUpload son de tipo Multipart.
x-oss-next-append-position	String	Se devuelve para objetos Appendable. Indica la posición desde la cual comienza la siguiente operación de anexado.
x-oss-hash-crc64ecma	String	El valor CRC-64 del objeto, calculado mediante el algoritmo CRC-64/XZ. Es posible que este encabezado no se devuelva para objetos creados antes de que OSS admitiera CRC-64.
x-oss-sealed-time	String	Se devuelve para objetos Appendable sellados. Indica cuándo se selló el objeto, en formato HTTP 1.1 GMT (por ejemplo, Sat, 11 Oct 2025 06:41:42 GMT).
x-oss-transition-time	String	La hora en que el objeto se convirtió a Cold Archive o Deep Cold Archive mediante una regla de ciclo de vida. Nota Si elimina un objeto de Cold Archive o Deep Cold Archive más de 180 días después de su conversión, no se cobra ninguna tarifa por eliminación anticipada. Si elimina el objeto dentro de los 180 días posteriores a su conversión, se cobra una tarifa por eliminación anticipada. Este campo no se puede utilizar para determinar la hora en que un objeto se convierte a la clase de almacenamiento IA o Archive mediante una regla de ciclo de vida. El cumplimiento del requisito de duración mínima de almacenamiento para un objeto IA o Archive depende de la hora `Last-Modified`.
x-oss-expiration	String	La fecha de vencimiento de un objeto en un bucket con reglas de ciclo de vida configuradas. El control de versiones está habilitado para el bucket Se envía una solicitud sin versionId. Si el objeto solicitado coincide con una regla de eliminación en la configuración de ciclo de vida, el encabezado x-oss-expiration se devuelve en la respuesta para indicar la fecha de vencimiento de la versión actual del objeto. Se envía una solicitud con versionId. El encabezado x-oss-expiration no se devuelve en la respuesta, independientemente de si el objeto solicitado coincide con una regla de eliminación en la configuración de ciclo de vida. El control de versiones está deshabilitado para el bucket Si el objeto solicitado coincide con una regla de eliminación en la configuración de ciclo de vida, el encabezado x-oss-expiration se devuelve en la respuesta. Si el objeto solicitado no coincide con una regla de eliminación en la configuración de ciclo de vida, el encabezado x-oss-expiration no se devuelve en la respuesta.
x-oss-restore	String	Si la clase de almacenamiento del objeto es Archive, ColdArchive o DeepColdArchive y se ha enviado una solicitud de restauración, el estado de la restauración se devuelve en este encabezado: Si no se ha enviado ninguna solicitud de restauración o si el objeto restaurado ha caducado, este encabezado no se devuelve. Si la restauración está en curso, el valor es ongoing-request="true". Si la restauración se completó, el valor es ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT", donde expiry-date indica cuándo caduca la copia restaurada.
x-oss-process-status	String	Si se crea una notificación de eventos de OSS mediante Simple Message Queue (SMQ) y existe una regla coincidente, se devuelve este encabezado. El valor es el resultado de la notificación de eventos codificado en Base64 en formato JSON.
x-oss-request-charged	String	Se devuelve si el bucket utiliza el modo de pago por solicitante y el solicitante no es el propietario del bucket. El valor es requester.
Content-Md5	String	Para objetos Normal, este es el hash MD5 de 128 bits codificado en Base64 del contenido del mensaje (excluyendo encabezados), calculado según RFC 1864. Este encabezado no se devuelve para objetos Multipart o Appendable.
Last-Modified	String	La última hora de modificación del objeto, en formato HTTP 1.1 GMT. Nota La duración mínima de almacenamiento para objetos en la clase de almacenamiento Infrequent Access es de 30 días. La duración se calcula a partir de la hora Last-Modified del objeto. Si elimina un objeto más de 30 días después de su hora Last-Modified, no se cobra ninguna tarifa por eliminación anticipada. La duración mínima de almacenamiento para objetos en la clase de almacenamiento Archive es de 60 días. La duración se calcula a partir de la hora Last-Modified del objeto. Si elimina un objeto más de 60 días después de su hora Last-Modified, no se cobra ninguna tarifa por eliminación anticipada.
Access-Control-Allow-Origin	String	Se devuelve si el bucket tiene configurada una regla CORS y el origen de la solicitud coincide con la regla.
Access-Control-Allow-Methods	String	Se devuelve si el bucket tiene configurada una regla CORS y Access-Control-Request-Method coincide con la regla.
Access-Control-Max-Age	String	Se devuelve si el bucket tiene configurada una regla CORS y la solicitud coincide con la regla. Indica la duración de la caché de preflight.
Access-Control-Allow-Headers	String	Se devuelve si el bucket tiene configurada una regla CORS y la solicitud coincide con la regla.
Access-Control-Expose-Headers	String	Los encabezados a los que JavaScript del lado del cliente puede acceder. Se devuelve si el bucket tiene configurada una regla CORS y la solicitud coincide con la regla.
x-oss-tagging-count	String	El número de etiquetas asociadas con el objeto. Se devuelve solo si tiene permiso para leer etiquetas.

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

Ejemplos

Control de versiones deshabilitado

Ejemplo de solicitud

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta (El objeto es un archivo)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

Ejemplo de respuesta (El objeto es una carpeta)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Standard
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "null"
Content-Length: 0
Content-Type: application/x-directory
Connection: keep-alive
Server: AliyunOSS

Ejemplo de respuesta (El objeto es un objeto Appendable sellado)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Appendable
x-oss-storage-class: Standard
x-oss-sealed-time: Sat, 11 Oct 2025 06:41:42 GMT
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 100
Content-Type: text/plain
Connection: keep-alive
Server: AliyunOSS

Solicitud de una versión específica de un objeto (control de versiones habilitado)

Ejemplo de solicitud

HEAD /example?versionId=CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy****
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 06:27:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-versionId: CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy****
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 06:27:12 GMT
Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT
ETag: "A082B659EF78733A5A042FA253B1****"
Content-Length: 481827
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

Solicitud de la versión más reciente de un objeto (control de versiones habilitado)

Ejemplo de solicitud

HEAD /example HTTP/1.1    
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 06:27:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-versionId: CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 06:27:12 GMT
Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT
ETag: "3663F7B0B9D3153F884C821E7CF4****"
Content-Length: 485859
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

Tarea de restauración en curso

Ejemplo de solicitud

HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-request-id: 58F71A164529F18D7F00****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-restore: ongoing-request="true"
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

Tarea de restauración completada

Ejemplo de solicitud

HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 09:35:51 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-request-id: 58F725344529F18D7F00****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
Date: Fri, 7 Aug 2020 09:35:51 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606

Uso de cifrado del lado del servidor con SSE-OSS

Ejemplo de solicitud

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-server-side-encryption: AES256
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

Uso de cifrado del lado del servidor con SSE-KMS

Ejemplo de solicitud

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Ejemplo de respuesta

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-server-side-encryption: KMS
x-oss-server-side-encryption-key-id: 9468da86-3509-4f8d-a61e-6eab1eac****
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

SDKs

SDKs compatibles:

ossutil

El comando correspondiente de ossutil es head-object.

Códigos de error

Código de error	Código de estado HTTP	Descripción
NoSuchKey	404	El objeto solicitado no existe.
SymlinkTargetNotExist	404	El archivo solicitado es un enlace simbólico.
InvalidTargetType	400	El objeto solicitado es un enlace simbólico y su objeto de destino también es un enlace simbólico.
NotModified	304	Este error se devuelve por uno de los siguientes motivos: Se especificó el encabezado de solicitud If-Modified-Since, pero el objeto de origen no se ha modificado desde la hora especificada. Se especificó el encabezado de solicitud If-None-Match y el ETag del objeto de origen es igual al ETag proporcionado.
PreconditionFailed	412	Este error se devuelve por uno de los siguientes motivos: Se especificó el encabezado de solicitud If-Unmodified-Since, pero la hora especificada es anterior a la hora de modificación real del objeto. Se especificó el encabezado de solicitud If-Match, pero el ETag del objeto de origen no es igual al ETag proporcionado.