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 參數

名稱	位於	必要	類型	Description
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"

名稱	類型	Description
client-request-id	string	呼叫端產生的要求身分識別，格式為 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"

名稱	必要	類型	Description
applicationPackageReferences	True	BatchApplicationPackageReference[]	要安裝在集區中每個計算節點上的應用程式套件清單。此清單會取代集區上任何現有的應用程式套件參考。應用程式套件參考的變更會影響聯結集區的所有新計算節點，但在重新啟動或重新映像之前，不會影響已在集區中的計算節點。在任何指定的集區上，最多有10個應用程式套件參考。如果省略，或如果您指定空集合，則會從集區中移除任何現有的應用程式套件參考。在指定的集區上最多可以指定10個參考。
metadata	True	BatchMetadataItem[]	與集區相關聯的名稱/值組清單做為元數據。此清單會取代集區上設定的任何現有元數據。如果省略，或如果您指定空集合，則會從集區中移除任何現有的元數據。
startTask		BatchStartTask	在聯結集區時，要在每個計算節點上執行的工作。當計算節點新增至集區或計算節點重新啟動時，工作就會執行。如果此元素存在，則會覆寫任何現有的 StartTask。如果省略，則會從集區中移除任何現有的 StartTask。

回應

名稱	類型	Description
204 No Content		此要求沒有內容可傳送，但標頭可能很有用。標題 DataServiceId: string ETag: string Last-Modified: string client-request-id: string request-id: string
Other Status Codes	BatchError	未預期的錯誤回應。

名稱

類型

Description

204 No Content

此要求沒有內容可傳送，但標頭可能很有用。

標題

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

Other Status Codes

BatchError

未預期的錯誤回應。

安全性

OAuth2Auth

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

範圍

名稱	Description
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

定義

名稱	Description
AutoUserScope	AutoUserScope 枚舉
AutoUserSpecification	指定執行 Azure Batch 工作的自動用戶選項。
BatchApplicationPackageReference	要部署到計算節點之封裝的參考。
BatchError	從 Azure Batch 服務收到的錯誤回應。
BatchErrorDetail	Azure Batch 錯誤回應中包含的其他信息專案。
BatchErrorMessage	Azure Batch 錯誤回應中收到的錯誤訊息。
BatchMetadataItem	Batch 服務不會指派任何意義給此元數據;它僅供使用者程式代碼使用。
BatchNodeIdentityReference	與計算節點將使用的 Batch 集區相關聯的使用者指派身分識別參考。
BatchPoolReplaceOptions	用來取代 Azure Batch 集區上屬性的參數。
BatchStartTask	批次會在節點上觸發復原作業時重試工作。復原作業的範例包括當狀況不良的節點重新啟動或計算節點因主機失敗而消失時，包括（但不限於）。由於復原作業的重試與無關，而且不會計入 maxTaskRetryCount。即使 maxTaskRetryCount 是 0，由於復原作業，可能會發生內部重試。因此，所有工作都應該是等冪的。這表示工作必須容許中斷並重新啟動，而不會造成任何損毀或重複的數據。長時間執行工作的最佳做法是使用某種形式的檢查點。在某些情況下，即使計算節點未重新啟動，StartTask 仍可能會重新執行。請特別小心，以避免 StartTasks 從 StartTask 工作目錄建立中斷程式或安裝/啟動服務，因為這樣會阻止 Batch 重新執行 StartTask。
BatchTaskContainerSettings	工作的容器設定。
ContainerHostBatchBindMountEntry	您想要掛接至工作容器的路徑和掛接模式專案。
ContainerHostDataPath	要掛接至容器工作容器的路徑。
ContainerRegistryReference	私人容器登錄。
ContainerWorkingDirectory	ContainerWorkingDirectory 枚舉
ElevationLevel	高程層列舉
EnvironmentSetting	要設定於工作進程的環境變數。
ResourceFile	要下載至計算節點的單一檔案或多個檔案。
UserIdentity	執行工作的使用者身分識別定義。指定userName或 autoUser 屬性，但不能同時指定兩者。

AutoUserScope

列舉型別

AutoUserScope 枚舉

值	Description
task	指定服務應為該任務建立新使用者。
pool	指定該任務作為共用的自動使用者帳號執行，該帳號會在池中每個運算節點建立。

AutoUserSpecification

Object

指定執行 Azure Batch 工作的自動用戶選項。

