【AWS】AWS CLIを利用してS3の操作をする方法①

はじめに

なぜAWS CLIを学んだか？

日次処理システムを組む業務でAWS S3から自動でデータ連携させる必要があり学びました。

S3操作自体はマネージメントコンソールからもできますが、システムに組み込む場合はスクリプトに落とし込む必要があったので、CLIを使って操作しました。

なぜシステムに組み込むのにCLIが必要なのか？

システムに組み込む（今回は自動化として言及します）、自動化を行うための操作は明瞭な手順として定義される必要があります。手順が明確に定義されていなければ、毎回違った操作が行われ、期待した結果を得ることが難しくなります。
この手順の明確化というのが、つまるところスクリプトの記述ということです。そしてスクリプトでS3の操作を記述できるツールがAWS CLIです。

ナレッジとして記載すること

私が携わった案件の環境はWindowsOSのEC2（仮想サーバ）だったため、Windows PowerShellをスクリプトとして使用してAWS CLIを記述しました。AWS CLI自体はシェルスクリプトで記述することを基本としているっぽいです（cf. What is the AWS Command Line Interface?）。なのでWindowsであればコマンドプロンプトでも使用できますし、UNIX系のBashでも使用することができます。

しかし、AWS CLI自体の記述方法は共通なので、今回はAWS CLIの記述方法にフォーカスしてナレッジを記載します。 AWS S3の操作を自動化する必要があったり、大量のファイルを操作する必要がある方は参考になるかと思います（逆にそれ以外の操作においてはマネージメントコンソールで事足りる気がしてます）。

AWS CLI使用の準備

準備①：AWS CLIのダウンロード

1.下記リンクからダウンロードできます（画像赤枠部分）。
・AWS コマンドラインインターフェイス：https://aws.amazon.com/jp/cli/

2.ダウンロードしたファイル（Windows版なら.msi）を起動します。
3.起動したセットアップウィザードに沿って設定する。

基本的に難しいことはないと思いますが、1点注意点として、このあと環境変数PATHを通すのでexeファイルの保存場所だけ覚えておきましょう。 デフォルトだとC:\\Program Files\\Amazon\\AWSCLIV2\\配下になると思います。

準備②：AWS CLIの環境変数PATHの設定

ターミナル（黒い画面）でコマンドを実行するために環境変数PATHを追加します。インストール設定によってはすでにPATHが追加されているかもしれませんが確認しておくのが吉です。

環境変数PATHが追加されていれば、ターミナル上でaws コマンドを実行できるはずです。試しに下記コマンドを実行してみましょう。

aws help

awsのPATHが通っていれば下記の画像の内容が返ってきます（対話モードになるのでCtrl + Cで解除します）。

🤔 aws helpでエラーが出る場合

考えられる大きな原因は2つあります。

• PATHがうまく通ってない
• インストールがうまくいっていない

上記2つの問題を切り分けるため、exeファイルのPATHを絶対参照で指定して起動してみます（参照のファイルパスは自分の設定したパスに置き換えてください）。

• コマンドプロンプト：”C:\\Program FIles\\Amazon\\AWSCLIV2\\aws.exe” help
• Windows PowerShell：.”C:\\Program FIles\\Amazon\\AWSCLIV2\\aws.exe” help

下記画像の様になっていたらPATHの設定がうまくいっていない可能性があるので、環境変数をもう一度確認してみましょう。

上記コマンドでもエラーが出る場合は、インストールがうまくいっていない可能性があります。再度インストーラからインストールを行いましょう。

前提①：AWS CLIの文法

AWS CLIコマンドの文法は下記の様になっています。

 aws [オプション] <コマンド> <サブコマンド> [パラメータ]

[オプション]と[パラメータ]に関してはコマンドによってあったりなかったりします。

今回のS3の操作の文法は下記のとおりです。

aws <s3|s3api> <サブコマンド> [オプション] [引数] 

