獲取對象列表

功能說明

您可以使用 listObjects 接口列舉對象，以下代碼展示如何簡單列舉對象。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
};
s3Client.listObjects(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

請求參數

返回結果

listObjects 中可設置的列舉相關參數如下：

上傳對象

功能說明

您可以使用 putObject 接口上傳對象，可以上傳最大不超過5GB的文件，超過5GB的文件可以通過分片上傳操作上傳到媒體存儲服務，對象key的命名使用UTF-8編碼，長度必須在1~1023字節之間，不能反斜線（\）開頭，以下代碼展示如何上傳一個對象。

代碼示例

簡單文本上傳：

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    Body: 'STRING_VALUE',
    ACL: "private", // 初始化acl權限，默認為private，"private"|"public-read"|"public-read-write"
    ContentType: "text/plain", // 設置contentType, 默認是application/octet-stream
};
s3Client.putObject(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

文件上傳，指定待上傳的文件File對象，例如在HTML頁面中使用類型為“file”的input標簽：<input type="file" id="input-file"/>。

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    Body: document.getElementById('input-file').files[0],
    ACL: "private", // 初始化acl權限，默認為private，"private"|"public-read"|"public-read-write"
    ContentType: "text/plain", // 設置contentType, 默認是application/octet-stream
};
s3Client.putObject(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

請求參數

返回結果

下載對象

功能說明

您可以使用 getObject 接口下載對象，以下代碼展示如何下載一個對象。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
};
s3Client.getObject(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

請求參數

返回結果

復制對象

功能說明

您可以使用 copyObject 接口復制對象，您需要設置復制的對象名，所在的桶以及目標桶和對象名。

代碼示例

?var params = {
    Bucket: "<dst-bucket-name>",
    Key: "<dst-bucket-name>",
    CopySource: "<source-bucket-name>" + "/" + "<source-object-key>" // 必須加上桶名前綴,
};
s3Client.copyObject(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

注意事項：對象key會放到請求頭header來發送，如果其中包含中文的話會出現編碼格式問題，解決方法是可以將header中的中文字符進行URL編碼。

請求參數

返回結果

刪除對象

功能說明

您可以使用 deleteObject 接口刪除單個對象，以下代碼展示如何刪除一個對象。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
};
s3Client.deleteObject(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

請求參數

返回結果

根據返回碼判斷是否操作成功。

批量刪除對象

功能說明

您可以使用 deleteObjects 接口批量刪除多個對象，代碼示例如下。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Delete: {
        Objects: [
            {
                'Key': 'ExampleObject.txt',
            },
            {
                'Key': 'ExampleObject1.txt',
            },
        ]
    },
};
s3Client.deleteObjects(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success");
    }
});

請求參數

返回結果

根據返回碼判斷是否操作成功。

獲取對象元數據

功能說明

您可以使用 headObject 接口獲取對象元數據。headObject 操作的請求參數與 getObject 類似，但是 headObject 返回的http響應中沒有對象數據。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
};
s3Client.headObject(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success: ", data.ContentType);
    }
});

請求參數

返回結果

設置對象訪問權限

功能說明

與桶訪問權限類似，對象訪問權限設置方式具有 Canned ACL與 AccessControlPolicy兩種。需要注意的是，對象的訪問優先級要高于桶訪問權限。比如桶訪問權限是 private，但是對象訪問權限是 public read，則所有用戶都可以訪問該對象。默認情況下，只有對象的擁有者才能訪問該對象，即對象的訪問權限默認是 private。

代碼示例

使用canned ACL設置桶的訪問權限，對象訪問權限包含了：private(私有讀寫)，public-read（公共讀私有寫），public-read-write（公共讀寫），示例代碼如下：

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    ACL: "public-read-write",
};
?
s3Client.putObjectAcl(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

使用ACL對象授予權限，指定顯式訪問權限和被授權用戶 。這些參數映射到s3Client在ACL中支持的權限集。使用 AccessControlList 設置桶訪問權限時，可以設置特定用戶對桶的訪問權限：

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    AccessControlPolicy: {
        Grants: [
            {
                Grantee: {
                    Type: "CanonicalUser",
                    ID: "<grantee-canonical-id>"
                },
                Permission: "FULL_CONTROL"
            },
        ],
        Owner: {
            ID: "<owner-canonical-id>",
        }
    }
};
s3Client.putObjectAcl(params, function (err, data) {
    if (err) console.log(err, err.stack);
    else console.log(data);
});

請求參數

• 預定義的ACL

每個Canned ACL都有一組預定義的被授權者和權限，下表列出了相關的預定義授權含義:

• 指定顯式訪問權限和被授權用戶AccessControlPolicy

關于AccessControlPolicy的說明：

Owner參數用來指定桶的所有者信息，Grants參數用來指定被授權的用戶信息。其中和權限有關的參數是Permission，您可以選擇 FULL_CONTROL | READ | WRITE | READ_ACP | WRITE_ACP 來設定相應的權限。

返回結果

根據返回碼判斷是否操作成功。

獲取對象訪問權限

功能說明

您可以使用 getObjectAcl 接口獲取對象訪問的權限。以下代碼展示如何獲取對象的訪問權限。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
};
s3Client.getObjectAcl(params, function (err, data) {
    if (err)
        console.log(err, err.stack);
    else
        console.log(data);
});

