.NET(C#)で DigitalOcean Spaces にファイルをエクスポート
AWS SDK for .NET を使い、ローカルファイルを非公開の DigitalOcean Space にアップロードした後、ダウンロードして長さと SHA-256 ハッシュを比較します。以下のプログラムは空のファイルと最大 64 MiB のファイルを受け付け、検証後にのみ成功を報告します。
DigitalOcean Spaces の S3 互換性
Spaces は S3 API のサブセットを実装しています。既存の Space に対して、リージョン別エンドポイント、署名リージョン、Spaces の認証情報を明示的に設定します。この例ではパス形式のリクエストを使うため、エンドポイントにはリージョンを含めますが、バケット名は含めません:https://fra1.digitaloceanspaces.com。
既存の非公開 Space と、そのオブジェクトへの書き込みと読み取りができる Spaces キーが必要です。バケットポリシーのないバケットでは、DigitalOcean は Read/Write/Delete 権限を持つバケットスコープのキーをサポートしています。制限付きキーはバケットポリシーと併用できません。Spaces のアクセス管理を参照してください。DigitalOcean API トークンは、このプログラムで使う Spaces のキーペアとは異なります。この手順では、パブリック読み取りポリシーのない非公開バケットを前提とします。
必要な NuGet パッケージのインストール
シェルコマンドは Linux 上の Bash を使います。ランタイムだけでなく、現行の .NET 10 SDK をインストールしてください。この例は SDK 10.0.402 とランタイム 10.0.13 でテスト済みです。以下のパッケージバージョンは、再現可能なセットアップのために AWS SDK v4 を固定しています。テスト済みのバージョンであり、本質的な最小要件ではありません。
既存の .NET プロジェクトの外にある、書き込み可能なディレクトリで開始してください。このブロックは、既存の SpacesExport ファイルや、SDK の選択、ビルド、パッケージのインストールを変更しうる上位ディレクトリの設定がある場合、処理を拒否します。セットアップに成功すると新しいプロジェクトに移動し、失敗するとシェルは元のディレクトリに残ります。
(
command -v dotnet >/dev/null 2>&1 || { printf 'Install the .NET 10 SDK first.\n' >&2; exit 1; }
parent=$PWD
while :; do
for config in "$parent/global.json" "$parent"/Directory.Build.* \
"$parent/Directory.Packages.props" "$parent"/[Nn][Uu][Gg][Ee][Tt].[Cc][Oo][Nn][Ff][Ii][Gg]; do
if [ -e "$config" ]; then
printf 'Use a directory outside existing .NET configuration.\n' >&2
exit 1
fi
done
[ "$parent" = / ] && break
parent=${parent%/*}
[ -n "$parent" ] || parent=/
done
[ ! -e SpacesExport ] || { printf 'SpacesExport already exists.\n' >&2; exit 1; }
dotnet new console --framework net10.0 --name SpacesExport &&
cd SpacesExport &&
dotnet add package AWSSDK.Core --version 4.0.102.10 &&
dotnet add package AWSSDK.S3 --version 4.0.104.3
) && cd SpacesExport
プロジェクトの作成後にパッケージのインストールが失敗した場合は、プロジェクトを残してください。報告された NuGet の接続またはソースの問題を修正し、元のディレクトリから次のコマンドを再実行します。
dotnet add ./SpacesExport/SpacesExport.csproj package AWSSDK.Core --version 4.0.102.10 &&
dotnet add ./SpacesExport/SpacesExport.csproj package AWSSDK.S3 --version 4.0.104.3
再試行に成功したら、SpacesExport に移動してから続行してください。
DigitalOcean Spaces での AWS SDK for .NET の使用
シークレットマネージャーまたはシェル環境を通じて、次の環境変数を指定します。キーとシークレットは AWS ではなく、Spaces のものである必要があります。
| 変数 | 値 |
|---|---|
SPACES_ENDPOINT | リージョン別 HTTPS エンドポイント(例:https://fra1.digitaloceanspaces.com) |
SPACES_REGION | 既存の Space があるリージョン(例:fra1) |
SPACES_BUCKET | 既存の Space 名 |
SPACES_KEY_ID | Spaces アクセスキー ID |
SPACES_APPLICATION_KEY | Spaces シークレットキー |
エンドポイントの選び方は、DigitalOcean の SDK ガイドに記載されています。オブジェクトキーはエンコードしていない文字列として渡します。SDK がリクエストに署名し、スペース、#、?、+、パーセント記号、Unicode 文字をエンコードします。
Program.cs を次の完全なプログラムで置き換えます。通常のローカルファイルと、有効な UTF-8 の名前を使用してください。無効なネイティブファイル名が気付かないうちに別のファイルに解決されないよう、このプログラムは引数に置換文字 � が含まれていると拒否します。検証が終わるまでローカルファイルを変更せず、別のプロセスが書き込んでいない宛先キーを使ってください。
using System.Security.Cryptography;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;
public static class SpacesExporter
{
private const long MaxBytes = 64L * 1024 * 1024;
public static async Task<int> Main(string[] args)
{
using var deadline = new CancellationTokenSource(TimeSpan.FromMinutes(5));
Console.CancelKeyPress += (_, e) => { e.Cancel = true; deadline.Cancel(); };
try
{
if (args.Length is not (2 or 3) || (args.Length == 3 && args[2] != "--verify-only"))
throw new ArgumentException("Pass a local file, an object key, and optionally --verify-only.");
if (args.Any(value => value.Contains('\uFFFD')))
throw new ArgumentException("Use UTF-8 arguments without the replacement character.");
if (string.IsNullOrWhiteSpace(args[1]))
throw new ArgumentException("An object key is required.");
var endpoint = new Uri(Required("SPACES_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("SPACES_REGION"),
ForcePathStyle = true,
MaxErrorRetry = 2,
RequestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED,
ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED
};
using var client = new AmazonS3Client(
Required("SPACES_KEY_ID"), Required("SPACES_APPLICATION_KEY"), config);
var bucket = Required("SPACES_BUCKET");
await using var input = new FileStream(args[0], FileMode.Open, FileAccess.Read, FileShare.Read);
if (input.Length > MaxBytes)
{
Console.Error.WriteLine("File exceeds the 64 MiB limit.");
return 1;
}
var expectedHash = await SHA256.HashDataAsync(input, deadline.Token);
if (args.Length == 2)
await UploadAsync(client, bucket, args[0], args[1], deadline.Token);
using var stored = await client.GetObjectAsync(bucket, args[1], deadline.Token);
if (stored.ContentLength != input.Length)
throw new InvalidDataException();
using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
var buffer = new byte[64 * 1024];
long received = 0;
int count;
while ((count = await stored.ResponseStream.ReadAsync(buffer, deadline.Token)) != 0)
{
received += count;
if (received > input.Length) throw new InvalidDataException();
hash.AppendData(buffer, 0, count);
}
if (received != input.Length || !hash.GetHashAndReset().SequenceEqual(expectedHash))
throw new InvalidDataException();
Console.WriteLine($"Verified {received} bytes.");
return 0;
}
catch (OperationCanceledException) { Console.Error.WriteLine("Transfer canceled or timed out."); }
catch (AmazonS3Exception error) { Console.Error.WriteLine($"Storage returned HTTP {(int)error.StatusCode}."); }
catch (InvalidDataException) { Console.Error.WriteLine("Stored bytes do not match the local file."); }
catch (Exception) { Console.Error.WriteLine("Transfer failed. Check the file, arguments, 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 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 > MaxBytes) throw new IOException("File exceeds the 64 MiB limit.");
await client.PutObjectAsync(new PutObjectRequest
{
BucketName = bucket,
Key = key,
InputStream = input,
AutoCloseStream = false,
ContentType = "application/octet-stream",
UseChunkEncoding = false
}, cancellationToken);
}
}
プロジェクトディレクトリでビルドし、既にあるファイルをエクスポートします。
dotnet build && dotnet run --no-build -- './report.txt' 'reports/report #1.txt'
両方の引数を、ローカルパスと宛先キーに置き換えてください。-- は、.NET CLI のオプションとプログラムの引数を区切ります。これには - で始まるファイル名も含まれます。実行に成功すると、Verified に続けてダウンロードしたバイト数を出力し、終了ステータスゼロで終了します。ファイルは Spaces に残ります。同じキーを再利用すると現在の内容が置き換わるため、以前のエクスポートを残すには新しいキーを選んでください。
再試行ロジックとエラー処理の追加
MaxErrorRetry = 2 は、再試行可能な障害に対し、リクエストごとに最大二回の SDK による再試行を許可します。SDK は非同期呼び出しでキャンセルトークンを受け付けます。このプログラムは、ローカルでのハッシュ計算、アップロード、再試行、検証を合わせた全体に対し、五分の期限を一つ設定します。64 MiB 未満のファイルでも、低速な接続では期限を超える場合があります。Ctrl+C は同じトークンを通じてキャンセルを要求します。どちらの場合も検証済みの結果は出力せず、ゼロ以外のステータスで終了します。
応答が失われたり、その後の検証が失敗したりする前に、アップロードが Spaces に届いている場合があります。このプログラムは失敗時にリモートオブジェクトを削除しません。再アップロードせずに、変更していないローカルファイルとそのキーの内容を照合してください。
dotnet build && dotnet run --no-build -- './report.txt' 'reports/report #1.txt' --verify-only
このモードはダウンロードと比較のみを行い、内容が存在しないか異なる場合はゼロ以外を返します。検証に成功すれば、現在保存されているオブジェクトはローカルファイルと一致しています。成功しない場合は、問題を解決してから再アップロードするかどうかを判断してください。検証は現在のオブジェクトの状態を確認するものであり、他の書き込み元を排除するロックではありません。
サイズ制限付きファイルのストリーミング
アップロードでは、開いたファイルストリームから一回の PUT を送信します。検証では 64 KiB のバッファーで応答を読み取り、空のファイルも含めて長さ全体とハッシュを確認します。ファイルを一回ダウンロードするため、時間と帯域幅の見積もりにはこの追加転送も含めてください。64 MiB の上限はこの例のアプリケーション側の制限であり、Spaces のオブジェクトサイズ制限ではありません。
この設定ではチャンク化アップロードのエンコードを無効にし、オプションの SDK チェックサムは操作で必要な場合にのみ要求します。これらは、この Spaces へのアクセス方法で使う設定です。明示的に読み戻すことで、エンドツーエンドの内容を確認します。プログラムは成功時も失敗時も、ストリーム、応答、クライアントを破棄します。
この例はマルチパートアップロードを行いません。大きなファイルには、未完了アップロードの復旧とクリーンアップを含む、別のマルチパートワークフローが必要です。この定数を増やすだけでは実現できません。
アクセスキーと権限の安全な管理
認証情報はサーバー側の設定に保管してください。シークレットを URL、ソースファイル、ブラウザーバンドル、取得した SDK の通信ログに含めないでください。このプログラムはキーペアを明示的に指定し、HTTPS を使います。Space を公開したり、バケットの権限を変更したりすることはありません。診断出力はステータスとプログラム独自のメッセージのみに制限してください。
よくある問題のトラブルシューティング
Storage returned HTTP 403. の場合は、Spaces のキーペアを指定したこと、そのキーペアにこのバケットへの読み取りと書き込みの両方の権限があること、エンドポイントと署名リージョンがバケットの所在地と一致していることを確認してください。PUT が成功しても、その後の GET が拒否されれば検証は失敗します。
File exceeds the 64 MiB limit. の場合は、より小さいファイルか、別のマルチパート実装を使ってください。Stored bytes do not match the local file. の場合は、操作中にローカルファイルまたは宛先が変更されなかったか確認し、意図した組み合わせに対して検証専用モードを使ってください。接続が拒否された場合や、一時的な HTTP 障害で再試行を使い切った場合は、ゼロ以外を返します。再試行する前に到達可能か確認してください。実行が失敗したことを、オブジェクトが保存されていない証拠とみなさないでください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
