S3にオブジェクト（ファイル）が存在するか否かシェルスクリプトで確認する〜提案実装と、行き着くまでの回り道〜

はじめに

YAPC::Kyotoのチケット、2/3(金)までの販売に延長！¹ nikkieです。

S3にオブジェクトがあるかどうかをシェルスクリプトで確認する方法を考えてみました。
現時点の暫定解としてアウトプットします。
シェルスクリプトやAWSに関しては伸びしろ豊富と思いますので、フィードバックは大歓迎です。

はじめに
目次
実現したいこと
素振り準備
参考実装とその読み解き
提案実装（S3にオブジェクトがあるかどうかを確認する方法暫定解）
- aws s3 lsの終了コード
- 終了コードの扱い（set +eの理由）
供養したい実装
終わりに
（2023/05/02 追記）set +eが実は不要なことを教えていただく

実現したいこと

S3のオブジェクト（今回はファイルに限定します）のURIが手元にあります（s3://で始まるURIです）。
このURIが指すオブジェクト（ファイル）があるかどうかをシェルスクリプトで知りたいという状況です。
ここでは詳しく立ち入りませんが、存在有無に応じて後く処理を分岐させることを考えていました。

素振り準備

LocalStackで環境構築

Dockerを使ってローカル環境にS3を用意します。
以下の記事のPython スクリプトを使って、s3://awesome/foo/bar.txtを置きました。

docker runの出力には以下のバージョン記載がありました。

LocalStack version: 1.3.2.dev
LocalStack build date: 2023-01-28
LocalStack build git hash: 63e357fb

AWS CLIの設定

コマンドラインからAWSのサービスを操作するのにAWS CLIを使います。
インストールはこちらを参考にしました。

aws configureでLocalStack用のprofileを用意します²。

高速セットアップ - AWS Command Line Interface

$ aws configure --profile localstack
AWS Access Key ID [None]: dummy
AWS Secret Access Key [None]: dummy
Default region name [None]: us-east-1
Default output format [None]: json

使ったCLIのバージョンは以下です。

$ aws --version
aws-cli/2.1.30 Python/3.8.8 Darwin/18.7.0 exe/x86_64 prompt/off

準備できました！

$ aws --profile localstack --endpoint-url http://localhost:4566 s3 ls s3://awesome/foo/
2023-01-31 19:53:33         11 bar.txt

参考実装とその読み解き

以下を参考にしました。

aws s3 ls --sumの結果を取得
grepでオブジェクトの数を確認
- grep -sq 'Total Objects: 0'：URIで指定したディレクトリにオブジェクトがないことを検出
- -qは見つかった行を標準出力に書き出さない指定³
- -sはエラーメッセージを表示しない指定

提案実装（S3にオブジェクトがあるかどうかを確認する方法暫定解）

exist_or_not.sh

#!/usr/bin/env bash
set -euo pipefail

file_uri=$1
set +e
aws --profile localstack --endpoint-url http://localhost:4566 s3 ls ${file_uri} > /dev/null
ls_code=$?
set -e

if [ ${ls_code} -eq 0 ]; then
  echo "${file_uri} はあります"
else
  echo "${file_uri} はありません"
fi

オブジェクトが存在するURIs3://awesome/foo/bar.txtと、オブジェクトが存在しないURIs3://awesome/foo/baz.txtを渡して実行してみます。

$ ./exist_or_not.sh s3://awesome/foo/bar.txt
s3://awesome/foo/bar.txt はあります

$ ./exist_or_not.sh s3://awesome/foo/baz.txt
s3://awesome/foo/baz.txt はありません

`aws s3 ls`の終了コード

ドキュメントで見つけられなかったのですが、URIで指定したオブジェクトがない場合、aws s3 lsの終了コードは1になるようです⁴。

$ aws --profile localstack --endpoint-url http://localhost:4566 s3 ls s3://awesome/foo/bar.txt
2023-01-31 19:53:33         11 bar.txt
$ echo $?
0

$ aws --profile localstack --endpoint-url http://localhost:4566 s3 ls s3://awesome/foo/baz.txt
$ echo $?
1

これを利用して、aws s3 lsの終了コードで処理を分岐しました。

終了コードの扱い（`set +e`の理由）

単にaws s3 lsだけを使って実装したスクリプトは、ファイルが存在するときは期待通り動きますが、ファイルが存在しないときにはechoされません。
set -eにより、コマンドの終了コードが0以外だと、そこでスクリプトが終了する⁵ためです。

aws s3 lsでスクリプトが終了しないよう、set +eと書いて、set -eを一時的に無効にしています。

供養したい実装

実はこのエントリを書き始めた時点でのexist_or_not.shは以下の実装でした。
diffのシンタックスハイライトを利用して、大きく違うところを強調しています。

#!/usr/bin/env bash
set -euo pipefail

