このスキルがアクティブな場合、コード、コメント、出力内で絵文字を使用しないでください。

AWS SDK for Python (boto3)

boto3 は AWS 向けの高レベル Python SDK です。低レベル SDK である botocore をラップし、2 つの異なるインターフェイスを提供します：クライアント（低レベル、1:1 API マッピング）とリソース（高レベル、オブジェクト指向）。どちらをいつ使うべきかを理解することが必須です。

クライアント vs リソース

クライアントは AWS サービス API に直接マップします。すべてのサービスにはクライアントがあります。レスポンスはプレーン dict です。

リソースはアトリビュートとアクションを備えたオブジェクト指向インターフェイスを提供します。リソースを持つのはいくつかのサービスのみです（S3、DynamoDB、EC2、IAM、SQS、SNS、CloudFormation、CloudWatch、Glacier）。リソースは型を自動的にマーシャル化します（特に DynamoDB に有用）。

import boto3

# クライアント - 低レベル、すべてのサービス
s3_client = boto3.client("s3")
response = s3_client.list_buckets()
buckets = response["Buckets"]  # プレーン dict

# リソース - 高レベル、選定サービス
s3_resource = boto3.resource("s3")
for bucket in s3_resource.buckets.all():
    print(bucket.name)  # dict キーではなくアトリビュートアクセス

API の完全なカバレッジが必要な場合、またはサービスにリソースインターフェイスがない場合はクライアントを使用してください。リソースが存在し、コードを単純化できる場合（特に DynamoDB と S3）はリソースを使用してください。

セッションとクライアント作成

import boto3

# デフォルトセッションが暗黙的に作成される
client = boto3.client("s3")
resource = boto3.resource("dynamodb")

# クライアント作成方法をカスタマイズする必要があるとき、
# または特定のプロファイルを使用するときは明示的セッションを使用
session = boto3.Session(
    profile_name="my-profile",
    region_name="us-west-2",
)
client = session.client("s3")

ループ内でクライアントを作成しないでください。単一のクライアント インスタンスを再利用してください。クライアントはスレッドセーフであり、インスタンス化後はスレッド全体で共有できます。

API 呼び出し

# クライアント - パラメータをキーワード引数として渡し、dict を返す
response = client.get_object(Bucket="my-bucket", Key="my-key")
data = response["Body"].read()

# リソース - オブジェクトメソッドとアトリビュートを使用
obj = s3_resource.Object("my-bucket", "my-key")
response = obj.get()
data = response["Body"].read()

パラメータ名は AWS API の大文字小文字を正確に一致させます。通常は snake_case ではなく PascalCase です。

エラーハンドリング

例外は、実行可能なアクション（フォールバック値の返却、再試行、別のコードパスの選択）がある場合にのみキャッチしてください。例外をキャッチしてそれを出力するだけで無視することは間違っています。実際のエラーを隠し、呼び出し元が反応することを防ぎます。デフォルトでは例外を伝播させてください。

キャッチする場合は、文字列コードマッチングによる一般的な ClientError ではなく、client.exceptions アトリビュートを通じたクライアント上の型付き例外を優先してください：

lambda_client = boto3.client("lambda")

def get_function_config(name: str) -> dict | None:
    """関数設定を返すか、存在しない場合は None を返す。"""
    try:
        return lambda_client.get_function_configuration(FunctionName=name)
    except lambda_client.exceptions.ResourceNotFoundException:
        return None  # 実行可能：不足している関数を None に変換
    # その他すべてが伝播 - 呼び出し元または main() が処理

一般的な ClientError はビジネスロジック関数ではなく、トップレベルのエラーハンドラでのみキャッチオールとして使用してください。これは boto3 ではなく botocore に存在します：

from botocore.exceptions import ClientError

def main() -> int:
    try:
        result = do_the_work()
        print(result)
        return 0
    except ClientError as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1

完全なエラー階層と botocore 例外については、references/error-handling.md を参照してください。

スクリプト構造

