Pool - Patch

服務:

Batch Service

API 版本:

2023-11-01.18.0

匯報 指定集區的屬性。
這隻會取代要求中指定的集區屬性。 例如，如果集區有與其相關聯的 StartTask，而且要求未指定 StartTask 元素，則 Pool 會保留現有的 StartTask。

PATCH {batchUrl}/pools/{poolId}?api-version=2023-11-01.18.0

含選擇性參數:

PATCH {batchUrl}/pools/{poolId}?timeout={timeout}&api-version=2023-11-01.18.0

URI 參數

名稱	位於	必要	類型	Description
batchUrl	path	True	string	所有 Azure Batch 服務要求的基底 URL。
poolId	path	True	string	要更新之集區的標識碼。
api-version	query	True	string	用戶端 API 版本。
timeout	query		integer int32	伺服器可以花費在處理要求的最大時間，以秒為單位。 預設值為 30 秒。

要求標頭

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

名稱	必要	類型	Description
client-request-id		string uuid	呼叫端產生的要求識別，格式為不含大括弧的 GUID，例如大括弧，例如 9C4D50EE-2D56-4CD3-8152-34347DC9F2B0。
return-client-request-id		boolean	伺服器是否應該在回應中傳回 client-request-id。
ocp-date		string date-time-rfc1123	發出要求的時間。 用戶端連結庫通常會將此設定為目前的系統時鐘時間;如果您要直接呼叫 REST API，請明確設定它。
If-Match		string	與用戶端已知資源版本的 ETag 值相關聯。 只有在服務上資源的目前 ETag 完全符合用戶端所指定的值時，才會執行作業。
If-None-Match		string	與用戶端已知資源版本的 ETag 值相關聯。 只有在服務的目前 ETag 不符合用戶端所指定的值時，才會執行作業。
If-Modified-Since		string date-time-rfc1123	時間戳，表示用戶端已知資源的上次修改時間。 只有在服務上的資源自指定時間以來已修改時，才會執行作業。
If-Unmodified-Since		string date-time-rfc1123	時間戳，表示用戶端已知資源的上次修改時間。 只有在服務上的資源自指定時間之後尚未修改時，才會執行作業。

要求本文

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

名稱	類型	Description
applicationPackageReferences	ApplicationPackageReference[]	要安裝在集區中每個計算節點上的套件清單。 套件參考的變更會影響聯結集區的所有新節點，但不會影響已在集區中的計算節點，直到重新啟動或重新製作映像為止。 如果這個專案存在，它會取代任何現有的套件參考。 如果您指定空集合，則會從集區中移除所有封裝參考。 如果省略，則任何現有的套件參考會保持不變。
certificateReferences	CertificateReference[]	要安裝在集區中每個計算節點上的憑證清單。 如果這個專案存在，它會取代集區上設定的任何現有憑證參考。 如果省略，則任何現有的憑證參考會保持不變。 針對 Windows 節點，Batch 服務會將憑證安裝到指定的證書存儲和位置。 針對 Linux 計算節點，憑證會儲存在工作工作目錄內的目錄中，並將環境變數AZ_BATCH_CERTIFICATES_DIR提供給工作來查詢此位置。 對於可見度為 'remoteUser' 的憑證，會在使用者的主目錄中建立 'certs' 目錄 (，例如 /home/{user-name}/certs) ，而 Certificates 會放在該目錄中。 警告：此屬性已被取代，將在 2024 年 2 月之後移除。 請改用 Azure KeyVault 擴充功能 。
metadata	MetadataItem[]	與集區相關聯的名稱/值組清單作為元數據。 如果這個專案存在，它會取代集區上設定的任何現有元數據。 如果您指定空集合，則會從集區中移除任何元數據。 如果省略，任何現有的元數據會保持不變。
startTask	StartTask	加入集區時，要在每個計算節點上執行的工作。 當計算節點新增至集區或重新啟動計算節點時，工作就會執行。 如果此元素存在，則會覆寫任何現有的 StartTask。 如果省略，則任何現有的 StartTask 會保持不變。
targetNodeCommunicationMode	NodeCommunicationMode	集區所需的節點通訊模式。 如果存在此元素，它會取代集區上設定的現有 targetNodeCommunicationMode。 如果省略，任何現有的元數據會保持不變。

回應

名稱	類型	Description
200 OK		Batch 服務的要求成功。 標題 client-request-id: string request-id: string ETag: string Last-Modified: string DataServiceId: string
Other Status Codes	BatchError	Batch 服務的錯誤。

安全性

azure_auth

Microsoft Entra OAuth 2.0 驗證碼流程

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

範圍

名稱	Description
user_impersonation	模擬您的用戶帳戶

