你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Pool - Patch

Service:

Batch Service

API Version:

2023-11-01.18.0

汇报指定池的属性。
这仅替换请求中指定的池属性。 例如，如果池具有与之关联的 StartTask，并且请求未指定 StartTask 元素，则池将保留现有的 StartTask。

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

With optional parameters:

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

URI 参数

名称	在	必需	类型	说明
batchUrl	path	True	string	所有Azure Batch服务请求的基 URL。
poolId	path	True	string	要更新的池的 ID。
api-version	query	True	string	客户端 API 版本。
timeout	query		integer int32	服务器可以花费处理请求的最长时间（以秒为单位）。 默认为 30 秒。

请求头

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

名称	必需	类型	说明
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"

名称	类型	说明
applicationPackageReferences	ApplicationPackageReference[]	要安装在池中每个计算节点上的包列表。 对包引用的更改会影响加入池的所有新节点，但在重新启动或重置映像之前，不会影响池中已存在的计算节点。 如果存在此元素，它将替换任何现有的 Package 引用。 如果指定空集合，则会从池中删除所有包引用。 如果省略，则任何现有包引用保持不变。
certificateReferences	CertificateReference[]	要安装在池中每个计算节点上的证书列表。 如果存在此元素，它将替换池上配置的任何现有证书引用。 如果省略，则任何现有证书引用保持不变。 对于 Windows 节点，Batch 服务会将证书安装到指定的证书存储和位置。 对于 Linux 计算节点，证书存储在 Task 工作目录内的目录中，并向 Task 提供一个环境变量AZ_BATCH_CERTIFICATES_DIR来查询此位置。 对于“remoteUser”可见性的证书，在用户的主目录中创建一个“certs”目录， (例如 /home/{user-name}/certs) ，证书位于该目录中。 警告：此属性已弃用，将在 2024 年 2 月之后删除。 请改用 Azure KeyVault 扩展 。
metadata	MetadataItem[]	与作为元数据的池关联的名称/值对的列表。 如果存在此元素，它将替换池上配置的任何现有元数据。 如果指定空集合，则会从池中删除任何元数据。 如果省略，则任何现有元数据保持不变。
startTask	StartTask	加入池时在每个计算节点上运行的任务。 将计算节点添加到池或重启计算节点时，任务将运行。 如果存在此元素，它将覆盖任何现有的 StartTask。 如果省略，则任何现有的 StartTask 保持不变。
targetNodeCommunicationMode	NodeCommunicationMode	池的所需节点通信模式。 如果存在此元素，它将替换池上配置的现有 targetNodeCommunicationMode。 如果省略，则任何现有元数据保持不变。

响应

名称	类型	说明
200 OK		对 Batch 服务的请求已成功。 Headers 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 身份验证代码流

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

名称	说明
user_impersonation	模拟用户帐户

Authorization

Type: apiKey
In: header

示例

Patch the Pool

Sample Request

HTTP

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



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

Sample Response

Status code:

200

定义

名称	说明
ApplicationPackageReference	对要部署到计算节点的包的引用。
AutoUserScope	自动用户的范围
AutoUserSpecification	指定在 Batch 服务上运行 Task 的自动用户的参数。
BatchError	从Azure Batch服务收到的错误响应。
BatchErrorDetail	Azure Batch错误响应中包含的其他信息项。
CertificateReference	对要安装在池中计算节点上的证书的引用。
CertificateStoreLocation	要在其中安装证书的计算节点上的证书存储位置。
CertificateVisibility	计算节点上的哪些用户帐户应有权访问证书的专用数据。
ComputeNodeIdentityReference	对与计算节点将使用的 Batch 池关联的用户分配标识的引用。
ContainerRegistry	专用容器注册表。
ContainerWorkingDirectory	容器任务工作目录的位置。
ElevationLevel	用户的提升级别。
EnvironmentSetting	要对任务进程设置的环境变量。
ErrorMessage	Azure Batch错误响应中收到的错误消息。
MetadataItem	与 Batch 服务资源关联的名称/值对。
NodeCommunicationMode	确定池如何与 Batch 服务通信。
PoolPatchParameter	要对池进行的更改集。
ResourceFile	要下载到计算节点的单个文件或多个文件。
StartTask	当节点加入Azure Batch服务中的池时，或者在重新启动或重置计算节点映像时运行的任务。
TaskContainerSettings	Task 的容器设置。
UserIdentity	运行任务时所依据的用户标识的定义。