コマンドとしてはs3かs3apiを使用しており、そのうえで各種操作に応じてサブコマンド、オプションを指定するようになっています。

前提②：用語説明

• S3：
  Simple Strage Serviceの略。名前通りストレージを借りられるサービスです。
• バケット：
  オブジェクトを保存するコンテナです。このコンテナの中にファイルなどのオブジェクトを入れて保管できます。
• プレフィックス：
  英語の直訳だと接頭辞の意で、文字列の頭に付随する文字列を意味しますがS3においては別の意味を持ちます。仮想的に階層構造（ディレクトリ）を表現するファイルパスのようなものです。厳密には異なりますがローカル環境のディレクトリのイメージで大丈夫です。具体的には下記の様な文字列です。

 test/nested/

• S3のファイル指定（URI）：
  AWS CLI上でファイル指定を行う場合下記のURIのルールに従って記述します。

 s3://<バケット名>/<プレフィックス>/<ファイル名>

• S3内のデータ構造：
  バケット内のデータはプレフィックスによって一見階層構造を持つように見えますが、厳密には異なります。キーバリューペアのようにキーに対してファイルが一意になる形で格納されているため、内部でのデータは階層によって分かれていないそうです。詳細は下記リンクを参照してください。

Amazon S3 とは：https://docs.aws.amazon.com/ja_jp/AmazonS3/latest/userguide/Welcome.html

認証

AWS CLIはAWSサービスに対する操作をスクリプトを通して行えるサービスです。そのため、CLIの操作対象となるAWSサービスとつなげるためにアカウント認証が必要となります。

1.ターミナル上で下記を入力します。

aws configure

2.下記のようにアクセスキーとシークレットアクセスキーを問われるので画面の項目を入力していきます。

3.上記の情報を入力したら認証ファイルが作成されます。この情報間違っていなければ正常にAWSサービスにアクセスできるようになっているはず。

4.入力された情報はプロファイルとして（デフォルト設定なら）下記ディレクトリにcredentialsというファイル名で格納されています。

 C:\\User\\<ユーザー名>\\.aws\\ 

AWS CLIの基本操作

基本操作：高レベルコマンド

高レベルコマンドの高レベルはレイヤーのイメージです。よりユーザー（アプリケーション）に近いインターフェースの操作を意味しています。使用難易度が高レベルではなく、コマンドそれ自体がユーザーに近くて高レベルということのようです。

下記のバケット、プレフィックス、ローカルディレクトリをコマンド例に使って説明します。

重要なTipsとして、上記のコマンドを仮で実行できる--dryrun というオプションがあります。--dryrun で実行すれば、実行せずに想定結果が返ってくるので、--dryrunで想定結果を確認してから実行する習慣を身に着けるのが良いです。

コマンド実行の正否の判断：リターンコード

リターンコードとは、aws cliコマンドの実行結果の正否を示すコードです。
ターミナル上で直にコマンドを実行する場合などは、エラーメッセージが画面に表示されるのでコマンドの正否が一目瞭然です。
しかし、バッチとして日次システムに組み込む際はターミナル自体を開いていないケースがほとんどかと思います。なのでリターンコードで実行の正否を確認することになります。aws cliコマンドが正常に行われる前提のシステムの設計の仕方もあるかもしれませんが、エラーがどのステップで生じたかログに明示的に記録されるようにするためにリターンコードを用いたバリデーションをした方が良いでしょう。

aws cliコマンドが実行された後に返されるリターンコードですが、Windows PowerShellにおいては$LASTEXITCODEという変数に格納されています。aws cliコマンド実行後のスクリプトで、$LASTEXITCODE == 0 であれば正常終了となります。
それ以外の値であれば何かしらのエラーで正常に実行されていない可能性があります。リターンコードの値の意味は下記のリンクの通りです。

AWS CLI からのリターンコード：https://docs.aws.amazon.com/ja_jp/cli/latest/userguide/cli-usage-returncodes.html

バッチ処理のスクリプト作成

