.NET 用の Batch ファイル規則ライブラリを使用した Azure Storage へのジョブおよびタスクのデータの保持

[アーティクル]
06/01/2023

Azure Batch で実行するタスクによって、実行時に出力データが生成されることがあります。タスクの出力データは、多くの場合、ジョブ内の他のタスク、またはそのジョブを実行したクライアントアプリケーション (あるいは両方) が取得できるように格納される必要があります。タスクは Batch コンピューティングノードのファイルシステムに出力データを書き込みますが、再イメージ化されるとき、またはノードがプールを終了するときに、ノードのすべてのデータが失われます。タスクには、ファイルリテンション期間が設定されている場合もあります。この期間が過ぎると、タスクによって作成されたファイルが削除されます。これらの理由から、後で必要になるタスク出力をデータストア (Azure Storage など) に永続化することが重要です。

Batch のストレージアカウントオプションについては、「Batch アカウントと Azure Storage アカウント」を参照してください。

.NET 用ファイル規則ライブラリを使用して Azure Batch からのタスクデータを保持できます。ファイル規則ライブラリにより、Azure Storage でのタスク出力データの保存と取得の処理が簡素化されます。ファイル規則ライブラリは、タスクとクライアントの両方のコードで使用できます。タスクモードでは、ライブラリを使用してファイルを保持します。クライアントモードでは、ライブラリを使用してファイルの一覧表示と取得を行います。タスクの依存関係のシナリオのように、タスクコードでライブラリを使用して、上流のタスクの出力を取得することもできます。

ファイル規則ライブラリを使用して出力ファイルを取得するには、ジョブまたはタスクのファイルを見つけます。特定のジョブまたはタスクのファイルを容易に特定できます。代わりに、ID や目的別にファイルを一覧表示できます。たとえば、特定のタスクの中間ファイルをすべて一覧表示します。または、特定のジョブのプレビューファイルを取得します。

バージョン 2017-05-01 以降、仮想マシン (VM) 構成で作成されたプール上で実行されるタスクやジョブマネージャータスクについては、Batch サービス API で Azure Storage への出力データの保持がサポートされています。タスクを作成するコード内から、出力を保持できます。この方法は、ファイル規則ライブラリの代わりになります。 Batch クライアントアプリケーションを変更して、タスクを実行中のアプリケーションを更新する必要なしに出力を保持することもできます。詳細については、「Persist task data to Azure Storage with the Batch service API (Batch サービス API を使用した Azure Storage へのタスクのデータの保持)」を参照してください。

ライブラリのユースケース

Azure Batch には、タスクの出力を保持する複数の方法が用意されています。以下を行うときにはファイル規則ライブラリを使用します。

ファイルを保持するためにタスクで実行しているアプリケーションのコードを変更する。
タスクがまだ実行されている間にデータを Azure Storage にストリームする。
プールからのデータを保持する。
クライアントアプリケーションやその他のタスクで、ID または目的別にタスク出力ファイルを見つけてダウンロードする。
Azure portal でタスク出力を表示する。

その他のシナリオでは、別の方法を検討することをお勧めします。その他のオプションの詳細については、Azure Storage にジョブやタスクの出力を保持する方法に関するページを参照してください。

Batch ファイル規則の標準

Batch ファイル規則の標準は、出力ファイルの書き込み先となる保存先コンテナーや BLOB パスの名前付けスキームを示します。標準に従って Azure Storage に保持されたファイルは、自動的に Azure portal で表示できます。

.NET 用ファイル規則ライブラリにより、ストレージコンテナーとタスク出力ファイルには、ファイル規則の標準に従って自動的に名前が付けられます。ライブラリには、Azure Storage 内の出力ファイルをクエリするメソッドも用意されています。ジョブ ID、タスク ID、または目的別にクエリを実行できます。

.NET 以外の言語で開発しようとしている場合は、アプリケーションに、ファイル規則の標準を独自に実装できます。詳細については、「Batch ファイル規則の標準を実装する」を参照してください。

Azure Storage アカウントをリンクする

ファイル規則ライブラリを使用して Azure Storage への出力データを保持するには、まず、Azure Storage アカウントを Batch アカウントにリンクします。

