獲取對象列表

功能說明

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

代碼示例

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

如果 list 大于1000，則返回的結果中 isTruncated 為true，通過返回的 nextMarker 標記可以作為下次讀取的起點。列舉所有對象示例代碼如下：

let marker = ''; 
const params = {
    Bucket: "<your-bucket-name>",
    MaxKeys: 1000,
    Marker: marker
};
?
const fetchObjects = () => {
    s3Client.listObjects(params, function (err, data) {
        if (err) {
            console.error("Error listing objects:", err);
            return;
        }
?
        if (data.Contents && data.Contents.length > 0) {
            data.Contents.forEach(obj => {
                console.log("Object Key:", obj.Key);
            });
        }
?
        // 更新 marker
        if (data.IsTruncated) {
            params.Marker = data.NextMarker || '';
            fetchObjects(); 
        }
    });
};
?
fetchObjects(); 

請求參數

返回結果

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對象，以字節流的方式進行上傳：

var params = {
    Bucket: "<your-bucket-name>",
    Key: "<your-key-name>",
    Body: fs.createReadStream('<your-file-path>'),
    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接口為一個指定對象生成一個預簽名的上傳鏈接，訪問該鏈接可以直接上傳對象到指定的媒體存儲存儲桶。

代碼示例

生成預簽名上傳鏈接

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

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

putObjUsingPresignedUrl: function (presignedUrl, filePath) {
    const http = require('http');
    const fs = require('fs');
    const url = require('url');
    const parsedUrl = url.parse(presignedUrl);
    const fileData = fs.readFileSync(filePath);
?
    const options = {
        hostname: parsedUrl.hostname,
        port: parsedUrl.port,
        path: parsedUrl.path,
        method: 'PUT',
        headers: {
            'Content-Length': fileData.length
        }
    };
?
    const req = http.request(options, (res) => {
        if (res.statusCode === 200) {
            console.log("File uploaded successfully");
        } else {
            console.log(`Failed to upload. Status Code: ${res.statusCode}`);
        }
    });
?
    req.on('error', (e) => {
        console.error(`Problem with request: ${e.message}`);
    });
?
    req.write(fileData);
    req.end();
}

請求參數

返回結果

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

生成下載對象預簽名URL

功能說明

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

代碼示例

生成預簽名下載鏈接

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

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

getObjUsingPresignedUrl: function (presignedUrl, saveFilePath) {
    const http = require('http');
    const fs = require('fs');
    const url = require('url');
    const parsedUrl = url.parse(presignedUrl);
?
    const options = {
        hostname: parsedUrl.hostname,
        port: parsedUrl.port,
        path: parsedUrl.path,
        method: 'GET'
    };
?
    const file = fs.createWriteStream(saveFilePath);
?
    const req = http.request(options, (res) => {
        if (res.statusCode === 200) {
            console.log("Downloading file...");
            res.pipe(file);
?
            file.on('finish', () => {
                file.close();
                console.log("File downloaded successfully");
            });
        } else {
            console.log(`Failed to download. Status Code: ${res.statusCode}`);
        }
    });
?
    req.on('error', (e) => {
        console.error(`Problem with request: ${e.message}`);
    });
?
    req.end();
}

請求參數

返回結果

生成對應的預簽名下載 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);
    }
});

請求參數

返回結果

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

Post上傳

功能說明

createPresignedPost接口為一個指定對象生成一個支持post方式上傳文件的參數集合，可以在前端使用post form-data的方式上傳文件。

代碼示例

var params = {
    Bucket: "<your-bucket-name>",
    Fields: {
        key: "<your-key-name>",
    },
    Conditions: [
        ['starts-with', '$key', key],
        //{"acl": "public-read" },                          // 設置acl
        //["starts-with", "$Content-Type", "image/jpeg"]    // 設置content-type
        //["content-length-range", 10, 1024],               // 限制上傳的文件大小
    ],
    Expires: 900,
};
s3Client.createPresignedPost(params, function (err, data) {
    if (err) {
        console.error('Presigning post data encountered an error', err);
    } else {
        console.log('The post data is', data);
    }
});

請求參數

返回結果

前端使用方式如下：

<form action="<data.url>" method="POST" enctype="multipart/form-data">
    <input type="hidden" name="Policy" value="<data.fields['Policy']>" />
    <input type="hidden" name="X-Amz-Algorithm" value="<data.fields['X-Amz-Algorithm']>" />
    <input type="hidden" name="X-Amz-Credential" value="<data.fields['X-Amz-Credential']>" />
    <input type="hidden" name="X-Amz-Date" value="<data.fields['X-Amz-Date']>" />
    <input type="hidden" name="X-Amz-Signature" value="<data.fields['X-Amz-Signature']>" />
    <input type="hidden" name="bucket" value="<data.fields['bucket']>" />
    <input type="hidden" name="key" value="<data.fields['key']>" />
?
    <input type="file" name="file" value="" />
    <input type="submit" value="Submit" />
</form>

獲取多版本對象列表

功能說明

如果桶開啟了版本控制，您可以使用 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);
    }
});

請求參數

返回結果