Pool - Patch

Service:

Batch Service

API Version:

2022-01-01.15.0

Обновляет свойства указанного пула.
Это заменяет только свойства пула, указанные в запросе. Например, если с ним связан пул StartTask, а запрос не указывает элемент StartTask, пул сохраняет существующий элемент StartTask.

PATCH {batchUrl}/pools/{poolId}?api-version=2022-01-01.15.0

With optional parameters:

PATCH {batchUrl}/pools/{poolId}?timeout={timeout}&api-version=2022-01-01.15.0

Параметры URI

Name	In	Required	Type	Description
batchUrl	path	True	string	Базовый URL-адрес для всех запросов на обслуживание пакетная служба Azure.
poolId	path	True	string	Идентификатор обновляемого пула.
api-version	query	True	string	Версия КЛИЕНТСКОго API.
timeout	query		integer int32	Максимальное время, затрачивается сервером на обработку запроса в секундах. По умолчанию это 30 секунд.

Заголовок запроса

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

Name	Required	Type	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"

Name	Type	Description
applicationPackageReferences	ApplicationPackageReference[]	Список пакетов для установки на каждом вычислительном узле в пуле. Изменения ссылок на пакеты влияют на все новые узлы, присоединенные к пулу, но не влияют на вычислительные узлы, которые уже находятся в пуле, пока они не будут перезагружены или переосмыслены. Если этот элемент присутствует, он заменяет все существующие ссылки на пакеты. Если указать пустую коллекцию, все ссылки на пакеты удаляются из пула. Если он опущен, все существующие ссылки на пакеты остаются неизменными.
certificateReferences	CertificateReference[]	Список сертификатов, устанавливаемых на каждом вычислительном узле в пуле. Если этот элемент присутствует, он заменяет все существующие ссылки на сертификаты, настроенные в пуле. Если он опущен, все существующие ссылки на сертификаты остаются неизменными. Для Windows узлов пакетная служба устанавливает сертификаты в указанное хранилище сертификатов и расположение. Для вычислительных узлов Linux сертификаты хранятся в каталоге рабочей папки задачи, а переменная среды AZ_BATCH_CERTIFICATES_DIR предоставляется задаче для запроса этого расположения. Для сертификатов с видимостью remoteUser каталог certs создается в домашнем каталоге пользователя (например, /home/{user-name}/certs) и сертификаты помещаются в этот каталог.
metadata	MetadataItem[]	Список пар "имя-значение", связанных с пулом в качестве метаданных. Если этот элемент присутствует, он заменяет все существующие метаданные, настроенные в пуле. Если указать пустую коллекцию, все метаданные удаляются из пула. Если он опущен, все существующие метаданные остаются неизменными.
startTask	StartTask	Задача, выполняемая на каждом вычислительном узле при присоединении к пулу. Задача выполняется при добавлении вычислительного узла в пул или при перезапуске вычислительного узла. Если этот элемент присутствует, он перезаписывает все существующие startTask. Если этот параметр не указан, все существующие startTask остаются неизменными.

Ответы

Name	Type	Description
200 OK		Запрос к пакетной службе выполнен успешно. Headers client-request-id: string request-id: string ETag: string Last-Modified: string DataServiceId: string
Other Status Codes	BatchError	Ошибка пакетной службы.

Безопасность

azure_auth

Flow OAuth2 Azure Active Directory

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

Scopes

Name	Description
user_impersonation	Олицетворение учетной записи пользователя

Authorization

Type: apiKey
In: header

Примеры

Patch the Pool

Sample Request

HTTP

PATCH account.region.batch.azure.com/pools/poolId?api-version=2022-01-01.15.0



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

Sample Response

Status code:

200

Определения

