Azure CLI のファイル転送自動化とバイト単位の検証
az storage blob upload でローカルファイルを Azure Blob Storage に送信し、ダウンロードしてバイト単位で比較します。以下のスクリプトは、単一ファイルにも、ディレクトリ内のファイルにも対応します。既存の BLOB 名へのアップロードを拒否し、選択されたすべてのファイルが比較に合格した場合にのみ、バッチの完了を報告します。
インストールとセットアップ
この手順では、Linux 上の Bash と Microsoft の Azure CLI コンテナーを使用します。Azure CLI 2.91.0 で動作を検証しています。動作する Docker 環境、コンテナーを実行する権限、書き込み可能な作業ディレクトリが必要です。転送中はソースファイルを変更しないでください。転送とストレージには Azure の料金が発生するため、まずは機密情報を含まない小さなファイルで試してください。
コンテナーには Bash と Python が含まれるため、ホストに Azure CLI をインストールする必要はありません。イメージのインストールについては、Microsoft のコンテナーガイドを参照してください。検証済みのイメージを取得し、その中の CLI を確認します。
docker pull mcr.microsoft.com/azure-cli:2.91.0-azurelinux3.0 &&
docker run --rm mcr.microsoft.com/azure-cli:2.91.0-azurelinux3.0 az version
転送先と認可方式の選択
管理者から書き込みを許可された、既存のストレージアカウントと非公開の BLOB コンテナーを使用してください。新規アカウントには、Microsoft のアカウントの概要にある汎用 v2 を使用します。ここでの非公開とは、匿名での BLOB アクセスが無効であることを意味します。使用するマシンから、アカウントの Blob エンドポイントへのネットワーク接続も必要です。
この例では Shared Key 認証を使用します。管理者がこの認証を明示的に許可し、シークレットマネージャー経由でアカウント名とキーを提供する必要があります。それぞれを環境変数 AZURE_STORAGE_ACCOUNT と
AZURE_STORAGE_KEY としてエクスポートしてください。このキーはアカウントへの広範なアクセスを許可するため、スクリプト、シェル履歴、ログに残さないでください。この認可が適切な環境でのみ実行してください。
Microsoft は、利用可能な場合には
Microsoft Entra による認可を推奨しています。--auth-mode login を使用する場合、ID には BLOB データのロールが必要です。ストレージ管理のロールだけでは不十分です。このスクリプトは、提供されたキーを必須とする設計です。ログイン、アカウントキーの検索、リソースの作成、ロールの割り当ては行いません。Shared Key が無効なアカウントには、別の認証設定が必要です。
Azure CLI によるファイル転送
以下を作業ディレクトリに transfer.sh として保存してください。引数は四つあり、順にソースファイルまたはディレクトリ、既存のコンテナー名、新しい BLOB 名のプレフィックス、新しいダウンロード先ディレクトリです。コンテナーからアクセスできるよう、./input.bin や
./downloads のような、作業ディレクトリ配下の相対パスを使用してください。ダウンロード先ディレクトリの親ディレクトリは、あらかじめ存在している必要があります。
ソースのパスとファイル名は、復帰文字や改行を含まない有効な UTF-8 である必要があります。空白、リテラルのパーセント記号、#、?、先頭のハイフン、Unicode のファイル名に対応しています。プレフィックスには ASCII の小文字、数字、スラッシュ、アンダースコア、ハイフンを使用します。英字または数字で始め、空のセグメント、.、.. は避けてください。transfers/run-001 のようなプレフィックスを指定すると、リモートディレクトリを作成せずに、階層化された BLOB 名を作成できます。
#!/usr/bin/env bash
set -uo pipefail
for tool in az python3 mkdir sleep; do
command -v "$tool" >/dev/null || { printf 'Missing tool: %s\n' "$tool" >&2; exit 1; }
done
: "${AZURE_STORAGE_ACCOUNT:?Set AZURE_STORAGE_ACCOUNT}"
: "${AZURE_STORAGE_KEY:?Set AZURE_STORAGE_KEY}"
unset AZURE_STORAGE_CONNECTION_STRING AZURE_STORAGE_SAS_TOKEN AZURE_STORAGE_SERVICE_ENDPOINT
if [ "$#" -ne 4 ]; then
printf 'Usage: bash transfer.sh SOURCE CONTAINER PREFIX DOWNLOAD_DIR\n' >&2
exit 2
fi
source_path=$1
container=$2
prefix=$3
download_dir=$4
case "$source_path" in /*) ;; *) source_path="./$source_path" ;; esac
case "$download_dir" in /*) ;; *) download_dir="./$download_dir" ;; esac
if ! python3 - "$source_path" "$prefix" "$download_dir" <<'PY'
import os
import re
import sys
try:
source, prefix, destination = sys.argv[1:]
paths = [source, destination]
if os.path.isdir(source):
with os.scandir(source) as entries:
paths.extend(entry.path for entry in entries
if entry.is_file(follow_symlinks=False))
for path in paths:
os.fsencode(path).decode('utf-8')
if '\n' in path or '\r' in path:
raise ValueError()
if not re.fullmatch(r'[a-z0-9][a-z0-9/_-]*', prefix):
raise ValueError()
if any(part in ('', '.', '..') for part in prefix.split('/')):
raise ValueError()
except (OSError, UnicodeError, ValueError):
print('Check source access, UTF-8 paths, and the blob prefix.', file=sys.stderr)
sys.exit(1)
PY
then
exit 1
fi
if [ -L "$source_path" ] || { [ ! -f "$source_path" ] && [ ! -d "$source_path" ]; }; then
printf 'Source must be a regular file or directory, not a symbolic link.\n' >&2
exit 1
fi
mkdir -- "$download_dir" || exit 1
shopt -s nullglob dotglob
files=("$source_path")
if [ -d "$source_path" ]; then files=("$source_path"/*); fi
failed=0
verified=0
max_retries=3
for file in "${files[@]}"; do
[ -f "$file" ] && [ ! -L "$file" ] || continue
filename=${file##*/}
blob_name="$prefix/$filename"
uploaded=0
for ((attempt=1; attempt<=max_retries; attempt++)); do
if az storage blob upload --account-name "$AZURE_STORAGE_ACCOUNT" \
--container-name "$container" --name "$blob_name" --file "$file" \
--type block --auth-mode key --overwrite false \
--only-show-errors --output none >/dev/null 2>&1; then
uploaded=1
break
fi
if [ "$attempt" -lt "$max_retries" ]; then sleep 5; fi
done
if [ "$uploaded" -eq 0 ]; then
printf 'Upload refused or failed: %s\n' "$filename" >&2
failed=$((failed + 1))
continue
fi
downloaded_file="$download_dir/$filename"
if ! az storage blob download --account-name "$AZURE_STORAGE_ACCOUNT" \
--container-name "$container" --name "$blob_name" --file "$downloaded_file" \
--auth-mode key --overwrite false --only-show-errors --output none >/dev/null 2>&1; then
printf 'Download failed: %s\n' "$filename" >&2
failed=$((failed + 1))
continue
fi
if ! python3 - "$file" "$downloaded_file" <<'PY'
import filecmp
import sys
sys.exit(0 if filecmp.cmp(sys.argv[1], sys.argv[2], shallow=False) else 1)
PY
then
printf 'Byte comparison failed: %s\n' "$filename" >&2
failed=$((failed + 1))
continue
fi
printf 'Verified: %s\n' "$filename"
verified=$((verified + 1))
done
printf 'Verified %s file(s); failed %s.\n' "$verified" "$failed"
if [ "$failed" -ne 0 ]; then exit 1; fi
printf 'Transfer complete\n'
ファイルのアップロード
保存したスクリプトと同じディレクトリに、input.bin という名前のファイルを置いてください。二つの認証情報の変数をエクスポートした状態で、your-container を既存のコンテナー名に置き換え、未使用のプレフィックスを選んで、次を実行します。
docker run --rm --user "$(id -u):$(id -g)" \
--env HOME=/tmp --env AZURE_CONFIG_DIR=/tmp/azure \
--env AZURE_CORE_COLLECT_TELEMETRY=no \
--env AZURE_STORAGE_ACCOUNT --env AZURE_STORAGE_KEY \
--mount "type=bind,source=$PWD,target=/work" --workdir /work \
mcr.microsoft.com/azure-cli:2.91.0-azurelinux3.0 \
bash transfer.sh ./input.bin your-container transfers/run-001 ./downloads
実行後にコンテナーは終了します。アップロードした BLOB は Azure に残り、ダウンロードしたファイルは作業ディレクトリに残ります。--user オプションにより、ダウンロードしたファイルの所有者は使用中の Linux ユーザーのままになります。
ファイルのダウンロード
スクリプトの az storage blob download は、アップロード時と完全に同じ BLOB 名を指定して取得し、Python がダウンロード全体をローカルのソースと比較します。単一ファイルの処理が成功すると、Verified: input.bin、続いて Verified 1 file(s); failed 0. と Transfer complete が出力されます。空のファイルも有効です。アップロードに成功しても、その後のダウンロードや比較に失敗すると、ゼロ以外のステータスを返し、調査できるようリモートの BLOB を残します。
どちらの転送も --overwrite false を明示的に使用します。アップロードのリファレンスとダウンロードのリファレンスを参照してください。また、ダウンロード先ディレクトリがすでに存在する場合、スクリプトは Azure に接続する前に処理を拒否します。再実行するには、新しいプレフィックスとダウンロード先ディレクトリを選んでください。新しいダウンロード先ディレクトリを指定しても、BLOB 名を再利用すると、既存の BLOB を置き換えずに失敗します。これは意図した動作です。このスクリプトは、既存データの置き換えやロールバックを実装していません。
Azure CLI によるファイルのバッチ転送自動化
./input にファイルを置き、そのディレクトリを最初の引数に指定して、同じスクリプトを実行します。
docker run --rm --user "$(id -u):$(id -g)" \
--env HOME=/tmp --env AZURE_CONFIG_DIR=/tmp/azure \
--env AZURE_CORE_COLLECT_TELEMETRY=no \
--env AZURE_STORAGE_ACCOUNT --env AZURE_STORAGE_KEY \
--mount "type=bind,source=$PWD,target=/work" --workdir /work \
mcr.microsoft.com/azure-cli:2.91.0-azurelinux3.0 \
bash transfer.sh ./input your-container transfers/batch-001 ./batch-downloads
この実行では、隠しファイルを含め、./input の直下にある通常ファイルを選択します。サブディレクトリとシンボリックリンクはスキップし、再帰的には処理しません。選択された各ファイル名は、その BLOB 名の最後のセグメントと、ローカルのダウンロードファイル名になります。空のディレクトリでは、検証済みファイル数がゼロのまま完了します。想定より少ない場合は、出力された件数を確認してください。
転送は順次実行します。各アップロードでの CLI 呼び出しは最大三回で、失敗後に五秒待ってから再試行します。CLI 自体によるサービスへの再試行は、これに加わります。ダウンロードでの CLI 呼び出しは一回です。最終件数には、その後のファイルが成功しても、アップロード、ダウンロード、比較のすべての失敗が含まれます。一部のみ成功したバッチはゼロ以外のステータスで終了し、成功した BLOB とダウンロードを残します。この結果に対して Transfer complete を出力することはありません。
よくある問題のトラブルシューティング
認証情報の変数が不足している場合、スクリプトはダウンロード先ディレクトリを作成する前に停止します。アップロードが拒否された場合は、選択したアカウント、コンテナー、キーによる認可、ネットワーク経路を管理者と確認してください。スクリプトは対象のファイル名を報告しますが、認証情報や署名付き URL が出力に含まれないよう、CLI の診断情報をそのまま出力することはありません。
アップロードの失敗は、BLOB 名がすでに存在することを意味する場合もあります。三回拒否されたからといって、安全に置き換えられるわけではありません。応答が失われると、コマンドが失敗してもコミット済みの BLOB が残る場合があります。再試行する前に、その正確な名前の BLOB を確認してください。拒否を回避するために上書きポリシーを変更せず、別のコピーには未使用のプレフィックスを使用してください。
ダウンロードや比較に失敗した場合は、残された BLOB とローカルのダウンロードを個別に確認してください。元のソースは変更せずに保持してください。スクリプトは、不完全なダウンロードの削除、成功したアップロードの取り消し、アカウントの保持設定の変更を行いません。後片付けは、その実行で使用した正確な BLOB 名を基に、リソースの所有者と調整してください。
次のステップ
CLI の自動化ではなく HTTP リクエストを直接使用する場合は、cURL による Azure へのファイルのエクスポートを参照してください。これは別の REST ワークフローであり、そこで使用する認証やアップロードプログラムは、ここでは必要ありません。
