azure-compute-batch-java

Azure Batch SDK for Java

Azure で大規模な並列処理やハイパフォーマンスコンピューティング（HPC）のバッチジョブを実行するためのクライアントライブラリです。

インストール

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-compute-batch</artifactId>
    <version>1.0.0-beta.5</version>
</dependency>

前提条件

• Azure Batch アカウント
• コンピューティングノードを構成したプール
• Azure サブスクリプション

環境変数

AZURE_BATCH_ENDPOINT=https://<account>.<region>.batch.azure.com
AZURE_BATCH_ACCOUNT=<account-name>
AZURE_BATCH_ACCESS_KEY=<account-key>

クライアントの作成

Microsoft Entra ID を使用（推奨）

import com.azure.compute.batch.BatchClient;
import com.azure.compute.batch.BatchClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;

BatchClient batchClient = new BatchClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint(System.getenv("AZURE_BATCH_ENDPOINT"))
    .buildClient();

非同期クライアント

import com.azure.compute.batch.BatchAsyncClient;

BatchAsyncClient batchAsyncClient = new BatchClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint(System.getenv("AZURE_BATCH_ENDPOINT"))
    .buildAsyncClient();

共有キー資格情報を使用

import com.azure.core.credential.AzureNamedKeyCredential;

String accountName = System.getenv("AZURE_BATCH_ACCOUNT");
String accountKey = System.getenv("AZURE_BATCH_ACCESS_KEY");
AzureNamedKeyCredential sharedKeyCreds = new AzureNamedKeyCredential(accountName, accountKey);

BatchClient batchClient = new BatchClientBuilder()
    .credential(sharedKeyCreds)
    .endpoint(System.getenv("AZURE_BATCH_ENDPOINT"))
    .buildClient();

主な概念

概念	説明
プール	タスクを実行するコンピューティングノードの集合
ジョブ	タスクを論理的にまとめたもの
タスク	計算処理の単位（コマンド／スクリプト）
ノード	タスクを実行する VM
ジョブスケジュール	ジョブを定期的に作成する設定

プール操作

書き込み操作の前に、アカウント／テナント、プール／ジョブ ID、SKU／イメージの利用可否、リソース制限、コストを確認してください。イメージの例は、そのイメージがプールでサポートされていることを保証するものではありません。現在の Batch サポート対象イメージから選択してください。タスクのコマンドラインはシェルで暗黙的に実行されません。確認済みの固定コマンドに限り、適切なシェルを明示的に使用してください（以下の Linux の例は Windows の cmd /c とは異なります）。信頼できないタスク入力をシェルテキストに補間しないでください。割り当て、タスク、ポーリングの期限を設定し、タスクごとの失敗や終了コードを確認し、ID を制限してください。出力を保存してから、許可されたリソースのみを削除／再起動／終了してください。

プールの作成

import com.azure.compute.batch.models.*;

batchClient.createPool(new BatchPoolCreateParameters("myPoolId", "STANDARD_DC2s_V2")
    .setVirtualMachineConfiguration(
        new VirtualMachineConfiguration(
            new BatchVmImageReference()
                .setPublisher("Canonical")
                .setOffer("UbuntuServer")
                .setSku("22_04-lts")
                .setVersion("latest"),
            "batch.node.ubuntu 22.04"))
    .setTargetDedicatedNodes(2)
    .setTargetLowPriorityNodes(0), null);

プールの取得

BatchPool pool = batchClient.getPool("myPoolId");
System.out.println("Pool state: " + pool.getState());
System.out.println("Current dedicated nodes: " + pool.getCurrentDedicatedNodes());

プールの一覧表示

import com.azure.core.http.rest.PagedIterable;

PagedIterable<BatchPool> pools = batchClient.listPools();
for (BatchPool pool : pools) {
    System.out.println("Pool: " + pool.getId() + ", State: " + pool.getState());
}

プールのサイズ変更

import com.azure.core.util.polling.SyncPoller;

BatchPoolResizeParameters resizeParams = new BatchPoolResizeParameters()
    .setTargetDedicatedNodes(4)
    .setTargetLowPriorityNodes(2);

