帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>API 文档>对象操作>HeadObject

HeadObject

最近更新时间：2026-10-21 18:34:04
本文档已由 AI 辅助审校
我的收藏

本页目录：

HeadObject 接口请求可以判断指定对象（Object）是否存在，并返回该对象的元数据。该接口仅返回响应头部，不返回响应体。

注意事项

对象键末尾的 / 严格区分

对象键以 / 结尾代表目录对象，不以 / 结尾代表文件对象。两者属于不同的对象，本接口不会对对象键的末尾做任何容错。例如：
若实际只存在文件对象 foo，调用 HEAD /foo/ 会返回 404 NoSuchKey。
若实际只存在目录对象 foo/，调用 HEAD /foo 会返回 404 NoSuchKey。

目录对象

对以 / 结尾的目录对象调用 HeadObject 时，行为如下：
Content-Length 固定为 0。
Content-Type 固定为 application/x-directory。
不返回 x-cos-hash-crc64ecma 头部。

请求

请求语法

HEAD /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

此接口无请求参数。

请求头部

本接口仅使用 公共请求头部，无私有请求头部。

请求体

该请求的请求体为空。

响应

响应头部

除 公共响应头部 外，本接口还会返回以下响应头部：
Header 名称
描述
类型
是否必返
Cache-Control
RFC 2616 中定义的缓存指令，仅当对象元数据包含此项时才会返回该头部
string
否
Content-Disposition
RFC 2616 中定义的文件名称，仅当对象元数据包含此项时才会返回该头部
string
否
Content-Encoding
RFC 2616 中定义的编码格式，仅当对象元数据包含此项时才会返回该头部
string
否
Content-Language
RFC 2616 中定义的内容语言，仅当对象元数据包含此项时才会返回该头部
string
否
Expires
RFC 2616 中定义的缓存失效时间，仅当对象元数据包含此项时才会返回该头部
string
否
x-cos-meta-*
包括用户自定义元数据头部后缀和用户自定义元数据信息
string
否
x-cos-storage-class
对象存储类型，当前固定为 RAPID
enum
是

响应体

该接口的响应体为空。Content-Length 响应头部返回的是对象的实际大小（字节），而非响应体大小。

错误码

本接口遵循统一的错误响应和错误码，详情请参见错误码文档。

实际案例

案例一：查询文件对象元数据

请求

HEAD /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=date;host&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Tue, 28 May 2019 08:30:00 GMT
x-cos-storage-class: RAPID
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

案例二：查询包含用户自定义元数据的对象

请求

HEAD /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=date;host&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: keep-alive
Cache-Control: max-age=86400
Content-Disposition: attachment; filename=example.jpg
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Tue, 28 May 2019 08:30:00 GMT
x-cos-meta-author: alice
x-cos-meta-tag: release
x-cos-storage-class: RAPID
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

案例三：查询目录对象

请求

HEAD /folder/ HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=date;host&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Type: application/x-directory
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Last-Modified: Tue, 28 May 2019 08:30:00 GMT
x-cos-storage-class: RAPID
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

中国站