ApplicationPackageReference

对要部署到计算节点的包的引用。

名称	类型	说明
applicationId	string	要部署的应用程序的 ID。 创建池时，包的应用程序 ID 必须完全限定 (/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Batch/batchAccounts/{accountName}/applications/{applicationName}) 。
version	string	要部署的应用程序的版本。 如果省略，则部署默认版本。 如果在池中省略此项，并且未为此应用程序指定默认版本，则请求将失败，错误代码为 InvalidApplicationPackageReferences 和 HTTP 状态代码 409。 如果在 Task 上省略此版本，并且未为此应用程序指定默认版本，则任务将失败并出现预处理错误。

AutoUserScope

自动用户的范围

名称	类型	说明
pool	string	指定任务作为在池中的每个计算节点上创建的通用自动用户帐户运行。
task	string	指定服务应为 Task 创建新用户。

AutoUserSpecification

指定在 Batch 服务上运行 Task 的自动用户的参数。

名称	类型	说明
elevationLevel	ElevationLevel	自动用户的提升级别。 默认值为 nonAdmin。
scope	AutoUserScope	自动用户的范围 默认值为 pool。 如果池运行的是 Windows，则当任务之间需要更严格的隔离时，应指定任务值。 例如，如果任务以可能影响其他任务的方式更改注册表，或者已在池上指定了证书，而普通任务不应访问证书，但应由 StartTask 访问。

BatchError

从Azure Batch服务收到的错误响应。

名称	类型	说明
code	string	错误的标识符。 代码是固定的，旨在以编程方式使用。
message	ErrorMessage	描述错误的消息，该消息适用于在用户界面中显示。
values	BatchErrorDetail[]	包含有关错误的其他详细信息的键值对的集合。

BatchErrorDetail

Azure Batch错误响应中包含的其他信息项。

名称	类型	说明
key	string	指定 Value 属性含义的标识符。
value	string	错误响应附带的其他信息。

CertificateReference

对要安装在池中计算节点上的证书的引用。

名称	类型	说明
storeLocation	CertificateStoreLocation	要在其中安装证书的计算节点上的证书存储位置。 默认值为 currentuser。 此属性仅适用于使用 Windows 计算节点配置的池， (使用 cloudServiceConfiguration 创建的池，或使用 windows 映像引用) 通过 virtualMachineConfiguration 配置的池。 对于 Linux 计算节点，证书存储在 Task 工作目录内的目录中，并向 Task 提供环境变量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

要在其中安装证书的计算节点上的证书存储位置。

名称	类型	说明
currentuser	string	应将证书安装到 CurrentUser 证书存储区。
localmachine	string	证书应安装到 LocalMachine 证书存储中。

CertificateVisibility

计算节点上的哪些用户帐户应有权访问证书的专用数据。

名称	类型	说明
remoteuser	string	证书应该对用户远程访问计算节点的用户帐户可见。
starttask	string	运行 StartTask 的用户帐户应可以看到证书。 请注意，如果 AutoUser 作用域是 StartTask 和 Task 的池，则此证书也将对任务可见。
task	string	证书应对运行作业任务的用户帐户可见。

ComputeNodeIdentityReference

对与计算节点将使用的 Batch 池关联的用户分配标识的引用。

名称	类型	说明
resourceId	string	用户分配的标识的 ARM 资源 ID。

ContainerRegistry

专用容器注册表。

