1. 首页
  2. 对象存储
  3. S3 API
搜索ing...

S3 API

基于 AWS 架构的 S3 API，您可以使用任何编程语言发送 HTTP/HTTPS 请求与云存储通信。特别地，又拍云仅支持文件相关API，不支持配置区域。

请求方法

  • 访问域名：s3.api.upyun.com
  • 路径风格：s3.api.upyun.com/<bucket>/<path_to_file>
  • 支持虚拟主机风格：<bucket>.s3.api.upyun.com/<path_to_file>
  • 鉴权方法：同时兼容 AWS Signature Version 2 和 AWS Signature Version 4。
  • 存储类型：又拍云对象存储支持使用 S3 协议对标准、低频访问两种存储类型进行操作。

兼容公共头

公共请求头

请求头 说明
Authorization 兼容
Content-Length 兼容
Content-MD5 兼容
Content-Type 兼容
Date 兼容
Expect 兼容
Host 兼容
x-amz-content-sha256 兼容
x-amz-date 兼容
x-amz-security-token 不兼容

公共响应头

请求头 说明
Content-Length 兼容
Content-Type 兼容
Connection 兼容
Date 兼容
ETag 兼容
Server 兼容
x-amz-delete-marker 暂不支持
x-amz-request-id 兼容
x-amz-id-2 不兼容
x-amz-version-id 暂不支持

获取空间

获取签名中 AccessKey 所属账户的存储空间列表

请求信息

语法

GET / HTTP/1.1 
Host: s3.api.upyun.com
Date: date 
Authorization: authorization string

请求参数

该请求操作不使用任何请求参数。

请求头

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅「公共请求头」。

请求内容

该请求操作的请求体为空。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 说明
Bucket 存储空间信息的容器类
Buckets 存储空间列表的容器类
CreationDate 存储空间的创建时间
DisplayName 存储空间所有者的别称
ID 存储空间所有者的规范用户ID
ListAllMyBucketsResult 响应容器类
Name 存储空间名称
Owner 存储空间所有者信息的容器类

响应状态码

  • 成功：返回 200 状态码。

  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

GET / HTTP/1.1
Host: s3.api.upyun.com
Date: Mon, 10 Jul 2023 03:20:29 GMT
Authorization: authorization string


HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
        <ID>upyun</ID>
        <DisplayName></DisplayName>
    </Owner>
    <Buckets>
        <Bucket>
            <Name>Example-Bucket</Name>
            <CreationDate>2023-03-01T12:09:08.000Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>

文件列举

列出指定 bucket 下的所有文件，包括目录及目录下级文件

请求信息

语法

GET /?list-type=2 HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string

请求参数

请根据需要对请求参数进行 url 编码。请求只支持根目录，不支持列单个文件路径。

参数 必选 类型 说明
list-type 是 String API 的第二版本要求使用该参数，并且值必须设置为 2。
max-keys 否 String 返回资源的最大数量。默认值为 1000。
prefix 否 String 指定前缀，只有资源名匹配该前缀的资源会被列出。默认值为空字符串。
delimiter 否 String 指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。默认值为空字符串。
Content-Secret 否 String 当 API 调用的响应被截断（即 IsTruncated 响应元素的值为true）时，响应还包括NextContinuationToken元素。要列出下一组对象，您可以在下一个请求中使用NextContinuationToken元素作为continuation-token。

请求头

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅「公共请求头」。

请求内容

