获取对象列表

功能说明

您可以使用 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();

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
MaxKeys	Int	设置响应中返回的最大键数。默认值和可设置最大值均为1000	否
Prefix	String	指定列出对象的键名需要包含的前缀	否
Marker	String	用于在某一个具体的键名后列出对象，可指定存储桶中的任一个键名	否

返回结果

listObjects 中可设置的列举相关参数如下：

参数	描述
Bucket	包含对象的存储桶的名称
Delimiter	分隔符是用于对对象 objectKey 进行分组的字符。所有名字包含指定的prefix（可以不指定）且第一次出现 delimiter 字符之间的对象作为一组返回对象
Marker	指定列出存储桶中的对象时以其开头的键
MaxKeys	设置响应中返回的最大键数。默认情况下，该操作最多返回1,000个键名
Prefix	将响应限制为以指定前缀开头的键

上传对象

功能说明

您可以使用 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);
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象名称	是
Body	String	对象内容	是
ACL	String	对象访问控制权限	否
ContentType	String	对象类型	是

返回结果

参数	类型	说明
ETag	String	上传对象后对应的Entity Tag

下载对象

功能说明

您可以使用 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);
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象名称	是

返回结果

参数	类型	说明
Body	Array	对象数据内容字节数组
ContentLength	Int	对象数据的长度，单位为字节
ContentType	String	数据的标准MIME类型
Metadata	Object	自定义元数据
ETag	String	对象的Entity Tag
LastModified	Time	最后修改对象的时。
StorageClass	String	对象的存储类型

复制对象

功能说明

您可以使用 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编码。

请求参数

参数	类型	说明	是否必要
Bucket	String	目的桶名称	是
Key	String	目的桶的对象key	是
CopySource	String	源对象地址（bucket+key）	是

返回结果

参数	类型	说明
CopyObjectResult	Object	包含拷贝生成对象的Entity Tag和最后修改时间等信息

删除对象

功能说明

您可以使用 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);
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象名称	是

返回结果

根据返回码判断是否操作成功。

批量删除对象

功能说明

您可以使用 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");
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Delete	Delete	要删除的对象key列表	是

返回结果

根据返回码判断是否操作成功。

获取对象元数据

功能说明

您可以使用 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);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象key	是

返回结果

参数	类型	说明
AcceptRanges	String	跨域访问规则
LastModified	Date	最后修改时间
ContentLength	Long	对象大小
ETag	String	资源标识符
ContentType	String	对象类型
Metadata	Object	对象元数据
StorageClass	String	对象存储类型

设置对象访问权限

功能说明

与桶访问权限类似，对象访问权限设置方式具有 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

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象名称	是
ACL	String	桶访问权限，参考上面的Canned ACL	是

每个Canned ACL都有一组预定义的被授权者和权限，下表列出了相关的预定义授权含义:

ACL	权限	描述
private	私有读写	对象拥有者有读写权限，其他用户没有访问权限
public-read	公共读私有写	对象拥有者有读写权限，其他用户只有该对象的读权限
public-read-write	公共读写	所有用户都有该对象的读写权限

指定显式访问权限和被授权用户AccessControlPolicy

参数	类型	说明	是否必要
Bucket	String	桶名称	是
AccessControlPolicy	Object	访问权限和被授权用户对象	是

关于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);
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象名	是

返回结果

参数	类型	说明
Owner	Object	对象的owner信息
Grants	Object	grants 授权信息，包含了每个用户与其权限Permission

获取对象标签

功能说明

您可以使用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]);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象key	是
VersionId	String	设置标签信息的对象的版本Id	否

返回结果

参数	类型	说明
TagSet	Array	设置的标签信息，包含了一个Tag结构体的数组，每个Tag以Key-Value的形式说明了标签的内容

删除对象标签

功能说明

您可以使用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);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	执行本操作的桶名称	是
Key	String	设置标签信息的对象key	是
VersionId	String	设置标签信息的对象的版本Id	否

返回结果

根据返回码判断是否操作成功。

设置对象标签

功能说明

您可以使用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);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	对象key	是
Tagging	Object	设置的标签信息，包含了一个Tag结构体的数组，每个Tag以Key-Value的形式说明了标签的内容	是
VersionId	String	设置标签信息的对象的版本Id	否

返回结果

根据返回码判断是否操作成功。

生成上传对象预签名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();
}

请求参数

参数	类型	说明	是否必要
Bucket	String	bucket的名称	是
Key	String	对象的key	是
Expires	Int	超时时间（秒）	否，默认900秒
ContentType	String	对象的ContentType	否。若生成预签名URL时指定了，则通过预签名链接上传时也需要指定为相同的ContentType

返回结果

生成对应的预签名上传 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();
}

请求参数

参数	类型	说明	是否必要
Bucket	String	bucket的名称	是
Key	String	对象的key	是
Expires	Int	超时时间（秒）	否，默认900秒

返回结果

生成对应的预签名下载 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);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
Key	String	上传对象名	是
Body	String	上传对象流	是
ServerSideEncryption	String	服务端加密算法	是

返回结果

根据返回码判断是否操作成功。

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);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	bucket的名称	是
Key	String	对象的key	是
Expires	Int	超时时间（秒）	否，默认900秒

返回结果

参数	类型	说明
url	String	请求上传的url
Policy	String	服务端用于校验的policy
X-Amz-Algorithm	String	v4签名，哈希算法
X-Amz-Signature	String	v4签名，请求的参数签名
X-Amz-Date	String	v4签名，日期信息
X-Amz-Credential	String	v4签名，ak信息

前端使用方式如下：

<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);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
MaxKeys	Int	设置响应中返回的最大键数。默认值和可设置最大值均为1000	否
Prefix	String	指定列出对象的键名需要包含的前缀	否
Marker	String	用于在某一个具体的键名后列出对象，可指定存储桶中的任一个键名	否

返回结果

参数	类型	说明
IsTruncated	Boolean	分页判断，指明是否已返回所有结果
KeyMarker	String	设定结果从KeyMarker之后按字母序开始返回，与VersionIdMarker组合使用
VersionIdMarker	String	设定结果从KeyMarker对象的VersionIdMarker之后按新旧版本排序开始返回
Versions	Array	保存除删除标记以外的对象多版本的数组
DeleteMarkers	Array	保存删除标记的对象数组
Name	String	桶名
Prefix	String	本次查询结果的前缀
MaxKeys	String	限定此次返回对象的最大个数
CommonPrefixes	Array	公共前缀

活动

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

媒体存储

媒体存储

获取对象列表

功能说明

代码示例

请求参数

返回结果

上传对象

功能说明

代码示例

请求参数

返回结果

下载对象

功能说明

代码示例

请求参数

返回结果

复制对象

功能说明

代码示例

请求参数

返回结果

删除对象

功能说明

代码示例

请求参数

返回结果

批量删除对象

功能说明

代码示例

请求参数

返回结果

获取对象元数据

功能说明

代码示例

请求参数

返回结果

设置对象访问权限

功能说明

代码示例

请求参数

返回结果

获取对象访问权限

功能说明

代码示例

请求参数

返回结果

获取对象标签

功能说明

代码示例

请求参数

返回结果

删除对象标签

功能说明

代码示例

请求参数

返回结果

设置对象标签

功能说明

代码示例

请求参数

返回结果

生成上传对象预签名URL

功能说明

代码示例

请求参数

返回结果

生成下载对象预签名URL

功能说明

代码示例

请求参数

返回结果