多段上传

在本地客户端对文件进行分段处理。

1. 【可选】创建文件。此处我们构造一个20M大小的文件test.file，如果您已经准备好待上传的文件，可以跳过此步骤。

   Linux或macOS环境：

   dd if=/dev/urandom of=test.file bs=1M count=20

   Windows环境下打开命令提示符cmd，执行以下命令：

   fsutil file createnew test.file 20971520

2. 将文件进行分段。此处将20M大小的test.file文件，分为5个4M大小的分段，分段名为test-part**，**为00至04的数字后缀。

   Linux或macOS环境：

   split -b 4M -d test.file test-part

   Windows环境，请使用PowerShell运行以下命令：

   $inputFile = "test.file"
   $outputFilePrefix = "test-part"
   $chunkSize = 4MB
   
   $fs = [System.IO.File]::OpenRead($inputFile)
   $buffer = New-Object byte[] $chunkSize
   $fileNumber = 0
   
   while ($fs.Position -lt $fs.Length) {
   $bytesRead = $fs.Read($buffer, 0, $chunkSize)
   $outputFile = "{0}{1:D2}" -f $outputFilePrefix, $fileNumber
   $fileStream = [System.IO.File]::Create($outputFile)
   $fileStream.Write($buffer, 0, $bytesRead)
   $fileStream.Close()
   $fileNumber++
   }
   
   $fs.Close()

3. 拆分完成后，您能在执行该命令的目录中看到各个分段。每个分段都有一个与其分段编号对应的后缀，例如：

   

调用初始化上传段任务接口，获取多段上传任务ID。

1. 进入API Explorer的初始化上传段任务接口调试页面。
2. 填写API调用参数。

   参数名称	示例	说明
   object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字。
   bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶。
   uploads	置为空值	该参数表明本次API调用是一个分段上传任务，而不是普通的POST上传。单击“置为空值”将参数置空。

3. 单击“调试”。
4. 调用成功后，可在页面右下角查看响应结果，得到任务ID。

   如图所示本次任务的ID为“000001987D77252A002424CADFB90B1C”

   

将步骤一：文件分段中拆分的文件分段上传至桶中。

1. 进入API Explorer的上传段接口调试页面。
2. 填写API调用参数。

   

   参数名称	示例	说明
   object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字，与初始化中填写的对象名一致。
   bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶，与初始化中填写的桶名一致。
   partNumber	1	上传段的段编号，取值为从1到10000的整数。注意，段编号唯一地标示了段及其位置，每个段必须按照在对象中的位置有序编号，比如20M的对象分成5段，第一段编号为1，第二段编号为2，后面段的段编号必须大于前面的段。 如果您使用之前上传的段的同一段编号上传新段，则之前上传的段将被覆盖。
   uploadId	000001987D77252A002424CADFB90B1C	上传任务ID，与初始化中获取的任务ID保持一致。
   Body	test-part00	分段文件。单击参数框右侧的，选择分段文件。

3. 单击“调试”。
4. 调用成功后，右侧调试结果页签会提示“调用成功”，可在页面右下角查看响应结果，响应结果中包含每一个段的ETag值。
5. 重复2~3，完成所有分段的上传。
6. 完成上传后，调用列举已上传的段接口，填写参数后单击“调试”，查看所有已上传的段。
   

   参数名称	示例	说明
   object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字，与初始化中填写的对象名一致。
   bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶，与初始化中填写的桶名一致。
   uploadId	000001987D77252A002424CADFB90B1C	上传任务ID，与初始化中获取的任务ID保持一致。

7. 检查分段是否都上传成功，并获取所有段的段号和ETag值。

   如果6中列举段接口响应结果包含所有分段，说明所有分段都上传成功，此时请记录响应结果中所有段的段编号和ETag值，这些值将作为下一步合并段的请求参数。

本步骤将上传至桶中的分段合并成一个完整的对象。

1. 进入API Explorer的合并段接口调试页面。
2. 填写API调用参数。
   

   参数名称	示例	说明
   object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字，与初始化中填写的对象名一致。
   bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶，与初始化中填写的桶名一致。
   uploadId	000001987D77252A002424CADFB90B1C	上传任务ID，与初始化中获取的任务ID保持一致。
   Body	<CompleteMultipartUpload> <Part> <PartNumber>1</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> <Part> <PartNumber>2</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> <Part> <PartNumber>3</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> <Part> <PartNumber>4</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> <Part> <PartNumber>5</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> </CompleteMultipartUpload>	任务中所有分段的段信息和Etag值，您可以待所有分段都上传后，调用列举段接口批量获取，参见7。或者每上传一个段，在响应结果中获取，参见4。 注意： 如果合并段时，遗漏了某个段，那么未被合并的段将会被系统自动删除且不可恢复。例如上传了10个段，但合并时只选择了9个段进行合并，那么遗漏的一个段会被删除且不可恢复。 所以合并段前请列出已上传的段，仔细核对所有段，确保没有段被遗漏。

