準備の基本は既存の記事を参照
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 も一緒に入る。
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 と同じ場所の設定ファイルを読む。
| ファイル | Windows | macOS / 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 もこの形式をそのまま読める。
[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 は、次の順番で認証情報を探し、最初に見つかったものを使う(公式ドキュメントの記載順)。
| 順 | 探す場所 | 補足 |
|---|---|---|
| 1 | boto3.client() に渡した引数 | aws_access_key_id= など。コードにキーを書くことになるので使わない |
| 2 | Session に渡した引数 | PART 06 で assume_role の結果を渡すときに使う |
| 3 | 環境変数 | AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN |
| 4〜5 | ロールの引き受け | config の role_arn、Web ID トークン(EKS など) |
| 6 | IAM Identity Center | config の sso_session など。トークンは aws sso login で取得 |
| 7 | credentials ファイル | アクセスキー |
| 8 | コンソールの認証情報によるログイン | AWS CLI の aws login で取得したもの |
| 9〜10 | config ファイル / 旧 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 では別のアカウントに接続した」という食い違いは、だいたいこれが原因だ。まず、残っている環境変数を確認する。
# AWS_ で始まる環境変数を表示
Get-ChildItem Env:AWS_*
# 不要なら、このターミナルから削除
Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN -ErrorAction SilentlyContinueenv | 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 を見れば、認証情報がどこから来たかが分かるので、前の節の落とし穴の調査に役立つ。
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の権限設定に関係なく呼び出せる(拒否するポリシーを書いても拒否されない)ので、接続確認に最適だ。
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)Account: 123456789012
Arn : arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_ReadOnlyAccess_0123456789abcdef/taro@example.com
Region : ap-northeast-1SSO で接続している場合、ARN は assumed-role/AWSReservedSSO_<許可セット名>_... という形になる。末尾のユーザー名と、許可セット名(ここでは ReadOnlyAccess)が意図どおりかを確認しておく。
SSO のトークンが切れたとき
IAM Identity Center のトークンには有効期限がある(期間は管理者の設定による)。期限が切れたあとにスクリプトを動かすと、次のようなエラーになる。
| 例外 | メッセージの例 | 状況 |
|---|---|---|
UnauthorizedSSOTokenError | The SSO session associated with this profile has expired or is otherwise invalid. | トークンの期限切れ・無効 |
TokenRetrievalError | Error when retrieving token from sso: Token has expired and refresh failed | sso-session 形式で、自動更新にも失敗した |
SSOTokenLoadError | Error loading SSO Token: Token for ... does not exist | 一度も aws sso login していない |
どれも対処は同じで、AWS CLI で aws sso login --profile dev を実行し直す。ブラウザでの承認が必要なため、人がいない時間帯に動かす定期実行には SSO は向かない。定期実行は、EC2 や Lambda などのロールで動かすのが基本だ。
リージョンの決まり方と NoRegionError
リージョンは、次の順で決まる。
- コードで指定した値(
Session(region_name=...)やsession.client("ec2", region_name=...)) - 環境変数
AWS_DEFAULT_REGION - 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 では、ページネーションによる取得漏れの防止、フィルターでの絞り込み、エラー処理とリトライ設定など、情報取得の基本パターンを解説する。