Pools - Replace Pool Properties

サービス:: Batch Service

API バージョン:: 2025-06-01

指定されたプールのプロパティを更新します。
これにより、プールの更新可能なプロパティはすべて置き換えられます。例えば、プールにStartTaskが関連付けられていて、このリクエストでStartTaskが指定されていない場合、バッチサービスは既存のStartTaskを削除します。

POST {endpoint}/pools/{poolId}/updateproperties?api-version=2025-06-01

省略可能なパラメーターを含む:

POST {endpoint}/pools/{poolId}/updateproperties?api-version=2025-06-01&timeOut={timeOut}

URI パラメーター

名前	/	必須	型	説明
endpoint	path	True	string (uri)	Batch アカウントエンドポイント (例: https://batchaccount.eastus2.batch.azure.com)。
poolId	path	True	string	プールのIDを更新してください。
api-version	query	True	string minLength: 1	この操作に使用する API バージョン。
timeOut	query		integer (int32)	サーバーが要求の処理に費やすことができる最大時間 (秒単位)。既定値は 30 秒です。値が30より大きい場合は、デフォルトが使われます。」

要求ヘッダー

Media Types: "application/json; odata=minimalmetadata"

名前	型	説明
client-request-id	string	呼び出し元によって生成された要求 ID。中かっこなどの装飾のない GUID の形式 (例: 9C4D50EE-2D56-4CD3-8152-34347DC9F2B0)。
return-client-request-id	boolean	サーバーが応答で client-request-id を返す必要があるかどうか。
ocp-date	string (date-time-rfc7231)	要求が発行された時刻。通常、クライアントライブラリはこれを現在のシステムクロック時間に設定します。REST API を直接呼び出す場合は、明示的に設定します。

要求本文

Media Types: "application/json; odata=minimalmetadata"

名前	必須	型	説明
applicationPackageReferences	True	BatchApplicationPackageReference[]	プール内の各コンピューティングノードにインストールするアプリケーションパッケージの一覧。この一覧は、プール上の既存のアプリケーションパッケージ参照を置き換えます。アプリケーションパッケージ参照への変更は、プールに参加しているすべての新しいコンピューティングノードに影響しますが、再起動または再イメージ化されるまで、既にプール内にあるコンピューティングノードには影響しません。特定のプールには、最大 10 個のアプリケーションパッケージ参照があります。省略した場合、または空のコレクションを指定した場合は、既存のアプリケーションパッケージ参照がプールから削除されます。特定のプールでは、最大 10 個の参照を指定できます。
metadata	True	BatchMetadataItem[]	メタデータとしてプールに関連付けられている名前と値のペアの一覧。この一覧は、プールで構成されている既存のメタデータを置き換えます。省略した場合、または空のコレクションを指定した場合は、既存のメタデータがプールから削除されます。
startTask		BatchStartTask	プールに参加する各コンピューティングノードで実行するタスク。タスクは、コンピューティングノードがプールに追加されたとき、またはコンピューティングノードが再起動されたときに実行されます。この要素が存在する場合は、既存の StartTask が上書きされます。省略すると、既存の StartTask がプールから削除されます。

応答

名前	型	説明
204 No Content		この要求に送信するコンテンツはありませんが、ヘッダーが役立つ場合があります。ヘッダー DataServiceId: string ETag: string Last-Modified: string client-request-id: string request-id: string
Other Status Codes	BatchError	予期しないエラー応答。

名前

型

説明

204 No Content

この要求に送信するコンテンツはありませんが、ヘッダーが役立つ場合があります。

ヘッダー

DataServiceId: string
ETag: string
Last-Modified: string
client-request-id: string
request-id: string

Other Status Codes

BatchError

予期しないエラー応答。

セキュリティ

OAuth2Auth

型: oauth2
フロー: implicit
Authorization URL (承認 URL): https://login.microsoftonline.com/common/oauth2/v2.0/authorize

スコープ

名前	説明
https://batch.core.windows.net//.default

例

Pool update

要求のサンプル

HTTP

POST {endpoint}/pools/poolId/updateproperties?api-version=2025-06-01



{
  "startTask": {
    "commandLine": "/bin/bash -c 'echo start task'"
  },
  "applicationPackageReferences": [],
  "metadata": []
}

応答のサンプル

状態コード:: 204

定義

名前	説明
AutoUserScope	AutoUserScopeの列挙
AutoUserSpecification	Azure Batch タスクを実行する自動ユーザーのオプションを指定します。
BatchApplicationPackageReference	コンピューティングノードにデプロイするパッケージへの参照。
BatchError	Azure Batch サービスから受信したエラー応答。
BatchErrorDetail	Azure Batch エラー応答に含まれる追加情報の項目。
BatchErrorMessage	Azure Batch エラー応答で受信したエラーメッセージ。
BatchMetadataItem	Batch サービスは、このメタデータに意味を割り当てません。これは、ユーザーコードの使用のみを目的とします。
BatchNodeIdentityReference	コンピューティングノードが使用する Batch プールに関連付けられているユーザー割り当て ID への参照。
BatchPoolReplaceOptions	Azure Batch プールのプロパティを置き換えるパラメーター。
BatchStartTask	Batch は、ノードで復旧操作がトリガーされたときにタスクを再試行します。復旧操作の例としては、異常なノードが再起動されたときや、ホスト障害が原因でコンピューティングノードが消えた場合などです (ただし、これらに限定されません)。回復操作による再試行は独立しており、maxTaskRetryCount に対してカウントされません。 maxTaskRetryCount が 0 の場合でも、復旧操作による内部再試行が発生する可能性があります。このため、すべてのタスクはべき等である必要があります。つまり、タスクは、破損やデータの重複を引き起こさずに中断および再起動されることを許容する必要があります。実行時間の長いタスクのベストプラクティスは、何らかの形式のチェックポイント処理を使用することです。場合によっては、コンピューティングノードが再起動されなかった場合でも、StartTask が再実行されることがあります。中断プロセスを作成したり、StartTask 作業ディレクトリからサービスをインストール/起動したりする StartTask を回避するには、特別な注意が必要です。これにより、Batch で StartTask を再実行できなくなるためです。
BatchTaskContainerSettings	タスクのコンテナー設定。
ContainerHostBatchBindMountEntry	タスクコンテナーにマウントするパスとマウントモードのエントリ。
ContainerHostDataPath	コンテナータスクのコンテナーにマウントされるパス。
ContainerRegistryReference	プライベートコンテナーレジストリ。
ContainerWorkingDirectory	ContainerWorkingDirectory 列挙
ElevationLevel	ElevationLevel 列挙
EnvironmentSetting	タスクプロセスで設定する環境変数。
ResourceFile	コンピューティングノードにダウンロードする 1 つのファイルまたは複数のファイル。
UserIdentity	タスクを実行するユーザー ID の定義。 userName プロパティまたは autoUser プロパティを指定しますが、両方を指定することはできません。

AutoUserScope

列挙

AutoUserScopeの列挙

値	説明
task	サービスがタスクのために新しいユーザーを作成することを指定します。
pool	タスクがプール内の各コンピュートノードで作成される共通自動ユーザーアカウントとして実行されることを指定します。

AutoUserSpecification

Object

Azure Batch タスクを実行する自動ユーザーのオプションを指定します。

名前	型	説明
elevationLevel	ElevationLevel	自動ユーザーの昇格レベル。既定値は nonAdmin です。
scope	AutoUserScope	自動ユーザーのスコープ。既定値は pool です。プールが Windows を実行している場合は、タスク間のより厳密な分離が必要な場合は、Task の値を指定する必要があります。たとえば、タスクが他のタスクに影響を与える可能性のある方法でレジストリを変更する場合などです。

BatchApplicationPackageReference

Object

コンピューティングノードにデプロイするパッケージへの参照。

名前	型	説明
applicationId	string	デプロイするアプリケーションのID。プールを作成する場合、パッケージのアプリケーション ID は完全修飾 (/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Batch/batchAccounts/{accountName}/applications/{applicationName}) である必要があります。
version	string	デプロイするアプリケーションのバージョン。省略すると、既定のバージョンがデプロイされます。もしプール上でこれを省略し、このアプリケーションにデフォルトバージョンが指定されていない場合、リクエストはInvalidApplicationPackageReferencesエラーコードとHTTPステータスコード409で失敗します。もしタスクでこれが省略され、かつそのアプリケーションにデフォルトバージョンが指定されていない場合、タスクは前処理エラーで失敗します。

BatchError

Object

Azure Batch サービスから受信したエラー応答。

名前	型	説明
code	string	エラーの識別子。コードは不変であり、プログラムで使用することを目的としています。
message	BatchErrorMessage	ユーザーインターフェイスでの表示に適したエラーを説明するメッセージ。
values	BatchErrorDetail[]	エラーに関する追加の詳細を含むキーと値のペアのコレクション。

BatchErrorDetail

Object

Azure Batch エラー応答に含まれる追加情報の項目。

名前	型	説明
key	string	Value プロパティの意味を指定する識別子。
value	string	エラー応答に含まれる追加情報。

BatchErrorMessage

Object

Azure Batch エラー応答で受信したエラーメッセージ。

名前	型	説明
lang	string	エラーメッセージの言語コード。
value	string	メッセージのテキスト。

BatchMetadataItem

Object

Batch サービスは、このメタデータに意味を割り当てません。これは、ユーザーコードの使用のみを目的とします。

名前	型	説明
name	string	メタデータ項目の名前。
value	string	メタデータ項目の値。

BatchNodeIdentityReference

Object

コンピューティングノードが使用する Batch プールに関連付けられているユーザー割り当て ID への参照。

名前	型	説明
resourceId	string (arm-id)	ユーザー割り当て ID の ARM リソース ID。

BatchPoolReplaceOptions

Object

Azure Batch プールのプロパティを置き換えるパラメーター。

名前	型	説明
applicationPackageReferences	BatchApplicationPackageReference[]	プール内の各コンピューティングノードにインストールするアプリケーションパッケージの一覧。この一覧は、プール上の既存のアプリケーションパッケージ参照を置き換えます。アプリケーションパッケージ参照への変更は、プールに参加しているすべての新しいコンピューティングノードに影響しますが、再起動または再イメージ化されるまで、既にプール内にあるコンピューティングノードには影響しません。特定のプールには、最大 10 個のアプリケーションパッケージ参照があります。省略した場合、または空のコレクションを指定した場合は、既存のアプリケーションパッケージ参照がプールから削除されます。特定のプールでは、最大 10 個の参照を指定できます。
metadata	BatchMetadataItem[]	メタデータとしてプールに関連付けられている名前と値のペアの一覧。この一覧は、プールで構成されている既存のメタデータを置き換えます。省略した場合、または空のコレクションを指定した場合は、既存のメタデータがプールから削除されます。
startTask	BatchStartTask	プールに参加する各コンピューティングノードで実行するタスク。タスクは、コンピューティングノードがプールに追加されたとき、またはコンピューティングノードが再起動されたときに実行されます。この要素が存在する場合は、既存の StartTask が上書きされます。省略すると、既存の StartTask がプールから削除されます。

BatchStartTask

Object

Batch は、ノードで復旧操作がトリガーされたときにタスクを再試行します。復旧操作の例としては、異常なノードが再起動されたときや、ホスト障害が原因でコンピューティングノードが消えた場合などです (ただし、これらに限定されません)。回復操作による再試行は独立しており、maxTaskRetryCount に対してカウントされません。 maxTaskRetryCount が 0 の場合でも、復旧操作による内部再試行が発生する可能性があります。このため、すべてのタスクはべき等である必要があります。つまり、タスクは、破損やデータの重複を引き起こさずに中断および再起動されることを許容する必要があります。実行時間の長いタスクのベストプラクティスは、何らかの形式のチェックポイント処理を使用することです。場合によっては、コンピューティングノードが再起動されなかった場合でも、StartTask が再実行されることがあります。中断プロセスを作成したり、StartTask 作業ディレクトリからサービスをインストール/起動したりする StartTask を回避するには、特別な注意が必要です。これにより、Batch で StartTask を再実行できなくなるためです。

名前	型	説明
commandLine	string	StartTask のコマンドライン。コマンドラインはシェルでは実行されないため、環境変数の拡張などのシェル機能を利用することはできません。このような機能を利用する場合は、コマンドラインでシェルを呼び出す必要があります。たとえば、Windows では "cmd /c MyCommand" を使用し、Linux では "/bin/sh -c MyCommand" を使用します。コマンドラインがファイルパスを参照している場合は、相対パス (Task 作業ディレクトリに対する相対パス) を使用するか、Batch で指定された環境変数 (https://learn.microsoft.com/azure/batch/batch-compute-node-environment-variables) を使用する必要があります。
containerSettings	BatchTaskContainerSettings	StartTaskが動作するコンテナの設定。これが指定されると、ノード上のAzure BatchディレクトリのルートであるAZ_BATCH_NODE_ROOT_DIRより下のすべてのディレクトリが再帰的にコンテナにマッピングされ、すべてのタスク環境変数がコンテナにマッピングされ、タスクコマンドラインがコンテナ内で実行されます。 AZ_BATCH_NODE_ROOT_DIR以外のコンテナで生成されたファイルはホストディスクに反映されない可能性があり、バッチファイルのAPIはそれらのファイルにアクセスできません。
environmentSettings	EnvironmentSetting[]	StartTask の環境変数設定の一覧。
maxTaskRetryCount	integer (int32)	タスクを再試行できる最大回数。終了コードが 0 以外の場合、Batch サービスはタスクを再試行します。この値は、再試行回数を特に制御します。 Batch サービスはタスクを 1 回試し、この制限まで再試行できます。たとえば、最大再試行回数が 3 の場合、Batch はタスクを最大 4 回試行します (1 回の最初の再試行と 3 回の再試行)。最大再試行回数が 0 の場合、Batch サービスはタスクを再試行しません。最大再試行回数が -1 の場合、Batch サービスは制限なくタスクを再試行しますが、これは開始タスクまたはタスクには推奨されません。既定値は 0 (再試行なし) です。
resourceFiles	ResourceFile[]	コマンドラインを実行する前に Batch サービスがコンピューティングノードにダウンロードするファイルの一覧。リソースファイルの一覧には最大サイズがあります。最大サイズを超えると、要求は失敗し、応答エラーコードは RequestEntityTooLarge になります。この場合、ResourceFiles のコレクションのサイズを小さくする必要があります。これは、.zip ファイル、アプリケーションパッケージ、または Docker コンテナーを使用して実現できます。この要素の下に一覧表示されるファイルは、タスクの作業ディレクトリにあります。
userIdentity	UserIdentity	StartTaskが動作するユーザーIDです。省略すると、タスクはタスク固有の非管理者ユーザーとして動作します。
waitForSuccess	boolean	コンピューティングノードでタスクをスケジュールする前に、Batch サービスが StartTask が正常に完了するまで (つまり、終了コード 0 で終了する) のを待つ必要があるかどうか。 True で、ノードで StartTask が失敗した場合、Batch サービスは StartTask を最大再試行回数 (maxTaskRetryCount) まで再試行します。すべての再試行の後もタスクが正常に完了していない場合、Batch サービスはノードを使用不可としてマークし、タスクをスケジュールしません。この状態は、コンピューティングノードの状態とエラー情報の詳細を使用して検出できます。 false の場合、Batch サービスは StartTask の完了を待機しません。この場合、StartTask がまだ実行されている間に、コンピューティングノードで他のタスクの実行を開始できます。StartTask が失敗した場合でも、新しいタスクはコンピューティングノードで引き続きスケジュールされます。既定値は true です。

BatchTaskContainerSettings

Object

タスクのコンテナー設定。

名前	型	説明
containerHostBatchBindMounts	ContainerHostBatchBindMountEntry[]	コンテナータスクにマウントするパス。この配列が null または存在しない場合、コンテナータスクは一時ディスクドライブ全体を Windows (または Linux では AZ_BATCH_NODE_ROOT_DIR) にマウントします。この配列が空として設定されている場合、データパスはコンテナーにマウントされません。
containerRunOptions	string	コンテナー作成コマンドの追加オプション。これらの追加オプションは、Batch サービスによって制御されるオプションに加えて、"docker create" コマンドの引数として提供されます。
imageName	string	タスクを実行するコンテナを作成するために使うイメージ。これは「docker pull」で指定される完全なイメージ参照です。画像名にタグが記載されていない場合は、デフォルトとして「:latest」タグが使われます。
registry	ContainerRegistryReference	コンテナイメージを含むプライベートレジストリです。この設定はプール作成時にすでに提供されていた場合は省略しても構いません。
workingDirectory	ContainerWorkingDirectory	コンテナタスクワーキングディレクトリの場所。既定値は 'taskWorkingDirectory' です。

ContainerHostBatchBindMountEntry

Object

タスクコンテナーにマウントするパスとマウントモードのエントリ。

名前	型	説明
isReadOnly	boolean	このソースパスを読み取り専用モードとしてマウントするかどうか。既定値は false (読み取り/書き込みモード) です。 Linux の場合、このパスを読み取り/書き込みモードとしてマウントした場合、コンテナー内のすべてのユーザーがパスの読み取り/書き込みアクセス権を持っているわけではありません。これは、ホスト VM のアクセスに依存します。このパスが読み取り専用でマウントされている場合、コンテナー内のすべてのユーザーはパスを変更できません。
source	ContainerHostDataPath	コンテナー顧客にマウントするパスを選択できます。

ContainerHostDataPath

列挙

コンテナータスクのコンテナーにマウントされるパス。

値	説明
Shared	複数インスタンスのタスクがファイルを共有するためのパス。
Startup	開始タスクのパス。
VfsMounts	パスには、このノードにマウントされているすべての仮想ファイルシステムが含まれています。
Task	タスクパス。
JobPrep	ジョブ準備タスクのパス。
Applications	アプリケーションパス。

ContainerRegistryReference

Object

プライベートコンテナーレジストリ。

名前	型	説明
identityReference	BatchNodeIdentityReference	ユーザー名とパスワードではなく、Azure Container Registry へのアクセスに使用するユーザー割り当て ID への参照。
password	string (password)	レジストリサーバーにログインするためのパスワード。
registryServer	string (uri)	レジストリ URL。省略した場合、既定値は "docker.io" です。
username	string	レジストリサーバーにログインするユーザー名。

ContainerWorkingDirectory

列挙

ContainerWorkingDirectory 列挙

値	説明
taskWorkingDirectory	標準のバッチサービスのタスク作業ディレクトリを使用してください。そこにはバッチによって埋め込まれたタスクリソースファイルが含まれます。
containerImageDefault	コンテナImageで定義されたワーキングディレクトリを使いましょう。ただし、このディレクトリにはバッチでダウンロードされたリソースファイルは含まれていないことに注意してください。

ElevationLevel

列挙

ElevationLevel 列挙

値	説明
nonadmin	ユーザーは、昇格されたアクセス権を持たない標準ユーザーです。
admin	ユーザーは昇格されたアクセス権を持つユーザーであり、完全な管理者権限で動作します。

EnvironmentSetting

Object

タスクプロセスで設定する環境変数。

名前	型	説明
name	string	環境変数の名前。
value	string	環境変数の値。

ResourceFile

Object

コンピューティングノードにダウンロードする 1 つのファイルまたは複数のファイル。

名前	型	説明
autoStorageContainerName	string	自動ストレージアカウントのストレージコンテナ名です。 autoStorageContainerName、storageContainerUrl、および httpUrl プロパティは相互に排他的であり、そのうちの 1 つを指定する必要があります。
blobPrefix	string	Azure Storage コンテナーから BLOB をダウンロードするときに使用する BLOB プレフィックス。指定したプレフィックスで始まる名前の BLOB のみがダウンロードされます。このプロパティは、autoStorageContainerName または storageContainerUrl が使用されている場合にのみ有効です。このプレフィックスには、部分的なファイル名またはサブディレクトリを指定できます。プレフィックスが指定されていない場合は、コンテナー内のすべてのファイルがダウンロードされます。
fileMode	string	ファイルアクセス許可モード属性 (8 進数形式)。この特性は、Linux Compute Nodesにダウンロードされるファイルにのみ適用されます。 WindowsのCompute NodeにダウンロードされるresourceFileに指定されている場合は無視されます。このプロパティがLinuxのコンピュートノードに指定されていない場合、ファイルにはデフォルト値0770が適用されます。
filePath	string	タスクの作業ディレクトリに対してファイルをダウンロードするためのComputeノード上の位置。 httpUrl プロパティが指定されている場合、filePath は必須であり、ファイルのダウンロード先となるパス (ファイル名を含む) を記述します。それ以外の場合、autoStorageContainerName または storageContainerUrl プロパティが指定されている場合、filePath は省略可能であり、ファイルをダウンロードするディレクトリです。 filePath がディレクトリとして使用されている場合、入力データに既に関連付けられているディレクトリ構造は完全に保持され、指定された filePath ディレクトリに追加されます。指定された相対パスはタスクの作業ディレクトリから抜け出すことはできません(例えば「..」を使うなど)。
httpUrl	string (uri)	ダウンロードするファイルの URL。 autoStorageContainerName、storageContainerUrl、および httpUrl プロパティは相互に排他的であり、そのうちの 1 つを指定する必要があります。 URL が Azure Blob Storage を指している場合は、コンピューティングノードから読み取ることができる必要があります。 Azure Storage 内の BLOB のこのような URL を取得するには、3 つの方法があります。BLOB に対する読み取りアクセス許可を付与する Shared Access Signature (SAS) を含めるか、読み取りアクセス許可を持つマネージド ID を使用するか、BLOB またはそのコンテナーの ACL を設定してパブリックアクセスを許可します。
identityReference	BatchNodeIdentityReference	storageContainerUrlまたはhttpUrlで指定されたAzure Blob Storageにアクセスするために使うユーザー割り当てのIDを参照します。
storageContainerUrl	string (uri)	Azure Blob Storage 内の BLOB コンテナーの URL。 autoStorageContainerName、storageContainerUrl、および httpUrl プロパティは相互に排他的であり、そのうちの 1 つを指定する必要があります。この URL は、コンピューティングノードから読み取り可能でリスト可能である必要があります。 Azure Storage 内のコンテナーのこのような URL を取得するには、3 つの方法があります。コンテナーに対する読み取りと一覧表示のアクセス許可を付与する Shared Access Signature (SAS) を含めるか、読み取りとリストのアクセス許可を持つマネージド ID を使用するか、コンテナーの ACL を設定してパブリックアクセスを許可します。

UserIdentity

Object

タスクを実行するユーザー ID の定義。 userName プロパティまたは autoUser プロパティを指定しますが、両方を指定することはできません。

名前	型	説明
autoUser	AutoUserSpecification	タスクを実行する自動ユーザーです。 userName プロパティと autoUser プロパティは相互に排他的です。1 つを指定する必要がありますが、両方を指定する必要はありません。
username	string	タスクが実行されるユーザーIDの名前。 userName プロパティと autoUser プロパティは相互に排他的です。1 つを指定する必要がありますが、両方を指定する必要はありません。

次の方法で共有

Pools - Replace Pool Properties

URI パラメーター

要求ヘッダー

要求本文

応答

セキュリティ

OAuth2Auth

スコープ

例

Pool update

要求のサンプル

応答のサンプル

定義

AutoUserScope

AutoUserSpecification

BatchApplicationPackageReference

BatchError

BatchErrorDetail

BatchErrorMessage

BatchMetadataItem

BatchNodeIdentityReference

BatchPoolReplaceOptions

BatchStartTask

BatchTaskContainerSettings

ContainerHostBatchBindMountEntry

ContainerHostDataPath

ContainerRegistryReference

ContainerWorkingDirectory

ElevationLevel

EnvironmentSetting

ResourceFile

UserIdentity