S3-boto3

秦英发

2023-12-01

1. list_objects(**kwargs)

定义：

返回存储桶中的部分或全部对象（最多 1,000 个）。
可以使用请求参数作为选择标准来返回存储桶中对象的子集。
200 OK 响应可以包含有效或无效的 XML。

请求语法：

response = client.list_objects(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    Marker='string',
    MaxKeys=123,
    Prefix='string',
    RequestPayer='requester',
    ExpectedBucketOwner='string'
)

参数

Bucket（string） --[REQUIRED]：包含对象的存储桶的名称；
Delimiter（string）–分隔符是用于对键进行分组的字符；
EncodingType（string）–请求 Amazon S3 对响应中的对象键进行编码并指定要使用的编码方法。对象键可以包含任何 Unicode 字符；
Marker（string）–标记是您希望 Amazon S3 开始列出的位置。Amazon S3 在此指定键之后开始列出。标记可以是桶中的任何键；
MaxKeys ( integer ) – 设置响应中返回的最大键数。默认情况下，该操作最多返回 1,000 个键名。响应可能包含更少的键，但永远不会包含更多；
Prefix ( string ) – 将响应限制为以指定前缀开头的键；
RequestPayer ( string ) – 确认请求者知道她或他将为列表对象请求付费。存储桶所有者无需在其请求中指定此参数；
ExpectedBucketOwner ( string ) – 预期存储桶所有者的帐户 ID。如果存储桶由其他帐户拥有，则请求将失败并显示 HTTP 403 （拒绝访问）错误。

返回类型：dict
响应语法：

{
    'IsTruncated': True|False,
    'Marker': 'string',
    'NextMarker': 'string',
    'Contents': [
        {
            'Key': 'string',
            'LastModified': datetime(2015, 1, 1),
            'ETag': 'string',
            'Size': 123,
            'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'GLACIER'|'STANDARD_IA'|'ONEZONE_IA'|'INTELLIGENT_TIERING'|'DEEP_ARCHIVE'|'OUTPOSTS',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            }
        },
    ],
    'Name': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxKeys': 123,
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url'
}

响应结构：

(dict) –
IsTruncated (boolean) --一个标志，指示 Amazon S3 是否返回了满足搜索条件的所有结果；
Marker (string) --指示存储桶列表中的何处开始。如果标记与请求一起发送，则标记包含在响应中；
NextMarker (string) --当响应被截断时（响应中的 IsTruncated 元素值为 true），您可以使用该字段中的键名作为后续请求中的标记，以获取下一组对象。Amazon S3 按字母顺序列出对象注意：仅当您指定了分隔符请求参数时，才会返回此元素。如果响应中没有包含NextMarker并且被截断了，可以使用响应中最后一个Key的值作为后续请求中的标记，获取下一组对象键；
Contents (list) --返回的每个对象的元数据.
(dict) --对象由数据及其描述性元数据组成；
Key (string) --您分配给对象的名称。您使用对象键来检索对象；
LastModified (datetime) --对象的创建日期；
ETag (string) --实体标签是对象的散列。ETag 仅反映对象内容的更改，而不反映其元数据。ETag 可能是也可能不是对象数据的 MD5 摘要。它是否取决于对象是如何创建的以及它是如何加密的，如下所述：
- 由 PUT 对象、POST 对象或复制操作或通过 Amazon Web 服务管理控制台创建并由 SSE-S3 或纯文本加密的对象具有作为其对象数据的 MD5 摘要的 ETag。
- 由 PUT 对象、POST 对象或复制操作或通过 Amazon Web Services 管理控制台创建并由 SSE-C 或 SSE-KMS 加密的对象具有不是其对象数据的 MD5 摘要的 ETag。
- 如果对象是通过分段上传或部分复制操作创建的，则 ETag 不是 MD5 摘要，无论加密方法如何。
Size (integer) --对象的大小（以字节为单位）
StorageClass (string) --用于存储对象的存储类
Owner (dict) --用于存储对象的存储类
DisplayName (string) --对象的所有者

2. list_objects_v2(**kwargs)

定义：