boto3 または botocore を使用するスクリプトを書くよう指示されたときは、if __name__ == "__main__" を単一の関数呼び出しに保ってください。引数の解析、エラー表示、および終了コードは、ビジネスロジック関数に分散させるのではなく main() に属します：

def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("bucket")
    args = parser.parse_args()

    try:
        do_the_work(args.bucket)
        return 0
    except ClientError as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1

if __name__ == "__main__":
    sys.exit(main())

ビジネスロジック関数から sys.exit() を呼び出さないでください。関数をテスト不可能で、ライブラリとして使用不可能にします。代わりに例外を発生させるか、エラー値を返し、main() にそれをどう提示するかを決定させてください。

ページネーション

NextToken で手動ループを行わないでください。ページネータを使用してください。特定のフィールドのみが必要な場合は、.search() を JMESPath 式と共に使用して、ページ全体で抽出およびフラット化してください：

paginator = iam.get_paginator("list_users")
for name in paginator.paginate().search("Users[].UserName"):
    print(name)

# フィルタリングと投影
for arn in paginator.paginate().search("Users[?Path == '/admin/'][].Arn"):
    print(arn)

アイテムごとに完全なレスポンスオブジェクトが必要な場合、またはページごとの制御が必要な場合（例えば、ページのカウント、ページごとのバッチ処理）は、ページを直接反復してください：

for page in paginator.paginate():
    for user in page.get("Users", []):
        process(user)

ページネーションの詳細については、references/pagination.md を参照してください。

ウェイター

リソースが目的の状態に到達するまで待機してください：

waiter = client.get_waiter("bucket_exists")
waiter.wait(
    Bucket="my-bucket",
    WaiterConfig={"Delay": 5, "MaxAttempts": 20},
)

ウェイターの詳細については、references/waiters.md を参照してください。

クライアント構成

再試行、タイムアウト、接続プール設定など、botocore.config.Config を使用してください：

from botocore.config import Config

config = Config(
    retries={"total_max_attempts": 2, "mode": "adaptive"},
    connect_timeout=5,
    read_timeout=10,
    max_pool_connections=50,
)
client = boto3.client("s3", config=config)

クライアント向けカスタム構成を作成するときは、references/configuration.md を参照してください。

ロギング

boto3 と botocore の両方は標準ライブラリ logging モジュールを使用します。標準 logging API を通じてロギングを設定することも、便宜上 boto3 と botocore が提供するヘルパーを使用することもできます：

# クイック：すべての botocore ワイヤレベルの詳細を stderr にログ
boto3.set_stream_logger("")  # ルートロガー -- すべて
boto3.set_stream_logger("botocore")  # botocore のみ

# Botocore、すべての botocore 詳細をログ
import logging

from botocore.session import Session

session = Session()

session.set_stream_logger('botocore', logging.DEBUG)
# または：ファイルにロギングを設定
session.set_file_logger(logging.DEBUG, '/tmp/botocore.log')

set_stream_logger(name, level=logging.DEBUG) は指定されたロガーに StreamHandler を追加します。これは SDK からのリクエスト/レスポンスデバッグ出力を取得するための慣用的な方法です。

一般的な問題

問題：ClientError インポート位置

誤り： from boto3.exceptions import ClientError 正し： from botocore.exceptions import ClientError

サービス固有のカスタマイズ

以下のサービスを使用する Python コードを作成する場合、ベストプラクティスとカスタム高レベル API のために以下の追加リファレンスファイルを読み込む必須です：

• S3 - references/s3.md を読み込む必須です。
• Dynamodb - references/dynamodb.md を読み込む必須です。

リファレンス

• クライアント構成（再試行、タイムアウト、エンドポイント）：references/configuration.md
• 認証情報とセッション：references/credentials.md
• エラーハンドリングパターン：references/error-handling.md
• ページネーション：references/pagination.md
• ウェイター：references/waiters.md
• S3 転送と署名付き URL：references/s3.md
• DynamoDB 操作：references/dynamodb.md