该请求操作的请求体为空。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 类型 说明
Delimiter String 指定目录分隔符。
IsTruncated Boolean 返表示是否还有更多可返回的资源。当所有结果都已返回时，该参数设为false；当还有更多资源可返回时，该参数设为true。如果结果数量超过了MaxKeys指定的数量，可能不会返回所有结果。
MaxKeys String 返回的资源的最大数量。
Prefix String 以特定前缀开头的资源。
ContinuationToken String 如果请求中带有 Continuation-token，它将包含在响应中。
KeyCount String 返回响应中包含的资源的数量。该值始终小于或等于MaxKeys的值。
NextContinuationToken String 返如果响应被截断，S3 将返回此参数及其对应的续传令牌。您可以将该令牌作为 continuation-token 在下一个请求中指定，检索下一组资源。
CommonPrefixes String 将合并为公共前缀的资源计为单个返回，并列出充当子目录的资源。
ETag String 对象的 MD5 哈希值。ETag 仅反映对象内容的更改，而不包括其元数据的更改。
Key String 资源名称。
LastModified Date 对象的最后修改日期和时间。
Size String 对象的大小，以字节为单位。
StorageClass String 存储类别。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

GET /?list-type=2 HTTP/1.1 
Host: Example-Bucket.s3.api.upyun.com
X-Amz-Date: 20230628T063714Z
Authorization: authorization string
Content-Type: text/plain 

HTTP/1.1 200 OK 
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.upyun.com/doc/2006-03-01/">
   <Name>bucket</Name>
   <Prefix/>
   <KeyCount>205</KeyCount>
   <MaxKeys>1000</MaxKeys>
   <IsTruncated>false</IsTruncated>
   <Contents>
      <Key>my-image.jpg</Key>
      <LastModified>2022-10-12T17:50:30.0Z</LastModified>
      <ETag>&quot;fba9dede5f27731c9771645a39863328&quot;</ETag>
      <Size>434234</Size>
      <StorageClass>STANDARD</StorageClass>
   </Contents>
   <Contents>
      ...
   </Contents>
   ...
</ListBucketResult>

上传文件

用于在一次 HTTP 会话中上传单一的一个文件

请求信息

语法

PUT /ObjectName HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string

请求参数

该请求操作不使用任何请求参数。

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 必选 类型 说明
Content-Length 是 String 请求内容长度。
Content-MD5 否 String 上传文件的 MD5 值，如果请求中文件太大计算 MD5 不方便，可以为空。使用时请勿在使用请求体上传文件。
Content-Type 否 String 文件类型，默认使用文件扩展名作为文件类型。
x-amz-meta-x 否 String 文件元数据。
x-amz-storage-class 否 Enum 存储类别。默认标准型 STANDARD，暂不支持其它类型。

请求内容

该请求接受跟随二进制数据。

响应信息

响应头

参数 说明
ETag 资源内容的哈希值，用于表示对象内容的变化，而不是元数据的变化。ETag 的值并不总是对象数据的 MD5 值，具体取决于请求的方式。

响应内容

该请求操作的响应体为空。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

以下请求将 my-image.jpg 图像存储在 myBucket 存储桶中。

PUT /my-image.jpg HTTP/1.1
Host: myBucket.s3.api.upyun.com
Date: Mon, 10 Jul 2023 03:20:29 GMT
Authorization: authorization string 
Content-Type: text/plain 
Content-Length: 11434 
x-amz-meta-author: Janet
Expect: 100-continue

分片上传

分片限制

限制项 规格
文件大小 150 GB
Part 数量 1~10,000
Part 编号 1 ~ 10,000
单个Part大小 1MB 到 10 MB。分片上传的最后一个 Part 不能大于其他 Part 。
单次ListParts请求返回Part的最大数量 1000 个

初始化任务

初始化分块上传任务，并得到全局唯一任务 UploadId，后续分块任务相关接口都需要 UploadId 作为请求参数。

请求信息

语法

POST /ObjectName?uploads HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string

请求参数

该操作的实现不使用请求参数。

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 必选 类型 说明
Content-Length 是 String 请求内容长度。
Content-MD5 否 String 上传文件的 MD5 值，如果请求中文件太大计算 MD5 不方便，可以为空。使用时请勿在使用请求体上传文件。
Content-Type 否 String 文件类型，默认使用文件扩展名作为文件类型。
x-amz-meta-x 否 String 文件元数据。
x-amz-storage-class 否 Enum 存储类别。默认标准型 STANDARD，暂不支持其它类型。

请求内容

