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 連線伺服器憑證的旗標。

關於並行使用的注意事項：當使用 Python threading 程式庫時，Minio 物件是執行緒安全的。具體而言，在多個程序之間共享它是不安全的，例如當使用 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`
`delete_object_lock_config`
`get_object_lock_config`
`set_object_lock_config`

2. 儲存桶操作

make_bucket(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)

list_buckets()

列出所有可存取儲存桶的資訊。

參數

回傳
Bucket 的列表

範例

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

bucket_exists(bucket_name)

檢查儲存桶是否存在。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

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

remove_bucket(bucket_name)

移除空的儲存桶。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.remove_bucket("my-bucket")

list_objects(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)

get_bucket_policy(bucket_name)

取得儲存桶的儲存桶原則組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳值

參數
儲存桶原則組態，以 JSON 字串表示。

範例

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

set_bucket_policy(bucket_name, policy)

設定儲存桶的儲存桶原則組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`Policy`	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))

delete_bucket_policy(bucket_name)

刪除儲存桶的儲存桶原則組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_bucket_policy("my-bucket")

get_bucket_notification(bucket_name)

取得儲存桶的通知組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳值

參數
NotificationConfig 物件。

範例

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

set_bucket_notification(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)

delete_bucket_notification(bucket_name)

刪除儲存桶的通知組態。成功後，S3 服務會停止先前為儲存桶設定的事件通知。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_bucket_notification("my-bucket")

listen_bucket_notification(bucket_name, prefix=’’, suffix=’’, events=(‘s3:ObjectCreated:’, ‘s3:ObjectRemoved:’, ‘s3:ObjectAccessed:*’))

監聽儲存桶中物件 prefix 和 suffix 的事件。呼叫者應迭代回傳的迭代器以讀取新的事件。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`prefix`	str	監聽以 prefix 開頭的物件事件。
`suffix`	str	監聽以 suffix 結尾的物件事件。
`events`	list	要監聽的事件。

回傳值

參數
事件記錄的迭代器，格式為 dict

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

get_bucket_encryption(bucket_name)

取得儲存桶的加密組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳值

參數
SSEConfig 物件。

範例

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

set_bucket_encryption(bucket_name, config)

設定儲存桶的加密組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`config`	SSEConfig	伺服器端加密組態。

範例

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

delete_bucket_encryption(bucket_name)

刪除儲存桶的加密組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_bucket_encryption("my-bucket")

get_bucket_versioning(bucket_name)

取得儲存桶的版本控制組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

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

set_bucket_versioning(bucket_name, config)

設定儲存桶的版本控制組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`config`	VersioningConfig	版本控制組態。

範例

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

delete_bucket_replication(bucket_name)

刪除儲存桶的複寫組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_bucket_replication("my-bucket")

get_bucket_replication(bucket_name)

取得儲存桶的複寫組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳
ReplicationConfig 物件。

範例

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

set_bucket_replication(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)

delete_bucket_lifecycle(bucket_name)

刪除儲存桶的生命週期組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_bucket_lifecycle("my-bucket")

get_bucket_lifecycle(bucket_name)

取得儲存桶的生命週期組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳
LifecycleConfig 物件。

範例

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

set_bucket_lifecycle(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)

delete_bucket_tags(bucket_name)

刪除儲存桶的標籤組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_bucket_tags("my-bucket")

get_bucket_tags(bucket_name)

取得儲存桶的標籤組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳
Tags 物件。

範例

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

set_bucket_tags(bucket_name, tags)

設定儲存桶的標籤組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`tags`	Tags	標籤組態。

範例

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

delete_object_lock_config(bucket_name)

刪除儲存桶的物件鎖定組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

範例

client.delete_object_lock_config("my-bucket")

get_object_lock_config(bucket_name)

取得儲存桶的物件鎖定組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。

回傳
ObjectLockConfig 物件。

範例

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

set_object_lock_config(bucket_name, config)

設定儲存桶的物件鎖定組態。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`config`	ObjectLockConfig	物件鎖定組態。

範例

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

3. 物件操作

get_object(bucket_name, object_name, offset=0, length=0, request_headers=None, ssec=None, version_id=None, extra_query_params=None)

從物件的偏移量到長度取得資料。使用後應關閉回傳的回應，以釋放網路資源。若要重複使用連線，則必須明確呼叫 response.release_conn()。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`object_name`	str	儲存桶中的物件名稱。
`offset`	int	物件資料的起始位元組位置。
`length`	int	從偏移量開始的物件資料位元組數。
`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()

select_object_content(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())

fget_object(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"),
)

copy_object(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`	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)

compose_object(bucket_name, object_name, sources, sse=None, metadata=None, tags=None, retention=None, legal_hold=False)

透過使用伺服器端複製，組合來自不同來源物件的資料來建立物件。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`object_name`	str	儲存桶中的物件名稱。
`sources`	list	ComposeSource 物件的清單。
`sse`	Sse	目的地物件的伺服器端加密。
`metadata`	dict	要與目的地物件一起複製的任何使用者定義中繼資料。
`tags`	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)

put_object(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`	object	具有可呼叫的 read() 的物件，會回傳位元組物件。
`length`	int	資料大小；-1 代表大小不明，並設定有效的 part_size。
`content_type`	str	物件的內容類型。
`metadata`	dict	任何與您的 PUT 請求一起上傳的額外中繼資料。
`sse`	Sse	伺服器端加密。
`進度`	執行緒處理	進度物件。
`part_size`	int	多部分上傳的單一部分大小。
`tags`	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,
    ),
)