3. 单击“调试”。
4. 调用成功后，右侧调试结果页签会提示“调用成功”，响应结果会返回最终的对象名、桶名和完整对象的Etag值：

   

1. 在OBS管理控制台左侧导航栏选择“对象存储”。
2. 在OBS管理控制台桶列表中，单击待操作的桶，进入“对象”页面。
3. 在对象列表页，单击“上传对象”，系统弹出“上传对象”对话框。

   也可以进入待上传文件的文件夹，单击“上传对象”。

   此处以批量上传为例。仅支持单个上传的区域请根据界面提示进行操作。

   

   如果待上传至OBS的文件存放在Microsoft OneDrive中，建议这些待上传文件的名称不要超过32位，以保证兼容性。

   图2 上传对象
   

4. 指定对象的存储类别。如果不指定，默认与桶的存储类别一致。
   

   对象存储类别和桶存储类别可以不一致。上传对象时，对象的存储类别默认继承桶的存储类别，您也可以重新指定对象的存储类别，同时也支持在对象上传完成后修改对象的存储类别。

5. 拖拽本地文件或文件夹至“上传对象”区域框内添加待上传的文件。

   也可以通过单击“上传对象”区域框内的“添加文件”，选择本地文件进行添加。

6. 服务端加密：选择“不开启加密”、“SSE-KMS”或“SSE-OBS”。详情请参见服务端加密。
   

   如果桶配置了服务端加密，上传对象时您可以选择“继承桶的加密配置”。

7. 可选：如果您需要配置元数据、保留策略、对象标签，可单击“下一步：高级配置（可选）”进行配置。
   

   当桶开启了WORM功能，高级配置才支持配置WORM保留策略。

   配置元数据：可配置的对象元数据包括：ContentDisposition、ContentLanguage、WebsiteRedirectLocation、ContentEncoding、ContentType。各元数据具体含义请参见OBS元数据。元数据是一组名称值对，包括名称和值，值不能为空。如需配置多个元数据，单击“添加”即可新增。

   保留策略：可选择“继承桶保留策略”或者选择“配置”后输入保留期，自动保护上传到此存储桶的新对象，保证其在指定时间点前不被删除。

   配置标签：通过使用标签来标识对象。输入标签键和值。关于标签相关内容，具体请参见对象标签。

   图3 配置元数据或WORM保留策略
   

8. 单击“上传”。

对象操作

大于50M的对象OBS Browser+会在后台自动转换为断点续传（本质上是分段上传）。

1. 登录OBS Browser+。
2. 单击想要上传文件或文件夹的桶。
3. 单击“上传”，并选择“添加文件”或“添加文件夹”，如图4所示。
   图4 上传文件或文件夹
   

   使用“添加文件”功能上传对象时，为了更好的体验，建议您最多同时选择100个文件进行上传，如果超过此限制，建议将多个文件放在文件夹中，然后使用“添加文件夹”功能进行上传。

   

   1. 如果上传文件时弹出“Service Unavailable”的错误提示，则可能是因为当前服务器繁忙，请稍后重试。
   2. 如果上传文件或文件夹时弹出拒绝访问的错误提示，则有可能是如下几种情况导致的：

   • 通过桶的ACL设置功能，限制了该桶的访问权限（如：该用户无桶的写入权限）。
   • 通过桶的桶策略功能，限制了该桶的访问权限(如:当前时间段不允许对桶进行写入、该用户无桶的写入权限等)。

     请检查桶的ACL设置和桶策略配置，排查错误。

   

   文件必须有访问权限才可以上传，否则上传任务会失败。

4. 在弹出的对话框中，选中需要上传的文件或文件夹后单击“打开”。

   客户端支持一次上传一个文件夹，或一次同时上传多个文件。上传多个文件时，按住“Ctrl”或“Shift”同时选择多个文件即可，同时支持“Ctrl+A”全选操作。操作习惯与Windows操作系统上的操作习惯保持一致。

5. 单击“确定”。

大于50M的对象obsutil会在后台自动转换为断点续传（本质上是分段上传）。

命令结构：

• Windows操作系统
  • 上传文件

    obsutil cp file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=5248800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

  • 上传文件夹

    obsutil cp folder_url obs://bucket[/key] -r [-arcDir=xxx] [-dryRun] [-link] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

  • 多文件/文件夹上传

    obsutil cp file1_url,folder1_url|filelist_url obs://bucket[/prefix] -msm=1 [-r] [-arcDir=xxx] [-dryRun] [-link] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx][-timeRange=time1-time2] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

    

    命令中的“/prefix”即为上传文件夹时的对象名前缀。运行示例请参见上传示例。