ApplicationPackageReference	Ссылка на пакет для развертывания на вычислительных узлах.
AutoUserScope	Область для автоматического пользователя
AutoUserSpecification	Задает параметры для автоматического пользователя, выполняющего задачу в пакетной службе.
BatchError	Ответ об ошибке, полученный от службы пакетная служба Azure.
BatchErrorDetail	Элемент дополнительных сведений, включенных в ответ на ошибку пакетная служба Azure.
CertificateReference	Ссылка на сертификат, установленный на вычислительных узлах в пуле.
CertificateStoreLocation	Расположение хранилища сертификатов на вычислительном узле, в которое необходимо установить сертификат.
ComputeNodeIdentityReference	Ссылка на назначенное пользователем удостоверение, связанное с пулом пакетной службы, который будет использовать вычислительный узел.
ContainerRegistry	Частный реестр контейнеров.
ContainerWorkingDirectory	Расположение рабочего каталога задачи контейнера.
ElevationLevel	Уровень повышения прав пользователя.
EnvironmentSetting	Переменная среды, устанавливаемая в процессе задачи.
ErrorMessage	Сообщение об ошибке, полученное в ответе на ошибку пакетная служба Azure.
MetadataItem	Пара "имя-значение", связанная с ресурсом пакетной службы.
PoolPatchParameter	Набор изменений, внесенных в пул.
ResourceFile	Один файл или несколько файлов, которые необходимо скачать на вычислительный узел.
StartTask	Задача, которая выполняется при присоединении узла к пулу в службе пакетная служба Azure или при перезагрузке или повторном создании вычислительного узла.
TaskContainerSettings	Параметры контейнера для задачи.
UserIdentity	Определение удостоверения пользователя, под которым выполняется задача.

ApplicationPackageReference

Ссылка на пакет для развертывания на вычислительных узлах.

Name	Type	Description
applicationId	string	Идентификатор развертываемого приложения.
version	string	Версия развертываемого приложения. Если этот параметр опущен, будет развернута версия по умолчанию. Если этот параметр опущен в пуле и для этого приложения не указана версия по умолчанию, запрос завершается ошибкой с кодом invalidApplicationPackageReferences и кодом состояния HTTP 409. Если это опущено для задачи, и для этого приложения не указана версия по умолчанию, задача завершается сбоем с ошибкой предварительной обработки.

AutoUserScope

Область для автоматического пользователя

Name	Type	Description
pool	string	Указывает, что задача выполняется в качестве общей автоматической учетной записи пользователя, созданной на каждом вычислительном узле в пуле.
task	string	Указывает, что служба должна создать нового пользователя для задачи.

AutoUserSpecification

Задает параметры для автоматического пользователя, выполняющего задачу в пакетной службе.

Name	Type	Description
elevationLevel	ElevationLevel	Уровень повышения прав автоматического пользователя. Значение по умолчанию — nonAdmin.
scope	AutoUserScope	Область для автоматического пользователя Значение по умолчанию — пул. Если пул выполняется Windows необходимо указать значение задачи, если требуется более жесткая изоляция между задачами. Например, если задача изменяет реестр таким образом, что может повлиять на другие задачи или сертификаты были указаны в пуле, которые не должны быть доступны обычным задачам, но должны быть доступны startTasks.

BatchError

Ответ об ошибке, полученный от службы пакетная служба Azure.

Name	Type	Description
code	string	Идентификатор ошибки. Коды инвариантны и предназначены для программного использования.
message	ErrorMessage	Сообщение, описывающее ошибку, предназначенное для отображения в пользовательском интерфейсе.
values	BatchErrorDetail[]	Коллекция пар "ключ-значение", содержащая дополнительные сведения об ошибке.

BatchErrorDetail

Элемент дополнительных сведений, включенных в ответ на ошибку пакетная служба Azure.

Name	Type	Description
key	string	Идентификатор, указывающий значение свойства Value.
value	string	Дополнительные сведения, включенные в ответ на ошибку.

CertificateReference

Ссылка на сертификат, установленный на вычислительных узлах в пуле.

Name	Type	Description
storeLocation	CertificateStoreLocation	Расположение хранилища сертификатов на вычислительном узле, в которое необходимо установить сертификат. Значение по умолчанию — currentuser. Это свойство применимо только для пулов, настроенных с Windows вычислительных узлов (т. е. созданных с помощью cloudServiceConfiguration или virtualMachineConfiguration с помощью ссылки на образ Windows). Для вычислительных узлов Linux сертификаты хранятся в каталоге рабочей папки задачи, а переменная среды AZ_BATCH_CERTIFICATES_DIR предоставляется задаче для запроса этого расположения. Для сертификатов с видимостью remoteUser каталог certs создается в домашнем каталоге пользователя (например, /home/{user-name}/certs) и сертификаты помещаются в этот каталог.
storeName	string	Имя хранилища сертификатов на вычислительном узле, в который необходимо установить сертификат. Это свойство применимо только для пулов, настроенных с Windows вычислительных узлов (т. е. созданных с помощью cloudServiceConfiguration или virtualMachineConfiguration с помощью ссылки на образ Windows). Распространенные имена хранилищ: My, Root, CA, Trust, Disallowed, TrustedPeople, TrustedPublisher, AuthRoot, AddressBook, но также можно использовать любое имя пользовательского хранилища. Значение по умолчанию - «My».
thumbprint	string	Отпечаток сертификата.
thumbprintAlgorithm	string	Алгоритм, с которым связан отпечаток. Это должно быть sha1.
visibility	string[]	Какие учетные записи пользователей на вычислительном узле должны иметь доступ к частным данным сертификата. В этой коллекции можно указать несколько видимостей. Значение по умолчанию — все учетные записи.

