boto3でできること

AWSのマネジメントコンソールで行う操作は、裏側ではすべて AWSのAPI 呼び出しだ。boto3 はそのAPIを Python の関数として呼べるようにしたライブラリで、AWS CLI と同じ設定ファイル(~/.aws/config・~/.aws/credentials)を読む。

APIは大きく「作る・変える・消す」と「読む」に分かれる。このシリーズで扱うのは後者で、名前が次のように始まるものが中心になる。

接頭辞役割例
describe_リソースの詳細を一覧で返す(EC2・RDS・ELBなど古くからあるサービスに多い)ec2.describe_instances()
list_IDや名前の一覧を返す(詳細は別APIで取る場合が多い)lambda_.list_functions()
get_1件の詳細や、集計結果を返すce.get_cost_and_usage()
lookup_ / search / select_条件で検索するcloudtrail.lookup_events()

読み取り系のAPIはリソースを変更しないため、権限を読み取り専用に絞れば、スクリプトの誤りで環境を壊す心配がない。棚卸し・定期レポート・監査など、「毎回コンソールを開いて確認している作業」を自動化するのに向いている。

仕組み:リクエストがAWSに届くまで

boto3 で1行のメソッドを呼ぶと、内部では次の順に処理が進む。

boto3のSession・client・botocoreからAWSのAPIエンドポイントまでの処理の流れ

図1: boto3 が API を呼び出すまでの流れ

  1. Session が、どの認証情報(アクセスキーやSSOのトークン)とどのリージョンを使うかを決める
  2. Session から作った client のメソッド(例: describe_instances)を呼ぶ
  3. 土台のライブラリ botocore が、引数をAPIの形式に変換し、リクエストに署名(Signature Version 4)を付ける
  4. HTTPS で リージョンごとのエンドポイント(例: ec2.ap-northeast-1.amazonaws.com)へ送る。IAM など一部のサービスはグローバルなエンドポイントを使う
  5. 返ってきたレスポンスを、Python の dict に変換して返す。混雑によるエラーなどは botocore が自動でリトライする

エラーが出たときも、この流れのどこで失敗したかを考えると原因を絞り込みやすい。認証情報が見つからなければ①、権限がなければ④でAWSから拒否される、という具合だ(エラー別の対処は PART 06 で扱う)。

client と resource の違い

boto3 には、APIを呼ぶための窓口が2種類ある。

client(低レベル)resource(高レベル)
作り方session.client("ec2")session.resource("ec2")
書き方APIと1対1のメソッド。戻り値は dictオブジェクト指向。instance.state のように属性で読める
対応サービスすべてのサービスEC2・S3・IAM・DynamoDB など一部のみ
新機能APIの追加にあわせて随時対応新しい機能は追加されない(公式ドキュメントに明記)
スレッドスレッドセーフ(複数スレッドで共有できる)スレッドセーフではない

resource は短く書ける反面、Cost Explorer や CloudWatch Logs のように resource が用意されていないサービスも多い。サービスごとに書き方を変えると読みにくくなるので、このシリーズでは client に統一する。古い記事やサンプルで boto3.resource を見かけたら、同じことを client でどう書くかを公式リファレンスで確かめるとよい。

API名・CLI・boto3 の名前の対応

AWSの公式ドキュメント(APIリファレンス)、AWS CLI、boto3 では、同じAPIでも表記が異なる。規則は単純で、覚えておくとリファレンスを行き来しやすくなる。

APIリファレンスAWS CLIboto3(client)
DescribeInstancesaws ec2 describe-instancesec2.describe_instances()
ListFunctionsaws lambda list-functionslambda_client.list_functions()
GetCostAndUsageaws ce get-cost-and-usagece.get_cost_and_usage()
パラメーター MaxResults--max-resultsMaxResults=(大文字始まりのまま)

メソッド名は「スネークケース(小文字+アンダースコア)」になるが、引数名とレスポンスのキーはAPIと同じ大文字始まりのままである点に注意したい。lambda は Python の予約語なので、変数名は lambda_client などにする(session.client("lambda") の文字列はそのままでよい)。

レスポンスの読み方

client のメソッドは dict を返す。EC2 の describe_instances を例に、構造を見てみよう。

レスポンスの構造(抜粋・IDはマスク)
{
  "Reservations": [
    {
      "ReservationId": "r-0aaaaaaaaaaaaaaaa",
      "Instances": [
        {
          "InstanceId": "i-0123456789abcdef0",
          "InstanceType": "t3.micro",
          "State": {"Code": 16, "Name": "running"},
          "PrivateIpAddress": "10.0.1.23",
          "LaunchTime": datetime.datetime(2026, 10, 1, 0, 12, 34, tzinfo=tzutc()),
          "Tags": [{"Key": "Name", "Value": "web-01"}]
        }
      ]
    }
  ],
  "ResponseMetadata": {"RequestId": "...", "HTTPStatusCode": 200, "RetryAttempts": 0}
}