该请求操作的请求体为空。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 类型 说明
InitiateMultipartUploadResult Container 响应的容器类。
Bucket String 空间名称。
Key String 资源名称。
UploadId String 初始化任务生成的ID。 上传分片 UploadPart API调用时用作请求参数 。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

这个操作为 “/test/v.mp4” 对象启动了一个分片上传任务。

POST /test/v.mp4?uploads HTTP/1.1 
Host: Example-Bucket.s3.api.upyun.com
X-Amz-Date: 20230629T022904Z
Content-Type: text/plain
Authorization: authorization string 


HTTP/1.1 200 OK 
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>Example-Bucket</Bucket>
    <Key>test/video.mp4</Key>
    <UploadId>e3868700-018b-41a3-8a9a-e093b7a22fc4</UploadId>
</InitiateMultipartUploadResult>

上传分片

分块上传数据，需指定的任务 UploadId

请求信息

语法

PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Content-Length: Size
Authorization: authorization string
  • 使用同一个 PartNumber 上传了新的数据，那么服务端已有的这个号码的 Part 数据将被覆盖。

请求参数

参数 必选 说明
ObjectName 是 初始化分片任务的对象。
PartNumber 是 上传的分块编号。介于1和10,000之间的正整数。
UploadId 是 上传任务ID。可从初始化任务接口响应信息中获取。

请求头

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅「公共请求头」。

请求内容

该请求接受跟随二进制数据。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 说明
ETag 上传块内容的标识符，用来标识块， 完成分片上传接口调用时作为请求参数。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

以下的PUT请求在一个分片上传中上传了一个分块（分块编号为1）。该请求包括了在发起分块上传请求后得到的uploadId。

PUT /my-movie.m2ts?partNumber=1&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1 
Host: Example-Bucket.s3.api.upyun.com
Date: Wed, 12 Oct 2009 17:50:00 GMT 
Content-Length: 10485760 
Content-MD5: pUNXr/BjKK5G2UKvaRRrOA== 
Authorization: authorization string 

***part data omitted*** 

HTTP/1.1 200 OK 
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg== 
x-amz-request-id: 656c76696e6727732072657175657374 
Date: Mon, 1 Nov 2010 20:34:56 GMT 
ETag: "b54357faf0632cce46e942fa68356b38" 
Content-Length: 0
Connection: keep-alive 
Server: UPYUN

分片复制

实现将一个对象的分块内容从源路径复制到目标路径

请求信息

语法

PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
x-amz-copy-source: CopySource
x-amz-copy-source-range:bytes=first-last
Date: date
Content-Length: Size
Authorization: authorization string

请求参数

参数 必选 说明
ObjectName 是 初始化分片任务的对象。
PartNumber 是 上传的分块编号。它是一个介于1和10,000之间的正整数。
UploadId 是 上传任务ID。可从初始化任务接口响应信息中获取。

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 必选 说明
x-amz-copy-source 是 源对象的URL路径
x-amz-copy-source-range 否 指定源对象的字节范围，范围格式为 bytes=first-last，不指定范围则表示复制整个对象

请求内容

该请求没有请求内容。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 说明
ETag 上传块内容的标识符，用来标识块， CompleteMultipartUpload API调用时作为请求参数。
LastModified 返回对象最后修改时间。

响应状态码

  • 成功：返回200。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

请求样例

以下的PUT请求在一个分片上传中上传了一个分块（分块编号为2）。该请求指定现有对象的字节范围作为上传源。该请求包括了在发起分块上传请求后得到的uploadId。

PUT /newobject?partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.<Region>.amazonaws.com
Date:  Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
x-amz-copy-source-range:bytes=500-6291456
Authorization: authorization string

响应样例

响应包含 ETag 值。您需要保留此值，以便在发送完整分块上传请求时使用。

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date:  Mon, 11 Apr 2011 20:34:56 GMT
Server: UPYUN

<CopyPartResult>
    <LastModified>2011-04-11T20:34:56.000Z</LastModified>
    <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyPartResult>