請求參數

返回結果

獲取對象標簽

功能說明

您可以使用getObjectTagging接口獲取對象標簽。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
};
s3Client.getObjectTagging(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data.TagSet[0]);
    }
});

請求參數

返回結果

刪除對象標簽

功能說明

您可以使用deleteObjectTagging接口刪除對象標簽。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
};
s3Client.deleteObjectTagging(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

請求參數

返回結果

根據返回碼判斷是否操作成功。

設置對象標簽

功能說明

您可以使用putObjectTagging接口為對象設置標簽。標簽是一個鍵值對，每個對象最多可以有10個標簽。bucket的擁有者默認擁有給bucket中的對象設置標簽的權限，并且可以將權限授予其他用戶。每次執行PutObjectTagging操作會覆蓋對象已有的標簽信息。每個對象最多可以設置10個標簽，標簽Key和Value區分大小寫，并且Key不可重復。每個標簽的Key長度不超過128字節，Value長度不超過256字節。SDK通過HTTP header的方式設置標簽且標簽中包含任意字符時，需要對標簽的Key和Value做URL編碼。設置對象標簽信息不會更新對象的最新更改時間。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    Tagging: {
        TagSet: [
            {
                Key: 'key1',
                Value: 'value1'
            },
        ]
    }
};
s3Client.putObjectTagging(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

請求參數

返回結果

根據返回碼判斷是否操作成功。

生成下載預簽名URL

功能說明

getSignedUrl接口為一個指定對象生成一個預簽名的下載鏈接，訪問該鏈接可以直接下載該對象。

代碼示例

生成預簽名下載鏈接

generateGetObjectSignedUrl: function (fileName, callback) {
    console.log("生成用于下載的預簽名URL");
    let params = {
        Bucket: this.bucket,
        Key: fileName,
        Expires: 900,
    };
    this.s3Client.getSignedUrl("getObject", params, function(err, url) {
        if (err) {
            console.error("生成URL時出錯: ", err);
        } else {
            console.log("預簽名URL: ", url);
            callback(url);
        }
    });
}

生成下載對象的預簽名URL后，可以直接通過該URL請求下載文件

getObjUsingPresignedUrl: function (presignedUrl) {
    console.log("開始下載文件...");
    fetch(presignedUrl, {
        method: 'GET',
    })
    .then(response => {
        if (response.ok) {
            return response.blob();
        } else {
            throw new Error(`下載失敗，狀態碼: ${response.status}`);
        }
    })
    .then(blob => {
        const url = URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = "downloadedFile";
        document.body.appendChild(a);
        a.click();
        a.remove();
        URL.revokeObjectURL(url);
        console.log("文件下載成功");
    })
    .catch(error => {
        console.error("下載出錯: ", error);
    });
}

請求參數

返回結果

生成對應的預簽名下載 URL，該鏈接允許用戶在指定的時間內直接從媒體存儲下載對象。

生成上傳預簽名URL

功能說明

getSignedUrl接口為一個指定對象生成一個預簽名的上傳鏈接，訪問該鏈接可以直接上傳對象到指定的媒體存儲存儲桶。

代碼示例

生成預簽名上傳鏈接

generatePutObjectSignedUrl: function (fileName, callback) {
    console.log("生成用于上傳對象的預簽名URL");
    let params = {
        Bucket: this.bucket,
        Key: fileName,
        Expires: 900,
        ContentType: "image/png",
    };
    this.s3Client.getSignedUrl("putObject", params, function(err, url) {
        if (err) {
            console.error("生成URL時出錯: ", err);
        } else {
            console.log("預簽名URL: ", url);
            callback(url);
        }
    });
}

生成上傳對象的預簽名URL后，可以直接通過該URL將文件上傳至媒體存儲。

putObjUsingPresignedUrl: function (presignedUrl, file) {
    console.log("開始上傳文件...");
    fetch(presignedUrl, {
        method: 'PUT',
        headers: {
            'Content-Type': 'image/png' // 需要跟生成預簽名URL時指定的ContentType一致
        },
        body: file
    })
    .then(response => {
        if (response.ok) {
            console.log("文件上傳成功");
        } else {
            console.error("上傳失敗，狀態碼: ", response.status);
        }
    })
    .catch(error => {
        console.error("上傳出錯: ", error);
    });
}

請求參數

返回結果

生成對應的預簽名上傳 URL，該鏈接允許用戶在指定的時間內直接將對象上傳到媒體存儲存儲桶。

服務端加密

功能說明

上傳對象時可以指定對象的加密算法，即使設置桶的加密配置也可以加密請求上傳的對象數據，服務端根據指定的加密算法對對象數據進行加密，目前支持AES256和國密SM4加密算法。

代碼示例

上傳對象，并開啟服務端加密：

//上傳文件
var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    Body: "<your-key-body>",
    ServerSideEncryption: "AES256"
};
s3Client.putObject(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

請求參數

返回結果

根據返回碼判斷是否操作成功。

獲取多版本對象列表

功能說明

如果桶開啟了版本控制，您可以使用 listObjectVersions接口列舉對象的版本，每次list操作最多返回1000個分片上傳事件，簡單列舉對象版本代碼如下。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
};
s3Client.listObjectVersions(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

請求參數

返回結果