名稱	類型	Description
elevationLevel	ElevationLevel	自動使用者的提高許可權層級。預設值為 nonAdmin。
scope	AutoUserScope	自動用戶的範圍。預設值為集區。如果集區正在執行 Windows，則當需要更嚴格的工作隔離時，應該指定 Task 的值。例如，如果工作以可能影響其他工作的方式改變登錄。

BatchApplicationPackageReference

Object

要部署到計算節點之封裝的參考。

名稱	類型	Description
applicationId	string	要部署的應用程式 ID。建立集區時，套件的應用程式標識碼必須完整（/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Batch/batchAccounts/{accountName}/applications/{applicationName}）。
version	string	要部署的應用程式版本。如果省略，則會部署預設版本。若池中省略此項，且未指定預設版本，請求將以錯誤代碼 InvalidApplicationPackageReferences 及 HTTP 狀態碼 409 失敗。若任務中省略此功能，且未指定預設版本，該任務將因預處理錯誤而失敗。

BatchError

Object

從 Azure Batch 服務收到的錯誤回應。

名稱	類型	Description
code	string	錯誤的識別碼。程序代碼是不變的，而且是要以程序設計方式取用。
message	BatchErrorMessage	描述錯誤的訊息，適用於在使用者介面中顯示。
values	BatchErrorDetail[]	索引鍵/值組的集合，其中包含錯誤的其他詳細數據。

BatchErrorDetail

Object

Azure Batch 錯誤回應中包含的其他信息專案。

名稱	類型	Description
key	string	指定 Value 屬性意義的識別碼。
value	string	錯誤回應隨附的其他資訊。

BatchErrorMessage

Object

Azure Batch 錯誤回應中收到的錯誤訊息。

名稱	類型	Description
lang	string	錯誤訊息的語言代碼。
value	string	訊息的文字。

BatchMetadataItem

Object

Batch 服務不會指派任何意義給此元數據;它僅供使用者程式代碼使用。

名稱	類型	Description
name	string	元數據項目的名稱。
value	string	元數據專案的值。

BatchNodeIdentityReference

Object

與計算節點將使用的 Batch 集區相關聯的使用者指派身分識別參考。

名稱	類型	Description
resourceId	string (arm-id)	使用者指派身分識別的 ARM 資源識別碼。

BatchPoolReplaceOptions

Object

用來取代 Azure Batch 集區上屬性的參數。

名稱	類型	Description
applicationPackageReferences	BatchApplicationPackageReference[]	要安裝在集區中每個計算節點上的應用程式套件清單。此清單會取代集區上任何現有的應用程式套件參考。應用程式套件參考的變更會影響聯結集區的所有新計算節點，但在重新啟動或重新映像之前，不會影響已在集區中的計算節點。在任何指定的集區上，最多有10個應用程式套件參考。如果省略，或如果您指定空集合，則會從集區中移除任何現有的應用程式套件參考。在指定的集區上最多可以指定10個參考。
metadata	BatchMetadataItem[]	與集區相關聯的名稱/值組清單做為元數據。此清單會取代集區上設定的任何現有元數據。如果省略，或如果您指定空集合，則會從集區中移除任何現有的元數據。
startTask	BatchStartTask	在聯結集區時，要在每個計算節點上執行的工作。當計算節點新增至集區或計算節點重新啟動時，工作就會執行。如果此元素存在，則會覆寫任何現有的 StartTask。如果省略，則會從集區中移除任何現有的 StartTask。

BatchStartTask

Object

批次會在節點上觸發復原作業時重試工作。復原作業的範例包括當狀況不良的節點重新啟動或計算節點因主機失敗而消失時，包括（但不限於）。由於復原作業的重試與無關，而且不會計入 maxTaskRetryCount。即使 maxTaskRetryCount 是 0，由於復原作業，可能會發生內部重試。因此，所有工作都應該是等冪的。這表示工作必須容許中斷並重新啟動，而不會造成任何損毀或重複的數據。長時間執行工作的最佳做法是使用某種形式的檢查點。在某些情況下，即使計算節點未重新啟動，StartTask 仍可能會重新執行。請特別小心，以避免 StartTasks 從 StartTask 工作目錄建立中斷程式或安裝/啟動服務，因為這樣會阻止 Batch 重新執行 StartTask。

