.NET C# で OpenStack Swift に手軽にファイルをエクスポート
.NET 組み込みの HttpClient で Swift の HTTP API を通じてファイルをアップロードします。この例では実際のセグメントを作成し、すべてのセグメントの受領が確認された後にのみ、静的大容量オブジェクトのマニフェストを公開します。
OpenStack Swift の概要
Swift はコンテナーにオブジェクトを保存します。静的大容量オブジェクト API は、アップロード済みセグメントの順序付きリストを、ダウンロード可能な単一のオブジェクトにまとめます。この例を実行するには、デプロイ環境で SLO ミドルウェアを有効にする必要があります。
環境のセットアップ
前提条件
保守が継続されている .NET 10 SDK をインストールします。この例は Linux 上の Bash で、SDK 10.0.111、ランタイム 10.0.11、Swift 2.38.2 を使ってテストしました。デプロイ環境の OpenStack 認証ワークフロー に従い、プロジェクトスコープのトークンとオブジェクトストレージのアカウント URL を取得します。トークンには、コンテナーの作成、オブジェクトのアップロード、SLO 検証用のセグメントメタデータの読み取り、アップロードに失敗したセグメントの削除を行う権限が必要です。
このサンプルでは 5 MiB のセグメントを最大 1,000 個使用します(上限を含めて 5,242,880,000 バイト)。デプロイ環境の SLO、オブジェクトサイズ、クォータの制限がこれらの値を許容することを確認してください。アップロード全体の制限時間は五分のため、接続が遅いとサイズ上限未満でも失敗する場合があります。ローカルパスとプロジェクトディレクトリ名には ASCII を使用してください。プログラムはファイルを開く前にこの制限を適用し、不正なファイル名のバイト列によって、引数のデコード後に別のファイルが選択されることを防ぎます。リモートオブジェクトのキーには Unicode を使用できます。SwiftExport というエントリがない、書き込み可能なディレクトリから始めます。上位ディレクトリの .NET SDK、NuGet、MSBuild の設定は引き続き適用されます。
if ! command -v dotnet >/dev/null 2>&1; then
printf '%s\n' 'Install the .NET 10 SDK first.' >&2
false
elif [ -e SwiftExport ] || [ -L SwiftExport ]; then
printf '%s\n' 'SwiftExport already exists; choose another parent directory.' >&2
false
else
dotnet new console --framework net10.0 --name SwiftExport --no-restore &&
dotnet restore SwiftExport/SwiftExport.csproj &&
cd SwiftExport
fi
セットアップに成功すると、プロジェクトディレクトリに移動します。復元に失敗した場合、新しいプロジェクトはそのまま残り、シェルは親ディレクトリにとどまります。報告された SDK または NuGet の問題を修正し、そのディレクトリで
dotnet restore SwiftExport/SwiftExport.csproj && cd SwiftExport を実行してセットアップを完了してください。追加の NuGet パッケージは不要です。
安全な設定管理
SWIFT_STORAGE_URL には、サービスカタログの完全な HTTPS アカウントエンドポイントを、/v1/AUTH_… パスも含めて設定します。SWIFT_TOKEN にはスコープ付きトークンを設定します。これらはシェルまたはシークレットマネージャーから渡してください。トークンの取得と更新は、デプロイ環境の Keystone ワークフローで行います。トークンの有効期限が切れていると、終了コードはゼロ以外になります。再実行する前に、新しいスコープ付きトークンを取得してください。
Swift ストレージ操作の実装
Program.cs を次の完全なプログラムに置き換えます。注入された HttpClient は呼び出し元が所有し、エクスポーターは各リクエストとレスポンスを破棄します。別の宛先にトークンが転送されないよう、リダイレクトを無効にしています。
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text.Json;
public static class Program
{
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 != 3) throw new ArgumentException("Pass container, object key, and local file.");
if (args[2].Any(character => character > 127) ||
Directory.GetCurrentDirectory().Any(character => character > 127))
throw new ArgumentException("Use ASCII local paths and working directory names.");
var endpoint = new Uri(Required("SWIFT_STORAGE_URL"));
if (endpoint.Scheme != "https" || endpoint.UserInfo.Length != 0 ||
endpoint.Query.Length != 0 || endpoint.Fragment.Length != 0)
throw new ArgumentException("Use the HTTPS account endpoint from the service catalog.");
using var handler = new SocketsHttpHandler { AllowAutoRedirect = false, MaxConnectionsPerServer = 4 };
using var http = new HttpClient(handler) { Timeout = Timeout.InfiniteTimeSpan };
var exporter = new SwiftExporter(http, endpoint, Required("SWIFT_TOKEN"));
await exporter.UploadAsync(args[0], args[1], args[2], deadline.Token);
Console.WriteLine("Uploaded.");
return 0;
}
catch (OperationCanceledException) { Console.Error.WriteLine("Upload canceled or timed out."); }
catch (HttpRequestException error) { Console.Error.WriteLine($"Swift request failed (HTTP {error.StatusCode})."); }
catch (Exception) { Console.Error.WriteLine("Upload failed. Check the file and Swift configuration."); }
return 1;
}
private static string Required(string name) =>
Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
? value : throw new ArgumentException($"Missing {name}.");
}
public sealed class SwiftExporter(HttpClient http, Uri endpoint, string token)
{
private const int SegmentSize = 5 * 1024 * 1024;
private const int MaxSegments = 1000;
private static string Encode(string value)
{
var parts = value.Split('/');
if (parts.Any(part => part.Length == 0 || part == "." || part == ".."))
throw new ArgumentException("Use nonempty path segments other than dot or dot-dot.");
return string.Join("/", parts.Select(Uri.EscapeDataString));
}
private async Task<string?> PutAsync(string path, HttpContent content,
bool container, CancellationToken ct, string? etag = null, string query = "")
{
content.Headers.ContentType ??= new MediaTypeHeaderValue("application/octet-stream");
using var request = new HttpRequestMessage(HttpMethod.Put,
endpoint.AbsoluteUri.TrimEnd('/') + "/" + Encode(path) + query) { Content = content };
request.Headers.Add("X-Auth-Token", token);
if (etag != null) request.Headers.Add("ETag", etag);
using var response = await http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, ct);
var status = (int)response.StatusCode;
if (status != 201 && !(container && status == 202))
throw new HttpRequestException("Unexpected Swift response.", null, response.StatusCode);
// Swift can return an unquoted MD5 that the typed ETag accessor cannot parse.
return response.Headers.TryGetValues("ETag", out var values)
? values.Single().Trim('"') : null;
}
public async Task UploadAsync(string container, string key, string file, CancellationToken ct)
{
if (container.Contains('/')) throw new ArgumentException("A container cannot contain slashes.");
Encode(container);
Encode(key);
await using var input = new FileStream(file, FileMode.Open, FileAccess.Read, FileShare.Read);
long length = input.Length;
if (length > (long)SegmentSize * MaxSegments) throw new IOException("File exceeds the example limit.");
await PutAsync(container, new ByteArrayContent([]), true, ct);
if (length == 0)
{
await PutAsync(container + "/" + key, new ByteArrayContent([]), false, ct);
return;
}
string segments = container + "_segments";
await PutAsync(segments, new ByteArrayContent([]), true, ct);
string version = Guid.NewGuid().ToString("N");
var manifest = new List<object>();
var attempted = new List<string>();
bool publicationStarted = false;
var buffer = new byte[SegmentSize];
long remaining = length;
try
{
for (int index = 0; remaining > 0; index++)
{
int count = (int)Math.Min(remaining, SegmentSize);
await input.ReadExactlyAsync(buffer.AsMemory(0, count), ct);
string hash = Convert.ToHexString(MD5.HashData(buffer.AsSpan(0, count))).ToLowerInvariant();
string name = $"{segments}/{version}/{index:D8}";
attempted.Add(name);
using var content = new ByteArrayContent(buffer, 0, count);
string? returned = await PutAsync(name, content, false, ct, hash);
if (!string.Equals(hash, returned, StringComparison.OrdinalIgnoreCase))
throw new IOException("Swift did not confirm the segment checksum.");
manifest.Add(new { path = "/" + name, etag = hash, size_bytes = count });
remaining -= count;
}
if (input.Length != length || input.ReadByte() != -1) throw new IOException("The input file changed.");
using var manifestContent = new StringContent(JsonSerializer.Serialize(manifest));
manifestContent.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
// After dispatch, a lost response cannot tell us whether these segments are live.
publicationStarted = true;
await PutAsync(container + "/" + key, manifestContent, false, ct,
query: "?multipart-manifest=put");
}
catch
{
if (!publicationStarted) await RemoveAttemptedAsync(attempted);
throw;
}
}
private async Task RemoveAttemptedAsync(List<string> paths)
{
using var cleanup = new CancellationTokenSource(TimeSpan.FromSeconds(15));
foreach (string path in paths)
{
try
{
using var request = new HttpRequestMessage(HttpMethod.Delete,
endpoint.AbsoluteUri.TrimEnd('/') + "/" + Encode(path));
request.Headers.Add("X-Auth-Token", token);
using var response = await http.SendAsync(request,
HttpCompletionOption.ResponseHeadersRead, cleanup.Token);
if ((int)response.StatusCode != 204 && (int)response.StatusCode != 404)
Console.Error.WriteLine("An unreferenced segment could not be removed.");
}
catch (HttpRequestException) { Console.Error.WriteLine("Segment cleanup lost its connection."); }
catch (OperationCanceledException) { Console.Error.WriteLine("Segment cleanup timed out."); break; }
}
}
}
大容量ファイルの処理
空でないファイルごとに、<container>_segments 内に新しいセグメントプレフィックスを作成します。順次アップロードすることで、ペイロードバッファーを 5 MiB に抑えます。マニフェストには各セグメントのパス、ETag、サイズが含まれ、Swift はオブジェクトの公開前にこれらを検証します。空のファイルには通常の空の PUT を使用し、空の SLO マニフェストに対するデプロイ環境固有の対応を不要にします。
リモートオブジェクトのキーには、空白と Unicode を使用できます。エンコード時にはパス区切り文字を保持し、URI の正規化を避けるため、空のセグメント、ドット(.)、ドットドット(..)のセグメントを拒否します。アップロード中はローカルファイルを変更しないでください。サイズの検査では、同時に行われる同じサイズの編集をすべて検出できるわけではありません。
堅牢なエラー処理の実装
コンテナーの作成では HTTP 201 または 202 を受け付けますが、オブジェクトとマニフェストのアップロードでは 201 が必要です。セグメントのチェックサムは Swift の生の ETag ヘッダーと比較し、引用符を省略するデプロイ環境にも対応します。クォータ、認証、チェックサム、接続、キャンセルによる失敗では、終了コードがゼロ以外になります。Ctrl+C と五分の制限時間によるキャンセルは、ファイルの読み取りと HTTP 操作に伝播します。この例では再試行しません。
マニフェスト送信前にアップロードが失敗すると、そのアップロード自身の正確なセグメント名だけを対象に削除を試みます。クリーンアップには別途 15 秒の制限時間を設けているため、キャンセルされてもスキップしません。ただし、削除に失敗すると孤立したセグメントが残る場合があります。既存のオブジェクトは、置き換え先が公開されるまで利用可能な状態を保ちます。
マニフェストの送信開始後に失敗した場合、プログラムは新しいセグメントを保持します。レスポンスが失われると、公開に成功していても確認できないため、それらのセグメントを削除するとオブジェクトが壊れるおそれがあります。再試行や未参照バージョンの回収を行う前に、現在のマニフェストを確認してください。置き換え時には新しいプレフィックスと明示的なセグメントリストを使用し、短いファイルに古いファイルの末尾が取り込まれることを防ぎます。置き換え後も古いセグメントは残ります。所有するバージョンのうち、参照もアクティブな読み取り処理も残っていないものだけを回収してください。この例では、その保守ワークフローは実装していません。
パフォーマンスの最適化
一括エクスポートではクライアントを再利用します。接続数の上限は SocketsHttpHandler が管理します。並行アップロードを追加する場合は、並行数を制限し、操作ごとにセグメントバッファーを一つ確保してください。
実践例:完全な実装
両方の環境変数を設定したら、エクスポートするファイルをプロジェクトディレクトリ内の
report.bin に配置します。次のコマンドは、指定したキーのリモートオブジェクトを作成または置換します。
dotnet run -- exports 'reports/report #1.bin' report.bin
このコマンドは、必要に応じて exports と exports_segments を作成し、セグメントをアップロードした後、最後に reports/report #1.bin を公開します。入力が空の場合は、代わりに通常の空のオブジェクトを作成します。コマンドは、最後の成功レスポンスを受信した後にのみ
Uploaded. と出力し、終了コードをゼロにして終了します。Swift の通常の認証付き GET API でオブジェクトをダウンロードし、そのバイト列を report.bin と比較してください。空でないオブジェクトの SLO ETag は、ファイル全体の MD5 ではありません。