fput_object(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	伺服器端加密。
`進度`	執行緒處理	進度物件。
`part_size`	int	多部分上傳的單一部分大小。
`tags`	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,
    ),
)

stat_object(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,
    ),
)

remove_object(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",
)

remove_objects(bucket_name, delete_object_list, bypass_governance_mode=False)

移除多個物件。

參數

參數	類型	描述
`bucket_name`	str	儲存桶的名稱。
`delete_object_list`	可迭代物件	一個包含 :class:`DeleteObject <DeleteObject>` 物件的可迭代物件。
`bypass_governance_mode`	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`	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	儲存桶中的物件名稱。
`expires`	datetime.timedelta	以秒為單位的到期時間；預設為 7 天。
`response_headers`	dict	可選的 response_headers 引數，用於指定回應欄位，例如日期、大小、檔案類型、有關伺服器的資料等。
`request_date`	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	儲存桶中的物件名稱。
`expires`	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 方法上傳其資料。

參數

參數	類型	描述
`policy`	PostPolicy	Post 原則。

回傳值

回傳
包含 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 方法、到期時間和自訂請求參數。

參數

參數	類型	描述
`method`	str	HTTP 方法。
`bucket_name`	str	儲存桶的名稱。
`object_name`	str	儲存桶中的物件名稱。
`expires`	datetime.timedelta	以秒為單位的到期時間；預設為 7 天。
`response_headers`	dict	可選的 response_headers 引數，用於指定回應欄位，例如日期、大小、檔案類型、有關伺服器的資料等。
`request_date`	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	儲存桶的名稱。
`object_list`	可迭代物件	一個包含 :class:`SnowballObject <SnowballObject>` 物件的可迭代物件。
`metadata`	dict	任何與您的 PUT 請求一起上傳的額外中繼資料。
`sse`	Sse	伺服器端加密。
`tags`	Tags	物件的標籤。
`retention`	Retention	保留組態。
`legal_hold`	bool	設定物件法律保留的旗標。
`staging_filename`	str	用於建立中間 tarball 的暫存檔案名稱。
`compression`	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. 儲存桶操作

make_bucket(bucket_name, location=’us-east-1’, object_lock=False)

list_buckets()

bucket_exists(bucket_name)

remove_bucket(bucket_name)

list_objects(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)

get_bucket_policy(bucket_name)

set_bucket_policy(bucket_name, policy)

delete_bucket_policy(bucket_name)

get_bucket_notification(bucket_name)

set_bucket_notification(bucket_name, config)

delete_bucket_notification(bucket_name)

listen_bucket_notification(bucket_name, prefix=’’, suffix=’’, events=(‘s3:ObjectCreated:*’, ‘s3:ObjectRemoved:*’, ‘s3:ObjectAccessed:*’))

get_bucket_encryption(bucket_name)

set_bucket_encryption(bucket_name, config)

delete_bucket_encryption(bucket_name)

get_bucket_versioning(bucket_name)

set_bucket_versioning(bucket_name, config)

delete_bucket_replication(bucket_name)

get_bucket_replication(bucket_name)

set_bucket_replication(bucket_name, config)

delete_bucket_lifecycle(bucket_name)

get_bucket_lifecycle(bucket_name)

set_bucket_lifecycle(bucket_name, config)

delete_bucket_tags(bucket_name)

get_bucket_tags(bucket_name)

set_bucket_tags(bucket_name, tags)

delete_object_lock_config(bucket_name)

get_object_lock_config(bucket_name)

set_object_lock_config(bucket_name, config)

3. 物件操作

get_object(bucket_name, object_name, offset=0, length=0, request_headers=None, ssec=None, version_id=None, extra_query_params=None)

select_object_content(bucket_name, object_name, request)

fget_object(bucket_name, object_name, file_path, request_headers=None, ssec=None, version_id=None, extra_query_params=None, tmp_file_path=None)

copy_object(bucket_name, object_name, source, sse=None, metadata=None, tags=None, retention=None, legal_hold=False, metadata_directive=None, tagging_directive=None)

compose_object(bucket_name, object_name, sources, sse=None, metadata=None, tags=None, retention=None, legal_hold=False)

put_object(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)

fput_object(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)

stat_object(bucket_name, object_name, ssec=None, version_id=None, extra_query_params=None)

remove_object(bucket_name, object_name, version_id=None)

remove_objects(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. 進一步探索

listen_bucket_notification(bucket_name, prefix=’’, suffix=’’, events=(‘s3:ObjectCreated:’, ‘s3:ObjectRemoved:’, ‘s3:ObjectAccessed:*’))