このトピックでは、すべてのオブジェクト、名前に特定のプレフィックスが含まれるオブジェクト、およびObject Storage Service (OSS) バケットの特定のディレクトリ内のオブジェクトとサブディレクトリを一覧表示する方法について説明します。
使用上の注意
Python 2.12.0以降のOSS SDKのみがGetBucketV2 (ListObjectsV2) 操作をサポートしています。
このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。 OSSと同じリージョンにある他のAlibaba CloudサービスからOSSにアクセスする場合は、内部エンドポイントを使用します。 OSSリージョンとエンドポイントの詳細については、「リージョン、エンドポイント、オープンポート」をご参照ください。
このトピックでは、アクセス資格情報は環境変数から取得します。 アクセス資格情報の設定方法の詳細については、「アクセス資格情報の設定」をご参照ください。
このトピックでは、OSSエンドポイントを使用してOSSClientインスタンスを作成します。 カスタムドメイン名またはSTS (Security Token Service) を使用してOSSClientインスタンスを作成する場合は、「初期化」をご参照ください。
オブジェクトを一覧表示するには、
oss:ListObjects
権限が必要です。 詳細については、「RAMユーザーへのカスタムポリシーのアタッチ」をご参照ください。
背景情報
GetBucket (ListObjects) またはGetBucketV2 (ListObjectsV2) 操作を呼び出して、一度に最大1,000個のオブジェクトをバケットに一覧表示できます。 リスト操作パラメーターを指定して、ビジネス要件に基づいてオブジェクトを一覧表示できます。 たとえば、特定の位置の後にすべてのオブジェクトを一覧表示したり、特定のディレクトリ内のすべてのオブジェクトとサブディレクトリを一覧表示したり、ページごとに1,000を超えるオブジェクトを一覧表示したりできます。 GetBucket (ListObjects) 操作とGetBucketV2 (ListObjectsV2) 操作にはいくつかの違いがあります。
GetBucket (ListObjects) 操作を呼び出してオブジェクトを一覧表示すると、オブジェクト所有者情報が応答に含まれます。
GetBucketV2 (ListObjectsV2) 操作を呼び出してオブジェクトを一覧表示する場合、fetchOwnerパラメーターを設定して、応答にオブジェクト所有者情報を含めるかどうかを指定できます。
説明バージョン管理が有効なバケット内のオブジェクトを一覧表示するには、GetBucketV2 (ListObjectsV2) 操作を呼び出すことを推奨します。
次の表では、GetBucket (ListObjects) またはGetBucketV2 (ListObjectsV2) 操作を呼び出してオブジェクトを一覧表示するときに設定できるパラメーターについて説明します。
GetBucket (ListObjects)
次の表に、GetBucket (ListObjects) 操作を呼び出してオブジェクトを一覧表示するときに設定できるパラメーターを示します。
パラメーター | 説明 |
prefix | 一覧表示するオブジェクトの名前のプレフィックス。 |
delimiter | リストするオブジェクトを名前でグループ化するために使用される文字。 |
marker | リスト操作の開始位置。 |
GetBucketV2 (ListObjectsV2)
次の表に、GetBucketV2 (ListObjectsV2) 操作を呼び出してオブジェクトを一覧表示するときに設定できるパラメーターを示します。
パラメーター | 説明 |
prefix | 一覧表示するオブジェクトの名前のプレフィックス。 |
delimiter | リストするオブジェクトを名前でグループ化するために使用される文字。 |
startAfter | リスト操作の開始位置。 |
fetchOwner | 応答に所有者情報を含めるかどうかを指定します。 有効な値:
|
特定の数のオブジェクトを一覧表示する
GetBucket (ListObjects)
次のサンプルコードは、GetBucket (ListObjects) 操作を呼び出してバケット内の10個のオブジェクトを一覧表示する方法の例を示しています。
ListObjects操作は、便宜上ObjectIteratorにカプセル化されています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from itertools import islice
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List 10 objects in the bucket.
for b in islice(oss2.ObjectIterator(bucket), 10):
print(b.key)
GetBucketV2 (ListObjectsV2)
次のサンプルコードでは、GetBucketV2 (ListObjectsV2) 操作を呼び出してバケット内の10個のオブジェクトを一覧表示する方法の例を示します。
ListObjectsV2操作は、便宜上ObjectIteratorV2にカプセル化されています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from itertools import islice
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List 10 objects in the bucket.
for obj in islice(oss2.ObjectIteratorV2(bucket), 10):
print(obj.key)
バケット内のすべてのオブジェクトの一覧表示
GetBucket (ListObjects)
次のサンプルコードは、GetBucket (ListObjects) 操作を呼び出してバケット内のすべてのオブジェクトを一覧表示する方法の例を示しています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List all objects in the bucket.
for obj in oss2.ObjectIterator(bucket):
print(obj.key)
GetBucketV2 (ListObjectsV2)
バケット内のすべてのオブジェクトを一覧表示し、レスポンスにオブジェクト所有者情報を含めない
次のサンプルコードは、GetBucketV2 (ListObjectsV2) 操作を呼び出してバケット内のすべてのオブジェクトを一覧表示し、レスポンスにオブジェクト所有者情報を含めない方法の例を示しています。
# -*- coding: utf-8 -*- import oss2 from oss2.credentials import EnvironmentVariableCredentialsProvider # Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider()) # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. endpoint = "https://oss-cn-hangzhou.aliyuncs.com" # Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4. region = "cn-hangzhou" # Specify the name of your bucket. bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region) # List all objects in the bucket. for obj in oss2.ObjectIteratorV2(bucket): print(obj.key)
バケット内のすべてのオブジェクトを一覧表示し、オブジェクト所有者情報をレスポンスに含める
次のサンプルコードでは、GetBucketV2 (ListObjectsV2) 操作を呼び出してバケット内のすべてのオブジェクトを一覧表示し、fetchOwnerパラメーターを指定してオブジェクト所有者情報を応答に含める方法の例を示します。
# -*- coding: utf-8 -*- import oss2 from oss2.credentials import EnvironmentVariableCredentialsProvider # Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider()) # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. endpoint = "https://oss-cn-hangzhou.aliyuncs.com" # Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4. region = "cn-hangzhou" # Specify the name of your bucket. bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region) # List all objects in the bucket and specify the fetchOwner parameter to include the object owner information in the response. for obj in oss2.ObjectIteratorV2(bucket, fetch_owner=True): print(obj.key) print('file owner display name: ' + obj.owner.display_name) print('file owner id: ' + obj.owner.id)
名前に特定のプレフィックスが含まれるオブジェクトのリスト
次の例では、oss.jpg、fun/test.jpg、fun/movie/001.avi、fun/movie/007.aviの4つのオブジェクトがバケットに格納されています。 スラッシュ (/) がディレクトリ区切り文字として使用されます。
GetBucket (ListObjects)
次のサンプルコードでは、GetBucket (ListObjects) 操作を呼び出して、名前に特定のプレフィックスが含まれるオブジェクトを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List all objects in the fun directory and its subdirectories.
for obj in oss2.ObjectIterator(bucket, prefix='fun/'):
print(obj.key)
GetBucketV2 (ListObjectsV2)
次のサンプルコードでは、GetBucketV2 (ListObjectsV2) 操作を呼び出して、名前に特定のプレフィックスが含まれているオブジェクトを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List all objects in the fun directory and its subdirectories.
for obj in oss2.ObjectIteratorV2(bucket, prefix='fun/'):
print(obj.key)
特定の開始位置からすべてのオブジェクトを一覧表示する
GetBucket (ListObjects)
マーカーパラメーターを設定して、リスト操作の開始位置を指定できます。 markerの値の後に名前がアルファベット順になっているすべてのオブジェクトが返されます。 次の例では、x1.txt、x2.txt、z1.txt、z2.txtの4つのオブジェクトがバケットに格納されています。
次のサンプルコードは、GetBucket (ListObjects) 操作を呼び出して、特定の開始位置からすべてのオブジェクトを一覧表示する方法の例を示しています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List all objects whose names are alphabetically after the value of marker. The object whose name is the same as the value of marker is not returned.
for obj in oss2.ObjectIterator(bucket, marker="x2.txt"):
print(obj.key)
GetBucketV2 (ListObjectsV2)
start_afterパラメーターを設定して、リスト操作の開始位置を指定できます。 start_afterの値の後に名前がアルファベット順であるすべてのオブジェクトが返されます。 次の例では、x1.txt、x2.txt、z1.txt、z2.txtの4つのオブジェクトがバケットに格納されています。
次のサンプルコードでは、GetBucketV2 (ListObjectsV2) 操作を呼び出して、特定の開始位置からすべてのオブジェクトを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# List all objects whose names are alphabetically after the value of marker. The object whose name is the same as the value of start_after is not returned.
for obj in oss2.ObjectIteratorV2(bucket, start_after="x2.txt"):
print(obj.key)
特定のディレクトリ内のオブジェクトとサブディレクトリの一覧表示
OSSは、階層構造の代わりにフラット構造を使用してオブジェクトを格納します。 ディレクトリは、名前がスラッシュ (/) で終わるゼロバイトのオブジェクトです。 このディレクトリをアップロードおよびダウンロードできます。 デフォルトでは、名前がスラッシュ (/) で終わるオブジェクトは、OSSコンソールにディレクトリとして表示されます。
デリミタとプレフィックスパラメータを指定して、ディレクトリごとにオブジェクトを一覧表示できます。
プレフィックスをディレクトリの名前に設定すると、プレフィックスを含む名前のオブジェクトとサブディレクトリが一覧表示されます。
プレフィックスを指定し、区切り文字としてスラッシュ (/) を指定すると、ディレクトリ内のオブジェクトとサブディレクトリのみが一覧表示されます。 サブディレクトリ内のオブジェクトおよびディレクトリはリストされません。
GetBucket (ListObjects)
次のサンプルコードでは、GetBucket (ListObjects) 操作を呼び出して、特定のディレクトリ内のオブジェクトとサブディレクトリを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List objects and subdirectories in the fun directory. Objects in the subdirectories are not listed.
for obj in oss2.ObjectIterator(bucket, prefix='fun/', delimiter ='/'):
# Use is_prefix to determine whether obj is a directory. (Configuration of delimiter & prefix is required to list objects in a folder and determine whether obj is a directory.)
if obj.is_prefix(): # Specify the operation to perform if obj is determined as a directory.
print('directory: ' + obj.key)
else: # Specify the operation to perform if obj is determined as an object.
print('file: ' + obj.key)
GetBucketV2 (ListObjectsV2)
次のサンプルコードでは、GetBucketV2 (ListObjectsV2) 操作を呼び出して、特定のディレクトリ内のオブジェクトとサブディレクトリを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# List objects and subdirectories in the fun directory. Objects in the subdirectories are not listed. If you do not need the object owner information, do not configure the fetch_owner parameter.
for obj in oss2.ObjectIteratorV2(bucket, prefix = 'fun/', delimiter = '/', start_after='fun/', fetch_owner=True):
# Use is_prefix to determine whether obj is a directory.
if obj.is_prefix(): # Specify the operation to perform if obj is determined as a directory.
print('directory: ' + obj.key)
else: # Specify the operation to perform if obj is determined as an object.
print('file: ' + obj.key)
print('file owner display name: ' + obj.owner.display_name)
print('file owner id: ' + obj.owner.id)
特定のディレクトリ内のオブジェクトのサイズを一覧表示する
GetBucket (ListObjects)
次のサンプルコードでは、GetBucket (ListObjects) 操作を呼び出して、特定のディレクトリ内のオブジェクトのサイズを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
def CalculateFolderLength(bucket, folder):
length = 0
for obj in oss2.ObjectIterator(bucket, prefix=folder):
length += obj.size
return length
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
for obj in oss2.ObjectIterator(bucket, delimiter='/'):
if obj.is_prefix(): # Specify the operation to perform if obj is determined as a directory.
length = CalculateFolderLength(bucket, obj.key)
print('directory: ' + obj.key + ' length:' + str(length) + "Byte.")
else: # Specify the operation to perform if obj is determined as an object.
print('file:' + obj.key + ' length:' + str(obj.size) + "Byte.")
GetBucketV2 (ListObjectsV2)
次のサンプルコードでは、GetBucketV2 (ListObjectsV2) 操作を呼び出して、特定のディレクトリ内のオブジェクトのサイズを一覧表示する方法の例を示します。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
def CalculateFolderLength(bucket, folder):
length = 0
for obj in oss2.ObjectIteratorV2(bucket, prefix=folder):
length += obj.size
return length
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
for obj in oss2.ObjectIteratorV2(bucket, delimiter='/'):
if obj.is_prefix(): # Specify the operation to perform if obj is determined as a directory.
length = CalculateFolderLength(bucket, obj.key)
print('directory: ' + obj.key + ' length:' + str(length) + "Byte.")
else: # Specify the operation to perform if obj is determined as a directory.
print('file:' + obj.key + ' length:' + str(obj.size) + "Byte.")
関連ドキュメント
オブジェクトの一覧表示に使用する完全なサンプルコードについては、『GitHub』をご参照ください。
オブジェクトを一覧表示するために呼び出すAPI操作の詳細については、「ListObjects (GetBucket) 」および「ListObjectsV2 (GetBucketV2) 」をご参照ください。