完成分片上传

完成整个文件的分块上传，并将这些数据 Part 组合成一个完整的 Object。

请求信息

语法

POST /ObjectName?uploadId=UploadId HTTP/1.1
Host: <bucket>.s3.api.upyun.com
Date: date 
Content-Length: Size 
Authorization: authorization string

<CompleteMultipartUpload>
 <Part>
   <PartNumber>PartNumber</PartNumber>
   <ETag>ETag</ETag>
 </Part>
 ...
</CompleteMultipartUpload>
  • 用户提交的 Part 列表中，Part 号码可以不连续，但必须是升序。
  • 调用该请求成功后，该 UploadId 就会变成无效，再次请求与该 UploadId 相关操作都会失败。

请求参数

参数 必选 类型 说明
ObjectName 是 String 资源名称。
UploadId 是 String 上传任务ID。可从初始化任务接口响应信息中获取。

请求头

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅「公共请求头」。

请求内容

使用 XML 格式的数据。

参数 必选 类型 说明
PartNumber 是 Integer 上传的分块编号。可从上传分片接口响应信息中获取。
ETag 是 String 上传块的标识符。可从上传分片接口响应信息中获取。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 类型 说明
Bucket String 空间名称。
Key String 资源名称。
ETag String 上传块的标识符。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：该请求具有以下特殊错误：
状态码 错误代码 说明
400 Bad equest EntityTooSmall 上传对象小于允许的最小对象大小。每个分块的大小必须至少为1 MB。
400 Bad equest InvalidPart 指定的一个或多个分块无法找到。可能未上传该分块，或者指定的实体标签与该分块的实体标签不匹配。
400 Bad equest InvalidPartOrder 分块列表未按照分块号的升序排列。分块列表必须按照分块号的顺序进行指定。
404 Not Found NoSuchUpload 指定的分块上传不存在。上传ID可能无效，或者分块上传可能已中止或完成。

样例

请求样例

以下请求在CompleteMultipartUpload元素中指定了三个部分。

PUT /example-object?uploadId=AAAsb2FkIElEIGZvciBlbHZpbmcncyWeeS1tb3ZpZS5tMnRzIRRwbG9hZA HTTP/1.1 
Host: Example-Bucket.s3.api.upyun.com
Date: Wed, 12 Oct 2009 17:50:00 GMT 
Content-Length: 10485760 
Authorization: authorization string 


<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"0c78aef83f66abc1fale8477f296d394"</ETag>
  </Part>
  <Part>
    <PartNumber>3</PartNumber>
    <ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
  </Part>
</CompleteMultipartUpload>

响应样例

以下响应表明对象已成功组装。

HTTP/1.1 200 OK 
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg== 
x-amz-request-id: 656c76696e6727732072657175657374 
Date: Mon, 1 Nov 2010 20:34:56 GMT 
Connection: close 
Server: UPYUN

<?xml version="1.” encoding="UTF-8"?>
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Location>http://Example-Bucket.s3.upyun.com/Example-Object</Location>
  <Bucket>Example-Bucket</Bucket>
  <Key>Example-Object</Key>
  <ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
</CompleteMultipartUploadResult>

示例响应：标头中指定的错误

以下响应表明在发送 HTTP 响应标头之前发生了错误。

HTTP/1.1 403 Forbidden
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date:  Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 237
Connection: keep-alive
Server: UPYUN

<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
<RequestId>656c76696e6727732072657175657374</RequestId>
<HostId>Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==</HostId>
</Error>

示例响应：正文中指定的错误

以下响应表明发送 HTTP 响应头后发生错误。请注意，虽然 HTTP 状态代码为 200 OK，但请求实际上失败，如Error元素中所述。

 HTTP/1.1 200 OK
 x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
 x-amz-request-id: 656c76696e6727732072657175657374
 Date:  Mon, 1 Nov 2010 20:34:56 GMT
 Connection: close
 Server: UPYUN

 <?xml version="1.0" encoding="UTF-8"?>
 <Error>
  <Code>InternalError</Code>
  <Message>We encountered an internal error. Please try again.</Message>
  <RequestId>656c76696e6727732072657175657374</RequestId>
  <HostId>Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==</HostId>
 </Error>

