上传对象

功能说明

上传对象操作用于上传对象。如果对同一个对象同时发起多个上传请求，最后一次完成的请求将覆盖之前所有请求的上传的对象。可以通过设置请求头部中的Content-MD5字段来保证数据被完整上传，如果上传的数据不能通过MD5校验，该操作将返回一个错误提示。用户可以通过比较上传对象后获得的ETag 与原文件的MD5值是否相等来确认上传操作是否成功。

上传对象操作在上传对象时可以在请求里携带HTTP协议规定的6个请求头：Cache-Control、Expires、Content-Encoding、Content-Disposition、Content-Type、Content-Language。如果上传对象的请求设置了这些请求头，服务端会直接将这些头域的值保存下来。这6个值也可以通过修改对象元数据操作进行修改。在该对象被下载或者执行HeadObject操作的时候，这些保存的值将会被设置到对应的HTTP头域中返回客户端。

上传对象操作可以上传最大不超过5GB的文件，超过5GB的文件可以通过分段上传操作上传到对象存储服务，对象key的命名使用UTF-8编码，长度必须在1~1023字节之间，不能反斜线（\）开头。

代码示例

func PutObject(svc *s3.S3) {
    file, err := os.Open("<file-path>")
    if err != nil {
        fmt.Printf("Unable to open file:%v", err)
        os.Exit(1)
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
​
    putObjectInput := &s3.PutObjectInput{
        Body:   file,
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    putObjectOutput, err := svc.PutObject(putObjectInput)
    if err != nil {
        fmt.Printf("Failed to put object. %v", err)
    } else {
        fmt.Println(putObjectOutput)
    }
}

通过PutObjectRequest操作：

PutObjectRequest操作首先生成一个"request.Request"对象，该对象是一个执行PutObject操作的请求。通过调用Request对象的Send方法完成上传对象的操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func PutObjectRequest(svc *s3.S3) {
    file, err := os.Open("exampleFile")
    if err != nil {
        fmt.Printf("Unable to open file:%v", err)
        os.Exit(1)
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
​
    putObjectInput := &s3.PutObjectInput{
        Body:   file,
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, putObjectOutput := svc.PutObjectRequest(putObjectInput)
​
    err = req.Send()
    if err != nil {
        fmt.Printf("fail to put object. %v\n", err)
    } else {
        fmt.Println(putObjectOutput)
    }
}

请求参数

PutObjectInput可设置的参数如下：

返回结果

PutObjectOutput返回的属性如下：

下载对象

功能说明

下载对象操作可以获取对象数据，并且保存为本地文件。执行GetObject操作必须对目标Object具有READ权限。

代码示例

func GetObject(svc *s3.S3) {
    getObjectInput := &s3.GetObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
​
    getObjectOutput, err := svc.GetObject(getObjectInput)
    if err != nil {
        fmt.Printf("Failed to get object. %v\n", err)
        return
    }
    defer func() {
        err := getObjectOutput.Body.Close()
        if err != nil {
            fmt.Printf("fail to close result body. %v\n", err)
        }
    }()
    fmt.Println(getObjectOutput)
    // 将对象保存为本地文件
    p := make([]byte, 1024)
    filepath := "<file-path>"
    file, err := os.Create(filepath)
    if err != nil {
        fmt.Println("fail to create file.", err)
        return
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
    for {
        readCount, readErr := getObjectOutput.Body.Read(p)
        _, _ = file.Write(p[:readCount])
        if readErr != nil {
            break
        }
    }
}

通过GetObjectRequest操作获取对象：

GetObjectRequest操作首先生成一个"request.Request"对象，该对象是一个执行GetObject操作的请求。通过调用Request对象的Send方法完成下载对象的操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func GetObjectRequest(svc *s3.S3) {
    getObjectInput := &s3.GetObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, getObjectOutput := svc.GetObjectRequest(getObjectInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to get object. %v\n", err)
        return
    }
    // 将对象保存为本地文件
    p := make([]byte, 1024)
    filepath := "<file-path>"
    file, err := os.Create(filepath)
    if err != nil {
        fmt.Println("fail to create file.", err)
        return
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
    for {
        readCount, readErr := getObjectOutput.Body.Read(p)
        _, _ = file.Write(p[:readCount])
        if readErr != nil {
            break
        }
    }
}

通过downloader下载对象：

func DownloadObject(sess *session.Session) {
    filePath := "<file-path>"
    file, err := os.Create(filePath)
    if err != nil {
        fmt.Println("fail to create file.", err)
        return
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
​
    downloader := s3manager.NewDownloader(sess)
    _, err = downloader.Download(file,
        &s3.GetObjectInput{
            Bucket: aws.String("<your-bucket-name>"),
            Key:    aws.String("<your-object-key>"),
        })
    if err != nil {
        fmt.Printf("fail to download file. %v\n", err)
        return
    }
}

请求参数

GetObjectInput可设置的参数如下：

返回结果

GetObjectOutput返回的属性如下：

范围下载

功能说明

范围下载可以下载对象指定范围的数据，通过Range参数指定需要下载的数据范围，如果指定的下载范围为0-9，则返回对象的第1至第10字节共10字节的数据。如果指定的起始位置大于对象的大小，或者起始位置大于结束位置，则返回{416: InvalidRange}错误码。如果指定的结束位置大于对象大小，则返回从对象从起始位置开始的全部数据。

代码示例

func GetObject(svc *s3.S3) {
    getObjectInput := &s3.GetObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
        // 请求对象第1至第10字节的数据
        Range:  aws.String("bytes=0-9"),
    }
​
    getObjectOutput, err := svc.GetObject(getObjectInput)
    if err != nil {
        fmt.Printf("Failed to get object. %v\n", err)
        return
    }
    defer func() {
        err := getObjectOutput.Body.Close()
        if err != nil {
            fmt.Printf("fail to close result body. %v\n", err)
        }
    }()
    // 将对象保存为本地文件
    p := make([]byte, 1024)
    filepath := "<file-path>"
    file, err := os.Create(filepath)
    if err != nil {
        fmt.Println("fail to create file.", err)
        return
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
    for {
        readCount, readErr := getObjectOutput.Body.Read(p)
        _, _ = file.Write(p[:readCount])
        if readErr != nil {
            break
        }
    }
}

请求参数

GetObjectInput可设置的参数如下：

返回结果

GetObjectOutput返回的属性如下：

限定条件下载

功能说明

下载对象时可以设置对象的Etag和修改时间是否匹配指定值等条件，当满足限定条件时则进行下载，否则返回错误码。

代码示例

func GetObject(svc *s3.S3) {
    format := "2006/01/02 15:04:05"
    mtime, _ := time.Parse(format, "2023/06/15 00:00:00")
​
    getObjectInput := &s3.GetObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
        // 当对象Etag等于指定值时才下载
        IfMatch: aws.String("781e5e245d69b566979b86e28d23f2c7"),
        // 当对象的修改时间大于指定值时才下载
        IfModifiedSince: &mtime,
    }
​
    getObjectOutput, err := svc.GetObject(getObjectInput)
    if err != nil {
        fmt.Printf("Failed to get object. %v\n", err)
        return
    }
    defer func() {
        err := getObjectOutput.Body.Close()
        if err != nil {
            fmt.Printf("fail to close result body. %v\n", err)
        }
    }()
​
    // 将对象保存为本地文件
    p := make([]byte, 1024)
    filepath := "<file-path>"
    file, err := os.Create(filepath)
    if err != nil {
        fmt.Println("fail to create file.", err)
        return
    }
    defer func() {
        err := file.Close()
        if err != nil {
            fmt.Printf("fail to close file. %v\n", err)
        }
    }()
    for {
        readCount, readErr := getObjectOutput.Body.Read(p)
        _, _ = file.Write(p[:readCount])
        if readErr != nil {
            break
        }
    }
}

请求参数

GetObjectInput可设置的参数如下：

返回结果

GetObjectOutput返回的属性如下：

复制对象

功能说明

复制对象操作用于创建一个已经在对象存储中的对象。复制对象可以拷贝单个最大为5GB的对象，如果需要拷贝更大的对象，可以使用复制段操作。执行复制对象操作，必须具有对被拷贝对象的READ权限和对目标桶的WRITE权限。

拷贝生成的对象默认保留原对象的元数据信息，也可以在复制对象操作中指定新的元数据。拷贝生成的对象不会保留原来的ACL信息，该对象默认是发起复制对象操作的用户私有的。

复制对象操作默认拷贝原对象的当前版本数据，如果需要拷贝原对象的指定版本，可以在复制对象时加入version id来拷贝指定的对象版本，如果原对象的version id为删除标记，则不会被拷贝。如果目标bucket开启了版本控制，那么拷贝生成的对象会有一个与原对象不同的唯一的version id，并且会在响应头部字段 x-amz-version-id中返回该version id。

代码示例

func CopyObject(svc *s3.S3) {
    copyObjectInput := &s3.CopyObjectInput{
        Bucket:     aws.String("<your-bucket-name>"),
        CopySource: aws.String("<copy-source>"),
        Key:        aws.String("<your-object-key>"),
    }
​
    copyObjectOutput, err := svc.CopyObject(copyObjectInput)
    if err != nil {
        fmt.Printf("fail to copy object. %v\n", err)
    }
    fmt.Println(copyObjectOutput)
}

通过CopyObjectRequest操作：

CopyObjectRequest操作首先生成一个"request.Request"对象，该对象是一个执行CopyObject操作的请求。通过调用Request对象的Send方法来完成拷贝对象操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func CopyObjectRequest(svc *s3.S3) {
    copyObjectInput := &s3.CopyObjectInput{
        Bucket:     aws.String("<your-bucket-name>"),
        CopySource: aws.String("<copy-source>"),
        Key:        aws.String("<your-object-key>"),
    }
    req, copyObjectOutput := svc.CopyObjectRequest(copyObjectInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to copy object. %v\n", err)
    } else {
        fmt.Println(copyObjectOutput)
    }
}

请求参数

CopyObjectInput可设置的参数如下：

返回结果

CopyObjectOutput返回的属性如下：

删除对象

功能说明

删除对象操作用于删除指定的一个对象。对于开启版本控制的桶执行 删除对象操作时，如果未指定version id ，则保留对象的当前版本，并插入删除标记（Delete Marker）。如果指定version id，则永久删除该指定版本的对象。如果在未指定version id的情况下执行删除对象操作时，默认仅作用于对象的当前版本，但不会直接删除该对象的当前版本，而是插入一个删除标记（Delete Marker），并保留原来的当前版本。当访问对象时，服务端会检测到当前版本为删除标记，并返回404 Not Found。

代码示例

func DeleteObject(svc *s3.S3) {
    deleteObjectInput := &s3.DeleteObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
​
    deleteObjectOutput, err := svc.DeleteObject(deleteObjectInput)
    if err != nil {
        fmt.Printf("Failed to delete object. %v\n", err)
    } else {
        fmt.Println(deleteObjectOutput)
    }
}

通过DeleteObjectRequest操作：

DeleteObjectRequest操作首先生成一个"request.Request"对象，该对象是一个执行DeleteObject操作的请求。通过调用Request对象的Send方法完成删除对象的操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func DeleteObjectRequest(svc *s3.S3) {
    deleteObjectInput := &s3.DeleteObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, deleteObjectOutput := svc.DeleteObjectRequest(deleteObjectInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to delete object. %v\n", err)
    } else {
        fmt.Println(deleteObjectOutput)
    }
}

请求参数

DeleteObjectInput可设置的参数如下：

返回结果

DeleteObjectOutput返回的属性如下：

批量删除对象

功能说明

（本接口目前仅支持部分资源池使用；如需使用，请联系天翼云客服确认。）

DeleteObjects操作可以实现通过一个HTTP请求批量删除多个对象的功能，可以减少发起多起请求去删除大量对象的花销。DeleteObjects操作发起一个包含了最多1000个key的删除请求，对象存储服务会对相应的对象逐个进行删除，并且将删除成功或者失败的结果通过response返回。如果请求删除的对象不存在，会返回已删除的结果。

DeleteObjects操作返回verbose 和quiet两种response模式。 verbose response是默认的返回模式，该模式的返回结果包含了每个key的删除结果。quiet response返回模式返回的结果仅包含了删除失败的key，对于一个完全成功的删除操作，该返回模式不在相应消息体中返回任何信息。

代码示例

func DeleteObjects(svc *s3.S3) {
    deleteObjectsInput := &s3.DeleteObjectsInput{
        Bucket: aws.String("<your-bucket-name>"),
        Delete: &s3.Delete{
            Objects: []*s3.ObjectIdentifier{
                {
                    Key: aws.String("exampleKey1"),
                },
                {
                    Key: aws.String("exampleKey2"),
                },
            },
            Quiet: aws.Bool(false),
        },
    }
​
    deleteObjectsOutput, err := svc.DeleteObjects(deleteObjectsInput)
    if err != nil {
        fmt.Printf("Failed to delete objects. %v\n", err)
    } else {
        fmt.Println(deleteObjectsOutput)
    }
}

通过DeleteObjectsRequest操作：

DeleteObjectsRequest操作首先生成一个"request.Request"对象，该对象是一个执行DeleteObjects操作的请求。通过调用Request对象的Send方法完成批量删除对象的操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func DeleteObjectsRequest(svc *s3.S3) {
    deleteObjectsInput := &s3.DeleteObjectsInput{
        Bucket: aws.String("<your-bucket-name>"),
        Delete: &s3.Delete{
            Objects: []*s3.ObjectIdentifier{
                {
                    Key: aws.String("exampleKey1"),
                },
                {
                    Key: aws.String("exampleKey2"),
                },
            },
            Quiet: aws.Bool(false),
        },
    }
    req, deleteObjectsOutput := svc.DeleteObjectsRequest(deleteObjectsInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to delete objects. %v\n", err)
    } else {
        fmt.Println(deleteObjectsOutput)
    }
}

请求参数

DeleteObjectsInput可设置的参数如下：

返回结果

DeleteObjectsOutput返回的属性如下：

获取对象元数据

功能说明

获取对象元数据操作用于获取对象的元数据信息。执行该操作需要具有对该对象的READ权限，请求参数与下载对象操作一样，区别在于获取对象元数据操作响应体中没有body部分。

代码示例

func HeadObject(svc *s3.S3) {
    headObjectInput := &s3.HeadObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
​
    headObjectOutput, err := svc.HeadObject(headObjectInput)
    if err != nil {
        fmt.Printf("fail to head object. %v\n", err)
        return
    }
    fmt.Printf("object info: %v\n", headObjectOutput)
}

通过HeadObjectRequest操作：

HeadObjectRequest操作首先生成一个"request.Request"对象，该对象是一个执行HeadObject操作的请求。通过调用Request对象的Send方法完成获取对象元数据信息的操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func HeadObjectRequest(svc *s3.S3) {
    headObjectInput := &s3.HeadObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, headObjectOutput := svc.HeadObjectRequest(headObjectInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to head object. %v\n", err)
    } else {
        fmt.Println(headObjectOutput)
    }
}

请求参数

HeadObjectInput可设置的参数如下：

返回结果

HeadObjectOutput返回的属性如下：

设置对象ACL

功能说明

设置对象ACL操作可以为对象存储服务中的对象设置访问权限，设置对象ACL操作需要具有对象的WRITE_ACP权限，执行操作的时候，要么使用封装好的ACL数据类型传入ACL信息，要么以字符串的形式详细描述ACL信息。

对象的访问权限说明：

代码示例

func PutObjectAcl(svc *s3.S3) {
    bucket := "<your-bucket-name>"
    key := "<your-object-key>"
    permission := "READ" // FULL_CONTROL、WRITE、WRITE_ACP、READ、READ_ACP
    granteeDisplayName := "<your-display-name>"
    granteeId := "<your-user-id>"
    userType := "CanonicalUser"
    // 获取当前acl
    getObjectAclOutput, err := svc.GetObjectAcl(&s3.GetObjectAclInput{
        Bucket: aws.String(bucket),
        Key:    aws.String(key),
    })
    if err != nil {
        fmt.Printf("fail to get acl of object %v, %v\n", key, err)
        os.Exit(1)
    }
    // 创建一个新的授权信息
    var newGrantee = s3.Grantee{
        Type:        aws.String(userType),
        DisplayName: aws.String(granteeDisplayName),
        ID:          aws.String(granteeId),
    }
    var newGrant = s3.Grant{Grantee: &newGrantee, Permission: &permission}
    grants := getObjectAclOutput.Grants
    owner := *getObjectAclOutput.Owner.DisplayName
    ownerId := *getObjectAclOutput.Owner.ID
    grants = append(grants, &newGrant)
    // 设置对象的ACL
    putObjectAclInput := &s3.PutObjectAclInput{
        AccessControlPolicy: &s3.AccessControlPolicy{
            Grants: grants,
            Owner: &s3.Owner{
                DisplayName: &owner,
                ID:          &ownerId,
            },
        },
        Bucket: aws.String(bucket),
        Key:    aws.String(key),
    }
​
    putObjectAclOutput, err := svc.PutObjectAcl(putObjectAclInput)
    if err != nil {
        fmt.Printf("fail to put objec acl. %v\n", err)
        return
    }
    fmt.Println(putObjectAclOutput)
}

通过PutObjectAclRequest操作：

PutObjectAclRequest操作首先生成一个"request.Request"对象，该对象是一个执行PutObjectAcl操作的请求。通过调用Request对象的Send方法来设置对象的ACL信息。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func PutObjectAclRequest(svc *s3.S3) {
    bucket := "<your-bucket-name>"
    key := "<your-object-key>"
    permission := "READ_ACP" // FULL_CONTROL、WRITE、WRITE_ACP、READ、READ_ACP
    granteeDisplayName := "<your-display-name>"
    granteeId := "<your-user-id>"
    userType := "CanonicalUser"
    // 获取当前acl
    currentACL, err := svc.GetObjectAcl(&s3.GetObjectAclInput{
        Bucket: aws.String(bucket),
        Key:    aws.String(key),
    })
    if err != nil {
        fmt.Printf("fail to get acl of object %v, %v\n", key, err)
        os.Exit(1)
    }
    // 创建一个新的授权信息
    var newGrantee = s3.Grantee{
        Type:        aws.String(userType),
        DisplayName: aws.String(granteeDisplayName),
        ID:          aws.String(granteeId),
    }
    var newGrant = s3.Grant{Grantee: &newGrantee, Permission: &permission}
    grants := currentACL.Grants
    owner := *currentACL.Owner.DisplayName
    ownerId := *currentACL.Owner.ID
    grants = append(grants, &newGrant)
    // 设置对象的ACL
    putObjectAclInput := &s3.PutObjectAclInput{
        AccessControlPolicy: &s3.AccessControlPolicy{
            Grants: grants,
            Owner: &s3.Owner{
                DisplayName: &owner,
                ID:          &ownerId,
            },
        },
        Bucket: aws.String(bucket),
        Key:    aws.String(key),
    }
    req, putObjectAclOutput := svc.PutObjectAclRequest(putObjectAclInput)
​
    err = req.Send()
    if err != nil {
        fmt.Printf("fail to put object ACL. %v\n", err)
    } else {
        fmt.Println(putObjectAclOutput)
    }
}

请求参数

PutObjectAclInput可设置的参数如下：

获取对象ACL

功能说明

获取对象ACL操作可以获取对象的access control list（ACL）信息。对一个对象执行获取ACL操作需要具有READ_ACP权限。

代码示例

func GetObjectAcl(svc *s3.S3) {
    getObjectAclInput := &s3.GetObjectAclInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
​
    getObjectAclOutput, err := svc.GetObjectAcl(getObjectAclInput)
    if err != nil {
​
        return
    }
    fmt.Println(getObjectAclOutput)
}

通过GetObjectAclRequest操作：

GetObjectAclRequest操作首先生成一个"request.Request"对象，该对象是一个执行GetObjectAcl操作的请求。通过调用Request对象的Send方法来获取对象的ACL信息。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func GetObjectAclRequest(svc *s3.S3) {
    getObjectAclInput := &s3.GetObjectAclInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, getObjectAclOutput := svc.GetObjectAclRequest(getObjectAclInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to get object ACL. %v\n", err)
    } else {
        fmt.Println(getObjectAclOutput)
    }
}

请求参数

GetObjectAclInput可设置的参数如下：

返回结果

GetObjectAclOutput返回的属性如下：

设置对象属性

功能说明

在上传对象时可以设置对象的属性，对象属性以key-value的形式描描述。

代码示例

func PutObjectWithMetadata(svc *s3.S3) {
    putObjectInput := &s3.PutObjectInput{
        Body:   strings.NewReader("<object-data>"),
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
        Metadata: map[string]*string{
            "<metadata1>": aws.String("<value1>"),
            "<metadata2>": aws.String("<value2>"),
        },
    }
    putObjectOutput, err := svc.PutObject(putObjectInput)
    if err != nil {
        fmt.Printf("Failed to put object. %v", err)
    } else {
        fmt.Println(putObjectOutput)
    }
}

请求参数

PutObjectInput可设置的参数如下：

返回结果

PutObjectOutput返回的属性如下：

设置对象标签

功能说明

设置对象标签操作可以为对象设置标签，标签是一个键值对，每个对象最多可以有10个标签。桶的拥有者默认拥有给桶中的对象设置标签的权限，并且可以将权限授予其他用户。

每次执行设置对象标签操作会覆盖对象已有的标签信息。每个对象最多可以设置10个标签，标签Key和Value区分大小写，并且Key不可重复。每个标签的Key长度不超过128字节，Value长度不超过255字节。通过HTTP header的方式设置标签且标签中包含任意字符时，需要对标签的Key和Value做URL编码。设置对象标签信息不会更新对象的最新更改时间。

代码示例

func PutObjectTagging(svc *s3.S3) {
    putObjectTaggingInput := &s3.PutObjectTaggingInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
        Tagging: &s3.Tagging{
            TagSet: []*s3.Tag{
                {
                    Key:   aws.String("<key1>"),
                    Value: aws.String("<value1>"),
                },
                {
                    Key:   aws.String("<key2>"),
                    Value: aws.String("<value2>"),
                },
            },
        },
    }
    putObjectTaggingOutput, err := svc.PutObjectTagging(putObjectTaggingInput)
    if err != nil {
        fmt.Printf("fail to put object tagging. %v\n", err)
        return
    }
    fmt.Println(putObjectTaggingOutput)
}

通过PutObjectTaggingRequest操作：

PutObjectTaggingRequest操作首先生成一个"request.Request"对象，该对象是一个执行PutObjectTaggingRequest操作的请求。通过调用Request对象的Send方法来设置对象的标签信息。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func PutObjectTaggingRequest(svc *s3.S3) {
    putObjectTaggingInput := &s3.PutObjectTaggingInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
        Tagging: &s3.Tagging{
            TagSet: []*s3.Tag{
                {
                    Key:   aws.String("<key1>"),
                    Value: aws.String("<value1>"),
                },
                {
                    Key:   aws.String("<key2>"),
                    Value: aws.String("<value2>"),
                },
            },
        },
    }
    req, putObjectTaggingOutput := svc.PutObjectTaggingRequest(putObjectTaggingInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to put object tagging. %v\n", err)
    } else {
        fmt.Println(putObjectTaggingOutput)
    }
}

请求参数

PutObjectTaggingInput可设置的参数如下：

获取对象标签

功能说明

获取对象标签操作可以查询对象的标签信息，标签是一个键值对，每个对象最多可以有10个标签。桶的拥有者默认拥有查询桶中对象的标签的权限，并且可以将权限授予其他用户。

代码示例

func GetObjectTagging(svc *s3.S3) {
    getObjectTaggingInput := &s3.GetObjectTaggingInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
​
    getObjectTaggingOutput, err := svc.GetObjectTagging(getObjectTaggingInput)
    if err != nil {
        fmt.Printf("fail to get object tagging. %v\n", err)
        return
    }
    fmt.Println(getObjectTaggingOutput)
}

通过GetObjectTaggingRequest操作：

GetObjectTaggingRequest操作首先生成一个"request.Request"对象，该对象是一个执行GetObjectTaggingRequest操作的请求。通过调用Request对象的Send方法来完成获取对象标签信息的操作。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func GetObjectTaggingRequest(svc *s3.S3) {
    getObjectTaggingInput := &s3.GetObjectTaggingInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, getObjectTaggingOutput := svc.GetObjectTaggingRequest(getObjectTaggingInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to get object tagging. %v\n", err)
    } else {
        fmt.Println(getObjectTaggingOutput)
    }
}

请求参数

GetObjectTaggingInput可设置的参数如下：

返回结果

GetObjectTaggingOutput返回的属性如下：

删除对象标签

功能说明

删除对象标签操作可以删除一个对象的全部标签信息，删除时可以设置版本Id参数删除指定版本对象的标签信息，如果不设置版本Id，则默认删除当前版本的对象标签信息。

代码示例

func DeleteObjectTagging(svc *s3.S3) {
    deleteObjectTaggingInput := &s3.DeleteObjectTaggingInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
​
    deleteObjectTaggingOutput, err := svc.DeleteObjectTagging(deleteObjectTaggingInput)
    if err != nil {
        fmt.Printf("fail to delete object tagging. %v\n", err)
        return
    }
    fmt.Println(deleteObjectTaggingOutput)
}

通过DeleteObjectTaggingRequest操作：

DeleteObjectTaggingRequest操作首先生成一个"request.Request"对象，该对象是一个执行DeleteObjectTagging操作的请求。通过调用Request对象的Send方法来删除对象的标签信息。该方法可以生成定制化的请求，例如自定义请求头部请求超时重试设置。

func DeleteObjectTaggingRequest(svc *s3.S3) {
    deleteObjectTaggingInput := &s3.DeleteObjectTaggingInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, deleteObjectTaggingOutput := svc.DeleteObjectTaggingRequest(deleteObjectTaggingInput)
​
    err := req.Send()
    if err != nil {
        fmt.Printf("fail to delete object tagging. %v\n", err)
    } else {
        fmt.Println(deleteObjectTaggingOutput)
    }
}

请求参数

DeleteObjectTaggingInput可设置的参数如下：

服务端加密

功能说明

上传对象时可以指定对象的加密算法，即使设置桶的加密配置也可以加密请求上传的对象数据，服务端根据指定的加密算法对对象数据进行加密。目前支持AES256和国密SM4加密算法。

代码示例

func PutObjectWithEncryption(svc *s3.S3) {
    putObjectInput := &s3.PutObjectInput{
        Body:                 strings.NewReader("<object-data>"),
        Bucket:               aws.String("<your-bucket-name>"),
        Key:                  aws.String("<your-object-key>"),
        ServerSideEncryption: aws.String("AES256"),
    }
    putObjectOutput, err := svc.PutObject(putObjectInput)
    if err != nil {
        fmt.Printf("Failed to put object. %v", err)
    } else {
        fmt.Println(putObjectOutput)
    }
}

请求参数

PutObjectInput可设置的参数如下：

返回结果

PutObjectOutput返回的属性如下：

生成预签名上传链接

功能说明

本接口能够为一个指定对象生成一个预签名的上传链接，访问该链接可以直接上传该对象。

代码示例

以下代码演示如何为一个指定对象生成一个预签名的上传链接。

func generatePresignedPut(svc *s3.S3) {
    req, _ := p.svc.PutObjectRequest(&s3.PutObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    })
    expires := 5 * time.Minute
    urlStr, err := req.Presign(expires)
    if err != nil {
        fmt.Println("Failed to generate presigned URL:", err)
    }else {
        fmt.Println("Generated upload URL:", urlStr)
    }
}

通过该预签名URL，可以直接将文件上传到指定的桶：

func (p *S3Demo) putObjUsingPresignedUrl(url string, filePath string) error {
    file, err := os.Open(filePath)
    if err != nil {
        return fmt.Errorf("failed to open file %s: %w", filePath, err)
    }
    defer file.Close()
​
    // 读取文件内容并获取长度
    fileData, err := ioutil.ReadAll(file)
    if err != nil {
        return fmt.Errorf("failed to read file data: %w", err)
    }
    contentLength := len(fileData)
​
    // 创建 PUT 请求
    req, err := http.NewRequest("PUT", url, bytes.NewReader(fileData))
    if err != nil {
        return fmt.Errorf("failed to create request: %w", err)
    }
​
    // 设置 Content-Length
    req.Header.Set("Content-Length", fmt.Sprintf("%d", contentLength))
    req.ContentLength = int64(contentLength)
​
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("failed to upload file: %w", err)
    }
    defer resp.Body.Close()
​
    if resp.StatusCode != http.StatusOK {
        bodyBytes, _ := io.ReadAll(resp.Body)
        return fmt.Errorf("failed to upload file, status: %s, response: %s", resp.Status, string(bodyBytes))
    }
​
    fmt.Println("Successfully uploaded file to:", url)
    return nil
}

请求参数

返回结果

生成对应的预签名上传 URL，该链接允许用户在指定的时间内直接将对象上传到媒体存储存储桶。

生成预签名下载链接

功能说明

本接口能够为一个指定对象生成一个预签名的下载链接，访问该链接可以直接下载该对象。

代码示例

以下代码演示如何为一个指定对象生成一个预签名的下载链接。

func GetObjectPresignedUrl(svc *s3.S3) {
    getObjectInput := &s3.GetObjectInput{
        Bucket: aws.String("<your-bucket-name>"),
        Key:    aws.String("<your-object-key>"),
    }
    req, _ := svc.GetObjectRequest(getObjectInput)
    expires := 10 * time.Minute
    urlStr, err := req.Presign(expires)
    if err != nil {
        fmt.Println("err, ", err)
        return
    }
    fmt.Println("success, ", urlStr)
}

通过该URL，可以直接下载对象。

func (p *S3Demo) getObjectUsingPresignedUrl(url string, downloadPath string) error {
    // 发送 GET 请求以下载对象
    resp, err := http.Get(url)
    if err != nil {
        return fmt.Errorf("failed to download file: %w", err)
    }
    defer resp.Body.Close()
​
    // 检查响应状态是否成功
    if resp.StatusCode != http.StatusOK {
        bodyBytes, _ := io.ReadAll(resp.Body)
        return fmt.Errorf("failed to download file, status: %s, response: %s", resp.Status, string(bodyBytes))
    }
​
    // 创建目标文件以保存下载内容
    outFile, err := os.Create(downloadPath)
    if err != nil {
        return fmt.Errorf("failed to create file %s: %w", downloadPath, err)
    }
    defer outFile.Close()
​
    // 将响应内容写入文件
    _, err = io.Copy(outFile, resp.Body)
    if err != nil {
        return fmt.Errorf("failed to save file: %w", err)
    }
​
    fmt.Println("Successfully downloaded file to:", downloadPath)
    return nil
}

请求参数

返回结果

生成对应的预签名下载 URL，该链接允许用户在指定的时间内直接从媒体存储下载对象。