CertificateStoreLocation

Расположение хранилища сертификатов на вычислительном узле, в которое необходимо установить сертификат.

Name	Type	Description
currentuser	string	Сертификаты должны быть установлены в хранилище сертификатов CurrentUser.
localmachine	string	Сертификаты должны быть установлены в хранилище сертификатов LocalMachine.

ComputeNodeIdentityReference

Ссылка на назначенное пользователем удостоверение, связанное с пулом пакетной службы, который будет использовать вычислительный узел.

Name	Type	Description
resourceId	string	Идентификатор ресурса ARM удостоверения, назначаемого пользователем.

ContainerRegistry

Частный реестр контейнеров.

Name	Type	Description
identityReference	ComputeNodeIdentityReference	Ссылка на назначенное пользователем удостоверение для доступа к Реестр контейнеров Azure вместо имени пользователя и пароля. Ссылка на назначенное пользователем удостоверение, связанное с пулом пакетной службы, который будет использовать вычислительный узел.
password	string	Пароль для входа на сервер реестра.
registryServer	string	URL-адрес реестра. Если этот параметр опущен, значение по умолчанию — "docker.io".
username	string	Имя пользователя для входа на сервер реестра.

ContainerWorkingDirectory

Расположение рабочего каталога задачи контейнера.

Name	Type	Description
containerImageDefault	string	Используйте рабочий каталог, определенный в образе контейнера. Убедитесь, что этот каталог не будет содержать файлы ресурсов, скачанные пакетной службой.
taskWorkingDirectory	string	Используйте стандартный рабочий каталог задачи пакетной службы, который будет содержать файлы ресурсов задач, заполненные пакетной службой.

ElevationLevel

Уровень повышения прав пользователя.

Name	Type	Description
admin	string	Пользователь является пользователем с повышенными правами доступа и работает с полными разрешениями администратора.
nonadmin	string	Пользователь является стандартным пользователем без повышенного доступа.

EnvironmentSetting

Переменная среды, устанавливаемая в процессе задачи.

Name	Type	Description
name	string	Имя переменной среды.
value	string	Значение переменной среды.

ErrorMessage

Сообщение об ошибке, полученное в ответе на ошибку пакетная служба Azure.

Name	Type	Description
lang	string	Код языка сообщения об ошибке
value	string	Текст сообщения.

MetadataItem

Пара "имя-значение", связанная с ресурсом пакетной службы.

Name	Type	Description
name	string	Имя элемента метаданных.
value	string	Значение элемента метаданных.

PoolPatchParameter

Набор изменений, внесенных в пул.

Name	Type	Description
applicationPackageReferences	ApplicationPackageReference[]	Список пакетов для установки на каждом вычислительном узле в пуле. Изменения ссылок на пакеты влияют на все новые узлы, присоединенные к пулу, но не влияют на вычислительные узлы, которые уже находятся в пуле, пока они не будут перезагружены или переосмыслены. Если этот элемент присутствует, он заменяет все существующие ссылки на пакеты. Если указать пустую коллекцию, все ссылки на пакеты удаляются из пула. Если он опущен, все существующие ссылки на пакеты остаются неизменными.
certificateReferences	CertificateReference[]	Список сертификатов, устанавливаемых на каждом вычислительном узле в пуле. Если этот элемент присутствует, он заменяет все существующие ссылки на сертификаты, настроенные в пуле. Если он опущен, все существующие ссылки на сертификаты остаются неизменными. Для Windows узлов пакетная служба устанавливает сертификаты в указанное хранилище сертификатов и расположение. Для вычислительных узлов Linux сертификаты хранятся в каталоге рабочей папки задачи, а переменная среды AZ_BATCH_CERTIFICATES_DIR предоставляется задаче для запроса этого расположения. Для сертификатов с видимостью remoteUser каталог certs создается в домашнем каталоге пользователя (например, /home/{user-name}/certs) и сертификаты помещаются в этот каталог.
metadata	MetadataItem[]	Список пар "имя-значение", связанных с пулом в качестве метаданных. Если этот элемент присутствует, он заменяет все существующие метаданные, настроенные в пуле. Если указать пустую коллекцию, все метаданные удаляются из пула. Если он опущен, все существующие метаданные остаются неизменными.
startTask	StartTask	Задача, выполняемая на каждом вычислительном узле при присоединении к пулу. Задача выполняется при добавлении вычислительного узла в пул или при перезапуске вычислительного узла. Если этот элемент присутствует, он перезаписывает все существующие startTask. Если этот параметр не указан, все существующие startTask остаются неизменными.

