tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    GET Object

    最后更新时间：2023-12-21 14:31:55
    下载PDF

      功能描述

      GET Object 接口请求可以将 COS 存储桶中的对象（Object）下载至本地。该 API 的请求者需要对目标对象有读取权限，或者目标对象向所有人开放了读取权限（公有读）。
      注意
      如果使用了 response-* 请求参数，那么该请求操作不支持匿名请求，必须携带签名。
      当通过 COS 控制台 设置回源 ，但未开启同步回源时，需注意，COS 从用户配置的源站拉取数据时，发起 GET Object 请求将返回 302 并重定向到设置的回源地址（如果该回源地址是不受信任的，强烈建议在使用 SDK 或自行调用 API 时，不要直接跟随 302，而应该由业务后端验证回源地址的合法性后再去请求回源地址，否则可能产生 SSRF 等安全风险，例如回源到一个内网地址）。
      

      版本控制

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

      归档类型

      如果该 GET 请求操作的对象为归档存储和深度归档存储类型，且没有使用 POST Object restore 进行恢复（或恢复后的副本已被过期删除），那么该请求将返回 HTTP 响应码403（Forbidden），同时在响应体中包含错误信息，其中错误码（Code）为 InvalidObjectState，表示对象的当前状态无法被 GET 请求操作，需要先经过恢复。

      请求

      请求示例

      GET /<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（详情请参见 请求签名 文档）。

      请求参数

      名称
      描述
      类型
      是否必选
      response-cache-control
      设置响应中的 Cache-Control 头部的值
      string
      否
      response-content-disposition
      设置响应中的 Content-Disposition 头部的值
      string
      否
      response-content-encoding
      设置响应中的 Content-Encoding 头部的值
      string
      否
      response-content-language
      设置响应中的 Content-Language 头部的值
      string
      否
      response-content-type
      设置响应中的 Content-Type 头部的值
      string
      否
      response-expires
      设置响应中的 Expires 头部的值
      string
      否
      versionId
      当启用版本控制时，指定要下载的版本 ID，如不指定则下载对象的最新版本
      string
      否

      请求头

      此接口除使用公共请求头部外，还支持以下请求头部，了解公共请求头部详情请参见 公共请求头部 文档。
      名称
      描述
      类型
      是否必选
      Range
      RFC 2616 中定义的字节范围，范围值必须使用 bytes=first-last 格式且仅支持单一范围，不支持多重范围。first 和 last 都是基于0开始的偏移量。
      例如 bytes=0-9，表示下载对象的开头10个字节的数据；bytes=5-9，表示下载对象的第6到第10个字节。此时返回 HTTP 状态码206（Partial Content）及 Content-Range 响应头部。
      如果 first 超过对象的大小，则返回 HTTP 状态码416（Requested Range Not Satisfiable）错误。如果不指定，则表示下载整个对象
      string
      否
      If-Modified-Since
      当对象在指定时间后被修改，则返回对象，否则返回 HTTP 状态码为304（Not Modified）
      string
      否
      If-Unmodified-Since
      当对象在指定时间后未被修改，则返回对象，否则返回 HTTP 状态码为412（Precondition Failed）
      string
      否
      If-Match
      当对象的 ETag 与指定的值一致，则返回对象，否则返回 HTTP 状态码为412（Precondition Failed）
      string
      否
      If-None-Match
      当对象的 ETag 与指定的值不一致，则返回对象，否则返回 HTTP 状态码为304（Not Modified）
      string
      否
      x-cos-traffic-limit
      针对本次下载进行流量控制的限速值，必须为数字，单位默认为 bit/s。限速值设置范围为819200 - 838860800，即100KB/s - 100MB/s，如果超出该范围将返回400错误
      integer
      否
      服务端加密相关头部
      如果指定的对象使用了服务端加密且加密方式为 SSE-C 时，则需要指定服务端加密的相关头部来解密对象，请参见 服务端加密专用头部。

      请求体

      此接口无请求体。

      响应

      响应头

      此接口除返回公共响应头部外，还返回以下响应头部，了解公共响应头部详情请参见 公共响应头部 文档。
      名称
      描述
      类型
      Cache-Control
      RFC 2616 中定义的缓存指令，仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
      string
      Content-Disposition
      RFC 2616 中定义的文件名称，仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
      string
      Content-Encoding
      RFC 2616 中定义的编码格式，仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
      string
      Content-Range
      RFC 2616 中定义的返回内容的字节范围，仅当请求中指定了 Range 请求头部时才会返回该头部
      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。
      enum
      版本控制相关头部
      启用版本控制的存储桶内的对象将返回下列响应头部：
      名称
      描述
      类型
      x-cos-version-id
      对象的版本 ID
      string
      服务端加密相关头部
      如果指定的对象使用了服务端加密，则此接口将返回服务端加密专用头部，请参见 服务端加密专用头部。

      响应体

      此接口请求的响应体为对象（文件）内容。

      错误码

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

      实际案例

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

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 09:35:16 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511316;1586518516&q-key-time=1586511316;1586518516&q-header-list=date;host&q-url-param-list=&q-signature=1bd1898e241fb978df336dc68aaef4c0acae****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Accept-Ranges: bytes
      Date: Fri, 10 Apr 2020 09:35:16 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 09:35:05 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDNkZDRfZDgyNzVkNjRfN2Q5M18xOWVi****
      
      
      
      [Object Content]

      案例二：通过请求参数指定响应头部

      请求

      GET /exampleobject?response-content-type=application%2Foctet-stream&response-cache-control=max-age%3D86400&response-content-disposition=attachment%3B%20filename%3Dexample.jpg HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 09:35:17 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511317;1586518517&q-key-time=1586511317;1586518517&q-header-list=date;host&q-url-param-list=response-cache-control;response-content-disposition;response-content-type&q-signature=4fcea9f80bc67fe475dff746eca0b9abff6a****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: application/octet-stream
      Content-Length: 16
      Connection: close
      Accept-Ranges: bytes
      Cache-Control: max-age=86400
      Content-Disposition: attachment; filename=example.jpg
      Date: Fri, 10 Apr 2020 09:35:17 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 09:35:05 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDNkZDVfNjZjODJhMDlfMTY2MDdfMThm****
      
      
      
      [Object Content]

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

      请求

      GET /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=20e39095b9f22ae1279bec2a3375b527c32d****
      Connection: close

      响应

      HTTP/1.1 304 Not Modified
      Content-Type: image/jpeg
      Content-Length: 0
      Connection: close
      Date: Wed, 29 Jul 2020 06:51:49 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWYyMTFjODVfOGZiNzJhMDlfNDcxZjZfZDY2****

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

      请求

      GET /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=1437a0d094c4e0f8e26909d35b2cca83dcbf****
      Connection: close

      响应

      HTTP/1.1 412 Precondition Failed
      Content-Type: application/xml
      Content-Length: 480
      Connection: close
      Date: Wed, 29 Jul 2020 06:51:50 GMT
      Server: tencent-cos
      x-cos-request-id: NWYyMTFjODZfOGRjOTJhMDlfMmIyMWVfOTJl****
      
      
      
      <?xml version='1.0' encoding='utf-8' ?>
      <Error>
                  <Code>PreconditionFailed</Code>
                  <Message>Precondition not match.</Message>
                  <Resource>examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Resource>
                  <RequestId>NWYyMTFjODZfOGRjOTJhMDlfMmIyMWVfOTJl****</RequestId>
                  <TraceId>OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODc0OWRkZjk0ZDM1NmI1M2E2MTRlY2MzZDhmNmI5MWI1OTdjMDczODYwZjM5YTU3ZmZmOWI5MmY4NjkxY2I3MGNiNjkyOWZiNzUxZjg5MGY2OWU4NmI0YWMwNTlhNTExYWU=</TraceId>
      </Error>

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

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 09:36:00 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511360;1586518560&q-key-time=1586511360;1586518560&q-header-list=date;host&q-url-param-list=&q-signature=6f9ec1af1aa86abd5b484b41ae1378850ad2****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Accept-Ranges: bytes
      Date: Fri, 10 Apr 2020 09:36:00 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 09:35:49 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDNlMDBfMzdiMDJhMDlfYTgyNl8xNjA2****
      x-cos-server-side-encryption: AES256
      
      
      
      [Object Content]

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

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 09:36:11 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511371;1586518571&q-key-time=1586511371;1586518571&q-header-list=date;host&q-url-param-list=&q-signature=bdadbe917a50feeb8dddf8c75642be172720****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Accept-Ranges: bytes
      Date: Fri, 10 Apr 2020 09:36:11 GMT
      ETag: "840af7c921f4b3230049af8663145bd0"
      Last-Modified: Fri, 10 Apr 2020 09:36:01 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDNlMGJfZGEyNzVkNjRfZDgxY18xYTBj****
      x-cos-server-side-encryption: cos/kms
      x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****
      
      
      
      [Object Content]

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

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 09:36:23 GMT
      x-cos-server-side-encryption-customer-algorithm: AES256
      x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
      x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511383;1586518583&q-key-time=1586511383;1586518583&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=7da5c304f9439df949b6550ab23aea67a5f0****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Accept-Ranges: bytes
      Date: Fri, 10 Apr 2020 09:36:23 GMT
      ETag: "582d9105f71525f3c161984bc005efb5"
      Last-Modified: Fri, 10 Apr 2020 09:36:12 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDNlMTdfNzBiODJhMDlfZTVmMV8xNDAy****
      x-cos-server-side-encryption-customer-algorithm: AES256
      x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
      
      
      
      [Object Content]

      案例八：下载对象最新版本（启用版本控制）

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 12:30:02 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586521802;1586529002&q-key-time=1586521802;1586529002&q-header-list=date;host&q-url-param-list=&q-signature=51b3c33f4cfae5d7b31ad61a974db7374f39****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 26
      Connection: close
      Accept-Ranges: bytes
      Date: Fri, 10 Apr 2020 12:30:02 GMT
      ETag: "22e024392de860289f0baa7d6cf8a549"
      Last-Modified: Fri, 10 Apr 2020 12:29:52 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 11596229263574363878
      x-cos-request-id: NWU5MDY2Y2FfMzFiYjBiMDlfMjE2NzVfMTgz****
      x-cos-version-id: MTg0NDUxNTc1NTE5MTc1NjM4MDA
      
      
      
      [Object Content Version 2]

      案例九：下载对象指定版本（启用版本控制）

      请求

      GET /exampleobject?versionId=MTg0NDUxNTc1NjIzMTQ1MDAwODg HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 09:36:45 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586511405;1586518605&q-key-time=1586511405;1586518605&q-header-list=date;host&q-url-param-list=versionid&q-signature=31aeb69334b973ef7406300a182de0645c91****
      Connection: close

      响应

      HTTP/1.1 200 OK
      Content-Type: image/jpeg
      Content-Length: 16
      Connection: close
      Accept-Ranges: bytes
      Date: Fri, 10 Apr 2020 09:36:45 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 09:36:35 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDNlMmRfNzBiODJhMDlfZTYwZl8xM2Fh****
      x-cos-version-id: MTg0NDUxNTc1NjIzMTQ1MDAwODg
      
      
      
      [Object Content]

      案例十：指定 Range 请求头部下载部分内容

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Fri, 10 Apr 2020 12:32:37 GMT
      Range: bytes=8-14
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1586521957;1586529157&q-key-time=1586521957;1586529157&q-header-list=date;host;range&q-url-param-list=&q-signature=719273479357f4b4b4c7d4f5ceb631753101****
      Connection: close

      响应

      HTTP/1.1 206 Partial Content
      Content-Type: image/jpeg
      Content-Length: 7
      Connection: close
      Accept-Ranges: bytes
      Content-Range: bytes 8-14/16
      Date: Fri, 10 Apr 2020 12:32:37 GMT
      ETag: "ee8de918d05640145b18f70f4c3aa602"
      Last-Modified: Fri, 10 Apr 2020 12:32:25 GMT
      Server: tencent-cos
      x-cos-hash-crc64ecma: 16749565679157681890
      x-cos-request-id: NWU5MDY3NjVfY2VjODJhMDlfOWVlZl8xNmMy****
      
      
      
      Content

      案例十一：下载未经恢复的归档（ARCHIVE）存储类型的对象

      请求

      GET /exampleobject HTTP/1.1
      Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
      Date: Thu, 26 Dec 2019 11:57:24 GMT
      Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1577361444;1577368644&q-key-time=1577361444;1577368644&q-header-list=date;host&q-url-param-list=&q-signature=d975dc7097b2dbffcf2ba001e6dec25dd80a****
      Connection: close
      

      响应

      HTTP/1.1 403 Forbidden
      Content-Type: application/xml
      Content-Length: 513
      Connection: close
      Date: Thu, 26 Dec 2019 11:57:24 GMT
      Server: tencent-cos
      x-cos-request-id: NWUwNGEwMjRfZDcyNzVkNjRfNjZlM183Zjcx****
      x-cos-storage-class: ARCHIVE
      
      
      
      <?xml version='1.0' encoding='utf-8' ?>
      <Error>
                  <Code>InvalidObjectState</Code>
                  <Message>The operation is not valid for the object storage class.</Message>
                  <Resource>examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Resource>
                  <RequestId>NWUwNGEwMjRfZDcyNzVkNjRfNjZlM183Zjcx****</RequestId>
                  <TraceId>OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODc0OWRkZjk0ZDM1NmI1M2E2MTRlY2MzZDhmNmI5MWI1OTBjNjIyOGVlZmJlNDg4NDQ1MzAzMjA2ZDg4OGQ3MDhlMjIzYjI1ZWUwODY5YjdlMTBjY2EwNTgyZWMyMjc0Mjc=</TraceId>
      </Error>
      
      联系我们

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

      联系我们
      技术支持

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

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