読むときのポイントは3つある。

  • 入れ子が深い:EC2 のインスタンスは Reservations(起動リクエストの単位)の下にある。for r in resp["Reservations"]: for i in r["Instances"]: の二重ループになる
  • キーが無いことがある:停止中のインスタンスには PublicIpAddress が無く、タグを1つも付けていなければ Tags キー自体が無い。i["Tags"] ではなく i.get("Tags", []) と書く
  • 日時は datetime 型(UTC):LaunchTime などはタイムゾーン付きの datetime で返る。そのまま json.dumps すると TypeError になるので、json.dumps(resp, default=str) とする

タグは [{"Key": ..., "Value": ...}] というリスト形式で返るので、扱いやすい dict に変換する関数を1つ用意しておくと便利だ。

tags.py
def tags_to_dict(tags):
    """[{"Key": "Name", "Value": "web-01"}] を {"Name": "web-01"} に変換する。"""
    return {t["Key"]: t["Value"] for t in (tags or [])}

最初の一歩:EC2の一覧を出す

仕組みが分かったところで、最小のスクリプトを動かしてみる。プロファイル dev とリージョン ap-northeast-1 を使い、EC2 のIDと状態を表示する。環境の準備は PART 02 で説明するので、ここでは「こう書く」という形だけ見てほしい。

list_ec2.py
import boto3

session = boto3.Session(profile_name="dev", region_name="ap-northeast-1")
ec2 = session.client("ec2")

resp = ec2.describe_instances()
for reservation in resp["Reservations"]:
    for inst in reservation["Instances"]:
        name = {t["Key"]: t["Value"] for t in inst.get("Tags", [])}.get("Name", "-")
        print(inst["InstanceId"], inst["State"]["Name"], inst["InstanceType"], name)
出力例
i-0123456789abcdef0 running t3.micro web-01
i-0fedcba9876543210 stopped t3.small batch-01

⚠️ このコードには取得漏れの可能性がある

多くのAPIは、1回の呼び出しで返す件数に上限がある。件数が多い環境では、続きを取得する処理(ページネーション)を書かないと一部しか取れない。正しい書き方は PART 03 で解説する。

読み取り専用のIAM権限を選ぶ

情報取得用のスクリプトには、書き込み権限を持たないIAMロールやユーザーを使うのが鉄則だ。AWS管理ポリシーでは、次の3つが候補になる。

AWS管理ポリシー範囲向いている用途
ViewOnlyAccess各サービスのリソース一覧と基本的なメタデータを見られる。データの中身(S3のオブジェクトなど)は読めず、一部の詳細設定を返すAPIも含まれない棚卸し・構成の確認。足りないアクションは個別に追加する
ReadOnlyAccessほぼすべてのサービスの読み取り。S3オブジェクトの取得やDynamoDBの項目の読み取りなど、データの中身も読める調査用。範囲が広いので常用は避けたい
SecurityAuditセキュリティ設定の監査に必要な読み取りIAM・CloudTrail・セキュリティ系の確認(PART 07)

定期実行するスクリプトなど、使うAPIが決まっているなら、必要なアクションだけを並べたポリシーを作るのが最も安全だ。各回で使うAPIと、必要なIAMアクションは PART 07 の一覧表にまとめている。なお、Cost Explorer(ce:GetCostAndUsage)のようにコスト系の権限は上の管理ポリシーとは別に考える必要があるので、PART 05 で個別に説明する。

このシリーズの前提環境と構成

  • Python 3.10 以降(2026年4月に boto3 の Python 3.9 サポートが終了したため)。Python の導入は Python 開発環境導入手順 を参照
  • boto3 は最新版(記事作成時点の 1.43 系)
  • ローカルPC:Windows 11(PowerShell)を中心に、macOS / Linux のコマンドも併記
  • 認証:IAM Identity Center(SSO)のプロファイル dev、リージョンは東京(ap-northeast-1)
回内容こんなときに読む
PART 01全体像と仕組み(この記事)boto3 を初めて使う
PART 02環境準備と接続確認プロファイルやSSOで接続したい
PART 03情報取得の基本パターン取得漏れ・絞り込み・エラー処理を正しく書きたい
PART 04リソース棚卸しスクリプト全リージョンのEC2・RDS・S3・Lambdaを一覧にしたい
PART 05メトリクスとコストの取得CPU使用率や月別コストを集計したい
PART 06複数アカウントとトラブルシュート複数アカウントを回したい・エラーが出た
PART 07付録:取得できる情報一覧と逆引き「これは取れる?」を調べたい

✅ 次の記事では…

PART 02 では、boto3 がどの認証情報とリージョンを使うかを決める仕組みと、Session を使った接続確認を解説する。

→ PART 02 — 環境準備と接続確認(Session・認証情報・リージョン)へ