ResourceFile

Один файл или несколько файлов, которые необходимо скачать на вычислительный узел.

Name	Type	Description
autoStorageContainerName	string	Имя контейнера хранилища в учетной записи автоматического хранения. Свойства autoStorageContainerName, storageContainerUrl и httpUrl являются взаимоисключающими, и их необходимо указать.
blobPrefix	string	Префикс большого двоичного объекта, используемый при скачивании больших двоичных объектов из контейнера служба хранилища Azure. Будут загружены только большие двоичные объекты, имена которых начинаются с указанного префикса. Свойство допустимо только при использовании autoStorageContainerName или storageContainerUrl. Этот префикс может быть частичным именем файла или подкаталогом. Если префикс не указан, будут загружены все файлы в контейнере.
fileMode	string	Атрибут режима разрешений файла в восьмеричном формате. Это свойство применяется только к файлам, скачиваемых на вычислительные узлы Linux. Он будет игнорироваться, если он указан для resourceFile, который будет скачан на Windows вычислительный узел. Если это свойство не указано для вычислительного узла Linux, то к файлу применяется значение по умолчанию 0770.
filePath	string	Расположение на вычислительном узле, на который нужно скачать файлы, относительно рабочего каталога задачи. Если задано свойство httpUrl, filePath является обязательным и описывает путь, в который будет скачан файл, включая имя файла. В противном случае, если указано свойство autoStorageContainerName или storageContainerUrl, filePath является необязательным и является каталогом для скачивания файлов. Если filePath используется в качестве каталога, любая структура каталогов, уже связанная с входными данными, будет сохранена в полном объеме и добавлена в указанный каталог filePath. Указанный относительный путь не может выйти из рабочего каталога задачи (например, с помощью "..").
httpUrl	string	URL-адрес для скачивания файла. Свойства autoStorageContainerName, storageContainerUrl и httpUrl являются взаимоисключающими, и их необходимо указать. Если URL-адрес указывает на Хранилище BLOB-объектов Azure, он должен быть доступен для чтения с вычислительных узлов. Существует три способа получить такой URL-адрес для большого двоичного объекта в службе хранилища Azure: включить подписанный URL-адрес (SAS), предоставляющий разрешения на чтение большого двоичного объекта, использовать управляемое удостоверение с разрешением на чтение или задать ACL для большого двоичного объекта или его контейнера, чтобы разрешить общий доступ.
identityReference	ComputeNodeIdentityReference	Ссылка на назначенное пользователем удостоверение, используемое для доступа к Хранилище BLOB-объектов Azure, заданному storageContainerUrl или httpUrl Ссылка на назначенное пользователем удостоверение, связанное с пулом пакетной службы, который будет использовать вычислительный узел.
storageContainerUrl	string	URL-адрес контейнера больших двоичных объектов в Хранилище BLOB-объектов Azure. Свойства autoStorageContainerName, storageContainerUrl и httpUrl являются взаимоисключающими, и их необходимо указать. Этот URL-адрес должен быть доступен для чтения и перечисления из вычислительных узлов. Существует три способа получить такой URL-адрес для контейнера в службе хранилища Azure: включить подписанный URL-адрес (SAS), предоставляющий разрешения на чтение и список для контейнера, использовать управляемое удостоверение с разрешениями на чтение и список или задать список ACL для контейнера, чтобы разрешить общий доступ.

StartTask

Задача, которая выполняется при присоединении узла к пулу в службе пакетная служба Azure или при перезагрузке или повторном создании вычислительного узла.

