上傳對象

功能說明

上傳對象操作用于上傳對象。如果對同一個對象同時發起多個上傳請求，最后一次完成的請求將覆蓋之前所有請求的上傳的對象。可以通過設置請求頭部中的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，該鏈接允許用戶在指定的時間內直接從媒體存儲下載對象。