SyncPoller<BatchPool, BatchPool> poller = batchClient.beginResizePool("myPoolId", resizeParams);
poller.waitForCompletion();
BatchPool resizedPool = poller.getFinalResult();

自動スケールの有効化

BatchPoolEnableAutoScaleParameters autoScaleParams = new BatchPoolEnableAutoScaleParameters()
    .setAutoScaleEvaluationInterval(Duration.ofMinutes(5))
    .setAutoScaleFormula("$TargetDedicatedNodes = min(10, $PendingTasks.GetSample(TimeInterval_Minute * 5));");

batchClient.enablePoolAutoScale("myPoolId", autoScaleParams);

プールの削除

SyncPoller<BatchPool, Void> deletePoller = batchClient.beginDeletePool("myPoolId");
deletePoller.waitForCompletion();

ジョブ操作

ジョブの作成

batchClient.createJob(
    new BatchJobCreateParameters("myJobId", new BatchPoolInfo().setPoolId("myPoolId"))
        .setPriority(100)
        .setConstraints(new BatchJobConstraints()
            .setMaxWallClockTime(Duration.ofHours(24))
            .setMaxTaskRetryCount(3)),
    null);

ジョブの取得

BatchJob job = batchClient.getJob("myJobId", null, null);
System.out.println("Job state: " + job.getState());

ジョブの一覧表示

PagedIterable<BatchJob> jobs = batchClient.listJobs(new BatchJobsListOptions());
for (BatchJob job : jobs) {
    System.out.println("Job: " + job.getId() + ", State: " + job.getState());
}

タスク数の取得

BatchTaskCountsResult counts = batchClient.getJobTaskCounts("myJobId");
System.out.println("Active: " + counts.getTaskCounts().getActive());
System.out.println("Running: " + counts.getTaskCounts().getRunning());
System.out.println("Completed: " + counts.getTaskCounts().getCompleted());

ジョブの終了

BatchJobTerminateParameters terminateParams = new BatchJobTerminateParameters()
    .setTerminationReason("Manual termination");
BatchJobTerminateOptions options = new BatchJobTerminateOptions().setParameters(terminateParams);

SyncPoller<BatchJob, BatchJob> poller = batchClient.beginTerminateJob("myJobId", options, null);
poller.waitForCompletion();

ジョブの削除

SyncPoller<BatchJob, Void> deletePoller = batchClient.beginDeleteJob("myJobId");
deletePoller.waitForCompletion();

タスク操作

単一タスクの作成

BatchTaskCreateParameters task = new BatchTaskCreateParameters("task1", "/bin/bash -c 'echo Hello World'");
batchClient.createTask("myJobId", task);

終了条件を指定したタスクの作成

batchClient.createTask("myJobId", new BatchTaskCreateParameters("task2", "cmd /c exit 3")
    .setExitConditions(new ExitConditions()
        .setExitCodeRanges(Arrays.asList(
            new ExitCodeRangeMapping(2, 4, 
                new ExitOptions().setJobAction(BatchJobActionKind.TERMINATE)))))
    .setUserIdentity(new UserIdentity()
        .setAutoUser(new AutoUserSpecification()
            .setScope(AutoUserScope.TASK)
            .setElevationLevel(ElevationLevel.NON_ADMIN))),
    null);

タスクコレクションの作成（最大 100 件）

List<BatchTaskCreateParameters> taskList = Arrays.asList(
    new BatchTaskCreateParameters("task1", "/bin/bash -c 'echo Task 1'"),
    new BatchTaskCreateParameters("task2", "/bin/bash -c 'echo Task 2'"),
    new BatchTaskCreateParameters("task3", "/bin/bash -c 'echo Task 3'")
);
BatchTaskGroup taskGroup = new BatchTaskGroup(taskList);
BatchCreateTaskCollectionResult result = batchClient.createTaskCollection("myJobId", taskGroup);

多数のタスクの作成（SDK によるバッチ処理。サービスのクォータは引き続き適用されます）

List<BatchTaskCreateParameters> tasks = new ArrayList<>();
for (int i = 0; i < 1000; i++) {
    tasks.add(new BatchTaskCreateParameters("task" + i, "/bin/bash -c 'echo Task " + i + "'"));
}
batchClient.createTasks("myJobId", tasks);