名稱	類型	Description
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	啟動任務所處容器的設定。當指定此位置時，所有位於AZ_BATCH_NODE_ROOT_DIR（節點上 Azure Batch 目錄根節點）下方的目錄會遞迴地映射到容器中，所有任務環境變數也映射到容器中，任務命令列則在容器中執行。容器中產生的檔案可能不會被反映到主機磁碟AZ_BATCH_NODE_ROOT_DIR，導致批次檔案 API 無法存取這些檔案。
environmentSettings	EnvironmentSetting[]	StartTask 的環境變數設定清單。
maxTaskRetryCount	integer (int32)	重試工作的最大次數。如果 Batch 服務結束代碼為非零，則會重試工作。請注意，這個值會特別控制重試次數。 Batch 服務會嘗試工作一次，然後可能會重試到此限制。例如，如果重試計數上限為 3，Batch 會嘗試工作最多 4 次（一次初始嘗試，3 次重試）。如果重試計數上限為0，Batch服務就不會重試工作。如果重試計數上限為 -1，Batch 服務會不限制地重試工作，但不建議用於啟動工作或任何工作。預設值為 0（沒有重試）。
resourceFiles	ResourceFile[]	Batch 服務在執行命令行之前，會先下載至計算節點的檔案清單。資源檔案清單的大小上限。超過大小上限時，要求將會失敗，而回應錯誤碼會是 RequestEntityTooLarge。如果發生這種情況，ResourceFiles 的集合必須縮小大小。這可以使用 .zip 檔案、應用程式套件或 Docker 容器來達成。此元素底下列出的檔案位於工作的工作目錄中。
userIdentity	UserIdentity	啟動任務執行的使用者身份。若省略，該任務將以非管理員使用者身份執行，且是任務獨一無二的使用者。
waitForSuccess	boolean	在排程計算節點上的任何工作之前，Batch 服務是否應該等候 StartTask 順利完成（也就是結束代碼 0）。如果 True 且 StartTask 在節點上失敗，Batch 服務會重試 StartTask，最多重試計數上限（maxTaskRetryCount）。如果工作在所有重試之後仍未順利完成，則 Batch 服務會將節點標示為無法使用，且不會排程工作。您可以透過計算節點狀態和失敗資訊詳細資料來偵測此狀況。如果為 false，Batch 服務將不會等候 StartTask 完成。在此情況下，當 StartTask 仍在執行時，其他工作可以在計算節點上開始執行;即使 StartTask 失敗，新的工作仍會繼續排程在計算節點上。默認值為 true。

BatchTaskContainerSettings

Object

工作的容器設定。

名稱	類型	Description
containerHostBatchBindMounts	ContainerHostBatchBindMountEntry[]	您要掛接至容器工作的路徑。如果此陣列為 Null 或不存在，容器工作將會在 Windows 中掛接整個暫存磁碟驅動器（或 Linux 中的AZ_BATCH_NODE_ROOT_DIR）。如果此陣列設定為空白，它就不會將任何數據路徑掛接至容器。
containerRunOptions	string	容器 create 命令的其他選項。除了 Batch 服務所控制的自變數之外，這些額外的選項也會提供為「docker create」命令的自變數。
imageName	string	用來建立任務執行容器的映像。這是完整的映像參考，正如「docker pull」所指定的。若圖片名稱中未提供標籤，則預設使用標籤「：latest」。
registry	ContainerRegistryReference	包含容器映像檔的私有登錄檔。若在創建池時已提供此設定，則可省略此設定。
workingDirectory	ContainerWorkingDirectory	容器任務工作目錄的位置。默認值為『taskWorkingDirectory』。

ContainerHostBatchBindMountEntry

Object

您想要掛接至工作容器的路徑和掛接模式專案。

名稱	類型	Description
isReadOnly	boolean	將此來源路徑掛接為唯讀模式或否。默認值為 false （讀取/寫入模式）。針對 Linux，如果您將此路徑掛接為讀取/寫入模式，這並不表示容器中的所有使用者都有路徑的讀取/寫入存取權，這取決於主機 VM 中的存取權。如果此路徑是只讀掛接，容器內的所有使用者將無法修改路徑。
source	ContainerHostDataPath	掛接至容器客戶的路徑可以選取。

ContainerHostDataPath

列舉型別

要掛接至容器工作容器的路徑。

值	Description
Shared	要共用其檔案之多重實例工作的路徑。
Startup	開始工作的路徑。
VfsMounts	路徑包含此節點上掛接的所有虛擬檔案系統。
Task	工作路徑。
JobPrep	作業準備工作路徑。
Applications	應用程式路徑。