每次请求返回存储桶中的部分或全部（最多 1,000 个）对象。
可以使用请求参数作为选择标准来返回存储桶中对象的子集。
一个200 OK响应可以包含有效或无效的XML，确保将应用程序设计为解析响应的内容并对其进行适当处理。
返回的对象按列表中各个键名的升序排序。

请求语法

response = client.list_objects_v2 ( 
    Bucket = 'string' , 
    Delimiter = 'string' , 
    EncodingType = 'url' , 
    MaxKeys = 123 , 
    Prefix = 'string' , 
    ContinuationToken = 'string' , 
    FetchOwner = True | False , 
    StartAfter = 'string' , 
    RequestPayer = 'requester' , 
    ExpectedBucketOwner = 'string'
)

参数

Bucket（string） --[REQUIRED]：包含对象的存储桶的名称；
Delimiter（string）–分隔符是用于对键进行分组的字符；
EncodingType（string）–请求 Amazon S3 对响应中的对象键进行编码并指定要使用的编码方法。对象键可以包含任何 Unicode 字符；
Marker（string）–标记是您希望 Amazon S3 开始列出的位置。Amazon S3 在此指定键之后开始列出。标记可以是桶中的任何键；
MaxKeys ( integer ) – 设置响应中返回的最大键数。默认情况下，该操作最多返回 1,000 个键名。响应可能包含更少的键，但永远不会包含更多；
Prefix ( string ) – 将响应限制为以指定前缀开头的键；
ContinuationToken ( string ) – ContinuationToken 指示 Amazon S3 正在使用令牌在此存储桶上继续列表。ContinuationToken 被混淆并且不是真正的密钥；
FetchOwner ( boolean ) – 默认情况下，listV2 中不存在 owner 字段，如果您想返回带有结果中每个键的 owner 字段，则将 fetch owner 字段设置为 true；
StartAfter ( string ) – StartAfter 是希望 Amazon S3 开始列出的位置。Amazon S3 在此指定键之后开始列出。StartAfter 可以是存储桶中的任何键；
RequestPayer ( string ) – 确认请求者知道她或他将为列表对象请求付费。存储桶所有者无需在其请求中指定此参数；
ExpectedBucketOwner ( string ) – 预期存储桶所有者的帐户 ID。如果存储桶由其他帐户拥有，则请求将失败并显示 HTTP 403 （拒绝访问）错误。

返回类型：dict
响应语法：

{
    'IsTruncated': True|False,
    'Contents': [
        {
            'Key': 'string',
            'LastModified': datetime(2015, 1, 1),
            'ETag': 'string',
            'Size': 123,
            'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'GLACIER'|'STANDARD_IA'|'ONEZONE_IA'|'INTELLIGENT_TIERING'|'DEEP_ARCHIVE'|'OUTPOSTS',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            }
        },
    ],
    'Name': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxKeys': 123,
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url',
    'KeyCount': 123,
    'ContinuationToken': 'string',
    'NextContinuationToken': 'string',
    'StartAfter': 'string'
}

3. delete_object ( **kwargs )

定义：删除对象的空版本（如果有）并插入删除标记，它成为对象的最新版本。如果没有空版本，Amazon S3 不会删除任何对象，但仍会响应命令成功。要删除特定版本，您必须是存储桶所有者并且必须使用版本 ID 子资源。使用此子资源会永久删除版本。如果删除的对象是删除标记，Amazon S3会将响应标头x-amz-delete-marker 设置为 true。如果要删除的对象位于存储桶版本控制配置启用 MFA 删除的存储桶中，则必须在 DELETE versionId请求中包含x-amz-mfa请求标头。包含x-amz-mfa 的请求必须使用 HTTPS。
请求语法：

response = client.delete_object(
    Bucket='string',
    Key='string',
    MFA='string',
    VersionId='string',
    RequestPayer='requester',
    BypassGovernanceRetention=True|False,
    ExpectedBucketOwner='string'
)

参数：

Bucket（string）–[REQUIRED]
Key (string) --[REQUIRED]

返回类型：dict
返回语法：

{
    'DeleteMarker': True|False,
    'VersionId': 'string',
    'RequestCharged': 'requester'
}

DeleteMarker：指定永久删除的版本化对象是 (true) 还是不是 (false) 删除标记；
VersionId：返回作为 DELETE 操作的结果创建的删除标记的版本 ID；
RequestCharged ：如果存在，则表明请求者已成功为请求收费。

