すべてのプロダクト
Search

このプロダクト

    Object Storage Service:オブジェクトのリスト (Python SDK V1)

    ドキュメントセンター

    Object Storage Service:オブジェクトのリスト (Python SDK V1)

    最終更新日:Nov 29, 2025

    このトピックでは、バージョン管理が有効になっているバケット内のオブジェクトをリストする方法について説明します。すべてのオブジェクト、指定した数のオブジェクト、または指定したプレフィックスを持つオブジェクトをリストできます。

    注意事項

    • このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。OSS と同じリージョンにある他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用します。OSS のリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。

    • このトopic では、アクセス認証情報は環境変数から取得されます。アクセス認証情報の設定方法の詳細については、「OSS SDK for Python 1.0 を使用したアクセス認証情報の設定」をご参照ください。

    • このトピックでは、OSS エンドポイントを使用して OSSClient インスタンスが作成されます。カスタムドメイン名または Security Token Service (STS) を使用して OSSClient インスタンスを作成する場合は、「初期化」をご参照ください。

    • オブジェクトをリストするには、oss:ListObjectVersions 権限が必要です。詳細については、「RAM ユーザーへのカスタムポリシーのアタッチ」をご参照ください。

    バケット内のすべてのオブジェクトバージョンのリスト

    次のコードは、指定されたバケット内のすべてのオブジェクト (削除マーカーを含む) のバージョン情報をリストする方法を示しています。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# バケットが配置されているリージョン (cn-hangzhou など) を指定します。注意：このパラメーターは V4 署名に必要です。
region = "cn-hangzhou"

# yourBucketName をバケットの名前に設定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)


# バケットのバージョン管理を有効にした後、list_object_versions 操作を呼び出して、さまざまなオブジェクトバージョンの情報を返すことができます。
# バケット内のすべてのオブジェクト (削除マーカーを含む) のバージョン情報をリストします。
result = bucket.list_object_versions()

# すべてのオブジェクトのバージョン情報をリストします。
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    # リストされたオブジェクトのバージョン情報を表示します。
    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    # リストされた削除マーカーのバージョン情報を表示します。
    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    is_truncated = result.is_truncated

    # リストが完全かどうかを確認します。リストが完全でない場合は、残りのオブジェクトのリストを続行します。リストが完全な場合は、ループを終了します。
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

    指定されたプレフィックスを持つオブジェクトバージョンのリスト

    次のコードは、指定されたプレフィックスを持つオブジェクトのバージョン情報をリストする方法を示しています。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# バケットが配置されているリージョン (cn-hangzhou など) を指定します。注意：このパラメーターは V4 署名に必要です。
region = "cn-hangzhou"

# yourBucketName をバケットの名前に設定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# バケットのバージョン管理を有効にした後、list_object_versions 操作を呼び出して、さまざまなオブジェクトバージョンの情報を返すことができます。
# バケット内のすべてのオブジェクト (削除マーカーを含む) のバージョン情報をリストします。
result = bucket.list_object_versions()

