Python 客户端 API 参考

1. 构造函数

Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None)

初始化一个新的客户端对象。

参数

参数	类型	描述
`endpoint`	str	S3 服务的主机名。
`access_key`	str	(可选) 您在 S3 服务中的帐户的访问密钥（也称为用户 ID）。
`secret_key`	str	(可选) 您在 S3 服务中的帐户的密钥（也称为密码）。
`session_token`	str	(可选) 您在 S3 服务中的帐户的会话令牌。
`secure`	bool	(可选) 指示是否使用安全 (TLS) 连接到 S3 服务的标志。
`region`	str	(可选) S3 服务中存储桶的区域名称。
`http_client`	urllib3.poolmanager.PoolManager	(可选) 自定义的 HTTP 客户端。
`credentials`	minio.credentials.Provider	(可选) 您在 S3 服务中的帐户的凭证提供程序。
`cert_check`	bool	(可选) 用于检查 HTTPS 连接的服务器证书的标志。

**关于并发使用的注意：**Minio 对象在使用 Python threading 库时是线程安全的。具体来说，**不**建议在多个进程之间共享它，例如在使用 multiprocessing.Pool 时。解决方案是在每个进程中创建一个新的 Minio 对象，并且不要在进程之间共享它。

示例

from minio import Minio

# Create client with anonymous access.
client = Minio("play.min.io")

# Create client with access and secret key.
client = Minio("s3.amazonaws.com", "ACCESS-KEY", "SECRET-KEY")

# Create client with access key and secret key with specific region.
client = Minio(
    "play.minio.io:9000",
    access_key="Q3AM3UQ867SPQQA43P2F",
    secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
    region="my-region",
)

# Create client with custom HTTP client using proxy server.
import urllib3
client = Minio(
    "SERVER:PORT",
    access_key="ACCESS_KEY",
    secret_key="SECRET_KEY",
    secure=True,
    http_client=urllib3.ProxyManager(
        "https://PROXYSERVER:PROXYPORT/",
        timeout=urllib3.Timeout.DEFAULT_TIMEOUT,
        cert_reqs="CERT_REQUIRED",
        retries=urllib3.Retry(
            total=5,
            backoff_factor=0.2,
            status_forcelist=[500, 502, 503, 504],
        ),
    ),
)

存储桶操作	对象操作
`make_bucket`	`get_object`
`list_buckets`	`put_object`
`bucket_exists`	`copy_object`
`remove_bucket`	`compose_object`
`list_objects`	`stat_object`
`get_bucket_versioning`	`remove_object`
`set_bucket_versioning`	`remove_objects`
`delete_bucket_replication`	`fput_object`
`get_bucket_replication`	`fget_object`
`set_bucket_replication`	`select_object_content`
`delete_bucket_lifecycle`	`delete_object_tags`
`get_bucket_lifecycle`	`get_object_tags`
`set_bucket_lifecycle`	`set_object_tags`
`delete_bucket_tags`	`enable_object_legal_hold`
`get_bucket_tags`	`disable_object_legal_hold`
`set_bucket_tags`	`is_object_legal_hold_enabled`
`delete_bucket_policy`	`get_object_retention`
`get_bucket_policy`	`set_object_retention`
`set_bucket_policy`	`presigned_get_object`
`delete_bucket_notification`	`presigned_put_object`
`get_bucket_notification`	`presigned_post_policy`
`set_bucket_notification`	`get_presigned_url`
`listen_bucket_notification`	`upload_snowball_objects`
`delete_bucket_encryption`
`get_bucket_encryption`
`set_bucket_encryption`
`删除对象锁定配置`
`获取对象锁定配置`
`设置对象锁定配置`

2. 存储桶操作

创建存储桶(bucket_name, location=’us-east-1’, object_lock=False)

创建一个带有区域和对象锁定的存储桶。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`location`	str	创建存储桶的区域。
`object_lock`	bool	设置对象锁定功能的标志。

示例

# Create bucket.
client.make_bucket("my-bucket")

# Create bucket on specific region.
client.make_bucket("my-bucket", "us-west-1")

# Create bucket with object-lock feature on specific region.
client.make_bucket("my-bucket", "eu-west-2", object_lock=True)

列出所有存储桶

列出所有可访问存储桶的信息。

参数

返回值
Bucket 列表

示例

buckets = client.list_buckets()
for bucket in buckets:
    print(bucket.name, bucket.creation_date)

检查存储桶是否存在(bucket_name)

检查存储桶是否存在。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

if client.bucket_exists("my-bucket"):
    print("my-bucket exists")
else:
    print("my-bucket does not exist")

删除存储桶(bucket_name)

删除一个空的存储桶。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.remove_bucket("my-bucket")

