オープンソースで .NET から Backblaze B2 にファイルをエクスポート
オープンソースの AWS SDK for .NET で、ローカルファイルを既存の B2 バケットにエクスポートします。この完全なコンソールプログラム例は B2 の S3 互換 API を使用し、最大 64 MiB のファイルを受け付け、保存したオブジェクトを読み戻してから成功を報告します。空のファイルも有効な入力です。
Backblaze B2 クラウドストレージの概要
B2 はネイティブ API と S3 互換 API に対応しています。ここでは後者を使用し、S3 バケット名と AWS SDK のリクエスト署名を利用します。AWS アカウントは不要です。
Backblaze B2 アカウントの設定
既存の非公開バケットと、そのバケットにアクセスを制限した専用のアプリケーションキーを使用します。必要に応じてエクスポート用プレフィックスにも制限します。この例では PUT に writeFiles、GET による検証に
readFiles が必要です。バケットの S3 エンドポイントとリージョンを記録します。アクセスキーにはアプリケーションのキー ID、シークレットにはアプリケーションキーを使用します。アカウント ID はキー ID の代わりにはなりません。S3 互換 API にはマスターキーではなく、標準のアプリケーションキーを使用します。これらの制限については、Backblaze のアプリケーションキーガイドで説明されています。
必要な .NET ライブラリのインストール
メンテナンスされている .NET 10 SDK をインストールします。以下のコマンドは Linux 上の Bash を使用し、SDK 10.0.111 でテストしています。SDK には常にパッチを適用してください。.NET 10 は LTS リリースです。パッケージバージョンは、この例でテストした AWS SDK v4 の組み合わせに固定しています。
既存の .NET プロジェクトツリーの外にある、書き込み可能なディレクトリで開始します。このブロックは、継承されるプロジェクト設定や既存の B2Export
ディレクトリがある場合に処理を拒否し、インストールに失敗してもシェルを元のディレクトリに保ちます。
(
command -v dotnet >/dev/null || { printf 'Install the .NET 10 SDK first.\n' >&2; exit 1; }
parent="$PWD"
while :; do
for config in "$parent"/global.json "$parent"/[Dd]irectory.[Bb]uild.* \
"$parent"/[Dd]irectory.[Pp]ackages.props "$parent"/[Nn]u[Gg]et.[Cc]onfig; do
if [ -e "$config" ]; then
printf 'Choose a directory outside an existing .NET project tree.\n' >&2
exit 1
fi
done
[ "$parent" = / ] && break
parent="${parent%/*}"
[ -n "$parent" ] || parent=/
done
mkdir B2Export && cd B2Export &&
dotnet new console --framework net10.0 --name B2Export --output . &&
dotnet add package AWSSDK.Core --version 4.0.102.11 &&
dotnet add package AWSSDK.S3 --version 4.0.104.4
)
.NET での Backblaze B2 API 認証
シークレットマネージャーまたはローカルの起動設定を通じて、プログラムのプロセス環境に以下の変数を設定します。アプリケーションキーをソースファイルやコマンド引数に含めないでください。
| 変数 | 値 |
|---|---|
B2_ENDPOINT | リージョンのエンドポイント(例:https://s3.us-west-004.backblazeb2.com) |
B2_REGION | 対応するリージョン(例:us-west-004) |
B2_BUCKET | 既存のバケット名 |
B2_KEY_ID | アプリケーションキー ID |
B2_APPLICATION_KEY | アプリケーションキー |
B2_OBJECT_KEY | 下記コマンドの保存先キー(例:reports/report #1.txt) |
B2_TIMEOUT_SECONDS | 操作全体の制限時間(任意)。1–300 秒、デフォルトは 300 秒 |
以下では認証情報を明示的に指定するため、SDK は AWS プロファイルやインスタンスメタデータを検索しません。Backblaze のドキュメントにキーの対応関係と SDK 設定が記載されています。
C# による Backblaze B2 へのファイルアップロード
B2Export/Program.cs を、この完全なプログラムで置き換えます。オブジェクトキーはローカルファイル名とは別に指定します。空白、Unicode、予約文字を
SDK がエンコードできるよう、エスケープせずに渡してください。ローカルパスは有効な UTF-8 で、置換文字 � を含んでいてはいけません。このガードにより、Linux でファイル名の変換時に情報が失われ、別のファイルが選択されることを防ぎます。
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;
public static class B2Exporter
{
public static async Task<int> Main(string[] args)
{
using var deadline = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; deadline.Cancel(); };
try
{
if (args.Length != 2) throw new ArgumentException("Pass a local file and an object key.");
if (args[0].Contains('\uFFFD')) throw new ArgumentException("Unsupported local filename.");
var seconds = Environment.GetEnvironmentVariable("B2_TIMEOUT_SECONDS") ?? "300";
if (!int.TryParse(seconds, out var timeout) || timeout < 1 || timeout > 300)
throw new ArgumentException("B2_TIMEOUT_SECONDS must be between 1 and 300.");
deadline.CancelAfter(TimeSpan.FromSeconds(timeout));
var endpoint = new Uri(Required("B2_ENDPOINT"));
if (endpoint.Scheme != "https" || endpoint.UserInfo.Length != 0 ||
endpoint.AbsolutePath != "/" || endpoint.Query.Length != 0 || endpoint.Fragment.Length != 0)
throw new ArgumentException("Use the HTTPS regional endpoint without a bucket or path.");
var config = new AmazonS3Config
{
ServiceURL = endpoint.AbsoluteUri,
AuthenticationRegion = Required("B2_REGION"),
ForcePathStyle = true,
RetryMode = RequestRetryMode.Standard,
MaxErrorRetry = 2,
RequestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED,
ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED
};
using var client = new AmazonS3Client(
Required("B2_KEY_ID"), Required("B2_APPLICATION_KEY"), config);
var bucket = Required("B2_BUCKET");
var version = await UploadAsync(client, bucket, args[0], args[1], deadline.Token);
await VerifyAsync(client, bucket, args[0], args[1], version, deadline.Token);
Console.WriteLine("Uploaded and verified.");
return 0;
}
catch (OperationCanceledException) { Console.Error.WriteLine("Upload canceled or timed out."); }
catch (AmazonS3Exception error) { Console.Error.WriteLine($"Storage returned HTTP {(int)error.StatusCode}."); }
catch (Exception) { Console.Error.WriteLine("Upload failed. Check the file and storage configuration."); }
return 1;
}
private static string Required(string name) =>
Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
? value : throw new ArgumentException($"Missing {name}.");
public static async Task<string?> UploadAsync(IAmazonS3 client, string bucket, string path,
string key, CancellationToken cancellationToken)
{
if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("An object key is required.");
await using var input = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read);
if (input.Length > 64L * 1024 * 1024) throw new IOException("This example accepts at most 64 MiB.");
var uploaded = await client.PutObjectAsync(new PutObjectRequest
{
BucketName = bucket,
Key = key,
InputStream = input,
AutoCloseStream = false,
ContentType = "application/octet-stream",
UseChunkEncoding = false
}, cancellationToken);
return uploaded.VersionId;
}
private static async Task VerifyAsync(IAmazonS3 client, string bucket, string path,
string key, string? version, CancellationToken cancellationToken)
{
using var stored = await client.GetObjectAsync(new GetObjectRequest
{
BucketName = bucket,
Key = key,
VersionId = version
}, cancellationToken);
await using var input = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read);
if (stored.ContentLength != input.Length) throw new IOException("Stored length differs.");
var local = new byte[64 * 1024];
var remote = new byte[64 * 1024];
int count;
while ((count = await input.ReadAsync(local, cancellationToken)) != 0)
{
await stored.ResponseStream.ReadExactlyAsync(remote.AsMemory(0, count), cancellationToken);
if (!local.AsSpan(0, count).SequenceEqual(remote.AsSpan(0, count)))
throw new IOException("Stored bytes differ.");
}
if (await stored.ResponseStream.ReadAsync(remote.AsMemory(0, 1), cancellationToken) != 0)
throw new IOException("Stored object has extra bytes.");
}
}
アプリケーションへの Backblaze アップロードの組み込み
B2Export を作成したディレクトリで実行します。最初のコマンドは小さな入力ファイルを作成し、既存の report.txt がある場合は上書きを拒否します。
(set -C; printf 'example export\n' > report.txt) &&
dotnet run --disable-build-servers --project B2Export -- ./report.txt "${B2_OBJECT_KEY:-}"
終了ステータスがゼロで、Uploaded and verified. と表示された場合、PUT が完了し、ダウンロードしたバイト列がローカルファイルと一致したことを意味します。GET では、返されたバージョン ID が利用できる場合にそれを使用します。検証時はファイル全体をメモリに保持せず、64 KiB 単位で読み取ります。ただし、SDK 自体のバッファーに数値的な上限を設けるものではありません。プロセスが終了するまで入力を変更しないでください。
UploadAsync は IAmazonS3 インスタンスとキャンセルトークンを受け取るため、アプリケーションでクライアントを再利用し、リクエストのキャンセルを伝播できます。クライアントの所有権は呼び出し元にあります。このメソッドは成功時も失敗時もファイルストリームを閉じます。UploadAsync だけでは、後続の検証は実行されません。
トラブルシューティングとベストプラクティス
設定した標準のリトライポリシーでは、SDK リクエストごとに最大 2回のリトライが許可されます。制限時間にはアップロード、リトライ、読み戻しのすべてが含まれるため、有効なファイルでも低速な接続では失敗することがあります。Ctrl+C、タイムアウト、ストレージによる拒否、バイトの不一致が発生すると、終了ステータスとして 1 を返します。SDK のリトライとキャンセルのドキュメントを参照してください。
HTTP で拒否された場合は、エンドポイント、対応するリージョン、キー ID、キーのシークレット、バケット、プレフィックス、読み取りと書き込みの権限を確認してください。診断情報にはプロバイダーのレスポンス本文とシークレットを含めません。GET が失敗しても、アップロード済みのデータが残ることがあります。PUT がキャンセルされた場合も、リモート側の結果が不確定になることがあります。何も保存されていないと想定せず、再試行の前にバケットを確認してください。
この例では、空のファイルも含め、マルチパートアップロードではなくストリーミング PUT リクエストを使用します。より大きなエクスポートには、SDK のマルチパート機能を使用し、中断されたマルチパートアップロードのクリーンアップも計画してください。チェックサム設定では、SDK が必須と判断するチェックサムのみを要求します。明示的な読み戻しにより、任意のチェックサムヘッダーとは独立してバイト列を検証します。HTTPS とリクエスト署名は引き続き有効です。
同じキーに再度アップロードすると、別の B2 ファイルバージョンが作成されます。置き換えを意図しない場合は、エクスポートごとに新しいキーを使用してください。テストデータを完全に削除するには、対象キーのすべてのバージョンと非表示マーカーを削除します。現在のファイルを非表示にするだけでは履歴が残ります。このプログラムはエクスポートしたオブジェクトを保持し、そのクリーンアップは管理しません。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
