HEAD Object

描述

此HEAD操作将会在不返回 object 的情况下获取对象的元数据信息。如果你只需要对象的元数据信息，那么这个方法非常合适。
使用此接口，你需要具有对对象的 READ 权限。

一个对象的HEAD请求与GET请求具有相同的操作，唯一的区别是响应回复中HEAD请求不具有响应体。

权限

该接口操作需要用户对Object拥有READ权限。如果请求的 object 不存在，KS3将根据你是否拥有对权限返回相应信息。

• 如果你拥有该Bucket的READ权限，KS3将会返回的 HTTP 状态码为404(no such key)错误。

• 如果你并不拥有该Bucket的READ权限，KS3将会返回的 HTTP 状态码为403(access denied)错误。

  请求

  语法

  HEAD /{ObjectKey} HTTP/1.1
  Host: {BucketName}.{endpoint}
  Date: {date}
  Authorization: {SignatureValue}
  

  注意：

  • endpoint与Region对应关系
  • SignatureValue签名算法

  请求参数

  该接口不使用请求参数。

  请求头部

  该接口可以使用所有常用请求头部，此外，也可以使用下表所列请求头部。获取更多信息，请点击常用请求头部。

名称	描述	是否必选
Range	下载指定 range 字节的 object。更多关于HTTP Range 头部信息，请访问http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.35 类型：String 默认值：None 约束条件：无	否
If-Modified-Since	如果 object 在指定时间后被改变，则返回 object。否则，返回304状态码 类型：String 默认值：None 约束条件：无	否
If-Unmodified-Since	如果 object 在指定时间后没有被改变，则返回 object。否则，返回412状态码 类型：String 默认值：None 约束条件：无	否
If-Match	如果 object 的 ETag(entity tag)与指定值一致，则返回 object。否则，返回412状态码 类型：String 默认值：None 约束条件：无	否
If-None-Match	如果 object 的 ETag(entity tag)与指定值不一致，则返回 object。否则，返回304状态码 类型：String 默认值：None 约束条件：无	否

加密相关请求头部

若使用客户提供的加密密钥的服务器端加密，则需要使用以下请求头 。

名称	描述
x-kss-server-side-encryption-customer-algorithm	客户端提供的加密算法，合法值：AES256
x-kss-server-side-encryption-customer-key	客户端提供的加密密钥
x-kss-server-side-encryption-customer-key-MD5	客户端提供的通过BASE64编码的通过128位MD5加密的密钥的MD5值

请求内容

该接口不使用请求内容。

响应

响应头部

名称	描述
Content-MD5	返回文件md5值的base64编码，前提条件为文件是通过PUT或POST上传到KS3；如果是分块上传的文件，将不会返回此响应头。
x-kss-meta-*	如果你在PUT Object中使用了用户元数据，格式为前缀 x-kss-meta- 后缀为你自定的字段，那么响应头部会返回它，并不解析。 类型：String
x-kss-restore	对解冻中的或已解冻的归档文件进行head请求时，会增加x-kss-restore响应头，响应头的内容指明解冻的状态以及解冻过期时间，解冻中的文件会返回x-kss-restore: ongoing-request="true"，已解冻的文件会返回，例如：x-kss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"；对标准存储文件、低频存储文件和未解冻的归档文件，进行Head请求时，不会增加x-kss-restore响应头。 类型：String
x-kss-storage-class	如果文件存储类型为低频存储，值为STANDARD_IA；如果文件存储类型为归档存储，值为ARCHIVE；如果文件存储类型为标准存储，不返回此响应头。 类型：String
ETag	用于标识Object内容的32位十六进制字符串，不同内容的Object对应着不同的ETag。对于Put Object或Post Object请求创建的Object，ETag值是其内容的MD5值；对于分块上传方式创建的Object，ETag值是每个分块的MD5值进行字符串拼接后再次计算所得到的MD5值。ETag值可以用于检查Object内容是否发生变化。 类型: String
x‑kss‑tagging‑count	对象关联的标签的个数。仅当用户有读取标签权限且Object有标签时返回。 类型：String
x-kss-crr	如果Object是从其他桶复制的文件，则会返回该响应头，对应的值为true。否则不返回该响应头。

加密相关响应头部

若使用KS3 托管密钥的服务器端加密，则会返回以下响应头。

名称	描述
x-kss-server-side-encryption	如果数据通过KS3 托管密钥的服务器端加密，则响应头将包含该值

若使用客户提供的加密密钥的服务器端加密，则会返回以下响应头。

名称	描述
x-kss-server-side-encryption-customer-algorithm	如果请求数据通过客户提供的加密密钥的服务器端加密，则响应头将包含该值
x-kss-server-side-encryption-customer-key-MD5	如果请求数据通过客户提供的加密密钥的服务器端加密，则响应头将包含该值

响应内容

该接口不返回响应内容。

特殊错误

该接口不返回任何特殊错误。

示例

请求示例

HEAD /my-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "54a3be97af36cdc9f2516c74550fa95d"
x‑kss‑tagging‑count:2
Content-Length: 434234
Content-Type: text/plain
Connection: keep-alive
Server: KS3
Content-MD5:VKO+l682zcnyUWx0VQ+pXQ==

注意：

1、如果文件通过分块上传保存在KS3，对文件调用GET接口时将不会返回Content_MD5响应头；

2、如果文件通过PUT或POST接口上传到KS3，对文件调用GET接口将会返回Content_MD5响应头。

接口细节分析

• HEAD Object不论请求成功与否，都不会返回body。
• 使用该接口可以用来判断object是否存在。
• 使用该接口可以用来获取object的元数据。
• x‑kss‑tagging‑count请求头的返回需要访问者具有读取标签的权限（ks3:GetObjectTagging ）。即当用户仅有ks3:GetObject权限，但没有ks3:GetObjectTagging权限时，HeadObject请求的响应头不返回示x-kss-tagging-count。

错误码

错误码	HTTP状态码	描述
InvalidArgument	400	提供了x-kss-server-side-encryption请求头。
Md5NotMatchForOldMd5	400	x-kss-copy-source-server-side-encryption-customer-key-MD5 不是 x-kss-copy-source-server-side-encryption-customer-key 的MD5值。
AlgorithmInvalidForCustomerKey	400	x-kss-server-side-encryption-customer-algorithm不是合法的AES256。
MissingCustomerKey	400	文件为SSE-C加密时，请求中未提供客户密钥。