Boto3を使ってS3バケットのすべてのオブジェクトをページネーションで取得する方法

問題の概要

S3バケットには大量のオブジェクトが保存されていることが多く、1回のAPI呼び出しですべてを取得することはできません。本記事では、Pythonのboto3ライブラリを使用して、アカウント内に作成されたS3バケットのすべてのオブジェクトをページネーション（ページ分割）しながら効率的に取得する方法を解説します。

解決のためのアプローチとアルゴリズム

• ステップ1： boto3およびbotocoreの例外クラスをインポートし、例外処理に備えます。

• ステップ2： max_items、page_size、starting_tokenは本関数の任意パラメータで、bucket_nameだけが必須パラメータです。

  • max_items： 返却するレコードの総数を表します。利用可能なレコード数がmax_itemsを超える場合、レスポンスにNextTokenが返され、これを指定することでページネーションを再開できます。

  • page_size： 1ページあたりのサイズを表します。

  • starting_token： ページネーションを継続するためのトークンで、前回のレスポンスに含まれていた最後のキーを指定します。

• ステップ3： boto3ライブラリを使用してAWSセッションを作成します。デフォルトプロファイルにregion_nameが設定されていることを確認してください。設定されていない場合は、セッション作成時に明示的にregion_nameを渡す必要があります。

• ステップ4： S3用のAWSクライアントを作成します。

• ステップ5： list_objectsを使用して、S3バケットのオブジェクト一覧を取得するためのpaginatorオブジェクトを作成します。

• ステップ6： paginate関数を呼び出し、max_items・page_size・starting_tokenをPaginationConfigパラメータとして、bucket_nameをBucketパラメータとしてそれぞれ渡します。

• ステップ7： max_itemsとpage_sizeの設定値に応じた件数のレコードが返されます。

• ステップ8： ページネーション処理中に問題が発生した場合に備え、汎用例外もハンドリングします。

サンプルコード

以下のコードを使用すると、自分のアカウントに作成したS3バケット内のすべてのオブジェクトをページネーションしながら取得できます。

import boto3
from botocore.exceptions import ClientError

def paginate_through_all_objects_s3_bucket(bucket_name, max_items: int = None,
                                           page_size: int = None,
                                           starting_token: str = None):
    session = boto3.session.Session()
    s3_client = session.client('s3')
    try:
        paginator = s3_client.get_paginator('list_objects')
        response = paginator.paginate(Bucket=bucket_name, PaginationConfig={
            'MaxItems': max_items,
            'PageSize': page_size,
            'StartingToken': starting_token
        })
        return response
    except ClientError as e:
        raise Exception("boto3 client error in paginate_through_all_objects_s3_bucket: " + e.__str__())
    except Exception as e:
        raise Exception("Unexpected error in paginate_through_all_objects_s3_bucket: " + e.__str__())

# 1回目の実行
a = paginate_through_all_objects_s3_bucket('s3-test-bucket', 2, 5)
print(*a)

# 2回目の実行（続きのデータを取得）
for items in a:
    if items['IsTruncated']:
        next_token = items['Contents'][-1]['Key']
        b = paginate_through_all_objects_s3_bucket('s3-test-bucket', 2, 5, next_token)
        print(*b)

実行結果

上記コードを実行すると、1回目ではバケット先頭のオブジェクト一覧が、2回目ではトークン以降の続きのオブジェクト一覧が出力されます。

# 1回目の実行
{'ResponseMetadata': {'RequestId': '5AE5VF7RK', 'HostId': **************, 'HTTPStatusCode': 200, 'HTTPHeaders': {'x-amz-id-2': **************, 'x-amz-request-id': '5AE5VF7RK', 'date': 'Sat, 03 Apr 2021 07:33:28 GMT', 'x-amz-bucket-region': 'us-east-1', 'content-type': 'application/xml', 'transfer-encoding': 'chunked', 'server': 'AmazonS3'}, 'RetryAttempts': 0}, 'IsTruncated': True, 'Marker': '',
'Contents': [{'Key': 'analytics-s3i/param.json', 'LastModified': datetime.datetime(2020, 10, 29, 19, 50, 55, tzinfo=tzutc()), 'ETag': '"e6f6b8e02"', 'Size': 1554, 'StorageClass': 'STANDARD', 'Owner': {'DisplayName': 'AWS.Development', 'ID': '92************************0'}}, {'Key': 'analytics-s3i/params.json', 'LastModified': datetime.datetime(2021, 3, 10, 20, 10, 47, tzinfo=tzutc()), 'ETag': '"22a4bf70c1ed2612"', 'Size': 1756, 'StorageClass': 'STANDARD', 'Owner': {'DisplayName': 'AWS.Development', 'ID': '92************************************************'}}], 'Name': 's3-test-bucket', 'Prefix': '', 'MaxKeys': 5, 'EncodingType': 'url', 'CommonPrefixes': None}

# 2回目の実行
{'ResponseMetadata': {'RequestId': '5AEAWX', 'HostId': 'Uc********************************', 'HTTPStatusCode': 200, 'HTTPHeaders': {'x-amz-id-2': *****************************, 'x-amz-request-id': '5AEAWX', 'date': 'Sat, 03 Apr 2021 07:33:28 GMT', 'x-amz-bucket-region': 'us-east-1', 'content-type': 'application/xml', 'transfer-encoding': 'chunked', 'server': 'AmazonS3'}, 'RetryAttempts': 0}, 'IsTruncated': True, 'Marker': 'analytics-s3i/params.json',
'Contents': [{'Key': 'analytics-s3i/template.json', 'LastModified': datetime.datetime(2020, 10, 29, 19, 50, 55, tzinfo=tzutc()), 'ETag': '"3af411f"', 'Size': 21334, 'StorageClass': 'STANDARD', 'Owner': {'DisplayName': 'AWS.Development', 'ID': '92************************'}}, {'Key': 'analytics-s3i2/param.json', 'LastModified': datetime.datetime(2020, 11, 20, 17, 32, 45, tzinfo=tzutc()), 'ETag': '"04c29cf86888f99"', 'Size': 1695, 'StorageClass': 'STANDARD', 'Owner': {'DisplayName': 'AWS.Development', 'ID': '92************************'}}], 'Name': 's3-test-bucket', 'Prefix': '', 'MaxKeys': 5, 'EncodingType': 'url', 'CommonPrefixes': None}

補足：list_objects_v2の活用

現在のAWS SDKでは、より新しいlist_objects_v2 APIの使用が推奨されています。v2ではMarkerの代わりにContinuationTokenが採用され、ページネーションをより直感的に扱えます。s3_client.get_paginator('list_objects_v2')と指定するだけで、同じpaginatorの仕組みをそのまま利用できるため、新規開発ではv2を選択することをおすすめします。