例子：

response = client.delete_object(
    Bucket='examplebucket',
    Key='objectkey.jpg',
)

print(response)

4. head_object（**kwargs）

定义：

HEAD 操作从对象中检索元数据，而不返回对象本身。如果您只对对象的元数据感兴趣，则此操作很有用。要使用 HEAD，必须对该对象具有 READ 访问权限。
HEAD请求具有相同的选项作为GET的对象上操作。除了没有响应正文之外，响应与GET响应相同。因此，如果HEAD请求产生错误，它会返回一个通用的404 Not Found或403 Forbidden代码。除了这些错误代码之外，无法检索确切的异常。

请求语法

response = client.head_object(
    Bucket='string',
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Key='string',
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester',
    PartNumber=123,
    ExpectedBucketOwner='string'
)

返回类型：dict
响应语法：

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'ArchiveStatus': 'ARCHIVE_ACCESS'|'DEEP_ARCHIVE_ACCESS',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'BucketKeyEnabled': True|False,
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'STANDARD_IA'|'ONEZONE_IA'|'INTELLIGENT_TIERING'|'GLACIER'|'DEEP_ARCHIVE'|'OUTPOSTS',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA',
    'PartsCount': 123,
    'ObjectLockMode': 'GOVERNANCE'|'COMPLIANCE',
    'ObjectLockRetainUntilDate': datetime(2015, 1, 1),
    'ObjectLockLegalHoldStatus': 'ON'|'OFF'
}

例子

response = client.head_object(
    Bucket='examplebucket',
    Key='HappyFace.jpg',
)

print(response)

5. put_object（**kwargs）

定义：

将对象添加到存储桶。您必须对存储桶具有 WRITE 权限才能向其中添加对象。
Amazon S3 从不添加部分对象；如果您收到成功响应，则 Amazon S3 将整个对象添加到存储桶中。
Amazon S3 是一个分布式系统。如果它同时收到对同一对象的多个写入请求，它会覆盖除最后写入的对象之外的所有对象。Amazon S3 不提供对象锁定；如果您需要它，请确保将其构建到您的应用程序层或改用版本控制。
为确保数据在通过网络时不会损坏，请使用Content-MD5标头。当您使用此标头时，Amazon S3 会根据提供的 MD5 值检查对象，如果它们不匹配，则返回错误。此外，您可以在将对象放入 Amazon S3 时计算 MD5，并将返回的 ETag 与计算的 MD5 值进行比较。

请求语法：

response = client.put_object(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'aws-exec-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Body=b'bytes'|file,
    Bucket='string',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength=123,
    ContentMD5='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Key='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'STANDARD_IA'|'ONEZONE_IA'|'INTELLIGENT_TIERING'|'GLACIER'|'DEEP_ARCHIVE'|'OUTPOSTS',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    SSEKMSEncryptionContext='string',
    BucketKeyEnabled=True|False,
    RequestPayer='requester',
    Tagging='string',
    ObjectLockMode='GOVERNANCE'|'COMPLIANCE',
    ObjectLockRetainUntilDate=datetime(2015, 1, 1),
    ObjectLockLegalHoldStatus='ON'|'OFF',
    ExpectedBucketOwner='string'
)

返回类型：dict
响应语法：

{
    'Expiration': 'string',
    'ETag': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'VersionId': 'string',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'SSEKMSEncryptionContext': 'string',
    'BucketKeyEnabled': True|False,
    'RequestCharged': 'requester'
}

例子：

response = client.put_object(
    Body='filetoupload',
    Bucket='examplebucket',
    Key='objectkey',
)

print(response)

输出：

{
    'ETag': '"6805f2cfc46c0f04559748bb039d69ae"',
    'VersionId': 'Bvq0EDKxOcXLJXNo_Lkz37eM3R4pfzyQ',
    'ResponseMetadata': {
        '...': '...',
    },
}

S3-boto3

1. list_objects(**kwargs)

2. list_objects_v2(**kwargs)

3. delete_object ( **kwargs )

4. head_object（**kwargs）

5. put_object（**kwargs）

相关阅读

相关文章

相关问答