Azure portal にサインインします。
検索バーで "Batch" を検索して選択します。
Azure Storage とリンクする Batch アカウントを選択します。
Batch アカウントページの [設定] で、[ストレージアカウント] を選択します。
Azure Storage アカウントをまだ Batch アカウントに関連付けていない場合は、[ストレージアカウント (なし)] を選択します。
使用する Azure Storage アカウントを選択します。最適なパフォーマンスを得るには、Batch アカウントと同じリージョン内のアカウントを使用します。

出力データの保持

ジョブとタスクの出力データは、ファイル規則ライブラリを使用して保持できます。まず、Azure Storage 内にコンテナーを作成します。次に、出力をそのコンテナーに保存します。タスク出力をコンテナーにアップロードするには、タスクコードで .NET 用 Azure Storage クライアントライブラリを使用します。

Azure Storage でのコンテナーと BLOB の操作の詳細については、「.NET を使用して Azure Blob Storage を使用する」を参照してください。

ファイル規則ライブラリを使用したジョブとタスクの出力はすべて同じコンテナーに格納されるため、大量のタスクで同時にファイルを保持しようとすると、Azure Storage による調整の制限が適用される場合があります。詳細については、「BLOB ストレージのパフォーマンスとスケーラビリティのチェックリスト」を参照してください。

ストレージコンテナーの作成

Azure Storage にタスク出力を保持するには、まず CloudJob.PrepareOutputStorageAsync を呼び出してコンテナーを作成します。この拡張メソッドは CloudStorageAccount オブジェクトをパラメーターとして受け取り、このメソッドでは、ファイル規則標準に従って名前を付けたコンテナーが作成されます。コンテナーの内容は、Azure portal や、この記事で説明した取得メソッドによって検出できます。

一般に、プール、ジョブ、タスクを作成するクライアントアプリケーションでコンテナーを作成します。次に例を示します。

CloudJob job = batchClient.JobOperations.CreateJob(
    "myJob",
    new PoolInformation { PoolId = "myPool" });

// Create reference to the linked Azure Storage account
CloudStorageAccount linkedStorageAccount =
    new CloudStorageAccount(myCredentials, true);

// Create the blob storage container for the outputs
await job.PrepareOutputStorageAsync(linkedStorageAccount);

タスク出力の格納

ストレージコンテナーの作成後、TaskOutputStorage を使用して、タスクの出力をコンテナーに保存できます。このクラスは、ファイル規則ライブラリに用意されています。

タスクコード内に TaskOutputStorage オブジェクトを作成します。タスクの作業が完了したら、TaskOutputStorage.SaveAsync メソッドを呼び出します。この手順によって出力が Azure Storage に保存されます。

CloudStorageAccount linkedStorageAccount = new CloudStorageAccount(myCredentials);
string jobId = Environment.GetEnvironmentVariable("AZ_BATCH_JOB_ID");
string taskId = Environment.GetEnvironmentVariable("AZ_BATCH_TASK_ID");

TaskOutputStorage taskOutputStorage = new TaskOutputStorage(
    linkedStorageAccount, jobId, taskId);

/* Code to process data and produce output file(s) */

await taskOutputStorage.SaveAsync(TaskOutputKind.TaskOutput, "frame_full_res.jpg");
await taskOutputStorage.SaveAsync(TaskOutputKind.TaskPreview, "frame_low_res.jpg");

保持されたファイルは TaskOutputStorage.SaveAsync メソッドの kind パラメーターによって分類されます。 TaskOutputKind として、事前に定義された 4 つの種類が存在します。TaskOutput、TaskPreview、TaskLog、TaskIntermediate. です。カスタム出力カテゴリを定義することもできます。

どの種類の出力を一覧表示するかは、後で Batch のクエリを実行するときに指定します。その後、タスクの出力を一覧表示するときに、いずれかの出力の種類に基づいてフィルター処理できます。たとえば、"タスク 109 の プレビュー出力を取得する" ようにフィルター処理します。詳細については、「出力データを取得する」を参照してください。

出力の種類によって、出力ファイルが Azure portal で表示される場所も決まります。 TaskOutput カテゴリのファイルは、[タスク出力ファイル] の下になります。 TaskLog カテゴリのファイルは、[タスクログ] の下になります。

ジョブの出力の格納