Authorization

類型: apiKey
位於: header

範例

Patch the Pool

範例要求

HTTP

PATCH account.region.batch.azure.com/pools/poolId?api-version=2023-11-01.18.0



{
  "startTask": {
    "commandLine": "/bin/bash -c 'echo start task'"
  }
}

範例回覆

狀態碼:

200

定義

名稱	Description
ApplicationPackageReference	要部署到計算節點之封裝的參考。
AutoUserScope	自動用戶的範圍
AutoUserSpecification	指定在 Batch 服務上執行工作之自動用戶的參數。
BatchError	從 Azure Batch 服務收到的錯誤回應。
BatchErrorDetail	Azure Batch 錯誤回應中包含的其他信息專案。
CertificateReference	要安裝在集區中計算節點上之憑證的參考。
CertificateStoreLocation	要在其中安裝憑證之計算節點上的證書存儲位置。
CertificateVisibility	計算節點上的哪些用戶帳戶應該可以存取憑證的私人數據。
ComputeNodeIdentityReference	與計算節點將使用之 Batch 集區相關聯的使用者指派身分識別參考。
ContainerRegistry	私人容器登錄。
ContainerWorkingDirectory	容器Task工作目錄的位置。
ElevationLevel	使用者的提高許可權層級。
EnvironmentSetting	要設定於工作進程的環境變數。
ErrorMessage	在 Azure Batch 錯誤回應中收到的錯誤訊息。
MetadataItem	與 Batch 服務資源相關聯的名稱/值組。
NodeCommunicationMode	決定集區如何與 Batch 服務通訊。
PoolPatchParameter	要對集區進行的一組變更。
ResourceFile	要下載至計算節點的單一檔案或多個檔案。
StartTask	當節點加入 Azure Batch 服務中的集區，或計算節點重新啟動或重新映射時，就會執行的工作。
TaskContainerSettings	Task 的容器設定。
UserIdentity	執行工作的使用者身分識別定義。

ApplicationPackageReference

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

名稱	類型	Description
applicationId	string	要部署之應用程式的標識碼。 建立集區時，套件的應用程式標識碼必須完整 (/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Batch/batchAccounts/{accountName}/applications/{applicationName}) 。
version	string	要部署的應用程式版本。 如果省略，則會部署預設版本。 如果在集區上省略此專案，而且未為此應用程式指定預設版本，要求就會失敗，並出現錯誤碼 InvalidApplicationPackageReferences 和 HTTP 狀態代碼 409。 如果在 Task 上省略此專案，且未為此應用程式指定預設版本，則 Task 會失敗，並出現前置處理錯誤。

AutoUserScope

自動用戶的範圍

名稱	類型	Description
pool	string	指定工作會以在集區中的每個計算節點上建立的一般自動使用者帳戶執行。
task	string	指定服務應該為 Task 建立新的使用者。

AutoUserSpecification

指定在 Batch 服務上執行工作之自動用戶的參數。

名稱	類型	Description
elevationLevel	ElevationLevel	自動使用者的提高許可權層級。 預設值為 nonAdmin。
scope	AutoUserScope	自動用戶的範圍 預設值為集區。 如果集區正在執行 Windows，則如果需要工作之間的更嚴格隔離，就應該指定 Task 的值。 例如，如果工作會以可能會影響其他工作的方式變動登錄，或已在集區上指定憑證，而該集區上不應該由一般工作存取，但應該可供 StartTasks 存取。

BatchError

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

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

BatchErrorDetail

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

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

CertificateReference

要安裝在集區中計算節點上之憑證的參考。

名稱	類型	Description
storeLocation	CertificateStoreLocation	要在其中安裝憑證之計算節點上的證書存儲位置。 默認值為 currentuser。 此屬性僅適用於使用 Windows 計算節點設定的集區， (使用 cloudServiceConfiguration 建立，或使用 Windows 映像參考) 搭配 virtualMachineConfiguration 來建立。 針對 Linux 計算節點，憑證會儲存在工作工作目錄內的目錄中，而AZ_BATCH_CERTIFICATES_DIR環境變數會提供給工作查詢此位置。 對於可見度為 『remoteUser』 的憑證，會在使用者的主目錄中建立 『certs』 目錄 (，例如 /home/{user-name}/certs) ，且憑證會放在該目錄中。
storeName	string	要在其中安裝憑證之計算節點上的證書存儲名稱。 此屬性僅適用於使用 Windows 計算節點設定的集區， (使用 cloudServiceConfiguration 建立，或使用 Windows 映像參考) 搭配 virtualMachineConfiguration 來建立。 常見的市集名稱包括：My、Root、CA、Trust、Disallowed、TrustedPeople、TrustedPublisher、AuthRoot、AddressBook，但也可以使用任何自定義存放區名稱。 預設值為 My。
thumbprint	string	憑證的指紋。
thumbprintAlgorithm	string	指紋相關聯的演算法。 這必須是sha1。
visibility	CertificateVisibility[]	計算節點上的哪些用戶帳戶應該可以存取憑證的私人數據。 您可以在此集合中指定多個可見度。 預設值為 [所有帳戶]。