名称	类型	说明
identityReference	ComputeNodeIdentityReference	对用户分配的标识的引用，用于访问Azure 容器注册表而不是用户名和密码。 对与计算节点将使用的 Batch 池关联的用户分配标识的引用。
password	string	用于登录到注册表服务器的密码。
registryServer	string	注册表 URL。 如果省略，则默认值为“docker.io”。
username	string	要登录到注册表服务器的用户名。

ContainerWorkingDirectory

容器任务工作目录的位置。

名称	类型	说明
containerImageDefault	string	使用容器映像中定义的工作目录。 请注意，此目录不包含 Batch 下载的资源文件。
taskWorkingDirectory	string	使用标准 Batch 服务任务工作目录，其中包含由 Batch 填充的任务资源文件。

ElevationLevel

用户的提升级别。

名称	类型	说明
admin	string	用户是具有提升访问权限的用户，使用完全的管理员权限进行操作。
nonadmin	string	用户是没有提升访问权限的标准用户。

EnvironmentSetting

要对任务进程设置的环境变量。

名称	类型	说明
name	string	环境变量的名称。
value	string	环境变量的值。

ErrorMessage

Azure Batch错误响应中收到的错误消息。

名称	类型	说明
lang	string	错误消息的语言代码
value	string	消息的文本。

MetadataItem

与 Batch 服务资源关联的名称/值对。

名称	类型	说明
name	string	元数据项的名称。
value	string	元数据项的值。

NodeCommunicationMode

确定池如何与 Batch 服务通信。

名称	类型	说明
classic	string	使用经典通信模式的节点需要来自“BatchNodeManagement”的端口 29876 和 29877 上的入站 TCP 通信。{region}“服务标记和端口 443 上与”Storage.region“和”BatchNodeManagement“的出站 TCP 通信。{region}“服务标记。
default	string	节点通信模式由 Batch 服务自动设置。
simplified	string	使用简化通信模式的节点需要在端口 443 上与“BatchNodeManagement”进行出站 TCP 通信。{region}“服务标记。 不需要打开的入站端口。

PoolPatchParameter

要对池进行的更改集。

名称	类型	说明
applicationPackageReferences	ApplicationPackageReference[]	要安装在池中每个计算节点上的包的列表。 对包引用的更改会影响加入池的所有新节点，但在重新启动或重置映像之前，不会影响池中已有的计算节点。 如果存在此元素，它将替换任何现有的 Package 引用。 如果指定空集合，则会从池中删除所有包引用。 如果省略，则任何现有包引用保持不变。
certificateReferences	CertificateReference[]	要安装在池中每个计算节点上的证书列表。 如果存在此元素，它将替换池上配置的任何现有证书引用。 如果省略，则任何现有证书引用将保持不变。 对于 Windows 节点，Batch 服务会将证书安装到指定的证书存储和位置。 对于 Linux 计算节点，证书存储在 Task 工作目录内的目录中，并向 Task 提供环境变量AZ_BATCH_CERTIFICATES_DIR以查询此位置。 对于具有“remoteUser”可见性的证书，在用户的主目录中创建一个“certs”目录， (例如/home/{user-name}/certs) ，证书放置在该目录中。 警告：此属性已弃用，将在 2024 年 2 月之后删除。 请改用 Azure KeyVault 扩展 。
metadata	MetadataItem[]	与作为元数据的池关联的名称/值对列表。 如果存在此元素，它将替换池上配置的任何现有元数据。 如果指定空集合，则会从池中删除任何元数据。 如果省略，则任何现有元数据保持不变。
startTask	StartTask	加入池时要在每个计算节点上运行的任务。 将计算节点添加到池或重启计算节点时，任务将运行。 如果存在此元素，它将覆盖任何现有的 StartTask。 如果省略，则任何现有 StartTask 保持不变。
targetNodeCommunicationMode	NodeCommunicationMode	池的所需节点通信模式。 如果存在此元素，它将替换池上配置的现有 targetNodeCommunicationMode。 如果省略，则任何现有元数据保持不变。

ResourceFile

要下载到计算节点的单个文件或多个文件。