ジョブ全体に関連付けられている出力を格納することもできます。たとえば、ムービーレンダリングジョブのマージタスクで、完全にレンダリングされたムービーをジョブの出力として保持できます。ジョブが完了すると、クライアントアプリケーションで、ジョブの出力を一覧表示したり、取得したりできます。クライアントアプリケーションで個々のタスクのクエリを実行する必要はありません。

ジョブの出力を格納するには、JobOutputStorage.SaveAsync メソッドを呼び出します。 JobOutputKind とファイル名を指定します。次に例を示します。

CloudJob job = new JobOutputStorage(acct, jobId);
JobOutputStorage jobOutputStorage = job.OutputStorage(linkedStorageAccount);

await jobOutputStorage.SaveAsync(JobOutputKind.JobOutput, "mymovie.mp4");
await jobOutputStorage.SaveAsync(JobOutputKind.JobPreview, "mymovie_preview.mp4");

タスク出力用の種類 TaskOutputKind と同様に、種類 JobOutputKind を使用して、保持されたジョブのファイルを分類します。特定の種類の出力は、後で一覧表示できます。種類 JobOutputKind には、出力とプレビューの両方のカテゴリが含まれます。この種類では、カスタムカテゴリの作成もサポートされています。

タスクのログの格納

タスクの実行中に更新されたファイルを保持する必要が生じる場合もあります。たとえば、ログファイルや、stdout.txt と stderr.txt を保持する必要がある場合があります。ファイル規則ライブラリには、これらの種類のファイルを保持するための TaskOutputStorage.SaveTrackedAsync メソッドが用意されています。 SaveTrackedAsync を使用して、指定した間隔でノード上のファイルに対する更新を追跡します。次に、それらの更新を Azure Storage に保持します。

次の例では、SaveTrackedAsync を使用して、タスクの実行中に 15 秒ごとに Azure Storage で stdout.txt を更新しています。

TimeSpan stdoutFlushDelay = TimeSpan.FromSeconds(3);
string logFilePath = Path.Combine(
    Environment.GetEnvironmentVariable("AZ_BATCH_TASK_DIR"), "stdout.txt");

// The primary task logic is wrapped in a using statement that sends updates to
// the stdout.txt blob in Storage every 15 seconds while the task code runs.
using (ITrackedSaveOperation stdout =
        await taskStorage.SaveTrackedAsync(
        TaskOutputKind.TaskLog,
        logFilePath,
        "stdout.txt",
        TimeSpan.FromSeconds(15)))
{
    /* Code to process data and produce output file(s) */

    // We are tracking the disk file to save our standard output, but the
    // node agent may take up to 3 seconds to flush the stdout stream to
    // disk. So give the file a moment to catch up.
     await Task.Delay(stdoutFlushDelay);
}

コメント付きセクションの Code to process data and produce output file(s) は、タスクで通常実行する任意のコードに置き換えます。たとえば、Azure Storage からデータをダウンロードしてから変換や計算を実行するコードがあるとします。このコードを using ブロックにラップして、SaveTrackedAsync によってファイルを定期的に更新できます。

ノードエージェントは、プール内の各ノードで実行されるプログラムです。このプログラムは、ノードと Batch サービスの間で、コマンドとコントロールのインターフェイスを提供するものです。この using ブロックの末尾では、Task.Delay の呼び出しが必要です。この呼び出しによって、ノードエージェントのために、標準の内容をノード上の stdout.txt ファイルにフラッシュする時間を確保します。この延期時間がないと、最後の数秒間の出力が失われる可能性があります。この延期時間が必要でないファイルもあります。

SaveTrackedAsync でファイルの追跡を有効にすると、追跡されているファイルへの "追加分" だけが Azure Storage で保持されます。このメソッドは、ローテーションが設定されていないログファイル、またはファイル末尾への追加操作によって書き込まれるその他のファイルを追跡するためにのみ使用してください。

出力データの取得

特定のタスクまたはジョブの出力ファイルを取得するために、Azure Storage 内のパスやファイル名を知っている必要はあります。タスクまたはジョブの ID で特定のタスクまたはジョブの出力を要求することができます。

