準備の基本は既存の記事を参照

boto3 を動かすには、次の3つが必要だ。前の2つは別の記事で手順を解説しているので、まだの場合は先に済ませてほしい。

準備するもの参照先
Python 3.10 以降と仮想環境(venv)Python 開発環境導入手順
AWS CLI v2 とプロファイル(アクセスキー または IAM Identity Center)ポートフォワード PART 02「AWS CLI v2 とプロファイルの準備」
boto3 本体この記事

boto3 自体はプロファイルを作る機能も、SSO にログインする機能も持っていない。プロファイルの作成と aws sso login は AWS CLI で行い、boto3 はその結果を読むだけ、という分担になる。そのため、boto3 だけを使う場合でも AWS CLI は入れておくのがおすすめだ。

boto3 のインストール

仮想環境を有効にしてから pip で入れる。依存ライブラリの botocore も一緒に入る。

PowerShell / bash 共通
pip install boto3
python -c "import boto3, botocore; print(boto3.__version__, botocore.__version__)"

boto3 はほぼ毎日新しいバージョンが出る。新しいAPIやリージョンは新しいバージョンでしか使えないことがあるので、古いまま使い続けず、定期的に pip install -U boto3 で更新する。チームで動かすスクリプトなら、requirements.txt にバージョンを書いて揃えておく。

💡 エディタで補完を効かせたい場合

boto3 のメソッドは実行時に動的に作られるため、そのままではエディタの補完が効きにくい。有志が公開している型定義パッケージ(例: pip install "boto3-stubs[ec2,s3]")を入れると、VS Code などでメソッド名や引数が補完されるようになる。実行には不要なので、開発用の依存として入れるとよい。

CLI と共有する設定ファイル

boto3 は AWS CLI と同じ場所の設定ファイルを読む。

ファイルWindowsmacOS / Linux主な内容
config%USERPROFILE%\.aws\config~/.aws/configリージョン、SSO の設定、ロールの引き受け、リトライ設定
credentials%USERPROFILE%\.aws\credentials~/.aws/credentialsアクセスキー(長期の認証情報)
SSO トークンのキャッシュ%USERPROFILE%\.aws\sso\cache\~/.aws/sso/cache/aws sso login で取得したトークン

IAM Identity Center(SSO)を使う場合、config は次のような形になる。sso-session セクションにポータルの情報を書き、各プロファイルからそれを参照する形式だ。boto3 もこの形式をそのまま読める。

~/.aws/config(IAM Identity Center の例)
[profile dev]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = ReadOnlyAccess
region = ap-northeast-1
output = json

[sso-session my-sso]
sso_start_url = https://d-xxxxxxxxxx.awsapps.com/start
sso_region = ap-northeast-1
sso_registration_scopes = sso:account:access

認証情報を探す順番

boto3 は、次の順番で認証情報を探し、最初に見つかったものを使う(公式ドキュメントの記載順)。

順探す場所補足
1boto3.client() に渡した引数aws_access_key_id= など。コードにキーを書くことになるので使わない
2Session に渡した引数PART 06 で assume_role の結果を渡すときに使う
3環境変数AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN
4〜5ロールの引き受けconfig の role_arn、Web ID トークン(EKS など)
6IAM Identity Centerconfig の sso_session など。トークンは aws sso login で取得
7credentials ファイルアクセスキー
8コンソールの認証情報によるログインAWS CLI の aws login で取得したもの
9〜10config ファイル / 旧 boto の設定ファイルconfig に直接書いたキーなど
11コンテナの認証情報ECS タスクロールなど
12インスタンスメタデータEC2 のインスタンスプロファイル(IAM ロール)

この順番のおかげで、同じスクリプトが手元のPCではSSOのプロファイルで、EC2上ではインスタンスのロールで、コードを変えずに動く。EC2 や Lambda で動かすときに、アクセスキーを置く必要はない。

落とし穴:環境変数がプロファイルより先に使われる

順番の表で、環境変数(3)はプロファイル系(4〜9)より前にある。以前の作業で設定した AWS_ACCESS_KEY_ID が残っていると、プロファイルを切り替えたつもりでも、環境変数のキーで接続してしまう。

ややこしいのは、プロファイルの指定方法によって結果が変わる点だ。

プロファイルの指定方法環境変数のキーが残っている場合
環境変数 AWS_PROFILE=dev環境変数のキーが使われる(プロファイルは無視される)
コードで boto3.Session(profile_name="dev")プロファイル dev が使われる(明示した場合は環境変数のキーを見に行かない)

「CLI では --profile を付けて正しく動いたのに、AWS_PROFILE を設定した Python では別のアカウントに接続した」という食い違いは、だいたいこれが原因だ。まず、残っている環境変数を確認する。

Windows(PowerShell)
# AWS_ で始まる環境変数を表示
Get-ChildItem Env:AWS_*

# 不要なら、このターミナルから削除
Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN -ErrorAction SilentlyContinue
macOS / Linux(bash)
env | grep ^AWS_
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

⚠️ Windows のシステム環境変数にも注意

Windows では「システムのプロパティ」→「環境変数」にキーが登録されていることがある。この場合、ターミナルで削除しても、開き直すとまた設定される。長期のアクセスキーを環境変数に常駐させるのはやめ、プロファイル(できれば SSO)に移すのが根本的な対策だ。

Session を明示して使う

