OSS バケットのオブジェクト一覧表示 - OSS

バケット内のオブジェクトを、数、プレフィックス、またはアルファベット順の範囲でリスト化します。大規模な結果セットのページングや、特殊文字を含むオブジェクト名の URL エンコーディングもサポートされています。

前提条件

開始する前に、次のことを確認してください：

初期化された OSSClient インスタンス。詳細については、「初期化」をご参照ください。

特定の数のオブジェクトのリスト化

MaxKeys を設定して、1 回の呼び出しで返されるオブジェクトの数を制御します。次の例では、examplebucket から最大 20 個のオブジェクトを返します。

// バケット名を指定します。
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// 返されるオブジェクトの最大数を設定します。デフォルト：100。最大：1,000。
request.setMaxKeys(20);

 oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", objectSummary.getKey());
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        if (clientException != null) {
            // ネットワーク障害などのクライアント側エラー。
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // サーバー側エラー。
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

プレフィックスによるオブジェクトのリスト化

プレフィックスを設定して、指定した文字列で始まる名前のオブジェクトをフィルターします。次の例では、examplebucket 内で名前が file で始まるオブジェクトを返します。

// バケット名を指定します。
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// プレフィックスを設定します。「file」で始まるすべてのオブジェクト (file1.txt や file-archive.zip など) を返します。
request.setPrefix("file");

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", objectSummary.getKey());
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

マーカー以降のオブジェクトのリスト化

マーカーを設定して、特定の位置からリスト化を開始します。リスト操作は、マーカーのアルファベット順で次のオブジェクトを返します。マーカー自体は含まれません。マーカーがバケットに存在しない場合、リスト化はアルファベット順で次のオブジェクトから開始されます。

次の例では、examplebucket 内で exampleobject.txt の後に続くオブジェクトをリスト化します。

// バケット名を指定します。
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// マーカーを設定します。リストは、「exampleobject.txt」のアルファベット順で次のオブジェクトから始まります。
request.setMarker("exampleobject.txt");

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", objectSummary.getKey());
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

ページ単位での全オブジェクトのリスト化

バケット全体をページングするには、isTruncated と NextMarker を一緒に使用します。isTruncated() が true を返す場合、結果は切り捨てられており、getNextMarker() は次のページの開始点を示します。isTruncated() が false を返す場合、最後のページに到達したことになります。

次の例では、examplebucket 内のすべてのオブジェクトを、1 ページあたり最大 20 個のオブジェクトでリスト化します。

private String marker = null;
private boolean isCompleted = false;

// すべてのオブジェクトをページングします。
public void getAllObject() {
    do {
        OSSAsyncTask task = getObjectList();
        // ページリクエストが完了するまで現在のスレッドをブロックし、
        // 次の反復処理で NextMarker を利用できるようにします。
        // このブロッキング戦略は、アプリのスレッドモデルに合わせて調整してください。
        task.waitUntilFinished();
    } while (!isCompleted);
}

// オブジェクトの 1 ページをフェッチします。
public OSSAsyncTask getObjectList() {
    // バケット名を指定します。
    ListObjectsRequest request = new ListObjectsRequest("examplebucket");
    // ページあたりの最大オブジェクト数を設定します。デフォルト：100。最大：1,000。
    request.setMaxKeys(20);
    request.setMarker(marker);

    OSSAsyncTask task = oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
        @Override
        public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
            for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
                Log.i("ListObjects", objectSummary.getKey());
            }
            if (!result.isTruncated()) {
                // これ以上ページはありません。
                isCompleted = true;
                return;
            }
            // 次のページのマーカーとして NextMarker を使用します。
            marker = result.getNextMarker();
        }

        @Override
        public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
            isCompleted = true;
            if (clientException != null) {
                clientException.printStackTrace();
            }
            if (serviceException != null) {
                Log.e("ErrorCode", serviceException.getErrorCode());
                Log.e("RequestId", serviceException.getRequestId());
                Log.e("HostId", serviceException.getHostId());
                Log.e("RawMessage", serviceException.getRawMessage());
            }
        }
    });
    return task;
}