次のコード例では、ジョブのタスクが反復処理されます。コードでは次に、タスクの出力ファイルに関する一部の情報が出力されます。その後、AzureStorage からファイルがダウンロードされます。

foreach (CloudTask task in myJob.ListTasks())
{
    foreach (OutputFileReference output in
        task.OutputStorage(storageAccount).ListOutputs(
            TaskOutputKind.TaskOutput))
    {
        Console.WriteLine($"output file: {output.FilePath}");

        output.DownloadToFileAsync(
            $"{jobId}-{output.FilePath}",
            System.IO.FileMode.Create).Wait();
    }
}

Azure Portal での出力ファイルの表示

出力ファイルで Batch ファイル規則の標準を使用している場合は、ファイルを Azure portal で表示できます。

ポータルで出力ファイルの表示を有効にするには、次の要件を満たす必要があります。

出力ファイルが Azure portal に自動的に表示されるようにするには、次の手順を実行する必要があります。

Azure Storage アカウントを Batch アカウントにリンクします。
Azure Storage のコンテナーとファイルについては、定義済みの名前付け規則に従います。すべての定義については、README を確認してください。出力の保持にファイル規則ライブラリを使用している場合、ファイルはファイル規則の標準に従って保持されます。

タスクの出力ファイルとログを Azure portal で表示するには:

Azure portal にサインインします。
出力を表示しようとしているタスクに移動します。
[保存された出力ファイル] または [保存されたログ] のいずれかを選択します。

コードサンプル

PersistOutputs サンプルプロジェクトは、GitHub にある Azure Batch コードサンプルの 1 つです。この Visual Studio ソリューションは、Azure Batch ファイル規則ライブラリを使用して永続的なストレージでタスク出力を保持する方法を示しています。サンプルを実行するには、次の手順に従います。

Visual Studio 2019 でプロジェクトを開きます。
Batch と Azure Storage のアカウント資格情報を、Microsoft.Azure.Batch.Samples.Common プロジェクトの AccountSettings.settings に追加します。
ソリューションをビルドします。ソリューションはまだ実行しないでください。
NuGet パッケージの復元を求められた場合は、復元します。
PersistOutputsTask のアプリケーションパッケージを、Azure portal からアップロードします。
1. 実行可能ファイル PersistOutputsTask.exe と、その依存アセンブリを .zip パッケージに含めます。
2. アプリケーション ID を PersistOutputsTask に設定します。
3. アプリケーションパッケージのバージョンを 1.0 に設定します。
[開始] を選択してプロジェクトを実行します。
使用する保持テクノロジを選択するよう求められたら、「1」と入力します。このオプションでは、ファイル規則ライブラリを使用してタスク出力を保持するサンプルが実行されます。

.NET 用 Batch ファイル規則ライブラリの入手

.NET 用 Batch ファイル規則ライブラリは NuGet にあります。このライブラリでは、新しいメソッドによって CloudJob クラスと CloudTask クラスが拡張されています。詳細については、ファイル規則ライブラリのリファレンスドキュメントを参照してください。

ファイル規則ライブラリのソースコードは GitHub で入手できます。

次の方法で共有

.NET 用の Batch ファイル規則ライブラリを使用した Azure Storage へのジョブおよびタスクのデータの保持

ライブラリのユースケース

Batch ファイル規則の標準

Azure Storage アカウントをリンクする

出力データの保持

ストレージコンテナーの作成

タスク出力の格納

ジョブの出力の格納

タスクのログの格納

出力データの取得

Azure Portal での出力ファイルの表示

コードサンプル

.NET 用 Batch ファイル規則ライブラリの入手

次のステップ

フィードバック

フィードバック

その他のリソース

次の方法で共有

.NET 用の Batch ファイル規則ライブラリを使用した Azure Storage へのジョブおよびタスクのデータの保持

ライブラリのユース ケース

Batch ファイル規則の標準

Azure Storage アカウントをリンクする

出力データの保持

ストレージ コンテナーの作成

タスク出力の格納

ジョブの出力の格納

タスクのログの格納

出力データの取得

Azure Portal での出力ファイルの表示

コード サンプル

.NET 用 Batch ファイル規則ライブラリの入手

次のステップ

フィードバック

フィードバック

その他のリソース

ライブラリのユースケース

ストレージコンテナーの作成

コードサンプル