上传大对象时可以分成多个数据块（part）来分别上传，最后调用合并分片将上传的数据块合并为一个对象。 ## **注意事项** * 分片上传前，您必须具有 `tos:PutObject` 权限，具体操作，请参见[权限配置指南](/docs/6349/102120)。 * 取消分片上传任务前，您必须具有 `tos:AbortMultipartUpload` 权限，具体操作，请参见[权限配置指南](/docs/6349/102120)。 * 分片编号从 1 开始，最大为 10000。除最后一个分片以外，其他分片大小最小为 4MiB。 * 上传对象时，对象名必须满足一定规范，详细信息，请参见[对象命名规范](/docs/6349/74822)。 * TOS 是面向海量存储设计的分布式对象存储产品，内部分区存储了对象索引数据，为横向扩展您上传对象和下载对象时的最大吞吐量，和减小热点分区的概率，请您避免使用字典序递增的对象命名方式，详细信息，请参见[性能优化](/docs/6349/155630)。 * 如果桶中已经存在同名对象，则新对象会覆盖已有的对象。如果您的桶开启了版本控制，则会保留原有对象，并生成一个新版本号用于标识新上传的对象。 ## 分片上传步骤分片上传一般包含以下三个步骤： 1. 初始化分片上传任务：调用 CreateMultipartUploadV2 方法返回 TOS 创建的全局唯一 UploadID。 2. 上传分片：调用 UploadPartV2 方法上传分片数据。 :::tip * 对于同一个分片上传任务(通过 UploadID 标识)，分片编号(PartNumber)标识了该分片在整个对象中的相对位置。若通过同一分片编号多次上传数据，TOS 中会覆盖原始数据，并以最后一次上传数据为准。 * 响应头中包含了数据的 MD5 值，可通过 Etag 获取。合并分片时，您需指定当前分片上传任务中的所有分片信息(分片编号、ETag 值)。 ::: 3. 完成分片上传：所有分片上传完成后，调用 CompleteMultipartUploadV2 方法将所有分片合并成一个完整的对象。 ## 示例代码 ### **分片上传完整过程** 下面代码展示将本地文件通过分片的方式上传完整过程，并在上传时指定 ACL 为 Private，存储类型为低频存储以及添加自定义元数据。 ```go package main import ( "context" "fmt" "io" "os" "github.com/volcengine/ve-tos-golang-sdk/v2/tos" "github.com/volcengine/ve-tos-golang-sdk/v2/tos/enum" ) func checkErr(err error) { if err != nil { if serverErr, ok := err.(*tos.TosServerError); ok { fmt.Println("Error:", serverErr.Error()) fmt.Println("Request ID:", serverErr.RequestID) fmt.Println("Response Status Code:", serverErr.StatusCode) fmt.Println("Response Header:", serverErr.Header) fmt.Println("Response Err Code:", serverErr.Code) fmt.Println("Response Err Msg:", serverErr.Message) } else if clientErr, ok := err.(*tos.TosClientError); ok { fmt.Println("Error:", clientErr.Error()) fmt.Println("Client Cause Err:", clientErr.Cause.Error()) } else { fmt.Println("Error:", err) } panic(err) } } func main() { var ( accessKey = os.Getenv("TOS_ACCESS_KEY") secretKey = os.Getenv("TOS_SECRET_KEY") // Bucket 对应的 Endpoint，以华北2（北京）为例：https://tos-cn-beijing.volces.com endpoint = "https://tos-cn-beijing.volces.com" region = "cn-beijing" // 填写 BucketName bucketName = "*** Provide your bucket name ***" // 指定的 ObjectKey objectKey = "*** Provide your object name ***" ctx = context.Background() ) // 初始化客户端 client, err := tos.NewClientV2(endpoint, tos.WithRegion(region), tos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey))) checkErr(err) // 初始化分片，指定对象权限为私有，存储类型为标准存储并设置元数据信息 createMultipartOutput, err := client.CreateMultipartUploadV2(ctx, &tos.CreateMultipartUploadV2Input{ Bucket: bucketName, Key: objectKey, ACL: enum.ACLPrivate, StorageClass: enum.StorageClassStandard, Meta: map[string]string{"key": "value"}, }) checkErr(err) fmt.Println("CreateMultipartUploadV2 Request ID:", createMultipartOutput.RequestID) // 获取到上传的 UploadID fmt.Println("CreateMultipartUploadV2 Upload ID:", createMultipartOutput.UploadID) // 需要上传的文件路径 localFile := "/root/example.txt" fd, err := os.Open(localFile) checkErr(err) defer fd.Close() stat, err := os.Stat(localFile) checkErr(err) fileSize := stat.Size() // partNumber 编号从 1 开始 partNumber := 1 // part size 大小设置为 20M partSize := int64(20 * 1024 * 1024) offset := int64(0) var parts []tos.UploadedPartV2 for offset < fileSize { uploadSize := partSize // 最后一个分片 if fileSize-offset < partSize { uploadSize = fileSize - offset } fd.Seek(offset, io.SeekStart) partOutput, err := client.UploadPartV2(ctx, &tos.UploadPartV2Input{ UploadPartBasicInput: tos.UploadPartBasicInput{ Bucket: bucketName, Key: objectKey, UploadID: createMultipartOutput.UploadID, PartNumber: partNumber, }, Content: io.LimitReader(fd, uploadSize), ContentLength: uploadSize, }) checkErr(err) fmt.Println("upload Request ID:", partOutput.RequestID) parts = append(parts, tos.UploadedPartV2{PartNumber: partNumber, ETag: partOutput.ETag}) offset += uploadSize partNumber++ } completeOutput, err := client.CompleteMultipartUploadV2(ctx, &tos.CompleteMultipartUploadV2Input{ Bucket: bucketName, Key: objectKey, UploadID: createMultipartOutput.UploadID, Parts: parts, }) checkErr(err) fmt.Println("CompleteMultipartUploadV2 Request ID:", completeOutput.RequestID) } ``` ### **列举已上传分片** 以下代码用于列举指定存储桶中指定对象已上传的分片信息。 ```go package main import ( "context" "fmt" "github.com/volcengine/ve-tos-golang-sdk/v2/tos" ) func checkErr(err error) { if err != nil { if serverErr, ok := err.(*tos.TosServerError); ok { fmt.Println("Error:", serverErr.Error()) fmt.Println("Request ID:", serverErr.RequestID) fmt.Println("Response Status Code:", serverErr.StatusCode) fmt.Println("Response Header:", serverErr.Header) fmt.Println("Response Err Code:", serverErr.Code) fmt.Println("Response Err Msg:", serverErr.Message) } else if clientErr, ok := err.(*tos.TosClientError); ok { fmt.Println("Error:", clientErr.Error()) fmt.Println("Client Cause Err:", clientErr.Cause.Error()) } else { fmt.Println("Error:", err) } panic(err) } } func main() { var ( accessKey = os.Getenv("TOS_ACCESS_KEY") secretKey = os.Getenv("TOS_SECRET_KEY") // Bucket 对应的 Endpoint，以华北2（北京）为例：https://tos-cn-beijing.volces.com endpoint = "https://tos-cn-beijing.volces.com" region = "cn-beijing" // 填写 BucketName bucketName = "*** Provide your bucket name ***" // 指定的 ObjectKey objectKey = "*** Provide your object name ***" uploadID = "*** Provide upload ID ***" ctx = context.Background() ) // 初始化客户端 client, err := tos.NewClientV2(endpoint, tos.WithRegion(region), tos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey))) checkErr(err) // 列举 uploadID 已上传分片信息 truncated := true marker := 0 for truncated { output, err := client.ListParts(ctx, &tos.ListPartsInput{ Bucket: bucketName, Key: objectKey, UploadID: uploadID, PartNumberMarker: marker, }) checkErr(err) truncated = output.IsTruncated marker = output.NextPartNumberMarker for _, part := range output.Parts { fmt.Println("Part Number:", part.PartNumber) fmt.Println("ETag:", part.ETag) fmt.Println("Size:", part.Size) } } } ``` ### **取消分片上传任务** 您可以通过 AbortMultipartUpload 方法来取消分片上传任务。当一个分片任务被取消后， TOS 会将已上传的分片数据删除，同时您无法再对此分片任务进行任何操作。 ```go package main import ( "context" "fmt" "github.com/volcengine/ve-tos-golang-sdk/v2/tos" ) func checkErr(err error) { if err != nil { if serverErr, ok := err.(*tos.TosServerError); ok { fmt.Println("Error:", serverErr.Error()) fmt.Println("Request ID:", serverErr.RequestID) fmt.Println("Response Status Code:", serverErr.StatusCode) fmt.Println("Response Header:", serverErr.Header) fmt.Println("Response Err Code:", serverErr.Code) fmt.Println("Response Err Msg:", serverErr.Message) } else if clientErr, ok := err.(*tos.TosClientError); ok { fmt.Println("Error:", clientErr.Error()) fmt.Println("Client Cause Err:", clientErr.Cause.Error()) } else { fmt.Println("Error:", err) } panic(err) } } func main() { var ( accessKey = os.Getenv("TOS_ACCESS_KEY") secretKey = os.Getenv("TOS_SECRET_KEY") // Bucket 对应的 Endpoint，以华北2（北京）为例：https://tos-cn-beijing.volces.com endpoint = "https://tos-cn-beijing.volces.com" region = "cn-beijing" // 填写 BucketName bucketName = "*** Provide your bucket name ***" // 指定的 ObjectKey objectKey = "*** Provide your object name ***" uploadID = "*** Provide upload ID ***" ctx = context.Background() ) // 初始化客户端 client, err := tos.NewClientV2(endpoint, tos.WithRegion(region), tos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey))) checkErr(err) // 取消分片上传 output, err := client.AbortMultipartUpload(ctx, &tos.AbortMultipartUploadInput{ Bucket: bucketName, Key: objectKey, UploadID: uploadID, }) checkErr(err) fmt.Println("AbortMultipartUpload Request ID:", output.RequestID) } ``` ## **相关文档** * 关于创建分片上传任务的 API 文档，请参见 [CreateMultipartUpload](/docs/6349/74867)。 * 关于上传分片的 API 文档，请参见 [UploadPart](/docs/6349/74869)。 * 关于合并分片的 API 文档，请参见 [CompleteMultipartUpload](/docs/6349/74868)。 * 关于取消分片上传任务的 API 文档，请参见 [AbortMultipartUpload](/docs/6349/74870)。