# 名前が "test-" プレフィックスで始まるオブジェクトのバージョン情報をリストすることを指定します。
prefix = 'test-'
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(prefix=prefix, key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    # リストされたオブジェクトのバージョン情報を表示します。
    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    # リストされた削除マーカーのバージョン情報を表示します。
    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    is_truncated = result.is_truncated

    # リストが完全かどうかを確認します。リストが完全でない場合は、残りのオブジェクトのリストを続行します。リストが完全な場合は、ループを終了します。
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

    指定された数のオブジェクトバージョンのリスト

    次のコードは、指定された数のオブジェクトのバージョン情報をリストする方法を示しています。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# バケットが配置されているリージョン (cn-hangzhou など) を指定します。注意：このパラメーターは V4 署名に必要です。
region = "cn-hangzhou"

# yourBucketName をバケットの名前に設定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# バケットのバージョン管理を有効にした後、list_object_versions 操作を呼び出して、さまざまなオブジェクトバージョンの情報を返すことができます。
# バケット内のすべてのオブジェクト (削除マーカーを含む) のバージョン情報をリストします。
result = bucket.list_object_versions()

# 最大 200 件の結果を返すように指定します。
max_keys = 200

result = bucket.list_object_versions(max_keys=max_keys)

# リストされたオブジェクトのバージョン情報を表示します。
for version_info in result.versions:
    print('version_info.versionid:', version_info.versionid)
    print('version_info.key:', version_info.key)
    print('version_info.is_latest:', version_info.is_latest)

# リストされたオブジェクトの削除マーカーのバージョン情報を表示します。
for del_maker_Info in result.delete_marker:
    print('del_maker.key:', del_maker_Info.key)
    print('del_maker.versionid:', del_maker_Info.versionid)
    print('del_maker.is_latest:', del_maker_Info.is_latest)

# リストが切り捨てられているかどうかを確認します。
# 最大 200 件の結果を返すように指定しました。バケット内のオブジェクト数が 200 を超える場合、リストは切り捨てられ、is_truncated は True になります。オブジェクト数が 200 未満の場合、リストは切り捨てられず、is_truncated は False になります。
print('is truncated', result.is_truncated)

    フォルダ機能

    OSS にはネイティブなフォルダ構造はありません。すべての要素はオブジェクトとして保存されます。名前がスラッシュ (/) で終わる 0 バイトのオブジェクトを作成することで、フォルダを作成できます。このオブジェクトはアップロードおよびダウンロードできます。OSS コンソールでは、名前がスラッシュ (/) で終わるオブジェクトがフォルダとして表示されます。

    `delimiter` と `prefix` パラメーターを使用して、フォルダをシミュレートできます。

    • `prefix` をフォルダ名に設定すると、名前がこのプレフィックスで始まるすべてのオブジェクトがリストされます。フォルダ内のすべてのファイルとサブフォルダがオブジェクトとして表示されます。

    • `prefix` を設定し、`delimiter` もスラッシュ (/) に設定すると、そのフォルダ内のファイルとサブフォルダのみがリストされます。サブフォルダは `CommonPrefixes` として表示されます。これらのサブフォルダ内のファイルとフォルダは表示されません。

    `examplebucket` という名前のバケットにオブジェクト oss.jpg、fun/test.jpg、fun/movie/001.avi、および fun/movie/007.txt が含まれており、フォルダ区切り文字としてスラッシュ (/) を使用していると仮定します。フォルダ構造は次のようになります。

    examplebucket           
 └── oss.jpg
 └── fun               
      └── test.jpg
      └── movie
           └── 001.avi
           └── 007.txt

    次の例は、フォルダをシミュレートしてオブジェクトをリストする方法を示しています。

    • ルートディレクトリ内のオブジェクトバージョンのリスト

      次のコードは、ルートディレクトリ内のオブジェクトのバージョン情報をリストする方法を示しています。

      # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# バケットが配置されているリージョン (cn-hangzhou など) を指定します。注意：このパラメーターは V4 署名に必要です。
region = "cn-hangzhou"

# yourBucketName をバケットの名前に設定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# バケットのバージョン管理を有効にした後、list_object_versions 操作を呼び出して、さまざまなオブジェクトバージョンの情報を返すことができます。
# バケット内のすべてのオブジェクト (削除マーカーを含む) のバージョン情報をリストします。
result = bucket.list_object_versions()

# delimiter をスラッシュ (/) に設定します。
delimiter = "/"
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(delimiter=delimiter, key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    # リストされたオブジェクトのバージョン情報を表示します。
    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    # リストされた削除マーカーのバージョン情報を表示します。
    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    # スラッシュ (/) で終わるディレクトリの名前を表示します。
    for common_prefix in result.common_prefix:
        print("common_prefix:", common_prefix)

    is_truncated = result.is_truncated

    # リストが完全かどうかを確認します。リストが完全でない場合は、残りのオブジェクトのリストを続行します。リストが完全な場合は、ループを終了します。
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

      結果：

      ('version_info.versionid:', 'CAEQEhiBgMCw8Y7FqBciIGIzMDE3MTEzOWRiMDRmZmFhMmRlMjljZWI0MWU4****')
('version_info.key:', 'oss.jpg')
('version_info.is_latest:', True)
('common_prefix:', 'fun/')

    • フォルダ内のファイルとサブフォルダのリスト

      次のコードは、指定されたフォルダ内のファイルとサブフォルダをリストする方法を示しています。

      # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# バケットが配置されているリージョン (cn-hangzhou など) を指定します。注意：このパラメーターは V4 署名に必要です。
region = "cn-hangzhou"

# yourBucketName をバケットの名前に設定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# バケットのバージョン管理を有効にした後、list_object_versions 操作を呼び出して、さまざまなオブジェクトバージョンの情報を返すことができます。
# バケット内のすべてのオブジェクト (削除マーカーを含む) のバージョン情報をリストします。
result = bucket.list_object_versions()

# delimiter をスラッシュ (/) に、prefix を fun/ に設定します。
prefix = "fun/"
delimiter = "/"
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(prefix=prefix, delimiter=delimiter, key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    # リストされたオブジェクトのバージョン情報を表示します。
    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    # リストされた削除マーカーのバージョン情報を表示します。
    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    # スラッシュ (/) で終わるフォルダの名前を表示します。
    for common_prefix in result.common_prefix:
        print("common_prefix:", common_prefix)

    is_truncated = result.is_truncated

    # リストが完全かどうかを確認します。リストが完全でない場合は、残りのオブジェクトのリストを続行します。リストが完全な場合は、ループを終了します。
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

      結果：

      ('version_info.versionid:', 'CAEQFRiBgMCh9JDkrxciIGE3OTNkYzFhYTc2YzQzOTQ4Y2MzYjg2YjQ4ODg*****')
('version_info.key:', 'fun/test.jpg')
('version_info.is_latest:', True)
('commonPrefix:', 'fun/movie/')

    関連ドキュメント

    オブジェクトをリストするための API 操作の詳細については、「ListObjectVersions (GetBucketVersions)」をご参照ください。