获取对象列表

功能说明

list_objects操作用于列出存储桶中的全部对象，该操作返回最多1000个对象信息，可以通过设置过滤条件来列出存储桶中符合特定条件的对象信息。

代码示例

def list_objects(self):
    print('list_objects')
    response = self.s3_client.list_objects(
        Bucket='<your-bucket-name>',
        MaxKeys=50,  # list up to 50 key at a time
    )
    for obj in response['Contents']:
        print(obj["Key"])

如果 list 大于1000，则返回的结果中 isTruncated 为true，通过Marker参数可以指定下次读取的起点。列举所有对象的示例代码如下：

def list_objects2(self):
    print('list_objects')
    objects = []
    response = self.s3_client.list_objects(
        Bucket=self.bucket,
        MaxKeys=100,
    )
    objects.extend(response['Contents'])
    while response['IsTruncated']:
        response = self.s3_client.list_objects(
            Bucket=self.bucket,
            MaxKeys=100,
            Marker=response['Contents'][-1]['Key']
        )
        objects.extend(response['Contents'])

    for obj in objects:
        print(obj["Key"])

请求参数

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

返回结果

参数	类型	说明
Contents	Content数组	对象列表

上传对象

功能说明

您可以使用put_object接口直接上传文件。

代码示例

def put_object(self):
    print('put_object')
    key = '<your-object-key>'
    local_path = '<file-path>'
    with open(local_path, 'rb') as f:
        resp = self.s3_client.put_object(
            Bucket='<your-bucket-name>',
            Key=key,
            Body=f,
            # ACL='public-read',
            # ContentType='text/json',
        )
        print(resp)

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名	是
Key	string	对象名	是
Body	bytes\|file	要上传的数据，如打开的文件对象	是
ACL	string	对象访问权限，取值private \| public-read \| public-read-write	否
ContentType	string	http content-type header	否
Metadata	dict	自定义元数据	否

返回结果

参数	类型	说明
ETag	string	对象的唯一标签

注意：put_object对文件大小有限制，最大能上传5GB大小的文件，超过5GB需要使用分片上传。

下载对象

功能说明

您可以使用get_object下载对象。

代码示例

def get_object(self):
    print('get_object')
    key = '<your-object-key>'
    local_path = 'E:/ExampleObject.txt'
    resp = self.s3_client.get_object(
        Bucket='<your-bucket-name>',
        Key=key
    )
    body = resp["Body"]
    with open(local_path, 'wb') as f:
        for chunk in body:
            f.write(chunk)

请求参数

参数	类型	说明	是否必须
Bucket	string	桶名	是
Key	string	对象名	是

返回结果

参数	类型	说明
Body	StreamingBody	对象数据内容
Metadata	dict	自定义元数据

复制对象

功能说明

您可以使用copy_object复制一个已经在媒体存储中的对象。使用copy_object可以复制单个最大为5GB的对象。执行copy_object操作，必须具有对被拷贝对象的READ权限和对目标bucket的WRITE权限。

代码示例

def copy_object(self):
    key = '<dst-object-key>'
    resp = self.s3_client.copy_object(
        Bucket='<dst-bucket-name>',
        Key=key,
        CopySource={'Bucket': '<source-bucket-name>', 'Key': '<source-object-key>'},
        ContentType="text/json",
        MetadataDirective='REPLACE',
    )
    print(resp)

文件比较大（超过1GB）的情况下，直接使用copyObject 可能会出现超时，需要使用分片复制的方式进行文件复制。TransferManager封装了分片复制的接口，可以用于复制文件。