最後にバッチスクリプトの作成についてです。

上記の基本的なコマンドだけで簡易的なバッチ処理を実装できます。例えば下記のようなファイル操作をスクリプトで実現できます。

処理実行手順

1. S3プレフィックス（ディレクトリ）やローカルディレクトリを変数に定義
2. S3のsyncフォルダからLocalのsyncフォルダに差分のファイルを同期
3. 同期完了を確認したのち、S3のbackupフォルダに当日のyyyyMMddのフォルダにコピーをバックアップ

解説

S3のsyncフォルダには日次でdaily_file.csvが連携され、週次、月次でそれぞれweekly_file.csv、monthly_file.csvが連携されるようになっている。連携されたファイルのみをLocalのsyncフォルダにダウンロードし、バックアップはS3で持つようなシステム。

# Windows PowerShellでのバッチ処理(ps1ファイル)

<# 変数定義 #>
# 本日日付
$currentDate = (Get-Date).ToString("yyyyMMdd")
# s3プレフィックス
$s3HomeDir = "s3://my-bucket/"
$s3SyncDir = -join ($s3HomeDir, "sync")
$s3backupDir = -join ($s3HomeDir, "backup")
$s3backupCurrentDir = -join ($s3backupDir, $currentDate)
#  Localディレクトリ
$localHomeDir = "C:\\Program Files"
$localSyncDir = Join-Path $localHomeDir "sync"
<# 変数定義ここまで #>

# 日次処理開始宣言
Write-Host "日次処理を開始します。"

try{
	# S3のsyncフォルダとLocalのsyncフォルダと同期(1)
	aws s3 sync $s3SyncDir $localSyncDir --exact-timestamps

	# aws s3 syncコマンドのバリデーション
	if ($lastexitcode -ne 0) {
		throw "Aws Cli Execution Error. Return Code: ${lastexitcode}"
	}
	
	# S3のbackupフォルダにS3のsyncフォルダの中のファイルをコピー(2)
	aws s3 cp $s3SyncDir $s3backupCurrentDir --recursive
	
	# aws s3 cpコマンドのバリデーション
	if ($lastexitcode -ne 0) {
		throw "Aws Cli Execution Error. Return Code: ${lastexitcode}"
	}
}catch{
	Write-Output "An Error Occured"
	Write-Output $_
}

# 正常終了
Write-Host "日次処理を完了しました。"
exit 0

上記の図のような簡易的なファイルの受け渡しであれば、高レベルコマンドだけで実現できます。
ファイル名のサフィックスやメタ情報を利用して判定・フィルタ処理を行う場合は、--exclude、--include や--query などの少しだけ込み入ったオプションを使う必要があったり、APIレベルのコマンドを使用する必要があったりします。
そちらについては後日記事化していきます。

おわりに

AWS CLIの設定から基本操作まで一通り説明しました。私がAWS CLIを初めて使ったときは、右も左もわからない状態だったので上記の簡易的なバッチ処理を書くのも苦労しました。結構当たり前のところで躓いてエラーを出していたりしたので、そういう当たり前のこともちゃんと記載してみました。

AWS CLIを以後使う方が同じような苦しみに合わずに、この記事で躓きポイントをうまく超えていただければ書いた甲斐があったというものです。

参考リンク

• aws configureについての詳細設定方法の参考 【AWS】CLIの初期設定について（認証情報とコマンド補完） – TASK NOTES
• AWS CLI リターンコード AWS CLI からのリターンコード – AWS Command Line Interface
• aws s3 高レベルコマンドリファレンス

この記事を書いた人

竹中 亨彰
（たけなか ともあき）

株式会社UNCOVER TRUTH
ビジネスデベロップメントグループ DX-Acceleratorチーム
2022年、UNCOVER TRUTHに中途入社。
アパレル会社の分析支援、パートナー会社にてデータパイプライン構築支援業務を経験。
よく使うツールはTableau、Bigquery。