列出对象(bucket_name, prefix=None, recursive=False, start_after=None, include_user_meta=False, include_version=False, use_api_v1=False, use_url_encoding_type=True)

列出存储桶中的对象信息。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`prefix`	str	对象名称以 prefix 开头。
`recursive`	bool	递归列出目录结构模拟。
`start_after`	str	列出此键名称之后的对象。
`include_user_meta`	bool	MinIO 特定的标志，用于控制是否包含用户元数据。
`include_version`	bool	控制是否包含对象版本的标志。
`use_api_v1`	bool	控制是否使用 ListObjectV1 S3 API 的标志。
`use_url_encoding_type`	bool	控制是否使用 URL 编码类型的标志。

返回值

返回值
Object 的迭代器

示例

# List objects information.
objects = client.list_objects("my-bucket")
for obj in objects:
    print(obj)

# List objects information whose names starts with "my/prefix/".
objects = client.list_objects("my-bucket", prefix="my/prefix/")
for obj in objects:
    print(obj)

# List objects information recursively.
objects = client.list_objects("my-bucket", recursive=True)
for obj in objects:
    print(obj)

# List objects information recursively whose names starts with
# "my/prefix/".
objects = client.list_objects(
    "my-bucket", prefix="my/prefix/", recursive=True,
)
for obj in objects:
    print(obj)

# List objects information recursively after object name
# "my/prefix/world/1".
objects = client.list_objects(
    "my-bucket", recursive=True, start_after="my/prefix/world/1",
)
for obj in objects:
    print(obj)

获取存储桶策略(bucket_name)

获取存储桶的策略配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值

参数
存储桶策略配置，以 JSON 字符串形式表示。

示例

policy = client.get_bucket_policy("my-bucket")

设置存储桶策略(bucket_name, policy)

为存储桶设置策略配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`策略`	str	存储桶策略配置，以 JSON 字符串形式表示。

示例