取消分片上传

中止分块上传任务，并且删除已经上传的块，需指定的任务 UploadId

请求信息

句法

DELETE /ObjectName?uploadId=UploadId HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string
  • 当调用该 API 终止分片上传任务后，无法再使用这个 UploadId 做任何操作，已经上传的 Part 数据也会被删除。

请求参数

参数 必选 类型 说明
ObjectName 是 String 资源名称。
UploadId 是 String 上传任务ID。可从初始化任务接口响应信息中获取。

请求头

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅「公共请求头」。

请求内容

该请求没有请求正文。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

该请求操作的响应体为空。

响应状态码

  • 成功：返回 204 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

列举已上传分片

可列举出指定 UploadId 所属任务所有已经上传成功的分块信息

请求信息

句法

GET /ObjectName?max-parts=MaxParts&part-number-marker=PartNumberMarker&uploadId=UploadId HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string
  • 返回结果按照 PartNumber 升序排列。

请求参数

参数 必选 类型 说明
UploadId 是 String 上传任务ID。可从初始化任务接口响应信息中获取。
max-parts 否 Integer 响应中的最大 Part 数目。默认值 ：1,000，最大值 ：1,000。
part-number-marker 否 Integer 指定列举的起始位置，只有 PartNumber 值大于该参数的 Part 会被列出。默认值 ：无。

请求头

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅「公共请求头」。

请求内容

该请求操作的请求体为空。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 说明
Bucket 存储空间名称。
Key 资源名称。
UploadId 上传任务ID。
IsTruncated 表示是否还有更多可返回的资源。当所有结果都已返回时，该参数设为false；当还有更多资源可返回时，该参数设为true。如果结果数量超过了MaxKeys指定的数量，可能不会返回所有结果。
MaxParts 存储空间名称。
NextPartNumberMarker 当列表被截断时，此参数指定列表中的最后一部分，以及part-number-marker在后续请求中用于请求参数的值。
Owner 资源所有者。
Part 分片资源。
PartNumberMarker 指定列举的起始位置，只有 PartNumber 值大于该参数的 Part 会被列出。
StorageClass 存储对象的存储类别。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

获取文件

用于获取一个资源的元数据及对象数据，可以获取全部数据或者使用 Range 指定获取部分数据。

请求信息

语法

GET /ObjectName HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string
Range:bytes=byte_range

请求参数

该请求操作不使用任何请求参数。

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 必选 类型 说明
Authorization 是 String 请求认证所需的信息。

请求内容

该请求操作的请求体为空。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

参数 说明
x-amz-meta- 文件元数据。
x-amz-storage-class 存储类别。默认标准型 STANDARD，暂不支持其它类型。

响应内容

该请求操作的响应体为空。

响应状态码

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

GET /my-image.jpg HTTP/1.1 
Host: Example-Bucket.s3.api.upyun.com
Date: Mon, 10 Jul 2023 03:20:29 GMT
Authorization: authorization string

HTTP/1.1 200 OK  
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran 
x-amz-request-id: 318BC8BC148832E5 
Date: Mon, 10 Jul 2023 03:20:29 GMT 
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT 
ETag: "fba9dede5f27731c9771645a39863328" 
Content-Length: 434234 


[434234 bytes of object data]

获取文件元数据

用于获取资源的 Metadata 信息

请求信息

语法

HEAD /ObjectName HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Authorization: authorization string

请求参数

该请求操作不使用任何请求参数。

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 说明
Authorization 请求认证所需的信息。
Date 请求者当前的日期和时间。 示例：Wed, 01 Mar 2006 12:00:00 GMT。当您指定Authorization 头部时，您必须指定 x-amz-date 或 Date 头部中的一个。

请求内容

