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行のメソッドを呼ぶと、内部では次の順に処理が進む。
図1: boto3 が API を呼び出すまでの流れ
- Session が、どの認証情報(アクセスキーやSSOのトークン)とどのリージョンを使うかを決める
- Session から作った client のメソッド(例:
describe_instances)を呼ぶ - 土台のライブラリ botocore が、引数をAPIの形式に変換し、リクエストに署名(Signature Version 4)を付ける
- HTTPS で リージョンごとのエンドポイント(例:
ec2.ap-northeast-1.amazonaws.com)へ送る。IAM など一部のサービスはグローバルなエンドポイントを使う - 返ってきたレスポンスを、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 CLI | boto3(client) |
|---|---|---|
DescribeInstances | aws ec2 describe-instances | ec2.describe_instances() |
ListFunctions | aws lambda list-functions | lambda_client.list_functions() |
GetCostAndUsage | aws ce get-cost-and-usage | ce.get_cost_and_usage() |
パラメーター MaxResults | --max-results | MaxResults=(大文字始まりのまま) |
メソッド名は「スネークケース(小文字+アンダースコア)」になるが、引数名とレスポンスのキーはAPIと同じ大文字始まりのままである点に注意したい。lambda は Python の予約語なので、変数名は lambda_client などにする(session.client("lambda") の文字列はそのままでよい)。
レスポンスの読み方
client のメソッドは dict を返す。EC2 の describe_instances を例に、構造を見てみよう。
{
"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つ用意しておくと便利だ。
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 で説明するので、ここでは「こう書く」という形だけ見てほしい。
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 を使った接続確認を解説する。