全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

HEAD Object

最近更新时间:2024-01-25 18:20:05

描述

该接口用于获取对象(Object)的元数据信息。该接口不会返回对象内容。

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

权限

  • 使用此接口的用户,必须是Bucket的拥有者或具有ks3:GetObject权限。

  • 当请求的Object不存在时,KS3将根据用户是否拥有权限返回相应信息。

    • 如果用户具有ks3:GetObject权限,KS3将会返回的状态码为404(No Such Key)的错误。

    • 如果用户没有ks3:GetObject权限,KS3将会返回的状态码为403(Access Denied)的错误。

请求

请求语法

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

注意:

请求参数

该接口不使用请求参数。

请求头部

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

名称

描述

是否必选

Range

下载指定Range字节的Object。有关HTTP Range头部的详细信息,点击查看

  • 类型:String

  • 默认值:None

  • 约束条件:无

If-Modified-Since

如果Object在指定时间后被改变,则返回Object。否则,返回304状态码

  • 类型:String

  • 默认值:None

  • 约束条件:无

If-Unmodified-Since

如果Object在指定时间后没有被改变,则返回Object。否则,返回412状态码

  • 类型:String

  • 默认值:None

  • 约束条件:无

If-Match

如果Object的Etag与指定值一致,则返回Object 。否则,返回412状态码

  • 类型:String

  • 默认值:None

  • 约束条件:无

If-None-Match

如果Object的 ETag与指定值不一致,则返回Object ct。否则,返回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"及解冻过期时间,例如: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 ObjectPost Object请求创建的ObjectETag值是其内容的MD5值;对于分块上传方式创建的ObjectETag值是每个分块的MD5值进行字符串拼接后再次计算所得到的MD5值。ETag值可以用于检查Object内容是否发生变化。

  • 类型: String

x‑kss‑tagging‑count

对象关联的标签的个数。仅当用户有读取标签权限且Object有标签时返回。

  • 类型:String

x-kss-crr

如果Object是从其他桶复制的文件,则会返回该响应头,对应的值为true。否则不返回该响应头。

x-kss-checksum-crc64ecma

对象的CRC64值,用来做数据完整性校验。关于CRC64的计算标准,请参见文档:ECMA-182标准

  • 类型:String

加密相关响应头部

若使用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: "54a3be97af36cdc9f2516c74550f****"
  Content-MD5:VKO+l682zcnyUWx0VQ+p****
  x-kss-checksum-crc64ecma: 503054087537662****
  x‑kss‑tagging‑count:2
  Content-Length: 434234
  Content-Type: text/plain
  Connection: keep-alive
  Server: KS3

注意:

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加密时,请求中未提供客户密钥。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