Name	Type	Description
commandLine	string	Командная строка startTask. Командная строка не выполняется под оболочкой и поэтому не может воспользоваться преимуществами функций оболочки, таких как расширение переменной среды. Если вы хотите воспользоваться такими функциями, необходимо вызвать оболочку в командной строке, например с помощью cmd /c MyCommand в Windows или "/bin/sh -c MyCommand" в Linux. Если командная строка ссылается на пути к файлам, она должна использовать относительный путь (относительно рабочего каталога задачи) или использовать предоставленную пакетную переменную среды (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
containerSettings	TaskContainerSettings	Параметры контейнера, под которым выполняется StartTask. Если этот параметр указан, все каталоги рекурсивно под AZ_BATCH_NODE_ROOT_DIR (корень каталогов пакетная служба Azure на узле) сопоставляются с контейнером, все переменные среды задач сопоставляются с контейнером, а командная строка задачи выполняется в контейнере. Файлы, созданные в контейнере за пределами AZ_BATCH_NODE_ROOT_DIR, могут не отражаться на диске узла, то есть API пакетной службы не смогут получить доступ к этим файлам.
environmentSettings	EnvironmentSetting[]	Список параметров переменной среды для StartTask.
maxTaskRetryCount	integer	Максимальное количество повторных попыток задачи. Пакетная служба повторяет задачу, если код выхода не является ненулевой. Обратите внимание, что это значение определяет количество повторных попыток. Пакетная служба попытается выполнить задачу один раз и может повторить попытку до этого ограничения. Например, если максимальное число повторных попыток равно 3, пакетная служба пытается выполнить задачу до 4 раз (одна начальная попытка и 3 повторных попытки). Если максимальное число повторных попыток равно 0, пакетная служба не повторяет задачу. Если максимальное число повторных попыток равно -1, пакетная служба повторяет задачу без ограничения, однако это не рекомендуется для задачи запуска или любой задачи. Значение по умолчанию — 0 (без повторных попыток)
resourceFiles	ResourceFile[]	Список файлов, скачиваемых пакетной службой на вычислительный узел перед выполнением командной строки. Максимальный размер списка файлов ресурсов. При превышении максимального размера запрос завершится ошибкой, и код ошибки ответа будет RequestEntityTooLarge. В этом случае необходимо уменьшить размер коллекции ResourceFiles. Это можно сделать с помощью .zip файлов, пакетов приложений или контейнеров Docker. Файлы, перечисленные в этом элементе, находятся в рабочем каталоге task.
userIdentity	UserIdentity	Удостоверение пользователя, под которым запускается StartTask. Если этот параметр опущен, задача выполняется как пользователь без прав администратора, уникальный для задачи.
waitForSuccess	boolean	Следует ли пакетной службе ждать успешного завершения начальной базы данных (т. е. выхода с кодом выхода 0) перед планированием задач на вычислительном узле. Если значение true и startTask завершается сбоем на узле, пакетная служба повторно повторяет startTask до максимального количества повторных попыток (maxTaskRetryCount). Если задача по-прежнему не завершена успешно после всех повторных попыток, пакетная служба помечает узел непригодным для использования и не будет планировать задачи. Это условие можно обнаружить с помощью сведений о состоянии вычислительного узла и сведения о сбое. Если значение равно false, пакетная служба не будет ожидать завершения начальной базы. В этом случае другие задачи могут запускаться на вычислительном узле во время запуска startTask; и даже в случае сбоя StartTask новые задачи будут по-прежнему планироваться на вычислительном узле. Значение по умолчанию — true.

TaskContainerSettings

Параметры контейнера для задачи.

Name	Type	Description
containerRunOptions	string	Дополнительные параметры для команды создания контейнера. Эти дополнительные параметры предоставляются в качестве аргументов для команды docker create, в дополнение к тем, которые управляются пакетной службой.
imageName	string	Образ, используемый для создания контейнера, в котором будет выполняться задача. Это полная ссылка на образ, как указано в "docker pull". Если тег не указан как часть имени изображения, тег ":latest" используется в качестве значения по умолчанию.
registry	ContainerRegistry	Частный реестр, содержащий образ контейнера. Этот параметр можно опустить, если он уже был указан при создании пула.
workingDirectory	ContainerWorkingDirectory	Расположение рабочего каталога задачи контейнера. Значение по умолчанию — taskWorkingDirectory.

UserIdentity

Определение удостоверения пользователя, под которым выполняется задача.

Name	Type	Description
autoUser	AutoUserSpecification	Автоматический пользователь, под которым выполняется задача. Свойства userName и autoUser являются взаимоисключающими; необходимо указать один, но не оба.
username	string	Имя удостоверения пользователя, под которым выполняется задача. Свойства userName и autoUser являются взаимоисключающими; необходимо указать один, но не оба.