HeadObject - recuperar metadados de objeto sem download de conteúdo - Object Storage Service: Central de Documentação do Alibaba Cloud

Versionamento

Se você chamar HeadObject sem especificar um versionId, o sistema retornará os metadados da versão atual. Se a versão atual for um marcador de exclusão, o OSS retornará 404 NoSuchKey.
Se você chamar HeadObject com um versionId específico, o sistema retornará os metadados dessa versão. Não especifique o versionId de um marcador de exclusão; caso contrário, o OSS retornará 405 MethodNotAllowed.

Permissões

Por padrão, uma conta Alibaba Cloud tem permissões totais. Usuários RAM ou funções RAM vinculados a uma conta Alibaba Cloud não têm permissões por padrão. A conta Alibaba Cloud ou o administrador da conta deve conceder as permissões de operação por meio de políticas do RAM ou Bucket Policy.

Sintaxe da solicitação

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

Cabeçalhos da solicitação

Nome	Tipo	Obrigatório	Descrição
If-Modified-Since	String	Não	Se o horário especificado for anterior ao horário real de modificação do objeto, o OSS retornará 200 OK com os metadados do objeto. Caso contrário, o OSS retornará 304 Not Modified. Valor padrão: None
If-Unmodified-Since	String	Não	Se o horário especificado for igual ou posterior ao horário real de modificação do objeto, o OSS retornará 200 OK com os metadados do objeto. Caso contrário, o OSS retornará 412 Precondition Failed. Valor padrão: None
If-Match	String	Não	Se o ETag especificado corresponder ao ETag do objeto, o OSS retornará 200 OK com os metadados do objeto. Caso contrário, o OSS retornará 412 Precondition Failed. Valor padrão: None
If-None-Match	String	Não	Se o ETag especificado não corresponder ao ETag do objeto, o OSS retornará 200 OK com os metadados do objeto. Caso contrário, o OSS retornará 304 Not Modified. Valor padrão: None

Esta operação também aceita Cabeçalhos comuns de solicitação, como Host e Date.

Cabeçalhos de resposta

Se o objeto solicitado for um link simbólico, os cabeçalhos de resposta se comportarão da seguinte forma:

Content-Length, ETag, x-oss-storage-class e Content-Md5 correspondem aos metadados do arquivo do objeto.
Last-Modified indica a última modificação do link simbólico ou do arquivo do objeto, prevalecendo a data mais recente.
Os demais cabeçalhos de resposta indicam os metadados do link simbólico.