CertificateStoreLocation

要在其中安裝憑證之計算節點上的證書存儲位置。

名稱	類型	Description
currentuser	string	憑證應安裝至 CurrentUser 證書存儲。
localmachine	string	憑證應該安裝到 LocalMachine 證書存儲。

CertificateVisibility

計算節點上的哪些用戶帳戶應該可以存取憑證的私人數據。

名稱	類型	Description
remoteuser	string	用戶帳戶應該會看到憑證，讓使用者從遠端訪問計算節點。
starttask	string	執行 StartTask 的用戶帳戶應該可以看到憑證。 請注意，如果 AutoUser 範圍同時是 StartTask 和 Task 的集區，工作也會看到此憑證。
task	string	執行作業工作的用戶帳戶應該可以看到憑證。

ComputeNodeIdentityReference

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

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

ContainerRegistry

私人容器登錄。

名稱	類型	Description
identityReference	ComputeNodeIdentityReference	使用者指派身分識別的參考，用來存取 Azure Container Registry，而不是使用者名稱和密碼。 與計算節點將使用之 Batch 集區相關聯的使用者指派身分識別參考。
password	string	登入登錄伺服器的密碼。
registryServer	string	登錄 URL。 如果省略，則預設值為 「docker.io」。。
username	string	要登入登錄伺服器的用戶名稱。

ContainerWorkingDirectory

容器Task工作目錄的位置。

名稱	類型	Description
containerImageDefault	string	使用容器映像中定義的工作目錄。 請注意，此目錄不會包含 Batch 下載的資源檔。
taskWorkingDirectory	string	使用標準 Batch 服務工作工作目錄，其中包含 Batch 填入的工作資源檔。

ElevationLevel

使用者的提高許可權層級。

名稱	類型	Description
admin	string	使用者是具有提高存取權的用戶，並且會以完整的系統管理員許可權操作。
nonadmin	string	用戶是沒有提高存取權的標準使用者。

EnvironmentSetting

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

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

ErrorMessage

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

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

MetadataItem

與 Batch 服務資源相關聯的名稱/值組。

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

NodeCommunicationMode

決定集區如何與 Batch 服務通訊。

名稱	類型	Description
classic	string	使用傳統通訊模式的節點需要來自 「BatchNodeManagement」 埠 29876 和 29877 上的輸入 TCP 通訊。{region}“ 服務卷標和埠 443 上的輸出 TCP 通訊到 ”Storage.region“ 和 ”BatchNodeManagement“。{region}“ 服務標籤。
default	string	Batch 服務會自動設定節點通訊模式。
simplified	string	使用簡化通訊模式的節點需要埠 443 上的輸出 TCP 通訊至 “BatchNodeManagement”。{region}“ 服務標籤。 不需要開啟的輸入埠。

PoolPatchParameter

要對集區進行的一組變更。

名稱	類型	Description
applicationPackageReferences	ApplicationPackageReference[]	要安裝在集區中每個計算節點上的套件清單。 封裝參考的變更會影響聯結集區的所有新節點，但不會影響已在集區中的計算節點，直到重新啟動或重新製作映像為止。 如果存在此元素，則會取代任何現有的套件參考。 如果您指定空的集合，則會從集區中移除所有封裝參考。 如果省略，任何現有的封裝參考會保持不變。
certificateReferences	CertificateReference[]	要安裝在集區中每個計算節點上的憑證清單。 如果存在此元素，它會取代集區上設定的任何現有憑證參考。 如果省略，任何現有的憑證參考會保持不變。 針對 Windows 節點，Batch 服務會將憑證安裝至指定的證書存儲和位置。 針對 Linux 計算節點，憑證會儲存在工作工作目錄內的目錄中，而AZ_BATCH_CERTIFICATES_DIR環境變數會提供給工作查詢此位置。 對於可見度為 『remoteUser』 的憑證，會在使用者的主目錄中建立 『certs』 目錄 (，例如 /home/{user-name}/certs) ，且憑證會放在該目錄中。 警告：此屬性已被取代，將在 2024 年 2 月之後移除。 請改用 Azure KeyVault 擴充功能 。
metadata	MetadataItem[]	與集區相關聯的名稱/值組清單做為元數據。 如果這個專案存在，它會取代集區上設定的任何現有元數據。 如果您指定空的集合，則會從集區中移除任何元數據。 如果省略，任何現有的元數據會保持不變。
startTask	StartTask	在聯結集區時，在每個計算節點上執行的工作。 工作會在將計算節點新增至集區或重新啟動計算節點時執行。 如果這個專案存在，它會覆寫任何現有的 StartTask。 如果省略，任何現有的 StartTask 會保持不變。
targetNodeCommunicationMode	NodeCommunicationMode	集區所需的節點通訊模式。 如果存在此元素，它會取代集區上設定的現有 targetNodeCommunicationMode。 如果省略，任何現有的元數據會保持不變。