• Linux/Mac操作系统
  • 上传文件

    ./obsutil cp file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=5248800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

  • 上传文件夹

    ./obsutil cp folder_url obs://bucket[/key] -r [-arcDir=xxx] [-dryRun] [-link] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

  • 多文件/文件夹上传

    ./obsutil cp file1_url,folder1_url|filelist_url obs://bucket[/prefix] -msm=1 [-r] [-arcDir=xxx] [-dryRun] [-link] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx][-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

    

    命令中的“/prefix”即为上传文件夹时的对象名前缀。运行示例请参见上传示例。

运行示例：

• 以Windows操作系统为例，运行obsutil cp d:\temp\test.txt obs://bucket-test/key，将D盘temp路径下名为test.txt的文件上传至bucket-test桶中，并且重命名为key。

  obsutil cp d:\temp\test.txt obs://bucket-test/key
  Start at 2024-09-30 08:11:41.6724827 +0000 UTC
  
  Parallel:      5                   Jobs:          5
  Threshold:     50.00MB             PartSize:      auto
  VerifyLength:  false               VerifyMd5:     false
  CheckpointDir: C:\Users\Administrator\.obsutil_checkpoint
  
  [====================================================] 100.00% 1.68 MB/s 8.46MB/8.46MB 5s
  Upload successfully, 8.46MB, n/a, d:\temp\test.txt --> obs://bucket-test/key, cost [5], status [200], request id [0000016979E1D2B2860BB5181229C72C]

• 以Windows操作系统为例，运行obsutil cp d:\temp obs://bucket-test -f -r，递归上传D盘temp文件夹中的所有文件和子文件夹至bucket-test桶的temp文件夹中。

  obsutil cp d:\temp obs://bucket-test -f -r
  Start at 2024-09-30 08:14:12.1406275 +0000 UTC
  
  Parallel:      5                   Jobs:          5
  Threshold:     50.00MB             PartSize:      auto
  VerifyLength:  false               VerifyMd5:     false
  CheckpointDir: C:\Users\Administrator\.obsutil_checkpoint
  
  Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
  OutputDir: C:\Users\Administrator\.obsutil_output
  
  [========================================================] 100.00% tps:35.71 2.02 KB/s 7.20MB/7.20MB 0s
  Succeed count:   5         Failed count:    0
  Succeed bytes:      xxx
  Metrics [max cost:90 ms, min cost:45 ms, average cost:63.80 ms, average tps:35.71, transferred size: 7.20MB]
  
  Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed

• 更多运行示例，请参见上传示例。

参数说明：

./obsutil cp /localpath/ obs://test/ -include=/localpath/2022-12-09/* -f -r

响应结果：

什么是已初始化的多段任务：指初始化后还未合并以及未取消的多段上传任务。

列举的原理：调用该接口会获得桶中所有已初始化但未合并、未取消的多段上传任务列表。每个请求最多返回1000个多段上传任务，如果正在进行的多段上传任务超过1000个，您需要发送其他请求以检索剩余的多段上传任务。

如何列举：

• obsutil：列举分段上传任务
• API：列举桶中已初始化多段任务
• SDK：

什么是已上传未合并的段：指已成功上传到桶中但是未进行合并的分段。

列举的原理：列出指定任务已上传但未合并的分段，OBS将返回特定任务的分段信息，每个请求最多返回1000个分段。如果分段超过1000个，您必须发送一系列请求以列举所有段。请注意，返回的分段列表不包括已合并的分段。

如何列举：

• 控制台：
  1. 在OBS管理控制台左侧导航栏选择“桶列表”
  2. 单击要查看的桶，进入“对象”页面。
  3. 单击“碎片”页签，即可查看桶内所有分段。
• OBS Browser+：碎片管理
• API：列举已上传未合并的段
• SDK：

什么是拷贝段：多段上传任务创建后，用户可以通过指定多段上传任务ID，为特定的任务调用拷贝段接口，将桶中已上传对象的一部分或全部拷贝为段。

拷贝段的原理：将源对象A拷贝为段part1，如果在拷贝前part1已存在，拷贝后老段数据part1会被新拷贝的段数据覆盖。拷贝成功后，只能列举到最新的段part1，老段数据将会被删除。因此拷贝段前请确保目标段不存在或者已无价值，避免因拷贝段导致数据误删除。拷贝过程中源对象A不会受到任何影响。

如何拷贝段：

• obsutil：复制对象
• API：拷贝段
• SDK：

如何判断拷贝段是否成功：拷贝段成功的标志是响应消息的body中包含段的ETag值，否则拷贝失败。拷贝段接口返回状态码200并不代表拷贝成功，只是代表服务端已经收到请求，且开始处理拷贝段请求。

取消多段上传任务的原理：取消多段上传任务之后无法再次使用任务ID上传任何段。取消后OBS将释放任务中每个段的存储空间。如果有分段正在上传过程中，即使您已执行中止操作，它们仍可以上传成功或失败。如果要释放所有分段使用的存储空间，建议等待分段全部上传完成后再取消多段上传任务。

如何取消多段上传任务：

• obsutil：删除分段上传任务
• API：取消多段上传任务
• SDK：