租户端 存储 对象存储（COS） COS API参考 下载对象

下载对象

最近更新时间: 2024-10-17 17:10:00

功能描述

GET Object 接口请求可以在 COS 的存储桶中将一个文件（对象）下载至本地。该操作需要请求者对目标对象具有读权限或目标对象对所有人都开放了读权限（公有读）。

请求

请求示例：

GET /<ObjectName> HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String

说明：

Authorization: Auth String (详细参见请求签名章节)。

请求行

GET /{ObjectName} HTTP/1.1

该 API 接口接受 GET 请求。

请求参数

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

请求头

公共头部

该请求操作的实现使用公共请求头，了解公共请求头详细请参见 公共请求头部 章节。

非公共头部

名称 类型 必选 描述
Range string 否 RFC 2616 中定义的指定文件下载范围，以字节（bytes）为单位
If-Unmodified-Since string 否 如果文件修改时间早于或等于指定时间，才返回文件内容。否则返回 412 (precondition failed)
If-Modified-Since string 否 当 Object 在指定时间后被修改，则返回对应 Object meta 信息，否则返回 304(not modified)
If-Match string 否 当 ETag 与指定的内容一致，才返回文件。否则返回 412 (precondition failed)
If-None-Match string 否 当 ETag 与指定的内容不一致，才返回文件。否则返回 304 (not modified)

请求体

该请求请求体为空。

响应

响应头

此接口除返回公共响应头部外，还返回以下响应头部，了解公共响应头部详情请参见 公共响应头部 文档。

名称 描述 类型
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 对象存储类型，例如 STANDARD_IA，ARCHIVE。仅当对象不是标准存储（STANDARD）时才会返回该头部 Enum

版本控制相关头部

启用版本控制的存储桶内的对象将返回下列响应头部：

名称 描述 类型
x-cos-version-id 对象的版本 ID string

响应体

下载成功，文件内容在响应体中。

错误码

错误码 描述 HHTP 状态码
InvalidArgument 提供的参数错误 400 Bad Request
SignatureDoesNotMatch 提供的签名不符合规则，返回该错误码 403 Forbidden
NoSuchKey 如果下载的文件不存在，返回该错误码 404 Not Found

实际案例

请求一

GET /123 HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 28 Oct 2014 22:32:00 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDWtTCBYjM5OwLB9CAwA1Qb2ThTSUjfGFO&q-sign-time=1484212200;32557108200&q-key-time=1484212200;32557108200&q-header-list=host&q-url-param-list=&q-signature=11522aa3346819b7e5e841507d5b7f156f34e639

响应一

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2014 22:32:00 GMT
Content-Type: application/octet-stream
Content-Length: 16087
Connection: keep-alive
Accept-Ranges: bytes
Content-Disposition: attachment; filename=\"filename.jpg\"
Content-Range: bytes 0-16086/16087
ETag: \"9a4802d5c99dafe1c04da0a8e7e166bf\"
Last-Modified: Wed, 28 Oct 2014 20:30:00 GMT
x-cos-request-id: NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ==

[Object]

请求二

携带 response-xxx 参数

GET /123?response-content-type=application%2fxml HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 28 Oct 2014 22:32:00 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDWtTCBYjM5OwLB9CAwA1Qb2ThTSUjfGFO&q-sign-time=1484212200;32557108200&q-key-time=1484212200;32557108200&q-header-list=host&q-url-param-list=&q-signature=11522aa3346819b7e5e841507d5b7f156f34e639

响应二

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2014 22:32:00 GMT
Content-Type: application/xml
Content-Length: 16087
Connection: keep-alive
Accept-Ranges: bytes
Content-Disposition: attachment; filename=\"filename.jpg\"
Content-Range: bytes 0-16086/16087
ETag: \"9a4802d5c99dafe1c04da0a8e7e166bf\"
Last-Modified: Wed, 28 Oct 2014 20:30:00 GMT
x-cos-request-id: NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ==

[Object]