Rust で Microsoft Azure にファイルをエクスポート
この完全な Rust プログラムで、最大 16 MiB のローカルファイルを既存の非公開 Azure Blob Storage コンテナーにアップロードします。条件付きリクエストを一度だけ送信し、既存の Blob の置き換えを拒否します。空のファイルやバイナリデータも入力できます。
これは、非公式の azure_storage_blobs クレート 0.21.0 を使った保守用の例です。Microsoft のレガシークレートに関する告知では、このクレートを更新する予定はないとしています。新規アプリケーションでは、公式の azure_storage_blob SDKを検討してください。その認証例では Microsoft Entra ID を使用しています。このバージョン固定の例とは API が異なるため、依存関係の名前を変えるだけでは移行できません。
前提条件
- Bash、Rust、Cargo、および Rust のインストール環境に必要なシステムリンカーを備えた Linux シェル。この例は、Rust と Cargo 1.98.1、2021 エディションでテストしています。これはテスト済みの環境であり、コンパイラーの最低要件ではありません。現行ツールチェーンのインストール方法は、Rust インストールガイドを参照してください。
- C コンパイラー、
pkg-config、OpenSSL のライブラリとヘッダー。Linux では、デフォルトの TLS トランスポートにこれらが必要です。OpenSSL クレートのビルドガイドに、一般的なディストリビューションで必要なパッケージが記載されています。プロジェクトを作成する前に、これらをインストールしてください。 - Shared Key 認証をすでに許可している Azure Storage アカウントと、そのアカウント名およびアクセスキー。この方法は、既存の Shared Key 連携を対象としています。新規アプリケーションには Microsoft が Microsoft Entra ID を推奨しています。この例を試すためだけに Shared Key を有効にしないでください。
- 別途作成済みの、既存の非公開コンテナー。このプログラムはコンテナーの作成も、アクセス設定の変更も行いません。非公開コンテナーの Blob を読み取るには認可が必要です。詳しくは、Azure の匿名アクセスに関するドキュメントを参照してください。
- アップロード中に変更されない、完全な通常ファイル。ローカルパスを含むコマンド引数は、有効な UTF-8 である必要があります。この例は並列実行せず、順次実行してください。
プロジェクトのセットアップ
書き込み可能なディレクトリから実行してください。次のブロックはビルドツールを確認し、新しいディレクトリを作成します。azure_export がすでに存在する場合は、そのプロジェクトに移動することも変更することもなく停止します。
(
command -v cargo >/dev/null &&
command -v rustc >/dev/null &&
command -v cc >/dev/null &&
command -v pkg-config >/dev/null &&
pkg-config --exists openssl &&
mkdir azure_export &&
mkdir azure_export/src
) && cd azure_export
成功した場合にのみ、先に進んでください。以下を Cargo.toml として保存します。空の [workspace] により、このプロジェクトを親の Cargo ワークスペースから分離します。Tokio のファイルシステム機能と I/O 機能は明示的に指定しています。解決済みの推移的依存関係を維持するため、生成された Cargo.lock をアプリケーションとともに保持してください。
ディレクトリの作成が途中で失敗した場合は、再試行する前に作成済みの内容を確認してください。再試行には、新しい書き込み可能な親ディレクトリを使用します。このブロックは、意図的に既存のファイルを保持します。
[package]
name = "azure_export"
version = "0.1.0"
edition = "2021"
[workspace]
[dependencies]
azure_core = "=0.21.0"
azure_storage = "=0.21.0"
azure_storage_blobs = "=0.21.0"
tokio = { version = "=1.48.0", features = ["fs", "io-util", "macros", "rt-multi-thread", "time"] }
Azure クライアントの初期化
シークレットマネージャーまたはプロセスの環境変数を通じて、AZURE_STORAGE_ACCOUNT と AZURE_STORAGE_KEY を指定してください。キーはストレージアカウントのアクセスキーであり、接続文字列ではありません。プログラムは StorageCredentials::access_key() を呼び出し、Azure CLI のログイン情報は読み込みません。キーをソース管理やターミナルのコマンド引数に含めないでください。
以下のプログラム全体を src/main.rs として保存してください。
ファイルアップロードの実装
プログラムはリクエストを送信する前に最大 16 MiB と 1 バイトを読み取り、サイズ超過の入力を拒否します。16 MiB という上限はこの例の方針であり、Azure のストレージ上限ではありません。一度の put_block_blob 操作のために入力をバッファリングします。ファイルをステージング用のブロックに分割したり、並列アップロードしたりはしません。宛先の Blob 名は、ローカルパスとは別の引数です。
use azure_core::{prelude::IfMatchCondition, RetryOptions};
use azure_storage::StorageCredentials;
use azure_storage_blobs::prelude::{BlobServiceClient, ClientBuilder};
use std::{env, error::Error, path::Path, time::Duration};
use tokio::{fs::File, io::AsyncReadExt, time::timeout};
type AppResult<T> = Result<T, Box<dyn Error + Send + Sync>>;
const MAX_BYTES: u64 = 16 * 1024 * 1024;
async fn upload_file(
service: &BlobServiceClient,
container: &str,
blob_name: &str,
path: &Path,
) -> AppResult<()> {
if container.is_empty() || blob_name.is_empty() {
return Err("Container and blob name must not be empty".into());
}
let file = File::open(path).await?;
if !file.metadata().await?.is_file() {
return Err("Input must be a regular file".into());
}
let mut contents = Vec::new();
file.take(MAX_BYTES + 1).read_to_end(&mut contents).await?;
if contents.len() as u64 > MAX_BYTES {
return Err("Input exceeds the 16 MiB example limit".into());
}
let blob = service.container_client(container).blob_client(blob_name);
blob.put_block_blob(contents)
.content_type("application/octet-stream")
.if_match(IfMatchCondition::NotMatch("*".to_owned()))
.await?;
Ok(())
}
async fn run() -> AppResult<()> {
let args: Vec<String> = env::args().skip(1).collect();
if args.len() != 3 {
return Err("Usage: azure_export CONTAINER BLOB_NAME FILE".into());
}
let account = env::var("AZURE_STORAGE_ACCOUNT")?;
let key = env::var("AZURE_STORAGE_KEY")?;
let credentials = StorageCredentials::access_key(account.clone(), key);
let service = ClientBuilder::new(account, credentials)
.retry(RetryOptions::none())
.blob_service_client();
timeout(
Duration::from_secs(60),
upload_file(&service, &args[0], &args[1], Path::new(&args[2])),
)
.await??;
println!("Upload confirmed.");
Ok(())
}
#[tokio::main]
async fn main() {
if run().await.is_err() {
eprintln!("Upload was not confirmed; check the input, credentials, container, and destination.");
std::process::exit(1);
}
}
エクスポートするファイルを、プロジェクトディレクトリ内の data.bin に配置してください。認証情報を指定し、非公開の rust-exports コンテナーがすでに存在する状態で、次を実行します。
cargo run -- rust-exports 'exports/data.bin' './data.bin'
Cargo が依存関係を解決し、プログラムをビルドして実行します。引数は、コンテナー、宛先の Blob 名、ローカルファイルのパスの三つです。スペースを含むパスは引用符で囲んでください。リクエストが成功すると、Upload confirmed. を出力し、終了コード 0 で終了します。Blob の名前は exports/data.bin です。スラッシュは名前の一部であり、ローカルのディレクトリ構造とは無関係です。先頭や末尾にスラッシュのない Blob 名を選んでください。この SDK は、それらの文字を取り除きます。
60 秒の期限は、クライアントの構築後に行うローカルファイルの読み取りと SDK のアップロードを対象とします。Cargo による依存関係のインストールとコンパイルは対象外です。サイズ上限未満のファイルでも、低速な接続ではこの期限を超える場合があります。
エラー処理
ローカルでの読み取り失敗、設定の不足、リクエストの拒否、タイムアウトが発生すると、汎用的な診断メッセージ Upload was not confirmed を出力し、非ゼロの終了コードで終了します。認証情報や SDK の生のレスポンスは、意図的に出力しません。まずローカルファイルとそのサイズを確認し、次に選択したアカウント、キー、コンテナー、宛先を確認してください。この診断メッセージだけでは、Azure が拒否した理由は特定できず、Blob が書き込まれなかったことも証明できません。
IfMatchCondition::NotMatch("*") オプションは If-None-Match: * を送信します。Azure の条件付きヘッダーの仕様では、宛先が存在しない場合にのみ書き込みを許可します。既存の宛先に対してコマンドを再実行すると失敗し、以前の内容が保持されます。新たにエクスポートする場合は、コマンドを成功させるために既存のオブジェクトを削除するのではなく、別の Blob 名を選んでください。
SDK の再試行は無効にしています。タイムアウト、接続の切断、中断が発生した後でも、Azure はすでに受信したアップロードを完了する場合があります。ローカルプロセスを停止しても、そのリモート書き込みはキャンセルされません。むやみに再試行したり、一覧が空であることを、保留中の書き込みが後から現れない証拠とみなしたりしないでください。認証済みクライアントで該当する宛先を調べ、最初の操作の結果とリモートの状態を突き合わせてから再試行してください。後の試行が拒否された場合、最初のアップロードが成功していた可能性があります。
保存結果の確認
Upload confirmed. は、SDK がアップロードの成功レスポンスを受信したことを意味します。プログラムは Blob をダウンロードせず、保存されたバイト列も比較しません。エクスポート結果の検証が必要な場合は、認証済みクライアントでその Blob をダウンロードし、ダウンロードしたファイル全体を、変更されていない元ファイルと比較してください。元ファイルが 0 バイトの場合も同様です。名前やバイト数だけを確認しても、同じサイズで内容が異なることは検出できません。検証が完了するまでローカルの元ファイルを保持してください。
コンテナーが非公開であることは別途満たすべき前提条件であり、アップロードの成功によってアクセスポリシーが確認できるわけではありません。この例は、再開可能なアップロードにも、本番環境の転送監視・制御にも対応していません。より大きいファイルや ID ベースの認証を扱う場合は、移行の検討なしにレガシーのバージョン固定を拡張するのではなく、公式 SDK のアップロードと認証情報の例から始めてください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