该请求操作的请求体为空。

响应信息

响应头

参数 说明
Last-Modified 最后修改时间。
ETag 资源内容的哈希值，用于表示对象内容的变化，而不是元数据的变化。ETag 的值并不总是对象数据的 MD5 值，具体取决于请求的方式。
x-amz-meta-x 文件元数据。
x-amz-storage-class 存储类别。

响应内容

该请求操作的响应体为空。

响应信息

  • 成功：返回 200 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

请求样例

以下请求返回对象的元数据。

HEAD /my-image.jpg HTTP/1.1 
Host:Example-Bucket.s3.api.upyun.com
Date: Wed, 12 Oct 2009 17:50:00 GMT 
Authorization: authorization string 

HTTP/1.1 200 OK 
x-amz-id-2: ef8yU9AS1ed4OpIszj7UDNEHGran 
x-amz-request-id: 318BC8BC143432E5 
x-amz-version-id: 3HL4kqtJlcpXroDTDmjVBH40Nrjfkd 
x-amz-storage-class: STANDARD
x-amz-meta-author: rick.wu Date: Wed, 28 Oct 2009 22:32:00 GMT 
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT 
ETag: "fba9dede5f27731c9771645a39863328" 
Content-Length: 434234 
Content-Type: text/plain 
Connection: close 
Server: UPYUN

删除文件

用于删除指定文件

请求信息

句法

DELETE /ObjectName HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
Content-Length: length
Authorization: authorization string

请求参数

该操作的实现不使用请求参数。

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 说明
Authorization 请求认证所需的信息。
Date 请求者当前的日期和时间。 示例：Wed, 01 Mar 2006 12:00:00 GMT。当您指定Authorization 头部时，您必须指定 x-amz-date 或 Date 头部中的一个。

请求内容

该请求操作的请求体为空。

响应信息

  • 成功：返回 204 状态码。
  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

DELETE /my-second-image.jpg HTTP/1.1 
Host: Example-Bucket.s3.api.upyun.com
Date: Wed, 12 Oct 2009 17:50:00 GMT 
Authorization: authorization string 
Content-Type: text/plain

HTTP/1.1 204 NoContent 
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 
x-amz-request-id: 0A49CE4060975EAC 
Date: Wed, 12 Oct 2009 17:50:00 GMT 
Content-Length: 0 
Connection: close 
Server: UPYUN

复制文件

本接口支持跨空间复制文件，将一个对象从源路径复制到目标路径

请求信息

句法

PUT /ObjectName HTTP/1.1 
Host: <bucket>.s3.api.upyun.com
Date: date 
x-amz-copy-source: CopySource
Authorization: authorization string

  • 文件不支持跨区域复制

  • 该操作限制 500M 以内的文件，超过限制的请使用分块复制。

请求参数

参数 必选 类型 说明
ObjectName 是 String 目标文件
bucket 是 String 目标存储桶

请求头

除了所有操作通用的请求头之外，操作的此实现还可以使用以下请求头。请求标头的大小限制在 8KB 以内。

参数 必选 类型 说明
x-amz-copy-source 是 String 源文件的URL路径

请求内容

该请求操作的请求体为空。

响应信息

响应头

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅「公共响应头」。

响应内容

参数 类型 说明
ETag String 新对象的MD5哈希值。ETag仅反映对象内容的更改，而不包括其元数据的更改。
LastModified Date 对象最后修改时间。

响应状态码

  • 成功：返回200 。

  • 失败：返回出错信息，具体请参阅「API 错误码表」。

样例

请求样例

以下示例将my-Image.jpg源文件复制到 bucket 桶中，目标文件是my-second-image.jpg。

PUT /my-second-image.jpg HTTP/1.1
Host: <bucket>.s3.api.upyun.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg
Authorization: authorization string

响应样例

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<CopyObjectResult>
   <LastModified>2009-10-12T17:50:30.000Z</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

更多复制操作请参考CopyObject。

这篇文章有帮助吗?

Yes No

相关文章