プレフィックスとページ単位によるオブジェクトのリスト化

プレフィックスフィルタリングとページングを組み合わせて、大規模なフィルター済み結果セットを反復処理します。次の例では、examplebucket 内で名前が file で始まるオブジェクトを、1 ページあたり 20 個ずつリスト化します。

private String marker = null;
private boolean isCompleted = false;

// 「file」プレフィックスを持つすべてのオブジェクトをページングします。
public void getAllObject() {
    do {
        OSSAsyncTask task = getObjectList();
        task.waitUntilFinished();
    } while (!isCompleted);
}

// オブジェクトの 1 ページをフェッチします。
public OSSAsyncTask getObjectList() {
    // バケット名を指定します。
    ListObjectsRequest request = new ListObjectsRequest("examplebucket");
    // ページあたりの最大オブジェクト数を設定します。デフォルト：100。最大：1,000。
    request.setMaxKeys(20);
    // オブジェクトを名前でフィルターするためのプレフィックスを設定します。
    request.setPrefix("file");
    request.setMarker(marker);

    OSSAsyncTask task = oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
        @Override
        public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
            for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
                Log.i("ListObjects", objectSummary.getKey());
            }
            if (!result.isTruncated()) {
                // これ以上ページはありません。
                isCompleted = true;
                return;
            }
            // 次のページのマーカーとして NextMarker を使用します。
            marker = result.getNextMarker();
        }

        @Override
        public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
            isCompleted = true;
            if (clientException != null) {
                clientException.printStackTrace();
            }
            if (serviceException != null) {
                Log.e("ErrorCode", serviceException.getErrorCode());
                Log.e("RequestId", serviceException.getRequestId());
                Log.e("HostId", serviceException.getHostId());
                Log.e("RawMessage", serviceException.getRawMessage());
            }
        }
    });
    return task;
}

名前に特殊文字を含むオブジェクトのリスト化

OSS は、特殊文字を含むオブジェクト名の URL エンコーディングをサポートしています。リクエストを行う前にエンコーディングタイプを "url" に設定し、返された各オブジェクト名を使用する前に URLDecoder でデコードします。

URL エンコーディングが必要なオブジェクト名には、次のような文字を含むものがあります：

単一引用符 (')
二重引用符 (")
アンパサンド (&)
山括弧 (<>)
中国語文字

次の例では、examplebucket 内の特殊文字を含むオブジェクトをリスト化します。

// バケット名を指定します。
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// オブジェクト名の URL エンコーディングを有効にします。
request.setEncodingType("url");

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", URLDecoder.decode(objectSummary.getKey(), "UTF-8"));
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        if (clientException != null) {
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

OSS では、特殊文字を含むオブジェクト名に対して URL エンコーディングのみがサポートされています。

パラメーター

すべての例では、ListObjectsRequest を使用して oss.asyncListObjects() を呼び出します。以下の表は、利用可能なリクエストパラメーターをまとめたものです。

パラメーター	メソッド	タイプ	説明	デフォルト	最大値
バケット名	`new ListObjectsRequest(name)`	String	リスト化するバケットの名前。	—	—
MaxKeys	`setMaxKeys(int)`	int	リクエストごとに返されるオブジェクトの最大数。	100	1,000
Prefix	`setPrefix(String)`	String	この値で始まる名前のオブジェクトに結果をフィルターします。	—	—
Marker	`setMarker(String)`	String	この値のアルファベット順で次のオブジェクトを返します。前の応答の `getNextMarker()` を使用して、次のページに進みます。	—	—
Encoding type	`setEncodingType(String)`	String	応答のオブジェクト名に適用されるエンコーディング。オブジェクト名に特殊文字が含まれる場合は、`"url"` に設定します。	—	—

次のステップ

基盤となる API リファレンスについては、「GetBucket (ListObjects)」および「ListObjectsV2 (GetBucketV2)」をご参照ください。
OSSClient の初期化オプションについては、「初期化」をご参照ください。