ContainerRegistryReference

Object

私人容器登錄。

名稱	類型	Description
identityReference	BatchNodeIdentityReference	使用者指派身分識別的參考，用來存取 Azure Container Registry，而不是使用者名稱和密碼。
password	string (password)	登入登錄伺服器的密碼。
registryServer	string (uri)	登錄 URL。如果省略，預設值為「docker.io」。。
username	string	要登入登錄伺服器的用戶名稱。

ContainerWorkingDirectory

列舉型別

ContainerWorkingDirectory 枚舉

值	Description
taskWorkingDirectory	使用標準的批次服務任務工作目錄，該目錄會包含由批次填充的任務資源檔案。
containerImageDefault	請使用容器 Image 中定義的工作目錄。請注意，此目錄不會包含批次下載的資源檔案。

ElevationLevel

列舉型別

高程層列舉

值	Description
nonadmin	使用者是標準使用者，沒有提升許可權的存取權。
admin	使用者是具有較高存取權的使用者，且會以完整的系統管理員許可權運作。

EnvironmentSetting

Object

要設定於工作進程的環境變數。

名稱	類型	Description
name	string	環境變數的名稱。
value	string	環境變數的值。

ResourceFile

Object

要下載至計算節點的單一檔案或多個檔案。

名稱	類型	Description
autoStorageContainerName	string	自動儲存帳戶中的儲存容器名稱。 autoStorageContainerName、storageContainerUrl 和 httpUrl 屬性互斥，其中一個必須指定。
blobPrefix	string	從 Azure 記憶體容器下載 Blob 時要使用的 Blob 前置詞。只會下載名稱開頭為指定前置詞的 Blob。只有在使用 autoStorageContainerName 或 storageContainerUrl 時，屬性才有效。此前置詞可以是部分檔名或子目錄。如果未指定前置詞，則會下載容器中的所有檔案。
fileMode	string	以八進位格式的檔案許可權模式屬性。此特性僅適用於下載至 Linux 運算節點的檔案。如果是為 resourceFile 指定，該檔案會被下載到 Windows 運算節點，則會被忽略。若 Linux 運算節點未指定此屬性，則預設值為 0770。
filePath	string	相對於任務工作目錄，在計算節點上下載檔案的位置。如果指定 HTTPUrl 屬性，則需要 filePath，並描述將下載檔案的路徑，包括檔名。否則，如果指定 autoStorageContainerName 或 storageContainerUrl 屬性，則 filePath 是選擇性的，而且是要下載檔案的目錄。在 filePath 當做目錄使用的情況下，任何已經與輸入數據相關聯的目錄結構都會完整保留，並附加至指定的 filePath 目錄。指定的相對路徑不能從任務的工作目錄中跳出（例如使用「..」）。
httpUrl	string (uri)	要下載之檔案的 URL。 autoStorageContainerName、storageContainerUrl 和 httpUrl 屬性互斥，其中一個必須指定。如果 URL 指向 Azure Blob 記憶體，則必須從計算節點讀取它。在 Azure 記憶體中取得 Blob 的這類 URL 有三種方式：包括授與 Blob 讀取許可權的共用存取簽章（SAS），使用具有讀取許可權的受控識別，或設定 Blob 或其容器的 ACL 以允許公用存取。
identityReference	BatchNodeIdentityReference	這是用來存取 Azure Blob 儲存裝置的使用者指定身份的參考，該身份由 storageContainerUrl 或 httpURL 指定。
storageContainerUrl	string (uri)	Azure Blob 記憶體中 Blob 容器的 URL。 autoStorageContainerName、storageContainerUrl 和 httpUrl 屬性互斥，其中一個必須指定。此 URL 必須可從計算節點讀取和列出。有三種方式可以取得 Azure 記憶體中容器的這類 URL：包括授與容器讀取和清單許可權的共用存取簽章（SAS），使用具有讀取和清單許可權的受控識別，或為容器設定 ACL 以允許公用存取。

UserIdentity

Object

執行工作的使用者身分識別定義。指定userName或 autoUser 屬性，但不能同時指定兩者。

名稱	類型	Description
autoUser	AutoUserSpecification	執行任務的自動使用者。 userName 和 autoUser 屬性互斥;您必須指定一個，但不能同時指定兩者。
username	string	任務執行時所使用的使用者身份名稱。 userName 和 autoUser 屬性互斥;您必須指定一個，但不能同時指定兩者。

共用方式為

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