ResourceFile

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

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

StartTask

當節點加入 Azure Batch 服務中的集區，或計算節點重新啟動或重新映射時，就會執行的工作。

名稱	類型	Description
commandLine	string	StartTask 的命令行。 命令行不會在殼層下執行，因此無法利用殼層功能，例如環境變數擴充。 如果您想要利用這類功能，您應該在命令行中叫用殼層，例如在 Windows 中使用 “cmd /c MyCommand” 或 Linux 中的 “/bin/sh -c MyCommand”。 如果命令行參考檔案路徑，它應該使用相對於Task工作目錄) 的相對路徑 (，或使用 Batch 提供的環境變數 (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables) 。
containerSettings	TaskContainerSettings	StartTask 執行所在容器的設定。 當指定這個值時，節點) 上 Azure Batch 目錄根目錄AZ_BATCH_NODE_ROOT_DIR (递归地对应到容器、所有 Task 環境變數都會對應至容器，並在容器中執行 Task 命令行。 在AZ_BATCH_NODE_ROOT_DIR外部容器中產生的檔案可能不會反映到主機磁碟，這表示 Batch 檔案 API 將無法存取這些檔案。
environmentSettings	EnvironmentSetting[]	StartTask 的環境變數設定清單。
maxTaskRetryCount	integer	重試工作的最大次數。 如果 Batch 服務的結束代碼為非零，Batch 服務會重試工作。 請注意，這個值會特別控制重試次數。 Batch 服務會嘗試工作一次，然後可能會重試到此限制。 例如，如果重試計數上限為 3，Batch 會嘗試工作最多 4 次， (一次初始嘗試，3 次重試) 。 如果重試計數上限為0，Batch服務不會重試工作。 如果重試計數上限為 -1，Batch 服務會重試工作，但不建議用於啟動工作或任何工作。 預設值為 0 (不重試)。
resourceFiles	ResourceFile[]	Batch 服務在執行命令行之前會下載到計算節點的檔案清單。 資源檔案清單的大小上限。 超過大小上限時，要求將會失敗，而回應錯誤碼會是 RequestEntityTooLarge。 如果發生這種情況，ResourceFiles 的集合必須縮小大小。 這可以使用 .zip 檔案、應用程式套件或 Docker 容器來達成。 此專案底下的檔案位於Task的工作目錄中。
userIdentity	UserIdentity	StartTask 執行所在的使用者身分識別。 如果省略，工作會以工作唯一的非系統管理使用者身分執行。
waitForSuccess	boolean	Batch 服務是否應該等候 StartTask 順利完成 (也就是說，先結束結束代碼 0) ，再排程計算節點上的任何工作。 如果為 true 且 StartTask 在節點上失敗，Batch 服務會重試 StartTask，最多重試次數上限， (maxTaskRetryCount) 。 如果工作在重試之後仍未順利完成，Batch 服務會將節點標示為無法使用，且不會排程工作。 您可以透過計算節點狀態和失敗資訊詳細資料來偵測此狀況。 如果為 false，Batch 服務將不會等候 StartTask 完成。 在此情況下，其他工作可以在 StartTask 仍在執行時開始在計算節點上執行;即使 StartTask 失敗，新的工作仍會繼續排程在計算節點上。 預設值是 true。

TaskContainerSettings

Task 的容器設定。

名稱	類型	Description
containerRunOptions	string	容器 create 命令的其他選項。 除了 Batch 服務所控制的自變數之外，這些額外的選項也會提供為 「docker create」 命令的自變數。
imageName	string	要用來建立工作執行所在容器的映像。 這是完整的映像參考，如同指定為 “docker pull”。 如果未提供標籤作為映像名稱的一部分，則會使用標籤 “：latest” 作為預設值。
registry	ContainerRegistry	包含容器映像的私人登錄。 如果已在集區建立時提供，則可以省略此設定。
workingDirectory	ContainerWorkingDirectory	容器Task工作目錄的位置。 默認值為 『taskWorkingDirectory』。

UserIdentity

執行工作的使用者身分識別定義。

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