Nome	Tipo	Descrição
x-oss-meta-*	String	Cabeçalhos de metadados definidos pelo usuário via PutObject com o prefixo x-oss-meta- são retornados na resposta.
Cabeçalhos personalizados que não começam com x-oss-meta-	String	Cabeçalhos personalizados que não começam com x-oss-meta- (por exemplo, x-oss-persistent-headers:`key1:base64_encode(value1),key2:base64_encode(value2)...`) definidos via PutObject são retornados na resposta.
x-oss-server-side-encryption	String	Retornado se o objeto usar criptografia no lado do servidor. O valor indica o algoritmo de criptografia.
x-oss-server-side-encryption-key-id	String	Retornado se o objeto usar criptografia no lado do servidor baseada em KMS. O valor é o ID da chave KMS.
x-oss-storage-class	String	Classe de armazenamento do objeto. Valores válidos: Standard, IA, Archive, ColdArchive e DeepColdArchive. Classes de armazenamento.
x-oss-object-type	String	Tipo do objeto. Objetos enviados via PutObject ou criados via CreateDirectory são do tipo Normal. Objetos enviados via AppendObject são do tipo Appendable. Objetos enviados via MultipartUpload são do tipo Multipart.
x-oss-next-append-position	String	Retornado para objetos Appendable. Indica a posição onde a próxima operação de anexação começará.
x-oss-hash-crc64ecma	String	Valor CRC-64 do objeto, calculado com o algoritmo CRC-64/XZ. Este cabeçalho pode não ser retornado para objetos criados antes do suporte a CRC-64 pelo OSS.
x-oss-sealed-time	String	Retornado para objetos Appendable selados. Indica quando o objeto foi selado, no formato HTTPS 1.1 GMT (por exemplo, Sat, 11 Oct 2025 06:41:42 GMT).
x-oss-transition-time	String	Momento em que o objeto foi convertido para Cold Archive ou Deep Cold Archive por uma regra de ciclo de vida. Nota Se você excluir um objeto Cold Archive ou Deep Cold Archive mais de 180 dias após a conversão, nenhuma taxa de exclusão antecipada será cobrada. Se a exclusão ocorrer dentro de 180 dias após a conversão, uma taxa de exclusão antecipada será aplicada. Este campo não serve para determinar quando um objeto foi convertido para a classe de armazenamento IA ou Archive por uma regra de ciclo de vida. O cumprimento do requisito de duração mínima de armazenamento para objetos IA ou Archive depende do horário `Last-Modified`.
x-oss-expiration	String	Data de expiração de um objeto em um bucket com regras de ciclo de vida configuradas. Versionamento ativado no bucket Solicitação enviada sem versionId. Se o objeto solicitado corresponder a uma regra de exclusão na configuração de ciclo de vida, o cabeçalho x-oss-expiration será retornado na resposta para indicar a expiração da versão atual do objeto. Solicitação enviada com versionId. O cabeçalho x-oss-expiration não será retornado na resposta, independentemente de o objeto solicitado corresponder ou não a uma regra de exclusão na configuração de ciclo de vida. Versionamento desativado no bucket Se o objeto solicitado corresponder a uma regra de exclusão na configuração de ciclo de vida, o cabeçalho x-oss-expiration será retornado na resposta. Se o objeto solicitado não corresponder a uma regra de exclusão na configuração de ciclo de vida, o cabeçalho x-oss-expiration não será retornado na resposta.
x-oss-restore	String	Se a classe de armazenamento do objeto for Archive, ColdArchive ou DeepColdArchive e uma solicitação Restore tiver sido enviada, o status da restauração será retornado neste cabeçalho: Se nenhuma solicitação Restore tiver sido enviada ou se o objeto restaurado tiver expirado, este cabeçalho não será retornado. Se a restauração estiver em andamento, o valor será ongoing-request="true". Se a restauração estiver concluída, o valor será ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT", onde expiry-date indica quando a cópia restaurada expira.
x-oss-process-status	String	Se uma notificação de evento do OSS for criada usando Simple Message Queue (SMQ) e existir uma regra correspondente, este cabeçalho será retornado. O valor é o resultado da notificação de evento codificado em Base64 no formato JSON.
x-oss-request-charged	String	Retornado se o bucket usar o modo pay-by-requester e o solicitante não for o proprietário do bucket. O valor é requester.
Content-Md5	String	Para objetos Normal, trata-se do hash MD5 de 128 bits codificado em Base64 do conteúdo da mensagem (excluindo cabeçalhos), calculado conforme RFC 1864. Este cabeçalho não é retornado para objetos Multipart ou Appendable.
Last-Modified	String	Última data de modificação do objeto, no formato HTTPS 1.1 GMT. Nota A duração mínima de armazenamento para objetos na classe Infrequent Access é de 30 dias. Esse período é calculado a partir do horário Last-Modified do objeto. Se você excluir um objeto mais de 30 dias após seu horário Last-Modified, nenhuma taxa de exclusão antecipada será cobrada. A duração mínima de armazenamento para objetos na classe Archive Storage é de 60 dias. Esse período é calculado a partir do horário Last-Modified do objeto. Se você excluir um objeto mais de 60 dias após seu horário Last-Modified, nenhuma taxa de exclusão antecipada será cobrada.
Access-Control-Allow-Origin	String	Retornado se o bucket tiver uma regra CORS configurada e a source da solicitação corresponder à regra.
Access-Control-Allow-Methods	String	Retornado se o bucket tiver uma regra CORS configurada e o Access-Control-Request-Method corresponder à regra.
Access-Control-Max-Age	String	Retornado se o bucket tiver uma regra CORS configurada e a solicitação corresponder à regra. Indica a duração do cache de preflight.
Access-Control-Allow-Headers	String	Retornado se o bucket tiver uma regra CORS configurada e a solicitação corresponder à regra.
Access-Control-Expose-Headers	String	Cabeçalhos que o JavaScript do lado do cliente tem permissão para acessar. Retornado se o bucket tiver uma regra CORS configurada e a solicitação corresponder à regra.
x-oss-tagging-count	String	Número de tags associadas ao objeto. Retornado apenas se você tiver permissão para ler tags.

Esta operação também aceita Cabeçalhos comuns de resposta, como ETag e x-oss-request-id.

Exemplos

Versionamento desativado

Exemplo de solicitação

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

Exemplo de resposta (O objeto é um arquivo)

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

Exemplo de resposta (O objeto é uma pasta)

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

Exemplo de resposta (O objeto é um objeto Appendable selado)

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

Solicitação de uma versão específica de um objeto (versionamento ativado)

Exemplo de solicitação

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

Exemplo de resposta

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

Solicitação da versão mais recente de um objeto (versionamento ativado)

Exemplo de solicitação

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

Exemplo de resposta

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

Tarefa de restauração em andamento

Exemplo de solicitação

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

Exemplo de resposta

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

Tarefa de restauração concluída

Exemplo de solicitação

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

Exemplo de resposta

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 criptografia no lado do servidor com SSE-OSS

Exemplo de solicitação

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

Exemplo de resposta

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 criptografia no lado do servidor com SSE-KMS

Exemplo de solicitação

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

Exemplo de resposta

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 suportados:

ossutil

O comando ossutil correspondente é head-object.

Códigos de erro

Código de erro	Código de status HTTPS	Descrição
NoSuchKey	404	O objeto solicitado não existe.
SymlinkTargetNotExist	404	O arquivo solicitado é um link simbólico.
InvalidTargetType	400	O objeto solicitado é um link simbólico e seu objeto de destino também é um link simbólico.
NotModified	304	Este erro ocorre por um dos seguintes motivos: O cabeçalho de solicitação If-Modified-Since foi especificado, mas o objeto de source não foi modificado desde o horário indicado. O cabeçalho de solicitação If-None-Match foi especificado e o ETag do objeto de source é idêntico ao ETag fornecido.
PreconditionFailed	412	Este erro ocorre por um dos seguintes motivos: O cabeçalho de solicitação If-Unmodified-Since foi especificado, mas o horário indicado é anterior ao horário real de modificação do objeto. O cabeçalho de solicitação If-Match foi especificado, mas o ETag do objeto de source difere do ETag fornecido.

API	Action	Descrição
HeadObject	`oss:GetObject`	Consulta os metadados de um objeto.