file_uri=$1
set +e
+ls_output=$(aws --profile localstack --endpoint-url http://localhost:4566 s3 ls ${file_uri} --sum)
+echo "${ls_output}" | grep -sq 'Total Objects: 1'
+grep_code=$?
set -e

if [ ${grep_code} -eq 0 ]; then
  echo "${file_uri} はあります"
else
  echo "${file_uri} はありません"
fi

エントリを書いているうちにaws s3 lsの終了コードだけで判定できることに気付き、その方が実装が簡潔になるので差し替えました。
この実装に至るまでに調べたことを以下にアウトプットしておきます。

`aws s3 ls --sum`

--sumは--summarizeオプションです。

Displays summary information (number of objects, total size). （aws s3 lsのドキュメントより引用）

summary information（要約情報。「Total Objects」「Total Size」のこと）が表示されるようになります。

$ aws --profile localstack --endpoint-url http://localhost:4566 s3 ls s3://awesome/foo/bar.txt --sum
2023-01-31 19:53:33         11 bar.txt

Total Objects: 1
   Total Size: 11

ドキュメントの「Example 5: Summarizing all prefixes and objects in a bucket」も参考になりました。

`grep`

aws s3 ls --sumの結果の文字列をgrepで検索します。
存在しないオブジェクトのURIを指定したときも--sumオプションにより要約情報は表示されます。

$ aws --profile localstack --endpoint-url http://localhost:4566 s3 ls s3://awesome/foo/baz.txt --sum

Total Objects: 0
   Total Size: 0

そこで（ここではオブジェクトはファイルの想定なので）、aws s3 ls --sumの結果に

「Total Objects: 1」があれば、URIで指定したオブジェクト（ファイル）が存在する
なければ、URIで指定したオブジェクトが存在しない

と判定することにしました。

`set +e`

ここまでの要素で実装したスクリプトは、ファイルが存在するときは期待通り動きますが、ファイルが存在しないときにはechoされませんでした。
これはaws s3 lsとgrepの終了コードによります。

URIに対応するオブジェクトが存在しないときaws s3 lsは終了コード1となります。
set -eによりエラーが送出されたらスクリプトを終了します。

また、grepも検索語句が見つからなかったときに終了コードが1となります。

選択される行が見つかったときの終了ステータスは 0 であり、見つからなかったときは 1 であり、エラーが起きた場合は 2 です。

Man page of GREP

grepの終了コードは行が見つかったか否かを表すことを知り、これを判定ロジックで使いたいと考えました。

終了コードをまとめると以下のようになります⁶。

ファイル有無	`aws s3 ls`の終了コード	`grep`の終了コード
あり	0	0
なし	1	1

ファイルがない場合、aws s3 lsもgrepも終了コードは0でありません。
aws s3 lsやgrepでスクリプトが終了しないよう、set +eを使っています。

終わりに

S3にオブジェクト（ファイル）が存在するか否か確認するスクリプトについてアウトプットしました。
aws s3 lsの終了コードを使う考えです。
またこの実装に至るまでにaws s3 ls --sumやgrepを調べた回り道もアウトプットしました。

（2023/05/02 追記）set +eが実は不要なことを教えていただく

そうか、if文の条件の部分では終了コードしか見ない（シェルスクリプトが落ちることはない）のか！
arterminalさん、ありがとうございます！

シェルの方に関してコメントです🤗現在の実装でも問題ないと思いますので、聞き流してもらっても大丈夫です！
setを設定し直すのはちょっと面倒なので、自分だったら「aws … 」のコマンドを直接 if の条件式に突っ込むかなあと思いました
— NP (@arterminal) 2023年2月2日

ただ、条件式が頭でっかちになって美しくないので、コマンドラインを一度変数に入れるかもしれん。つまり以下のようになります
…
cmd="aws（略）${file_uri}"
if $cmd > /dev/null; then
…

※if構文の本質はコマンドの終了ステータスによる分岐です。「［」も実はコマンドなんですよね🤗
— NP (@arterminal) 2023年2月2日

> if構文の本質はコマンドの終了ステータスによる分岐

なるほど！💡
set +e不要にできるんですね！！

なぎPさんの実装は行数少なく美しいと思いますし、この書き方を教えていただき、めちゃめちゃ学びになりました🙌
誠にありがとうございます！
— nikkie にっきー (@ftnext) 2023年2月2日

リンク先にありますが、売り切れも近いそうです。お早めに！↩
LocalStackを使ってローカル環境でS3を立ち上げ、Lambdaでファイルをアップロードしてみた - Qiita を参考にしました↩
『マスタリングLinuxシェルスクリプト第2版』8.1によると> /dev/nullと同じです↩
ドキュメントに記載がない情報を使うのは反対という立場も全然あると思います。私は「lsコマンドの終了コードと似ているし、突然実装も変わりづらいだろうから利用しちゃえ」と考えました↩
set -eはエラーが送出されたらそれをハンドルしてから終了するシェルスクリプトの書き方を理解しました（set -e, trap, exit） - nikkie-ftnextの日記で完全に理解しました↩
この表を書いたのが簡潔な実装に気付くきっかけとなりました↩