boto3.client("ec2") のように直接 client を作ると、boto3 が内部で持つ「デフォルトの Session」が使われ、プロファイルとリージョンは環境変数や config の [default] から決まる。どの環境で動かしても結果が分かるように、Session を明示して作る習慣を付けておくとよい。

Session からは、実際に使われる設定を確認できる。get_credentials().method を見れば、認証情報がどこから来たかが分かるので、前の節の落とし穴の調査に役立つ。

check_session.py
import boto3

session = boto3.Session(profile_name="dev")

print("使えるプロファイル:", session.available_profiles)
print("プロファイル     :", session.profile_name)
print("リージョン       :", session.region_name)

creds = session.get_credentials()
# 認証情報の取得元(env / sso / shared-credentials-file / assume-role / iam-role など)
print("認証情報の取得元 :", creds.method if creds else "見つからない")
出力例
使えるプロファイル: ['default', 'dev', 'prod-readonly']
プロファイル     : dev
リージョン       : ap-northeast-1
認証情報の取得元 : sso

デフォルトの Session を使いたい場合は、スクリプトの冒頭で boto3.setup_default_session(profile_name="dev") と書いて設定を固定する方法もある。ただし、関数の外の状態に依存するため、複数のプロファイルを扱うスクリプトでは Session を変数で持ち回るほうが分かりやすい。

接続確認:get_caller_identity

準備ができたら、まず 「誰として、どのアカウントに」接続しているかを確認する。STS の get_caller_identity は、IAMの権限設定に関係なく呼び出せる(拒否するポリシーを書いても拒否されない)ので、接続確認に最適だ。

whoami.py
import sys

import boto3
from botocore.exceptions import (
    NoCredentialsError,
    ProfileNotFound,
    SSOTokenLoadError,
    TokenRetrievalError,
    UnauthorizedSSOTokenError,
)

PROFILE = sys.argv[1] if len(sys.argv) > 1 else "dev"

try:
    session = boto3.Session(profile_name=PROFILE)
    ident = session.client("sts").get_caller_identity()
except ProfileNotFound:
    sys.exit(f"プロファイル {PROFILE} が config にありません")
except (UnauthorizedSSOTokenError, SSOTokenLoadError, TokenRetrievalError):
    sys.exit(f"SSO のログインが切れています。aws sso login --profile {PROFILE} を実行してください")
except NoCredentialsError:
    sys.exit("認証情報が見つかりません")

print("Account:", ident["Account"])
print("Arn    :", ident["Arn"])
print("Region :", session.region_name)
出力例(IAM Identity Center の場合)
Account: 123456789012
Arn    : arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_ReadOnlyAccess_0123456789abcdef/taro@example.com
Region : ap-northeast-1

SSO で接続している場合、ARN は assumed-role/AWSReservedSSO_<許可セット名>_... という形になる。末尾のユーザー名と、許可セット名(ここでは ReadOnlyAccess)が意図どおりかを確認しておく。

SSO のトークンが切れたとき

IAM Identity Center のトークンには有効期限がある(期間は管理者の設定による)。期限が切れたあとにスクリプトを動かすと、次のようなエラーになる。

例外メッセージの例状況
UnauthorizedSSOTokenErrorThe SSO session associated with this profile has expired or is otherwise invalid.トークンの期限切れ・無効
TokenRetrievalErrorError when retrieving token from sso: Token has expired and refresh failedsso-session 形式で、自動更新にも失敗した
SSOTokenLoadErrorError loading SSO Token: Token for ... does not exist一度も aws sso login していない

どれも対処は同じで、AWS CLI で aws sso login --profile dev を実行し直す。ブラウザでの承認が必要なため、人がいない時間帯に動かす定期実行には SSO は向かない。定期実行は、EC2 や Lambda などのロールで動かすのが基本だ。

リージョンの決まり方と NoRegionError

リージョンは、次の順で決まる。

  1. コードで指定した値(Session(region_name=...) や session.client("ec2", region_name=...))
  2. 環境変数 AWS_DEFAULT_REGION
  3. config のプロファイルの region

どこにも設定がないと、client を作った時点で botocore.exceptions.NoRegionError: You must specify a region. になる。また、EC2 のようにリージョンごとにリソースが分かれているサービスでは、指定したリージョンのリソースしか返らない。「EC2 が1台も返ってこない」ときは、権限より先にリージョンを疑うとよい。

一方、次のサービスはリージョンの扱いが特殊なので、PART 04 以降で使うときにあらためて触れる。

  • IAM・Organizations:グローバルなサービスで、どのリージョンを指定しても同じ結果が返る
  • S3:バケットの一覧はアカウント全体で返るが、バケットごとに所属リージョンがある
  • Cost Explorer:エンドポイントが us-east-1 にあるため、region_name="us-east-1" を指定する

準備のチェックリスト

  • aws --version で AWS CLI v2 が表示される
  • aws sts get-caller-identity --profile dev が成功する
  • 仮想環境に boto3 が入っている(pip show boto3)
  • AWS_ACCESS_KEY_ID などの環境変数が意図せず残っていない
  • whoami.py の Account・Arn・Region が想定どおり
  • 使うプロファイル(許可セット)が読み取り専用になっている

✅ 次の記事では…

PART 03 では、ページネーションによる取得漏れの防止、フィルターでの絞り込み、エラー処理とリトライ設定など、情報取得の基本パターンを解説する。

→ PART 03 — 情報取得の基本パターン(ページネーション・絞り込み・エラー処理)へ