# Example anonymous read-only bucket policy.
policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {"AWS": "*"},
            "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
            "Resource": "arn:aws:s3:::my-bucket",
        },
        {
            "Effect": "Allow",
            "Principal": {"AWS": "*"},
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-bucket/*",
        },
    ],
}
client.set_bucket_policy("my-bucket", json.dumps(policy))

# Example anonymous read-write bucket policy.
policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {"AWS": "*"},
            "Action": [
                "s3:GetBucketLocation",
                "s3:ListBucket",
                "s3:ListBucketMultipartUploads",
            ],
            "Resource": "arn:aws:s3:::my-bucket",
        },
        {
            "Effect": "Allow",
            "Principal": {"AWS": "*"},
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts",
                "s3:AbortMultipartUpload",
            ],
            "Resource": "arn:aws:s3:::my-bucket/images/*",
        },
    ],
}
client.set_bucket_policy("my-bucket", json.dumps(policy))

删除存储桶策略(bucket_name)

删除存储桶的策略配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_bucket_policy("my-bucket")

获取存储桶通知(bucket_name)

获取存储桶的通知配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值

参数
NotificationConfig 对象。

示例

config = client.get_bucket_notification("my-bucket")

设置存储桶通知(bucket_name, config)

设置存储桶的通知配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`config`	NotificationConfig	通知配置。

示例

config = NotificationConfig(
    queue_config_list=[
        QueueConfig(
            "QUEUE-ARN-OF-THIS-BUCKET",
            ["s3:ObjectCreated:*"],
            config_id="1",
            prefix_filter_rule=PrefixFilterRule("abc"),
        ),
    ],
)
client.set_bucket_notification("my-bucket", config)

删除存储桶通知(bucket_name)

删除存储桶的通知配置。成功后，S3 服务将停止之前为存储桶设置的事件通知。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_bucket_notification("my-bucket")

监听存储桶通知(bucket_name, prefix=’’, suffix=’’, events=(‘s3:ObjectCreated:’, ‘s3:ObjectRemoved:’, ‘s3:ObjectAccessed:*’))

监听存储桶中对象前缀和后缀的事件。调用者应迭代返回的迭代器以读取新事件。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`prefix`	str	监听以 prefix 开头的对象事件。
`suffix`	str	监听以 suffix 结尾的对象事件。
`events`	列表	要监听的事件。

返回值

参数
事件记录的迭代器，以 dict 表示

with client.listen_bucket_notification(
    "my-bucket",
    prefix="my-prefix/",
    events=["s3:ObjectCreated:*", "s3:ObjectRemoved:*"],
) as events:
    for event in events:
        print(event)

获取存储桶加密配置(bucket_name)

获取存储桶的加密配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值

参数
SSEConfig 对象。

示例

config = client.get_bucket_encryption("my-bucket")

设置存储桶加密配置(bucket_name, config)

设置存储桶的加密配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`config`	SSEConfig	服务器端加密配置。

示例

client.set_bucket_encryption(
    "my-bucket", SSEConfig(Rule.new_sse_s3_rule()),
)

删除存储桶加密配置(bucket_name)

删除存储桶的加密配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_bucket_encryption("my-bucket")

获取存储桶版本控制配置(bucket_name)

获取存储桶的版本控制配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

config = client.get_bucket_versioning("my-bucket")
print(config.status)

设置存储桶版本控制配置(bucket_name, config)

为存储桶设置版本控制配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`config`	VersioningConfig	版本控制配置。

示例

client.set_bucket_versioning("my-bucket", VersioningConfig(ENABLED))

删除存储桶复制配置(bucket_name)

删除存储桶的复制配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_bucket_replication("my-bucket")

获取存储桶复制配置(bucket_name)

获取存储桶的复制配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值
ReplicationConfig 对象。

示例

config = client.get_bucket_replication("my-bucket")

设置存储桶复制配置(bucket_name, config)

为存储桶设置复制配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`config`	ReplicationConfig	复制配置。

示例

config = ReplicationConfig(
    "REPLACE-WITH-ACTUAL-ROLE",
    [
        Rule(
            Destination(
                "REPLACE-WITH-ACTUAL-DESTINATION-BUCKET-ARN",
            ),
            ENABLED,
            delete_marker_replication=DeleteMarkerReplication(
                DISABLED,
            ),
            rule_filter=Filter(
                AndOperator(
                    "TaxDocs",
                    {"key1": "value1", "key2": "value2"},
                ),
            ),
            rule_id="rule1",
            priority=1,
        ),
    ],
)
client.set_bucket_replication("my-bucket", config)

删除存储桶生命周期配置(bucket_name)

删除存储桶的生命周期配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_bucket_lifecycle("my-bucket")

获取存储桶生命周期配置(bucket_name)

获取存储桶的生命周期配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值
LifecycleConfig 对象。

示例

config = client.get_bucket_lifecycle("my-bucket")

设置存储桶生命周期配置(bucket_name, config)

为存储桶设置生命周期配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`config`	LifecycleConfig	生命周期配置。

示例

config = LifecycleConfig(
    [
        Rule(
            ENABLED,
            rule_filter=Filter(prefix="documents/"),
            rule_id="rule1",
            transition=Transition(days=30, storage_class="GLACIER"),
        ),
        Rule(
            ENABLED,
            rule_filter=Filter(prefix="logs/"),
            rule_id="rule2",
            expiration=Expiration(days=365),
        ),
    ],
)
client.set_bucket_lifecycle("my-bucket", config)

删除存储桶标签(bucket_name)

删除存储桶的标签配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_bucket_tags("my-bucket")

获取存储桶标签(bucket_name)

获取存储桶的标签配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值
Tags 对象。

示例

tags = client.get_bucket_tags("my-bucket")

设置存储桶标签(bucket_name, tags)

为存储桶设置标签配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`tags`	标签	标签配置。

示例

tags = Tags.new_bucket_tags()
tags["Project"] = "Project One"
tags["User"] = "jsmith"
client.set_bucket_tags("my-bucket", tags)

删除对象锁定配置(bucket_name)

删除存储桶的对象锁定配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

示例

client.delete_object_lock_config("my-bucket")

获取对象锁定配置(bucket_name)

获取存储桶的对象锁定配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。

返回值
ObjectLockConfig 对象。

示例

config = client.get_object_lock_config("my-bucket")

设置对象锁定配置(bucket_name, config)

为存储桶设置对象锁定配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`config`	ObjectLockConfig	对象锁定配置。

示例

config = ObjectLockConfig(GOVERNANCE, 15, DAYS)
client.set_object_lock_config("my-bucket", config)

3. 对象操作

获取对象(bucket_name, object_name, offset=0, length=0, request_headers=None, ssec=None, version_id=None, extra_query_params=None)

获取对象从 offset 到 length 的数据。使用后应关闭返回的响应以释放网络资源。要重用连接，需要显式调用 response.release_conn()。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`offset`	int	对象数据开始的字节位置。
`length`	int	从 offset 开始的对象数据字节数。
`request_headers`	dict	要与 GET 请求一起添加的任何其他标头。
`ssec`	SseCustomerKey	服务器端加密客户机密钥。
`version_id`	str	对象的版本 ID。
`extra_query_params`	dict	用于高级用途的其他查询参数。

返回值

返回值
urllib3.response.HTTPResponse 对象。

示例

# Get data of an object.
try:
    response = client.get_object("my-bucket", "my-object")
    # Read data from response.
finally:
    response.close()
    response.release_conn()

# Get data of an object of version-ID.
try:
    response = client.get_object(
        "my-bucket", "my-object",
        version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d",
    )
    # Read data from response.
finally:
    response.close()
    response.release_conn()

# Get data of an object from offset and length.
try:
    response = client.get_object(
        "my-bucket", "my-object", offset=512, length=1024,
    )
    # Read data from response.
finally:
    response.close()
    response.release_conn()

# Get data of an SSE-C encrypted object.
try:
    response = client.get_object(
        "my-bucket", "my-object",
        ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"),
    )
    # Read data from response.
finally:
    response.close()
    response.release_conn()

选择对象内容(bucket_name, object_name, request)

通过 SQL 表达式选择对象的内容。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`request`	SelectRequest	选择请求。

返回值

返回值
包含请求记录和进度信息的读取器，以 SelectObjectReader 表示

示例

with client.select_object_content(
        "my-bucket",
        "my-object.csv",
        SelectRequest(
            "select * from S3Object",
            CSVInputSerialization(),
            CSVOutputSerialization(),
            request_progress=True,
        ),
) as result:
    for data in result.stream():
        print(data.decode())
    print(result.stats())

将对象下载到文件(bucket_name, object_name, file_path, request_headers=None, ssec=None, version_id=None, extra_query_params=None, tmp_file_path=None)

将对象的数据下载到文件。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`file_path`	str	要下载的文件名。
`request_headers`	dict	要与 GET 请求一起添加的任何其他标头。
`ssec`	SseCustomerKey	服务器端加密客户机密钥。
`version_id`	str	对象的版本 ID。
`extra_query_params`	dict	用于高级用途的其他查询参数。
`tmp_file_path`	str	临时文件的路径。

返回值

返回值
对象信息，以 Object 表示

示例

# Download data of an object.
client.fget_object("my-bucket", "my-object", "my-filename")

# Download data of an object of version-ID.
client.fget_object(
    "my-bucket", "my-object", "my-filename",
    version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d",
)

# Download data of an SSE-C encrypted object.
client.fget_object(
    "my-bucket", "my-object", "my-filename",
    ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"),
)

复制对象(bucket_name, object_name, source, sse=None, metadata=None, tags=None, retention=None, legal_hold=False, metadata_directive=None, tagging_directive=None)

通过服务器端复制另一个对象的数据来创建对象。在此 API 中，最大支持的源对象大小为 5GiB。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`source`	CopySource	源对象信息。
`sse`	Sse	目标对象的服务器端加密。
`metadata`	dict	要与目标对象一起复制的任何用户定义的元数据。
`tags`	标签	目标对象的标签。
`retention`	Retention	保留配置。
`legal_hold`	bool	设置目标对象法律保留的标志。
`metadata_directive`	str	用于处理目标对象用户元数据的指令。
`tagging_directive`	str	用于处理目标对象标签的指令。

返回值

返回值
ObjectWriteResult 对象。

示例

from datetime import datetime, timezone
from minio.commonconfig import REPLACE, CopySource

# copy an object from a bucket to another.
result = client.copy_object(
    "my-bucket",
    "my-object",
    CopySource("my-sourcebucket", "my-sourceobject"),
)
print(result.object_name, result.version_id)

# copy an object with condition.
result = client.copy_object(
    "my-bucket",
    "my-object",
    CopySource(
        "my-sourcebucket",
        "my-sourceobject",
        modified_since=datetime(2014, 4, 1, tzinfo=timezone.utc),
    ),
)
print(result.object_name, result.version_id)

# copy an object from a bucket with replacing metadata.
metadata = {"test_meta_key": "test_meta_value"}
result = client.copy_object(
    "my-bucket",
    "my-object",
    CopySource("my-sourcebucket", "my-sourceobject"),
    metadata=metadata,
    metadata_directive=REPLACE,
)
print(result.object_name, result.version_id)

组合对象(bucket_name, object_name, sources, sse=None, metadata=None, tags=None, retention=None, legal_hold=False)

通过使用服务器端复制将来自不同源对象的数据组合在一起创建对象。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`sources`	列表	ComposeSource 对象列表。
`sse`	Sse	目标对象的服务器端加密。
`metadata`	dict	要与目标对象一起复制的任何用户定义的元数据。
`tags`	标签	目标对象的标签。
`retention`	Retention	保留配置。
`legal_hold`	bool	设置目标对象法律保留的标志。

返回值

返回值
ObjectWriteResult 对象。

示例

from minio.commonconfig import ComposeSource
from minio.sse import SseS3

sources = [
    ComposeSource("my-job-bucket", "my-object-part-one"),
    ComposeSource("my-job-bucket", "my-object-part-two"),
    ComposeSource("my-job-bucket", "my-object-part-three"),
]

# Create my-bucket/my-object by combining source object
# list.
result = client.compose_object("my-bucket", "my-object", sources)
print(result.object_name, result.version_id)

# Create my-bucket/my-object with user metadata by combining
# source object list.
result = client.compose_object(
    "my-bucket",
    "my-object",
    sources,
    metadata={"test_meta_key": "test_meta_value"},
)
print(result.object_name, result.version_id)

# Create my-bucket/my-object with user metadata and
# server-side encryption by combining source object list.
client.compose_object("my-bucket", "my-object", sources, sse=SseS3())
print(result.object_name, result.version_id)

上传对象(bucket_name, object_name, data, length, content_type=”application/octet-stream”, metadata=None, sse=None, progress=None, part_size=0, num_parallel_uploads=3, tags=None, retention=None, legal_hold=False)

将数据从流上传到存储桶中的对象。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`data`	对象	一个具有可调用 read() 方法的对象，返回字节对象。
`length`	int	数据大小；-1 表示大小未知并设置有效的 part_size。
`content_type`	str	对象的类型。
`metadata`	dict	要与 PUT 请求一起上传的任何其他元数据。
`sse`	Sse	服务器端加密。
`progress`	线程	进度对象。
`part_size`	int	分块上传部分大小。
`tags`	标签	对象的标签。
`retention`	Retention	保留配置。
`legal_hold`	bool	设置对象法律保留的标志。

返回值

返回值
ObjectWriteResult 对象。

示例

# Upload data.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload unknown sized data.
data = urlopen(
    "https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.4.81.tar.xz",
)
result = client.put_object(
    "my-bucket", "my-object", data, length=-1, part_size=10*1024*1024,
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with content-type.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    content_type="application/csv",
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with metadata.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    metadata={"My-Project": "one"},
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with customer key type of server-side encryption.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    sse=SseCustomerKey(b"32byteslongsecretkeymustprovided"),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with KMS type of server-side encryption.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    sse=SseKMS("KMS-KEY-ID", {"Key1": "Value1", "Key2": "Value2"}),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with S3 type of server-side encryption.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    sse=SseS3(),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with tags, retention and legal-hold.
date = datetime.utcnow().replace(
    hour=0, minute=0, second=0, microsecond=0,
) + timedelta(days=30)
tags = Tags(for_object=True)
tags["User"] = "jsmith"
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    tags=tags,
    retention=Retention(GOVERNANCE, date),
    legal_hold=True,
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with progress bar.
result = client.put_object(
    "my-bucket", "my-object", io.BytesIO(b"hello"), 5,
    progress=Progress(),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

将文件上传到对象(bucket_name, object_name, file_path, content_type=”application/octet-stream”, metadata=None, sse=None, progress=None, part_size=0, num_parallel_uploads=3, tags=None, retention=None, legal_hold=False)

将数据从文件上传到存储桶中的对象。

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`file_path`	str	要上传的文件名。
`content_type`	str	对象的类型。
`metadata`	dict	要与 PUT 请求一起上传的任何其他元数据。
`sse`	Sse	服务器端加密。
`progress`	线程	进度对象。
`part_size`	int	分块上传部分大小。
`tags`	标签	对象的标签。
`retention`	Retention	保留配置。
`legal_hold`	bool	设置对象法律保留的标志。

返回值

返回值
ObjectWriteResult 对象。

示例

# Upload data.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with content-type.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    content_type="application/csv",
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with metadata.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    metadata={"My-Project": "one"},
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with customer key type of server-side encryption.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    sse=SseCustomerKey(b"32byteslongsecretkeymustprovided"),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with KMS type of server-side encryption.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    sse=SseKMS("KMS-KEY-ID", {"Key1": "Value1", "Key2": "Value2"}),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with S3 type of server-side encryption.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    sse=SseS3(),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with tags, retention and legal-hold.
date = datetime.utcnow().replace(
    hour=0, minute=0, second=0, microsecond=0,
) + timedelta(days=30)
tags = Tags(for_object=True)
tags["User"] = "jsmith"
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    tags=tags,
    retention=Retention(GOVERNANCE, date),
    legal_hold=True,
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

# Upload data with progress bar.
result = client.fput_object(
    "my-bucket", "my-object", "my-filename",
    progress=Progress(),
)
print(
    "created {0} object; etag: {1}, version-id: {2}".format(
        result.object_name, result.etag, result.version_id,
    ),
)

获取对象信息(bucket_name, object_name, ssec=None, version_id=None, extra_query_params=None)

获取对象的信息和元数据。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`ssec`	SseCustomerKey	服务器端加密客户机密钥。
`version_id`	str	对象的版本 ID。
`extra_headers`	dict	用于高级用途的其他 HTTP 标头。
`extra_query_params`	dict	用于高级用途的其他查询参数。

返回值

返回值
对象信息，以 Object 表示

示例

# Get object information.
result = client.stat_object("my-bucket", "my-object")
print(
    "last-modified: {0}, size: {1}".format(
        result.last_modified, result.size,
    ),
)

# Get object information of version-ID.
result = client.stat_object(
    "my-bucket", "my-object",
    version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d",
)
print(
    "last-modified: {0}, size: {1}".format(
        result.last_modified, result.size,
    ),
)

# Get SSE-C encrypted object information.
result = client.stat_object(
    "my-bucket", "my-object",
    ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"),
)
print(
    "last-modified: {0}, size: {1}".format(
        result.last_modified, result.size,
    ),
)

删除对象(bucket_name, object_name, version_id=None)

删除对象。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

示例

# Remove object.
client.remove_object("my-bucket", "my-object")

# Remove version of an object.
client.remove_object(
    "my-bucket", "my-object",
    version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d",
)

删除多个对象(bucket_name, delete_object_list, bypass_governance_mode=False)

删除多个对象。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`删除对象列表`	可迭代对象	包含 :class:`DeleteObject <DeleteObject>` 对象的可迭代对象。
`绕过治理模式`	bool	绕过治理保留模式。

返回值

返回值
包含 :class:`DeleteError <DeleteError>` 对象的迭代器

示例

# Remove list of objects.
errors = client.remove_objects(
    "my-bucket",
    [
        DeleteObject("my-object1"),
        DeleteObject("my-object2"),
        DeleteObject("my-object3", "13f88b18-8dcd-4c83-88f2-8631fdb6250c"),
    ],
)
for error in errors:
    print("error occurred when deleting object", error)

# Remove a prefix recursively.
delete_object_list = map(
    lambda x: DeleteObject(x.object_name),
    client.list_objects("my-bucket", "my/prefix/", recursive=True),
)
errors = client.remove_objects("my-bucket", delete_object_list)
for error in errors:
    print("error occurred when deleting object", error)

delete_object_tags(bucket_name, object_name, version_id=None)

删除对象的标签配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

示例

client.delete_object_tags("my-bucket", "my-object")

get_object_tags(bucket_name, object_name, version_id=None)

获取对象的标签配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

返回值
Tags 对象。

示例

tags = client.get_object_tags("my-bucket", "my-object")

set_object_tags(bucket_name, object_name, tags, version_id=None)

设置对象的标签配置。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`tags`	标签	标签配置。
`version_id`	str	对象的版本 ID。

示例

tags = Tags.new_object_tags()
tags["Project"] = "Project One"
tags["User"] = "jsmith"
client.set_object_tags("my-bucket", "my-object", tags)

enable_object_legal_hold(bucket_name, object_name, version_id=None)

启用对象的法律保留。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

示例

client.enable_object_legal_hold("my-bucket", "my-object")

disable_object_legal_hold(bucket_name, object_name, version_id=None)

禁用对象的法律保留。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

示例

client.disable_object_legal_hold("my-bucket", "my-object")

is_object_legal_hold_enabled(bucket_name, object_name, version_id=None)

如果对象的法律保留已启用，则返回 true。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

示例

if client.is_object_legal_hold_enabled("my-bucket", "my-object"):
    print("legal hold is enabled on my-object")
else:
    print("legal hold is not enabled on my-object")

get_object_retention(bucket_name, object_name, version_id=None)

获取对象的保留信息。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`version_id`	str	对象的版本 ID。

返回值

返回值
保留对象

示例

config = client.get_object_retention("my-bucket", "my-object")

set_object_retention(bucket_name, object_name, config, version_id=None)

设置对象的保留信息。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`config`	Retention	保留配置。
`version_id`	str	对象的版本 ID。

示例

config = Retention(GOVERNANCE, datetime.utcnow() + timedelta(days=10))
client.set_object_retention("my-bucket", "my-object", config)

presigned_get_object(bucket_name, object_name, expires=timedelta(days=7), response_headers=None, request_date=None, version_id=None, extra_query_params=None)

获取对象的预签名 URL，以便在过期时间和自定义请求参数下下载其数据。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`过期时间`	datetime.timedelta	以秒为单位的过期时间；默认为 7 天。
`响应头`	dict	可选的 response_headers 参数，用于指定响应字段，例如日期、大小、文件类型、服务器数据等。
`请求日期`	datetime.datetime	可选的 request_date 参数，用于指定不同的请求日期。默认为当前日期。
`version_id`	str	对象的版本 ID。
`extra_query_params`	dict	用于高级用途的其他查询参数。

返回值

返回值
URL 字符串

示例

# Get presigned URL string to download 'my-object' in
# 'my-bucket' with default expiry (i.e. 7 days).
url = client.presigned_get_object("my-bucket", "my-object")
print(url)

# Get presigned URL string to download 'my-object' in
# 'my-bucket' with two hours expiry.
url = client.presigned_get_object(
    "my-bucket", "my-object", expires=timedelta(hours=2),
)
print(url)

presigned_put_object(bucket_name, object_name, expires=timedelta(days=7))

获取对象的预签名 URL，以便在过期时间和自定义请求参数下上传数据。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`过期时间`	datetime.timedelta	以秒为单位的过期时间；默认为 7 天。

返回值

返回值
URL 字符串

示例

# Get presigned URL string to upload data to 'my-object' in
# 'my-bucket' with default expiry (i.e. 7 days).
url = client.presigned_put_object("my-bucket", "my-object")
print(url)

# Get presigned URL string to upload data to 'my-object' in
# 'my-bucket' with two hours expiry.
url = client.presigned_put_object(
    "my-bucket", "my-object", expires=timedelta(hours=2),
)
print(url)

presigned_post_policy(policy)

获取对象的 PostPolicy 的表单数据，以便使用 POST 方法上传其数据。

参数

参数	类型	描述
`策略`	PostPolicy	发布策略。

返回值

返回值
包含 dict 的表单数据

示例

policy = PostPolicy(
    "my-bucket", datetime.utcnow() + timedelta(days=10),
)
policy.add_starts_with_condition("key", "my/object/prefix/")
policy.add_content_length_range_condition(
    1*1024*1024, 10*1024*1024,
)
form_data = client.presigned_post_policy(policy)

get_presigned_url(method, bucket_name, object_name, expires=timedelta(days=7), response_headers=None, request_date=None, version_id=None, extra_query_params=None)

获取对象的预签名 URL，用于 HTTP 方法、过期时间和自定义请求参数。

参数

参数	类型	描述
`方法`	str	HTTP 方法。
`bucket_name`	str	存储桶的名称。
`object_name`	str	存储桶中的对象名称。
`过期时间`	datetime.timedelta	以秒为单位的过期时间；默认为 7 天。
`响应头`	dict	可选的 response_headers 参数，用于指定响应字段，例如日期、大小、文件类型、服务器数据等。
`请求日期`	datetime.datetime	可选的 request_date 参数，用于指定不同的请求日期。默认为当前日期。
`version_id`	str	对象的版本 ID。
`extra_query_params`	dict	用于高级用途的其他查询参数。

返回值

返回值
URL 字符串

示例

# Get presigned URL string to delete 'my-object' in
# 'my-bucket' with one day expiry.
url = client.get_presigned_url(
    "DELETE",
    "my-bucket",
    "my-object",
    expires=timedelta(days=1),
)
print(url)

# Get presigned URL string to upload 'my-object' in
# 'my-bucket' with response-content-type as application/json
# and one day expiry.
url = client.get_presigned_url(
    "PUT",
    "my-bucket",
    "my-object",
    expires=timedelta(days=1),
    response_headers={"response-content-type": "application/json"},
)
print(url)

# Get presigned URL string to download 'my-object' in
# 'my-bucket' with two hours expiry.
url = client.get_presigned_url(
    "GET",
    "my-bucket",
    "my-object",
    expires=timedelta(hours=2),
)
print(url)

upload_snowball_objects(bucket_name, object_list, metadata=None, sse=None, tags=None, retention=None, legal_hold=False, staging_filename=None, compression=False)

在单个 put 调用中上传多个对象。这是通过创建可选压缩的中间 TAR 文件来完成的，该文件上传到 S3 服务。

参数

参数	类型	描述
`bucket_name`	str	存储桶的名称。
`对象列表`	可迭代对象	包含 :class:`SnowballObject <SnowballObject>` 对象的可迭代对象。
`metadata`	dict	要与 PUT 请求一起上传的任何其他元数据。
`sse`	Sse	服务器端加密。
`tags`	标签	对象的标签。
`retention`	Retention	保留配置。
`legal_hold`	bool	设置对象法律保留的标志。
`暂存文件名`	str	用于创建中间 tarball 的暂存文件名。
`压缩`	bool	压缩 tarball 的标志。

返回值

返回值
ObjectWriteResult 对象。

示例

# Upload snowball object.
client.upload_snowball_objects(
    "my-bucket",
    [
        SnowballObject("my-object1", filename="/etc/hostname"),
        SnowballObject(
            "my-object2", data=io.BytesIO("hello"), length=5,
        ),
        SnowballObject(
            "my-object3", data=io.BytesIO("world"), length=5,
            mod_time=datetime.now(),
        ),
    ],
)

Python 客户端 API 参考

1. 构造函数

Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None)

2. 存储桶操作

创建存储桶(bucket_name, location=’us-east-1’, object_lock=False)

列出所有存储桶

检查存储桶是否存在(bucket_name)

删除存储桶(bucket_name)

列出对象(bucket_name, prefix=None, recursive=False, start_after=None, include_user_meta=False, include_version=False, use_api_v1=False, use_url_encoding_type=True)

获取存储桶策略(bucket_name)

设置存储桶策略(bucket_name, policy)

删除存储桶策略(bucket_name)

获取存储桶通知(bucket_name)

设置存储桶通知(bucket_name, config)

删除存储桶通知(bucket_name)

监听存储桶通知(bucket_name, prefix=’’, suffix=’’, events=(‘s3:ObjectCreated:*’, ‘s3:ObjectRemoved:*’, ‘s3:ObjectAccessed:*’))

获取存储桶加密配置(bucket_name)

设置存储桶加密配置(bucket_name, config)

删除存储桶加密配置(bucket_name)

获取存储桶版本控制配置(bucket_name)

设置存储桶版本控制配置(bucket_name, config)

删除存储桶复制配置(bucket_name)

获取存储桶复制配置(bucket_name)

设置存储桶复制配置(bucket_name, config)

删除存储桶生命周期配置(bucket_name)

获取存储桶生命周期配置(bucket_name)

设置存储桶生命周期配置(bucket_name, config)

删除存储桶标签(bucket_name)

获取存储桶标签(bucket_name)

设置存储桶标签(bucket_name, tags)

删除对象锁定配置(bucket_name)

获取对象锁定配置(bucket_name)

设置对象锁定配置(bucket_name, config)

3. 对象操作

获取对象(bucket_name, object_name, offset=0, length=0, request_headers=None, ssec=None, version_id=None, extra_query_params=None)

选择对象内容(bucket_name, object_name, request)

将对象下载到文件(bucket_name, object_name, file_path, request_headers=None, ssec=None, version_id=None, extra_query_params=None, tmp_file_path=None)

复制对象(bucket_name, object_name, source, sse=None, metadata=None, tags=None, retention=None, legal_hold=False, metadata_directive=None, tagging_directive=None)

组合对象(bucket_name, object_name, sources, sse=None, metadata=None, tags=None, retention=None, legal_hold=False)

上传对象(bucket_name, object_name, data, length, content_type=”application/octet-stream”, metadata=None, sse=None, progress=None, part_size=0, num_parallel_uploads=3, tags=None, retention=None, legal_hold=False)

将文件上传到对象(bucket_name, object_name, file_path, content_type=”application/octet-stream”, metadata=None, sse=None, progress=None, part_size=0, num_parallel_uploads=3, tags=None, retention=None, legal_hold=False)

获取对象信息(bucket_name, object_name, ssec=None, version_id=None, extra_query_params=None)

删除对象(bucket_name, object_name, version_id=None)

删除多个对象(bucket_name, delete_object_list, bypass_governance_mode=False)

delete_object_tags(bucket_name, object_name, version_id=None)

get_object_tags(bucket_name, object_name, version_id=None)

set_object_tags(bucket_name, object_name, tags, version_id=None)

enable_object_legal_hold(bucket_name, object_name, version_id=None)

disable_object_legal_hold(bucket_name, object_name, version_id=None)

is_object_legal_hold_enabled(bucket_name, object_name, version_id=None)

get_object_retention(bucket_name, object_name, version_id=None)

set_object_retention(bucket_name, object_name, config, version_id=None)

presigned_get_object(bucket_name, object_name, expires=timedelta(days=7), response_headers=None, request_date=None, version_id=None, extra_query_params=None)

presigned_put_object(bucket_name, object_name, expires=timedelta(days=7))

presigned_post_policy(policy)

get_presigned_url(method, bucket_name, object_name, expires=timedelta(days=7), response_headers=None, request_date=None, version_id=None, extra_query_params=None)

upload_snowball_objects(bucket_name, object_list, metadata=None, sse=None, tags=None, retention=None, legal_hold=False, staging_filename=None, compression=False)

5. 进一步探索

监听存储桶通知(bucket_name, prefix=’’, suffix=’’, events=(‘s3:ObjectCreated:’, ‘s3:ObjectRemoved:’, ‘s3:ObjectAccessed:*’))