class TransferDemo(object):
    def __init__(self):
        config = botocore.config.Config(
            signature_version='s3v4',  # s3 or s3v4
        )

        session = botocore.session.get_session()
        self.s3_client = session.create_client(
            's3',
            aws_access_key_id='<your-access-key>',
            aws_secret_access_key='<your-secret-key>',
            endpoint_url='<your-endpoint>',
            config=config)

        MB = 1024 * 1024
        transConfig = s3transfer.manager.TransferConfig(
            multipart_threshold=5 * MB,  # 大于该值使用分片上传
            multipart_chunksize=5 * MB,  # 分片大小
            max_request_concurrency=2,
            )

        # 设置带宽，不填表示不限制
        # transConfig.max_bandwidth = 1 * MB

        self.transfer = s3transfer.manager.TransferManager(self.s3_client, transConfig)

    def copy(self):
        print(datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f'), "copy start")
        source={'Bucket': '<source-bucket-name>', 'Key': '<source-object-key>'}
        dstBucket = '<dst-bucket-name>'
        dstKey = '<dst-object-key>'
        # 扩展配置
        extraArgs = {'ContentType': 'text/plain', 'ACL': 'public-read'}
        future = self.transfer.copy(source, dstBucket, dstKey, extra_args=extraArgs)
        future.result()
        print(datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f'), "copy success")

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是
Key	string	目的对象key	是
CopySource	CopySource	源对象	是
ContentType	string	设置目的对象的ContentType	否

关于CopySource：

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

返回结果

参数	类型	说明
ETag	string	对象的唯一标签

删除对象

功能说明

您可以使用delete_object接口删除对象。

代码示例

def delete_object(self):
    key = '<your-object-key>'
    resp = self.s3_client.delete_object(
        Bucket='<your-bucket-name>',
        Key=key,
    )
    print(resp)

请求参数

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

返回结果

根据返回码判断是否删除成功，204表示删除成功

批量删除对象

功能说明

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

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

代码示例

def delete_objects(self):
    resp = self.s3_client.delete_objects(
        Bucket='<your-bucket-name>',
        Delete={
            'Objects': [
                {
                    'Key': 'ExampleObject.txt',
                },
                {
                    'Key': 'ExampleObject1.txt',
                },
            ],
        },
    )
    print(resp)

请求参数

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

返回结果

参数	类型	说明
Deleted	数组	删除结果数组，包含每一个key的删除信息

获取对象元数据

功能说明

您可以使用head_object接口获取对象元数据信息

代码示例

def head_object():
    resp = s3_client.head_object(
        Bucket='<your-bucket-name>',
        Key='<your-object-key>',
    )
    print(resp)

请求参数

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

返回结果

参数	类型	说明
ETag	string	对象唯一标签
VersionId	string	对象的版本ID
ContentType	string	对象ContentType
Metadata	数组	自定义元数据
StorageClass	string	存储类型
ContentLength	int	对象大小

设置对象访问权限

功能说明

媒体存储支持一组预先定义的授权，称为Canned ACL。每个Canned ACL都有一组预定义的被授权者和权限，下表列出了相关的预定义授权含义。

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

您可以通过put_object_acl接口为媒体存储服务中的对象设置ACL。对一个对象执行该操作需要具有WRITE_ACP权限。

代码示例

def put_object_acl(self):
    key = '<your-object-key>'
    resp = self.s3_client.put_object_acl(
        Bucket='<your-bucket-name>',
        Key=key,
        ACL='public-read',
    )
    print(resp)

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是
Key	string	对象key	是
ACL	string	acl值	是

返回结果

根据返回码判断是否设置成功，200表示成功。

获取对象访问权限

功能说明

您可以使用 get_object_acl操作获取对象的access control list（ACL）信息。

代码示例

def get_object_acl(self):
    key = '<your-object-key>'
    resp = self.s3_client.get_object_acl(
        Bucket='<your-bucket-name>',
        Key=key,
    )
    for grant in resp['Grants']:
        print(grant)

请求参数

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

返回结果

参数	类型	说明
Owner	Owner	所有者信息
Grants	Grant数组	每种类型用户的详细权限信息

获取对象标签

功能说明

您可以使用get_object_tagging接口获取对象标签。

代码示例

def get_object_tagging():
    resp = s3_client.get_object_tagging(
        Bucket='<your-bucket-name>',
        Key='<your-object-key>'
    )
    print(resp)

请求参数

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

返回结果

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

删除对象标签

功能说明

您可以使用delete_object_tagging接口删除对象标签。

代码示例

def delete_object_tagging():
    resp = s3_client.delete_object_tagging(
        Bucket='<your-bucket-name>',
        Key='<your-object-key>'
    )
    print(resp)

请求参数

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

返回结果

根据返回码判断是否删除成功，204表示删除成功

设置对象标签

功能说明

您可以使用put_object_tagging接口为对象设置标签。标签是一个键值对，每个对象最多可以有10个标签。bucket的拥有者默认拥有给bucket中的对象设置标签的权限，并且可以将权限授予其他用户。每次执行PutObjectTagging操作会覆盖对象已有的标签信息。每个对象最多可以设置10个标签，标签Key和Value区分大小写，并且Key不可重复。每个标签的Key长度不超过128字节，Value长度不超过256字节。SDK通过HTTP header的方式设置标签且标签中包含任意字符时，需要对标签的Key和Value做URL编码。设置对象标签信息不会更新对象的最新更改时间。

代码示例

def put_object_tagging():
    resp = s3_client.put_object_tagging(
        Bucket='<your-bucket-name>',
        Key='<your-object-key>',
        Tagging={
            'TagSet': [
                {
                    'Key': 'key1',
                    'Value': 'value1'
                },
            ]
        }
    )
    print(resp)

请求参数

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

返回结果

根据返回码判断是否设置成功，200表示设置成功

生成预签名URL

功能说明

您可以通过generate_presigned_url接口为一个指定对象生成一个预签名的链接，用于下载或上传对象。

代码示例

生成一个预签名的下载链接：

def generate_getobject_presigned_url(self):
    print('generate_getobject_presigned_url')
    key = '<your-object-key>'
    url = self.s3_client.generate_presigned_url(
        ClientMethod='get_object',
        Params={'Bucket': '<your-bucket-name>', 'Key': key},
        ExpiresIn=900)
    print(url)

访问该预签名下载链接可以直接下载该对象：

def getObjUsingPresignedUrl(self, presigned_url, download_path):
    import requests
    response = requests.get(presigned_url)

    if response.status_code == 200:
        with open(download_path, 'wb') as file:
            file.write(response.content)
        print(f"Downloaded object saved to: {download_path}")
    else:
        print(f"Failed to download object. Status code: {response.status_code}")
    
    return response.status_code, response.text

生成一个预签名的上传链接：

def generate_putobject_presigned_url(self):
    print('generate_putobject_presigned_url')
    key = '<your-object-key>'
    url = self.s3_client.generate_presigned_url(
        ClientMethod='put_object',
        Params={'Bucket': '<your-bucket-name>', 'Key': key},
        ExpiresIn=900)

    print(url)

通过该预签名上传链接可以直接上传该对象：

def putObjUsingPresignedUrl(self, presigned_url, file_path):
    import requests
    with open(file_path, 'rb') as file:
        response = requests.put(presigned_url, data=file)
    
    print(f"Upload Response Status: {response.status_code}")
    return response.status_code, response.text

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是
Key	string	对象key	是
ExpiresIn	int	超时时间（秒）	否，默认3600秒

返回结果

参数	类型	说明
url	string	生成的链接

Post上传

功能说明

generate_presigned_post接口为一个指定对象生成一个支持post方式上传文件的参数集合，可以在前端使用post form-data的方式上传文件。

代码示例

def generate_postobject_presigned(self):
    print('generate_postobject_presigned')
    key = '<your-object-key>'
    Conditions = [
        ['starts-with', '$key', key],
    ]

    response = self.s3_client.generate_presigned_post(
        '<your-bucket-name>', 
        key,
        Fields={},
        Conditions=Conditions,
        ExpiresIn=3600)

    print(response)

请求参数

参数	类型	说明	是否必要
Bucket	string	bucket的名称	是
Key	string	对象的key	是
ExpiresIn	int	超时时间（秒）	否
Fields	数组	前端输入参数，用于配置acl，ContentType	否
Conditions	数组	参数策略，可以限制输入的参数	否

返回结果

参数	类型	说明
url	string	请求上传的url
key	string	对象的key
policy	string	服务端用于校验的policy
x-amz-algorithm	string	v4签名，哈希算法
x-amz-signature	string	v4签名，请求的参数签名
x-amz-date	string	v4签名，日期信息
x-amz-credential	string	v4签名，ak信息
AWSAccessKeyId	string	v2签名，ak信息
signature	string	v2签名，请求的参数签名

前端使用方式如下：

<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>

获取多版本对象列表

功能说明

如果桶开启了版本控制，您可以使用 list_object_versions接口列举对象的版本，每次list操作最多返回1000个对象。

代码示例

def list_object_versions(self):
    print('list_object_versions')
    response = self.s3_client.list_object_versions(
        Bucket='<your-bucket-name>',
        MaxKeys=50,  # list up to 50 key at a time
    )
    for obj in response['Versions']:
        print(obj["Key"])

请求参数

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

返回结果

参数	类型	说明
Versions	数组	对象列表

活动

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

媒体存储

媒体存储

获取对象列表

功能说明

代码示例

请求参数

返回结果

上传对象

功能说明

代码示例

请求参数

返回结果

下载对象

功能说明

代码示例

请求参数

返回结果

复制对象

功能说明

代码示例

请求参数

返回结果

删除对象

功能说明

代码示例

请求参数

返回结果

批量删除对象

功能说明

代码示例

请求参数

返回结果

获取对象元数据

功能说明

代码示例

请求参数

返回结果

设置对象访问权限

功能说明

代码示例

请求参数

返回结果

获取对象访问权限

功能说明

代码示例

请求参数

返回结果

获取对象标签

功能说明

代码示例

请求参数

返回结果

删除对象标签

功能说明

代码示例

请求参数

返回结果

设置对象标签

功能说明

代码示例

请求参数

返回结果

生成预签名URL

功能说明

代码示例

请求参数

返回结果

Post上传

功能说明

代码示例

请求参数

返回结果