# 获取对象元数据-HeadObject #### 功能介绍 拥有对象读权限的用户可以执行HEAD操作命令获取对象元数据，返回信息包含对象的元数据信息。 获取采用SSE-C加密的对象的元数据时，需要携带SSE-C相关头域，详见[表2]。 #### 多版本 默认情况下，获取的是最新版本的对象元数据。如果最新版本的对象是删除标记，则返回404。如果要获取指定版本的对象元数据，请求可携带versionId消息参数。 #### 授权信息 您必须是对象拥有者或拥有获取对象元数据的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。 - 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限： - 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:object:getObject（未开启多版本）** 、**obs:object:getObjectVersion（开启或暂停多版本）** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。 - 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:object:GetObject（未开启多版本）** 、**obs:object:GetObjectVersion（开启或暂停多版本）** 权限，授权操作请参见[创建IAM自定义身份策略](https://support.huaweicloud.com/usermanual-iam5/iam_01_0917.html)。 | 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | [条件键](https://support.huaweicloud.com/api-obs/obs_04_0112.html#ZH-CN_TOPIC_0000002375307974__condition_table) Condition Key | [别名](https://support.huaweicloud.com/iam5_faq/iam_01_1103.html) Alias | 依赖的授权项 Dependencies | |:---|:---|:---|:---|:---|:---| | obs:object:getObject（未开启多版本） obs:object:getObjectVersion（开启或暂停多版本） | Read | object \* | - [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) - obs:versionId | - | obs:object:getObjectRetention | | obs:object:getObject（未开启多版本） obs:object:getObjectVersion（开启或暂停多版本） | Read | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | obs:object:getObjectRetention | - 如果使用**桶策略** 进行授权，需具备**obs:object:GetObject（未开启多版本）** 、**obs:object:GetObjectVersion（开启或暂停多版本）** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。 #### URI HEAD /{*object_key*} #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。 您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=HeadObject)在线调试接口。 #### 请求消息样式 ``` HEAD /ObjectName HTTP/1.1 Host: bucketname.obs.cn-north-4.myhuaweicloud.com Date: date Authorization: authorization ``` #### URI参数（URI Parameters） 请求参数说明如[表1]所示。 表1URI参数 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | versionId | String | 否 | **参数解释：** 对象的版本号。 **约束限制：** 无 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 另外该请求可以使用附加的消息头，具体如[表2]所示。 表2请求头参数 | **消息头名称** | **消息头类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | Origin | String | 否 | **参数解释：** 预请求指定的跨域请求Origin（通常为域名）。 **约束限制：** 允许多条匹配规则，以回车换行为间隔。每个匹配规则允许使用最多一个"\*"通配符。 **取值范围：** 符合CORS协议的取值范围。 **默认取值：** 无 | | Access-Control-Request-Headers | String | 否 | **参数解释：** 实际请求可以使用的HTTP头域，可以带多个头域。 **约束限制：** 允许的头域可设置多个，多个头域之间换行隔开，每行最多可填写一个\*符号，不支持\&、:、\<、空格以及中文字符。 **取值范围：** 符合CORS协议的取值范围。 **默认取值：** 无 | | x-obs-server-side-encryption-customer-algorithm | String | 否。当使用SSE-C方式时，必选。 | **参数解释：** 在SSE-C加密方式下使用该头域，该头域表示解密使用的算法。 示例：x-obs-server-side-encryption-customer-algorithm：AES256 **约束限制：** 需要和x-obs-server-side-encryption-customer-key， x-obs-server-side-encryption-customer-key-MD5一起使用。 **取值范围：** AES256 **默认取值：** 无 | | x-obs-server-side-encryption-customer-key | String | 否。当使用SSE-C方式时，必选。 | **参数解释：** 在SSE-C加密方式下使用该头域，该头域表示解密使用的密钥。 示例：x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= **约束限制：** 该头域由256-bit的密钥经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key-MD5一起使用。 **取值范围：** 无 **默认取值：** 无 | | x-obs-server-side-encryption-customer-key-MD5 | String | 否。当使用SSE-C方式时，必选。 | **参数解释：** 在SSE-C加密方式下使用该头域，该头域表示解密使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== **约束限制：** 该头域由密钥的128-bit MD5值经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key一起使用。 **取值范围：** 密钥ID MD5的base64值。 **默认取值：** 无 | #### 请求体参数（Request body） 该请求消息中不带请求体参数。 #### 响应消息样式 ``` HTTP/1.1 status_code Content-Type: type Date: date Content-Length: length Etag: etag Last-Modified: time ``` #### 响应头 (Response Headers) 该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。 除公共响应头 (Response Headers)之外，还可能使用如下[表3]中的消息头。 表3响应头 | **消息头名称** | **消息头类型** | **描述** | |:---|:---|:---| | x-obs-expiration | String | **参数解释：** 对象的详细过期信息。 **取值范围：** 当对象单独设置了对象lifecycle，过期时间以对象lifecycle为准，该消息头用expiry-date描述对象的详细过期信息；如果对象没有设置对象lifecycle，设置了桶级别lifecycle，过期时间以桶级别lifecycle为准，该消息头用expiry-date和rule-id两个键值对描述对象的详细过期信息；否则不显示该头域。 | | x-obs-website-redirect-location | String | **参数解释：** 当桶设置了Website配置，就可以设置对象元数据的这个属性，Website接入点返回301重定向响应，将获取这个对象的请求重定向到该属性指定的桶内另一个对象或一个外部的URL，该参数指明对象的重定向地址。必须以"/"、"http://"或"https://"开头，长度不超过2KB，且仅支持为桶根目录下的对象设置重定向，不支持为桶中文件夹下的对象设置重定向。 例如，重定向请求到桶内另一对象： x-obs-website-redirect-location:/anotherPage.html 或重定向请求到一个外部URL： x-obs-website-redirect-location:http://www.example.com/ OBS将这个值从头域中取出，保存在对象的元数据"WebsiteRedirectLocation"中。 **取值范围：** 无 | | x-obs-version-id | String | **参数解释：** 对象的版本号，长度为32的字符串。如果该对象无版本号，则响应中不会出现该消息头。 **取值范围：** 无 | | Access-Control-Allow-Origin | String | **参数解释：** 当桶设置了CORS配置，如果请求中的Origin满足服务端的CORS配置，则在响应中包含这个Origin。 **取值范围：** | | Access-Control-Allow-Headers | String | **参数解释：** 当桶设置了CORS配置，如果请求的headers满足服务端的CORS配置，则在响应中包含这个headers。最多可填写一个"\*"通配符，不支持\&、:、\<、空格以及中文字符。 **取值范围：** 符合CORS协议的取值范围。 | | Access-Control-Max-Age | Integer | **参数解释：** 桶CORS规则中的MaxAgeSeconds。MaxAgeSeconds指请求来源的客户端可以对跨域请求返回结果的缓存时间。每个CORSRule可以包含至多一个MaxAgeSeconds。 **取值范围：** 大于等于0的整型数，单位：秒。 | | Access-Control-Allow-Methods | String | **参数解释：** 当桶设置了CORS配置，如果请求的Access-Control-Request-Method满足服务端的CORS配置，则在响应中包含这条rule中的Methods。 **取值范围：** - GET - PUT - HEAD - POST - DELETE | | Access-Control-Expose-Headers | String | **参数解释：** 桶CORS规则中的ExposeHeader。ExposeHeader是指CORS规则允许响应中可返回的附加头域，给客户端提供额外的信息。默认情况下浏览器只能访问以下头域：Content-Length、Content-Type，如果需要访问其他头域，需要在附加头域中配置。不支持\*、\&、:、\<、空格以及中文字符。 **取值范围：** 无 | | x-obs-server-side-encryption | String | **参数解释：** 该头域表示服务端的加密方式。如果服务端加密是SSE-KMS方式，响应包含该头域。 **取值范围：** - kms：使用SSE-KMS加密方式 - AES256：使用SSE-OBS加密方式，且使用AES256算法 | | x-obs-server-side-data-encryption | String | **参数解释：** 如果服务端加密是SSE-KMS方式，且数据加密算法为SM4，响应包含该头域。 示例：x-obs-server-side-data-encryption：SM4 **约束限制：** 仅在SSE-KMS加密方式下使用该头域，如果开启SSE-KMS但不返回该头域则表明使用AES256算法。 **取值范围：** SM4：国密SM4算法。 **默认取值：** 无 | | x-obs-server-side-encryption-kms-key-id | String | **参数描述：** 当加密方式为SSE-KMS且使用指定密钥加密时，需输入密钥ID。密钥ID获取方法请参见[查看密钥](https://support.huaweicloud.com/usermanual-dew/dew_01_0179.html)。 **约束限制：** 当您设置了x-obs-server-side-encryption头域且赋值为"kms"，即选择kms加密方式时，才能使用该头域指定加密密钥。 **默认取值：** 当您选择使用kms加密方式，但未设置此头域时，默认的主密钥将会被使用。如果默认主密钥不存在，系统将默认创建并使用。 | | x-obs-server-side-encryption-customer-algorithm | String | **参数解释：** 如果服务端加密是SSE-C方式，响应包含该头域，该头域表示解密使用的算法。 示例：x-obs-server-side-encryption-customer-algorithm：AES256 **取值范围：** AES256：AES256算法 | | x-obs-server-side-encryption-customer-key-MD5 | String | **参数解释：** 如果服务端加密是SSE-C方式，响应包含该头域，该头域表示解密使用的密钥的MD5值。 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== 由密钥值经过MD5加密再经过Base64编码后得到，示例：4XvB3tbNTN+tIEVa0/fGaQ== **取值范围：** 密钥ID MD5的base64值。 | | x-obs-storage-class | String | **参数解释：** 对象的存储类型。仅当对象为非标准存储类型时，会返回此头域。 **取值范围：** - STANDARD：标准存储 - WARM：低频访问存储 - COLD：归档存储 - DEEP_ARCHIVE：深度归档存储 注意： 深度归档数据存储不会跨境传输。 | | x-obs-restore | String | **参数解释：** 标识对象的恢复状态。 示例：正在恢复ongoing-request="true"；已恢复 ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT"。其中expiry-date表示对象恢复后的失效时间。 说明： - 仅当对象为归档存储或深度归档存储类型，并且处于正在恢复或已经恢复时，会返回此头域。 - 如果软链接的目标对象为归档或者深度归档类型，那么调用本接口查询软连接对象的信息，x-obs-restore会返回目标对象的恢复状态。 **取值范围：** 无 | | x-obs-object-type | String | **参数解释：** 对象的类型。仅当对象为非Normal对象时，会返回此头域。 **取值范围：** - Appendable：通过追加写生成的对象。 - Symlink：软链接对象。 | | x-obs-next-append-position | Integer | **参数解释：** 指明下一次请求应该提供的position。仅当对象为Appendable对象时，会返回此头域。 **取值范围：** 无 | | x-obs-uploadId | String | **参数解释：** 表示对应的多段任务ID。仅当对象由多段上传任务合而来时，会返回此头域。 **取值范围：** 无 | | x-obs-tagging-count | String | **参数解释：** 对象关联的标签个数。仅当有读取标签权限时返回。 示例：x-obs-tagging-count:1 **取值范围：** 无 | | x-obs-object-lock-mode | String | **参数解释：** 应用于此对象的WORM模式。仅当对象有配置过对象级WORM保护策略或应用桶级默认WORM策略时返回该参数。 示例：x-obs-object-lock-mode:COMPLIANCE 说明： 用户具有GetObjectRetention权限才可执行此操作。 **取值范围：** 目前仅支持COMPLIANCE，即合规模式。 | | x-obs-object-lock-retain-until-date | String | **参数解释：** 此对象的锁定过期的截止时间。仅当对象有配置过对象级WORM保护策略或应用桶级默认WORM策略时返回该参数。格式要求为UTC时间，并符合ISO 8601标准。 示例：x-obs-object-lock-retain-until-date:2015-07-01T04:11:15.297Z 说明： 用户具有GetObjectRetention权限才可执行此操作。 **取值范围：** 设置该值时需要大于当前时间。 | | x-obs-checksum-crc64ecma | UnsignedLong | **参数解释：** 按照ECMA-182标准计算出消息体的crc64值，采用64位无符号数编码。 示例：x-obs-checksum-crc64ecma: 11051210869376104954 **取值范围：** 无 | | x-obs-replication-status | String | **参数解释：** 对象的复制状态。仅记录最近一次的复制状态，不支持查看对象的历史复制状态。 **取值范围：** - FAILED： 源对象的状态，表示复制任务失败。 - COMPLETED： 源对象的状态，表示复制任务成功。 - REPLICA：目标对象的状态，表示该对象是副本对象。 | | Last-Modified | String | **参数解释：** 对象最近一次被修改的时间（UTC时间）。 **取值范围：** 长度大于0且不超过1024的字符串。 | #### 响应体 (Response Body) 该请求的响应消息中不带消息元素。 #### 错误响应消息 无特殊错误；所有错误已经包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。 #### 请求示例 ``` HEAD /object1 HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Wed, 01 Jul 2015 04:19:25 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:/cARjk81l2iExMfQqn6iT3qEZ74= ``` #### 响应示例 ``` HTTP/1.1 200 OK Server: OBS x-obs-request-id: 8DF400000163D3E4BB5905C41B6E65B6 Accept-Ranges: bytes ETag: "3b46eaf02d3b6b1206078bb86a7b7013" Last-Modified: Wed, 01 Jul 2015 01:19:21 GMT Content-Type: binary/octet-stream x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSD3nAiTaBoeyt9oHp9vTYtXnLDmwV6D Date: Wed, 01 Jul 2015 04:19:21 GMT Content-Length: 4572 ``` #### 请求示例：当Bucket启用版本控制时获取对象元数据 ``` HEAD /object1?versionId=G001118A49821905FFFFD28739D419DA HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: Wed, 01 Jul 2015 02:37:22 GMT Content-Type: application/xml ``` #### 响应示例：当Bucket启用版本控制时获取对象元数据 ``` HTTP/1.1 200 OK x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShLiL70qeT0g5qpMquCeztsnr1jJmRs Accept-Ranges: bytes x-obs-request-id: 0000018A4986DDCDD24538ACF6B54255 Server: OBS ETag: "3b46eaf02d3b6b1206078bb86a7b7013" x-obs-tagging-count: 0 Last-Modified: Thu, 31 Aug 2013 02:52:57 GMT Content-Length: 0 Date: Wed, 01 Jul 2015 02:37:22 GMT Content-Type: text/plain x-obs-version-id: G001118A49821905FFFFD28739D419DA ``` #### 使用SDK调用接口 建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。 | [Java](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0606.html) | [Python](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_0921.html) | [C](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_0404.html) | [Go](https://support.huaweicloud.com/sdk-go-devg-obs/obs_33_0920.html) | [BrowserJS](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_0506.html) | [.NET](https://support.huaweicloud.com/sdk-dotnet-devg-obs/obs_25_0407.html) | [Android](https://support.huaweicloud.com/sdk-android-devg-obs/obs_26_0406.html) | [iOS](https://support.huaweicloud.com/sdk-ios-devg-obs/obs_27_0405.html) | [PHP](https://support.huaweicloud.com/sdk-php-devg-obs/obs_28_0406.html) | [Node.js](https://support.huaweicloud.com/sdk-nodejs-devg-obs/obs_29_0406.html) | |---|---|---|---|---|---|---|---|---|---| #### 相关文档 - 使用obsutil获取对象元数据，请参见[查看对象属性](https://support.huaweicloud.com/utiltg-obs/obs_11_0015.html)。 - 了解更多获取对象元数据相关介绍，请参见[配置、编辑、查看对象元数据](https://support.huaweicloud.com/usermanual-obs/obs_03_0324.html)。 - API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。