名称	类型	说明
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 目录。 指定的相对路径不能从 Task 的工作目录 (中断，例如使用“.”。) 。
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服务中的池时，或者在重新启动或重置计算节点映像时运行的任务。

名称	类型	说明
commandLine	string	StartTask 的命令行。 命令行不在 shell 下运行，因此无法利用 shell 功能，例如环境变量扩展。 如果要利用此类功能，则应在命令行中调用 shell，例如在 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 的容器的设置。 指定此项后，AZ_BATCH_NODE_ROOT_DIR (节点上 Azure Batch) 目录的根目录以递归方式映射到容器中，所有 Task 环境变量都映射到容器中，并在容器中执行 Task 命令行。 AZ_BATCH_NODE_ROOT_DIR 之外的容器中生成的文件可能不会反映在主机磁盘上，这意味着 Batch 文件 API 无法访问这些文件。
environmentSettings	EnvironmentSetting[]	StartTask 的环境变量设置列表。
maxTaskRetryCount	integer	可以重试 Task 的最大次数。 如果任务退出代码不为零，Batch 服务会重试该任务。 请注意，此值专门用于控制重试的次数。 Batch 服务将尝试一次任务，然后可能会重试到此限制。 例如，如果最大重试计数为 3 次，则 Batch (一次初始尝试和 3 次重试) 最多尝试任务 4 次。 如果最大重试计数为 0，Batch 服务不会重试 Task。 如果最大重试计数为 -1，Batch 服务将无限制地重试任务，但不建议对启动任务或任何任务执行此操作。 默认值为 0（不重试）。
resourceFiles	ResourceFile[]	在运行命令行之前，Batch 服务将下载到计算节点的文件列表。 资源文件列表有一个最大大小。 超过最大大小时，请求将失败，响应错误代码为 RequestEntityTooLarge。 如果发生这种情况，则必须减小 ResourceFiles 集合的大小。 这可以使用 .zip 文件、应用程序包或 Docker 容器来实现。 此元素下列出的文件位于任务的工作目录中。
userIdentity	UserIdentity	运行 StartTask 时所依据的用户标识。 如果省略，则任务将作为 Task 唯一的非管理用户运行。
waitForSuccess	boolean	Batch 服务是否应等待 StartTask 成功完成 (即退出代码为 0) 退出，然后再在计算节点上计划任何任务。 如果为 true，并且节点上的 StartTask 失败，Batch 服务将重试 StartTask 的最大重试次数 (maxTaskRetryCount) 。 如果所有重试后任务仍未成功完成，Batch 服务会将节点标记为不可用，并且不会计划任务到该节点。 可以通过计算节点状态和故障信息详细信息来检测此情况。 如果为 false，则 Batch 服务不会等待 StartTask 完成。 在这种情况下，当 StartTask 仍在运行时，其他任务可能会开始在计算节点上执行;即使 StartTask 失败，新任务也将继续在计算节点上进行计划。 默认值为 true。

TaskContainerSettings

Task 的容器设置。

名称	类型	说明
containerRunOptions	string	容器 create 命令的其他选项。 除了 Batch 服务控制的选项外，这些附加选项还作为参数提供给“docker create”命令。
imageName	string	用于创建要在其中运行 Task 的容器的映像。 这是完整的映像引用，将指定为“docker pull”。 如果未提供标记作为映像名称的一部分，则默认使用标记“：latest”。
registry	ContainerRegistry	包含容器映像的专用注册表。 如果已在创建池时提供此设置，则可以省略此设置。
workingDirectory	ContainerWorkingDirectory	容器任务工作目录的位置。 默认值为“taskWorkingDirectory”。

UserIdentity

运行任务时所依据的用户标识的定义。

名称	类型	说明
autoUser	AutoUserSpecification	运行任务的自动用户。 userName 和 autoUser 属性是互斥的;必须指定一个，但不能同时指定两者。
username	string	运行任务时所依据的用户标识的名称。 userName 和 autoUser 属性是互斥的;必须指定一个，但不能同时指定两者。