タスクの取得

BatchTask task = batchClient.getTask("myJobId", "task1");
System.out.println("Task state: " + task.getState());
System.out.println("Exit code: " + task.getExecutionInfo().getExitCode());

タスクの一覧表示

PagedIterable<BatchTask> tasks = batchClient.listTasks("myJobId");
for (BatchTask task : tasks) {
    System.out.println("Task: " + task.getId() + ", State: " + task.getState());
}

タスク出力の取得

import com.azure.core.util.BinaryData;
import java.nio.charset.StandardCharsets;

BinaryData stdout = batchClient.getTaskFile("myJobId", "task1", "stdout.txt");
System.out.println(new String(stdout.toBytes(), StandardCharsets.UTF_8));

タスクの終了

batchClient.terminateTask("myJobId", "task1", null, null);

ノード操作

ノードの一覧表示

PagedIterable<BatchNode> nodes = batchClient.listNodes("myPoolId", new BatchNodesListOptions());
for (BatchNode node : nodes) {
    System.out.println("Node: " + node.getId() + ", State: " + node.getState());
}

ノードの再起動

SyncPoller<BatchNode, BatchNode> rebootPoller = batchClient.beginRebootNode("myPoolId", "nodeId");
rebootPoller.waitForCompletion();

リモートログイン設定の取得

BatchNodeRemoteLoginSettings settings = batchClient.getNodeRemoteLoginSettings("myPoolId", "nodeId");
System.out.println("IP: " + settings.getRemoteLoginIpAddress());
System.out.println("Port: " + settings.getRemoteLoginPort());

ジョブスケジュール操作

ジョブスケジュールの作成

batchClient.createJobSchedule(new BatchJobScheduleCreateParameters("myScheduleId",
    new BatchJobScheduleConfiguration()
        .setRecurrenceInterval(Duration.ofHours(6))
        .setDoNotRunUntil(OffsetDateTime.now().plusDays(1)),
    new BatchJobSpecification(new BatchPoolInfo().setPoolId("myPoolId"))
        .setPriority(50)),
    null);

ジョブスケジュールの取得

BatchJobSchedule schedule = batchClient.getJobSchedule("myScheduleId");
System.out.println("Schedule state: " + schedule.getState());

エラー処理

import com.azure.compute.batch.models.BatchErrorException;
import com.azure.compute.batch.models.BatchError;

try {
    batchClient.getPool("nonexistent-pool");
} catch (BatchErrorException e) {
    BatchError error = e.getValue();
    System.err.println("Error code: " + error.getCode());
    System.err.println("Message: " + error.getMessage().getValue());
    
    if ("PoolNotFound".equals(error.getCode())) {
        System.err.println("The specified pool does not exist.");
    }
}

ベストプラクティス

1. Entra ID を使用する — 認証には共有キーよりもこちらを推奨します
2. プールには管理 SDK を使用する — azure-resourcemanager-batch はマネージド ID をサポートしています
3. タスクの作成をバッチ処理する — 複数のタスクには createTaskCollection または createTasks を使用します
4. LRO を適切に処理する — プールのサイズ変更や削除操作は長時間実行されます
5. タスク数を監視する — getJobTaskCounts を使用して進行状況を追跡します
6. 制約を設定する — maxWallClockTime と maxTaskRetryCount を構成します
7. 低優先度ノードを使用する — 障害許容性のあるワークロードのコストを削減できます
8. 自動スケールを有効にする — ワークロードに応じてプールのサイズを動的に調整します

参考リンク

リソース	URL
Maven パッケージ	https://central.sonatype.com/artifact/com.azure/azure-compute-batch
GitHub	https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/batch/azure-compute-batch
API ドキュメント	https://learn.microsoft.com/java/api/com.azure.compute.batch
製品ドキュメント	https://learn.microsoft.com/azure/batch/
REST API	https://learn.microsoft.com/rest/api/batchservice/
サンプル	https://github.com/azure/azure-batch-samples

使用する状況

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用できます。

制限事項

• 上記の説明にある範囲とタスクが明確に一致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認してください。