tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    HEAD Object

    最后更新时间：2024-09-27 19:12:21
    下载PDF

      功能描述

      HEAD Object 接口请求可以判断指定对象是否存在和有权限，并在指定对象可访问时获取其元数据。该 API 的请求者需要对目标对象有读取权限，或者目标对象向所有人开放了读取权限（公有读）。
      

      授权说明

      授权策略中 action 设置为 cos:HeadObject 。查看所有 action。

      版本控制

      当启用版本控制时，该 HEAD 操作可以使用 versionId 请求参数指定要返回的版本 ID，此时将返回指定版本的元数据，如指定版本为删除标记则返回 HTTP 响应码404（Not Found），否则将返回最新版本的元数据。

      请求

      请求示例

      HEAD /<ObjectKey> HTTP/1.1
      Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
      Date: GMT Date
      Authorization: Auth String
      说明
      Host: <BucketName-APPID>.cos.<Region>.myqcloud.com，其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字，例如 examplebucket-1250000000，可参阅 存储桶概览 > 基本信息 和 存储桶概述 > 存储桶命名规范 文档；<Region> 为 COS 的可用地域，可参阅 地域和访问域名 文档。
      Authorization: Auth String（详情请参见 请求签名 文档）。

      请求参数

      名称
      描述
      类型
      是否必选
      versionId
      当启用版本控制时，指定要查询的版本 ID，如不指定则查询对象的最新版本
      string
      否

      请求头

      此接口除使用公共请求头部外，还支持以下请求头部，了解公共请求头部详情请参见 公共请求头部 文档。
      名称
      描述
      类型
      是否必选
      If-Modified-Since
      当对象在指定时间后被修改，则返回 HTTP 状态码为200（OK），否则返回 HTTP 状态码为304（Not Modified）
      string
      否
      If-Unmodified-Since
      当对象在指定时间后未被修改，则返回 HTTP 状态码为200（OK），否则返回 HTTP 状态码为412（Precondition Failed）
      string
      否
      If-Match
      当对象的 ETag 与指定的值一致，则返回 HTTP 状态码为200（OK），否则返回 HTTP 状态码为412（Precondition Failed）
      string
      否
      If-None-Match
      当对象的 ETag 与指定的值不一致，则返回 HTTP 状态码为200（OK），否则返回 HTTP 状态码为304（Not Modified）
      string
      否
      服务端加密相关头部
      如果指定的对象使用了服务端加密且加密方式为 SSE-C 时，则需要指定服务端加密的相关头部来解密对象，请参见 服务端加密专用头部。

      请求体

      此接口无请求体。

      响应

      响应头

      此接口除返回公共响应头部外，还返回以下响应头部，了解公共响应头部详情请参见 公共响应头部 文档。
      名称
      描述
      类型
      Cache-Control
      RFC 2616 中定义的缓存指令，仅当对象元数据包含此项时才会返回该头部
      string
      Content-Disposition
      RFC 2616 中定义的文件名称，仅当对象元数据包含此项时才会返回该头部
      string
      Content-Encoding
      RFC 2616 中定义的编码格式，仅当对象元数据包含此项时才会返回该头部
      string
      Expires
      RFC 2616 中定义的缓存失效时间，仅当对象元数据包含此项时才会返回该头部
      string
      x-cos-meta-*
      包括用户自定义元数据头部后缀和用户自定义元数据信息
      string
      x-cos-storage-class
      对象存储类型，枚举值请参见 存储类型 文档，例如 MAZ_STANDARD，MAZ_STANDARD_IA，INTELLIGENT_TIERING，MAZ_INTELLIGENT_TIERING，STANDARD_IA，ARCHIVE，DEEP_ARCHIVE。仅当对象不是标准存储（STANDARD）时才会返回该头部
      enum
      x-cos-storage-tier
      当对象的存储类型为智能分层存储时，该头部表示对象所处的存储层，有效值：
      FREQUENT
      INFREQUENT
      ARCHIVE_ACCESS
      DEEP_ARCHIVE_ACCESS
      enum

      归档类型对象相关头部

      当对象为归档类型且使用 POST Object restore 请求进行恢复操作时，该 HEAD 请求将返回下列响应头部：
      名称
      描述
      类型
      x-cos-restore
      指示当前恢复操作的状态：
      当恢复操作正在进行中时，该响应头部的值为ongoing-request="true"
      当对象已经恢复时，该响应头部包含 COS 即将删除临时副本的时间，例如ongoing-request="false", expiry-date="Tue, 19 Nov 2019 16:00:00 GMT"
      string
      x-cos-restore-status
      当恢复操作正在进行中时返回该响应头部，指示当前的恢复模式、恢复操作请求时间和恢复预期完成时间，例如tier="standard"; request-date="Mon, 18 Nov 2019 09:34:50 GMT";expect-restore-date="Fri, 27 Dec 2019 08:20:00 GMT"，有关恢复模式请参见 POST Object restore
      说明：
      仅归档类型对象支持展示恢复预期完成时间，深度归档对象不支持展示恢复预期完成时间。
      string
      版本控制相关头部
      启用版本控制的存储桶内的对象将返回下列响应头部：
      名称
      描述
      类型
      x-cos-version-id
      对象的版本 ID
      string
      服务端加密相关头部
      如果指定的对象使用了服务端加密，则此接口将返回服务端加密专用头部，请参见 服务端加密专用头部。
      
      存储桶复制相关头部
      如果对象是存储桶复制的源对象或目标对象，将返回下列响应头部。
      名称
      描述
      类型
      x-cos-replication-status
      当前的复制状态。源对象显示 Pending（待复制）、Failed（复制失败）、Complete（复制成功）；目标对象显示 Replica。
      string

      响应体

      此接口响应体为空。

      错误码

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

      实际案例

      案例一：简单案例（未启用版本控制）

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 18:17:36 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586542656;1586549856&q-key-time=1586542656;1586549856&q-header-list=date;host&q-url-param-list=&q-signature=cde88925e00d1c90ba74985ca43b610bdf6b****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Date: Fri, 10 Apr 2020 18:17:36 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 18:17:25 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MGI4NDBfNjFjODJhMDlfMzY2NjVfMjNi****

      案例二：通过请求头指定查询条件并返回 HTTP 状态码为304（Not Modified）

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Wed, 29 Jul 2020 06:51:49 GMT
      If-None-Match: "ee8de918d05640145b18f70f4c3aa602"
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1596005509;1596012709&q-key-time=1596005509;1596012709&q-header-list=date;host;if-none-match&q-url-param-list=&q-signature=9d087f05c259ca271efe91fc780cdced75c6****
      Connection: close

      响应

      HTTP/1.1 304 Not Modified
      Content-Type: application/xml
      Content-Length: 0
      Connection: close
      Date: Wed, 29 Jul 2020 06:51:49 GMT
      Server: tencent-cos
      x-cos-request-id: NWYyMTFjODVfZDNjODJhMDlfMWU1MWVfOTUy****
      x-cos-trace-id: OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODczNTBmNjMwZmQ0MTZkMjg0NjlkNTYyNmY4ZTRkZTk0NzJmZTI0ZmJhYTZmZjYyNmU5ZGNlZDI5YjkyODkwYjNhZjhlNGQ0MDY1ZGIxNDEwMWYwOTg1NDc4Mzg4MTE3****

      案例三：通过请求头指定查询条件并返回 HTTP 状态码为412（Precondition Failed）

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Wed, 29 Jul 2020 06:51:50 GMT
      If-Match: "aa488bb80185a6be87f4a7b936a80752"
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1596005510;1596012710&q-key-time=1596005510;1596012710&q-header-list=date;host;if-match&q-url-param-list=&q-signature=38afe94fc61ca0b3aa763e00b23fd90ac23e****
      Connection: close

      响应

      HTTP/1.1 412 Precondition Failed
      Content-Type: application/xml
      Content-Length: 0
      Connection: close
      Date: Wed, 29 Jul 2020 06:51:50 GMT
      Server: tencent-cos
      x-cos-request-id: NWYyMTFjODZfMzBjMDJhMDlfMmU3ZF9kYTE4****
      x-cos-trace-id: OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODczNTBmNjMwZmQ0MTZkMjg0NjlkNTYyNmY4ZTRkZTk0NzJmZTI0ZmJhYTZmZjYyNmU5ZGNlZDI5YjkyODkwYjNhZDRkOWFlZjczOWExNjZmY2RiNjhjNGIwZWQ3YjYw****

      案例四：使用服务端加密 SSE-COS

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 18:18:19 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586542699;1586549899&q-key-time=1586542699;1586549899&q-header-list=date;host&q-url-param-list=&q-signature=6a6d4dd5b5a9e6379f300715985bfb60b947****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Date: Fri, 10 Apr 2020 18:18:19 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 18:18:08 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MGI4NmJfNmRjMDJhMDlfZGQwNl8xZmE4****
      x-cos-server-side-encryption: AES256

      案例五：使用服务端加密 SSE-KMS

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 18:18:30 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586542710;1586549910&q-key-time=1586542710;1586549910&q-header-list=date;host&q-url-param-list=&q-signature=7c8a1c93b9701e653c2ab00419f976397d00****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Date: Fri, 10 Apr 2020 18:18:30 GMT
      ETag: "00ca268468481b847fc2d8a9bd84578d"
      Last-Modified: Fri, 10 Apr 2020 18:18:19 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MGI4NzZfN2FjODJhMDlfMjU3N18xYTEz****
      x-cos-server-side-encryption: cos/kms
      x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****
      

      案例六：使用服务端加密 SSE-C

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 18:18:41 GMT
      x-cos-server-side-encryption-customer-algorithm: AES256
      x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNE****
      x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG****
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586542721;1586549921&q-key-time=1586542721;1586549921&q-header-list=date;host;x-cos-server-side-encryption-customer-algorithm;x-cos-server-side-encryption-customer-key;x-cos-server-side-encryption-customer-key-md5&q-url-param-list=&q-signature=99ad258fc295f43feb0546bb2346c8269dc5****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Date: Fri, 10 Apr 2020 18:18:41 GMT
      ETag: "582d9105f71525f3c161984bc005efb5"
      Last-Modified: Fri, 10 Apr 2020 18:18:31 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MGI4ODFfN2NiODJhMDlfMmFmYTVfMWRh****
      x-cos-server-side-encryption-customer-algorithm: AES256
      x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG****

      案例七：请求对象最新版本（启用版本控制）

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 18:19:15 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586542755;1586549955&q-key-time=1586542755;1586549955&q-header-list=date;host&q-url-param-list=&q-signature=7909dc19780873dfaa51c8b238254098ca1a****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 26
      Connection: close
      Date: Fri, 10 Apr 2020 18:19:15 GMT
      ETag: "22e024392de860289f0baa7d6cf8a549"
      Last-Modified: Fri, 10 Apr 2020 18:19:04 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 11596229263574363878
      x-cos-request-id: NWU5MGI4YTNfZDZjODJhMDlfYmU0MV8xM2Y5****
      x-cos-version-id: MTg0NDUxNTc1MzA5NjQ2ODI5MTg

      案例八：请求对象指定版本（启用版本控制）

      请求

      HEAD /exampleobject?versionId=MTg0NDUxNTc1MzA5NzU4ODg1Mjg HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 18:19:04 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586542744;1586549944&q-key-time=1586542744;1586549944&q-header-list=date;host&q-url-param-list=versionid&q-signature=1307acd3e8649087c738ecca452a54fa5a79****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Date: Fri, 10 Apr 2020 18:19:04 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 18:18:53 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MGI4OThfN2RiNDBiMDlfMTk1MTBfMWZj****
      x-cos-version-id: MTg0NDUxNTc1MzA5NzU4ODg1Mjg

      案例九：归档存储正在恢复中

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 27 Dec 2019 08:19:35 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1577434775;1577441975&q-key-time=1577434775;1577441975&q-header-list=date;host&q-url-param-list=&q-signature=72408a09a5fc00d77d389559a0cfa5c98e31****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 13
      Connection: close
      Date: Fri, 27 Dec 2019 08:19:35 GMT
      ETag: "b62e10bcab55a88240bd9c436cffdcf9"
      Last-Modified: Fri, 27 Dec 2019 08:19:23 GMT
      Server: tencent-cos
      x-cos-request-id: NWUwNWJlOTdfN2VjODJhMDlfOGI1N18yYjYz****
      x-cos-restore: ongoing-request="true"
      x-cos-restore-status: tier="expedited"; request-date="Fri, 27 Dec 2019 08:19:29 GMT"
      x-cos-storage-class: ARCHIVE

      案例十：归档存储已恢复

      请求

      HEAD /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Thu, 02 Jan 2020 18:09:51 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1577988591;1577995791&q-key-time=1577988591;1577995791&q-header-list=date;host&q-url-param-list=&q-signature=ff23b3a44945f019916450add646e963c29b****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Date: Fri, 10 Apr 2020 18:17:36 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 18:17:25 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MWRiZjFfMmViMDJhMDlfNjIwOF8zNTU0****
      x-cos-restore: ongoing-request="false", expiry-date="Mon, 13 Apr 2020 16:00:00 GMT"
      x-cos-storage-class: ARCHIVE
      
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款