tasks

Creates, updates, deletes, gets or lists a tasks resource.

Overview

Name	tasks
Type	Resource
Id	azure.batch_dataplane.tasks

Fields

The following fields are returned by SELECT queries:

get_task

Name	Datatype	Description
id	string	A string that uniquely identifies the Task within the Job. The ID can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 64 characters. Required.
affinityInfo	object	A locality hint that can be used by the Batch service to select a Compute Node on which to start the new Task.
applicationPackageReferences	array	A list of Packages that the Batch service will deploy to the Compute Node before running the command line. Application packages are downloaded and deployed to a shared directory, not the Task working directory. Therefore, if a referenced package is already on the Node, and is up to date, then it is not re-downloaded; the existing copy on the Compute Node is used. If a referenced Package cannot be installed, for example because the package has been deleted or because download failed, the Task fails.
commandLine	string	The command line of the Task. For multi-instance Tasks, the command line is executed as the primary Task, after the primary Task and all subtasks have finished executing the coordination command line. The command line does not run under a shell, and therefore cannot take advantage of shell features such as environment variable expansion. If you want to take advantage of such features, you should invoke the shell in the command line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in Linux. If the command line refers to file paths, it should use a relative path (relative to the Task working directory), or use the Batch provided environment variable (https://learn.microsoft.com/azure/batch/batch-compute-node-environment-variables _). Required.
constraints	object	The execution constraints that apply to this Task.
containerSettings	object	The settings for the container under which the Task runs. If the Pool that will run this Task has containerConfiguration set, this must be set as well. If the Pool that will run this Task doesn't have containerConfiguration set, this must not be set. When this is specified, all directories recursively below the AZ_BATCH_NODE_ROOT_DIR (the root of Azure Batch directories on the node) are mapped into the container, all Task environment variables are mapped into the container, and the Task command line is executed in the container. Files produced in the container outside of AZ_BATCH_NODE_ROOT_DIR might not be reflected to the host disk, meaning that Batch file APIs will not be able to access those files.
creationTime	string (date-time)	The creation time of the Task. Required.
dependsOn	object	The Tasks that this Task depends on. This Task will not be scheduled until all Tasks that it depends on have completed successfully. If any of those Tasks fail and exhaust their retry counts, this Task will never be scheduled.
displayName	string	A display name for the Task. The display name need not be unique and can contain any Unicode characters up to a maximum length of 1024.
eTag	string	The ETag of the Task. This is an opaque string. You can use it to detect whether the Task has changed between requests. In particular, you can be pass the ETag when updating a Task to specify that your changes should take effect only if nobody else has modified the Task in the meantime. Required.
environmentSettings	array	A list of environment variable settings for the Task.
executionInfo	object	Information about the execution of the Task.
exitConditions	object	How the Batch service should respond when the Task completes.
lastModified	string (date-time)	The last modified time of the Task. Required.
multiInstanceSettings	object	An object that indicates that the Task is a multi-instance Task, and contains information about how to run the multi-instance Task.
nodeInfo	object	Information about the Compute Node on which the Task ran.
outputFiles	array	A list of files that the Batch service will upload from the Compute Node after running the command line. For multi-instance Tasks, the files will only be uploaded from the Compute Node on which the primary Task is executed.
previousState	string	The previous state of the Task. This property is not set if the Task is in its initial Active state. Known values are: "active", "preparing", "running", and "completed". (active, preparing, running, completed)
previousStateTransitionTime	string (date-time)	The time at which the Task entered its previous state. This property is not set if the Task is in its initial Active state.
requiredSlots	integer	The number of scheduling slots that the Task requires to run. The default is 1. A Task can only be scheduled to run on a compute node if the node has enough free scheduling slots available. For multi-instance Tasks, this must be 1.
resourceFiles	array	A list of files that the Batch service will download to the Compute Node before running the command line. For multi-instance Tasks, the resource files will only be downloaded to the Compute Node on which the primary Task is executed. There is a maximum size for the list of resource files. When the max size is exceeded, the request will fail and the response error code will be RequestEntityTooLarge. If this occurs, the collection of ResourceFiles must be reduced in size. This can be achieved using .zip files, Application Packages, or Docker Containers.
state	string	The current state of the Task. Required. Known values are: "active", "preparing", "running", and "completed". (active, preparing, running, completed)
stateTransitionTime	string (date-time)	The time at which the Task entered its current state. Required.
stats	object	Resource usage statistics for the Task.
url	string	The URL of the Task. Required.
userIdentity	object	The user identity under which the Task runs. If omitted, the Task runs as a non-administrative user unique to the Task.

list_tasks

Name	Datatype	Description
id	string	A string that uniquely identifies the Task within the Job. The ID can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 64 characters. Required.
affinityInfo	object	A locality hint that can be used by the Batch service to select a Compute Node on which to start the new Task.
applicationPackageReferences	array	A list of Packages that the Batch service will deploy to the Compute Node before running the command line. Application packages are downloaded and deployed to a shared directory, not the Task working directory. Therefore, if a referenced package is already on the Node, and is up to date, then it is not re-downloaded; the existing copy on the Compute Node is used. If a referenced Package cannot be installed, for example because the package has been deleted or because download failed, the Task fails.
commandLine	string	The command line of the Task. For multi-instance Tasks, the command line is executed as the primary Task, after the primary Task and all subtasks have finished executing the coordination command line. The command line does not run under a shell, and therefore cannot take advantage of shell features such as environment variable expansion. If you want to take advantage of such features, you should invoke the shell in the command line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in Linux. If the command line refers to file paths, it should use a relative path (relative to the Task working directory), or use the Batch provided environment variable (https://learn.microsoft.com/azure/batch/batch-compute-node-environment-variables _). Required.
constraints	object	The execution constraints that apply to this Task.
containerSettings	object	The settings for the container under which the Task runs. If the Pool that will run this Task has containerConfiguration set, this must be set as well. If the Pool that will run this Task doesn't have containerConfiguration set, this must not be set. When this is specified, all directories recursively below the AZ_BATCH_NODE_ROOT_DIR (the root of Azure Batch directories on the node) are mapped into the container, all Task environment variables are mapped into the container, and the Task command line is executed in the container. Files produced in the container outside of AZ_BATCH_NODE_ROOT_DIR might not be reflected to the host disk, meaning that Batch file APIs will not be able to access those files.
creationTime	string (date-time)	The creation time of the Task. Required.
dependsOn	object	The Tasks that this Task depends on. This Task will not be scheduled until all Tasks that it depends on have completed successfully. If any of those Tasks fail and exhaust their retry counts, this Task will never be scheduled.
displayName	string	A display name for the Task. The display name need not be unique and can contain any Unicode characters up to a maximum length of 1024.
eTag	string	The ETag of the Task. This is an opaque string. You can use it to detect whether the Task has changed between requests. In particular, you can be pass the ETag when updating a Task to specify that your changes should take effect only if nobody else has modified the Task in the meantime. Required.
environmentSettings	array	A list of environment variable settings for the Task.
executionInfo	object	Information about the execution of the Task.
exitConditions	object	How the Batch service should respond when the Task completes.
lastModified	string (date-time)	The last modified time of the Task. Required.
multiInstanceSettings	object	An object that indicates that the Task is a multi-instance Task, and contains information about how to run the multi-instance Task.
nodeInfo	object	Information about the Compute Node on which the Task ran.
outputFiles	array	A list of files that the Batch service will upload from the Compute Node after running the command line. For multi-instance Tasks, the files will only be uploaded from the Compute Node on which the primary Task is executed.
previousState	string	The previous state of the Task. This property is not set if the Task is in its initial Active state. Known values are: "active", "preparing", "running", and "completed". (active, preparing, running, completed)
previousStateTransitionTime	string (date-time)	The time at which the Task entered its previous state. This property is not set if the Task is in its initial Active state.
requiredSlots	integer	The number of scheduling slots that the Task requires to run. The default is 1. A Task can only be scheduled to run on a compute node if the node has enough free scheduling slots available. For multi-instance Tasks, this must be 1.
resourceFiles	array	A list of files that the Batch service will download to the Compute Node before running the command line. For multi-instance Tasks, the resource files will only be downloaded to the Compute Node on which the primary Task is executed. There is a maximum size for the list of resource files. When the max size is exceeded, the request will fail and the response error code will be RequestEntityTooLarge. If this occurs, the collection of ResourceFiles must be reduced in size. This can be achieved using .zip files, Application Packages, or Docker Containers.
state	string	The current state of the Task. Required. Known values are: "active", "preparing", "running", and "completed". (active, preparing, running, completed)
stateTransitionTime	string (date-time)	The time at which the Task entered its current state. Required.
stats	object	Resource usage statistics for the Task.
url	string	The URL of the Task. Required.
userIdentity	object	The user identity under which the Task runs. If omitted, the Task runs as a non-administrative user unique to the Task.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_task	select	job_id, task_id, endpoint	timeOut, ocp-date, If-Modified-Since, If-Unmodified-Since, $select, $expand	Gets information about the specified Task. For multi-instance Tasks, information such as affinityId, executionInfo and nodeInfo refer to the primary Task. Use the list subtasks API to retrieve information about subtasks.
list_tasks	select	job_id, endpoint	timeOut, ocp-date, maxresults, $filter, $select, $expand	Lists all of the Tasks that are associated with the specified Job. For multi-instance Tasks, information such as affinityId, executionInfo and nodeInfo refer to the primary Task. Use the list subtasks API to retrieve information about subtasks.
create_task	insert	job_id, endpoint, id, commandLine	timeOut, ocp-date	Creates a Task to the specified Job. The maximum lifetime of a Task from addition to completion is 180 days. If a Task has not completed within 180 days of being added it will be terminated by the Batch service and left in whatever state it was in at that time.
delete_task	delete	job_id, task_id, endpoint	timeOut, ocp-date, If-Modified-Since, If-Unmodified-Since	Deletes a Task from the specified Job. When a Task is deleted, all of the files in its directory on the Compute Node where it ran are also deleted (regardless of the retention time). For multi-instance Tasks, the delete Task operation applies synchronously to the primary task; subtasks and their files are then deleted asynchronously in the background.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
endpoint	string	The service endpoint host (no scheme), e.g. myaccount.table.cosmos.azure.com:443 - value of the client endpoint parameter. (default: )
job_id	string	The ID of the Job from which to delete the Task. Required.
task_id	string	The ID of the Task to delete. Required.
$expand	array	An OData $expand clause. Default value is None.
$filter	string	An OData $filter clause. For more information on constructing this filter, see https://learn.microsoft.com/rest/api/batchservice/odata-filters-in-batch#list-tasks _. Default value is None.
$select	array	An OData $select clause. Default value is None.
If-Modified-Since	string	A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has been modified since the specified time. Default value is None.
If-Unmodified-Since	string	A timestamp indicating the last modified time of the resource known to the client. The operation will be performed only if the resource on the service has not been modified since the specified time. Default value is None.
maxresults	integer	The maximum number of items to return in the response. A maximum of 1000 applications can be returned. Default value is None.
ocp-date	string	The time the request was issued. Client libraries typically set this to the current system clock time; set it explicitly if you are calling the REST API directly. Default value is None.
timeOut	integer	The maximum time that the server can spend processing the request, in seconds. The default is 30 seconds. If the value is larger than 30, the default will be used instead.". Default value is None.

SELECT examples

get_task

Gets information about the specified Task. For multi-instance Tasks, information such as affinityId, executionInfo and nodeInfo refer to the primary Task. Use the list subtasks API to retrieve information about subtasks.

SELECT
id,
affinityInfo,
applicationPackageReferences,
commandLine,
constraints,
containerSettings,
creationTime,
dependsOn,
displayName,
eTag,
environmentSettings,
executionInfo,
exitConditions,
lastModified,
multiInstanceSettings,
nodeInfo,
outputFiles,
previousState,
previousStateTransitionTime,
requiredSlots,
resourceFiles,
state,
stateTransitionTime,
stats,
url,
userIdentity
FROM azure.batch_dataplane.tasks
WHERE job_id = '{{ job_id }}' -- required
AND task_id = '{{ task_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND timeOut = '{{ timeOut }}'
AND ocp-date = '{{ ocp-date }}'
AND If-Modified-Since = '{{ If-Modified-Since }}'
AND If-Unmodified-Since = '{{ If-Unmodified-Since }}'
AND $select = '{{ $select }}'
AND $expand = '{{ $expand }}'
;

list_tasks

Lists all of the Tasks that are associated with the specified Job. For multi-instance Tasks, information such as affinityId, executionInfo and nodeInfo refer to the primary Task. Use the list subtasks API to retrieve information about subtasks.

SELECT
id,
affinityInfo,
applicationPackageReferences,
commandLine,
constraints,
containerSettings,
creationTime,
dependsOn,
displayName,
eTag,
environmentSettings,
executionInfo,
exitConditions,
lastModified,
multiInstanceSettings,
nodeInfo,
outputFiles,
previousState,
previousStateTransitionTime,
requiredSlots,
resourceFiles,
state,
stateTransitionTime,
stats,
url,
userIdentity
FROM azure.batch_dataplane.tasks
WHERE job_id = '{{ job_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND timeOut = '{{ timeOut }}'
AND ocp-date = '{{ ocp-date }}'
AND maxresults = '{{ maxresults }}'
AND $filter = '{{ $filter }}'
AND $select = '{{ $select }}'
AND $expand = '{{ $expand }}'
;

INSERT examples

create_task

Creates a Task to the specified Job. The maximum lifetime of a Task from addition to completion is 180 days. If a Task has not completed within 180 days of being added it will be terminated by the Batch service and left in whatever state it was in at that time.

INSERT INTO azure.batch_dataplane.tasks (
id,
displayName,
exitConditions,
commandLine,
containerSettings,
resourceFiles,
outputFiles,
environmentSettings,
affinityInfo,
constraints,
requiredSlots,
userIdentity,
multiInstanceSettings,
dependsOn,
applicationPackageReferences,
job_id,
endpoint,
timeOut,
ocp-date
)
SELECT 
'{{ id }}' /* required */,
'{{ displayName }}',
'{{ exitConditions }}',
'{{ commandLine }}' /* required */,
'{{ containerSettings }}',
'{{ resourceFiles }}',
'{{ outputFiles }}',
'{{ environmentSettings }}',
'{{ affinityInfo }}',
'{{ constraints }}',
{{ requiredSlots }},
'{{ userIdentity }}',
'{{ multiInstanceSettings }}',
'{{ dependsOn }}',
'{{ applicationPackageReferences }}',
'{{ job_id }}',
'{{ endpoint }}',
'{{ timeOut }}',
'{{ ocp-date }}'
;

Manifest

# Description fields are for documentation purposes
- name: tasks
props:
  - name: job_id
    value: "{{ job_id }}"
    description: Required parameter for the tasks resource.
  - name: endpoint
    value: "{{ endpoint }}"
    description: Required parameter for the tasks resource.
  - name: id
    value: "{{ id }}"
    description: |
      A string that uniquely identifies the Task within the Job. The ID can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 64 characters. The ID is case-preserving and case-insensitive (that is, you may not have two IDs within a Job that differ only by case). Required.
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A display name for the Task. The display name need not be unique and can contain any Unicode characters up to a maximum length of 1024.
  - name: exitConditions
    description: |
      How the Batch service should respond when the Task completes.
    value:
      exitCodes:
        - code: {{ code }}
          exitOptions:
            jobAction: "{{ jobAction }}"
            dependencyAction: "{{ dependencyAction }}"
      exitCodeRanges:
        - start: {{ start }}
          end: {{ end }}
          exitOptions:
            jobAction: "{{ jobAction }}"
            dependencyAction: "{{ dependencyAction }}"
      preProcessingError:
        jobAction: "{{ jobAction }}"
        dependencyAction: "{{ dependencyAction }}"
      fileUploadError:
        jobAction: "{{ jobAction }}"
        dependencyAction: "{{ dependencyAction }}"
      default:
        jobAction: "{{ jobAction }}"
        dependencyAction: "{{ dependencyAction }}"
  - name: commandLine
    value: "{{ commandLine }}"
    description: |
      The command line of the Task. For multi-instance Tasks, the command line is executed as the primary Task, after the primary Task and all subtasks have finished executing the coordination command line. The command line does not run under a shell, and therefore cannot take advantage of shell features such as environment variable expansion. If you want to take advantage of such features, you should invoke the shell in the command line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in Linux. If the command line refers to file paths, it should use a relative path (relative to the Task working directory), or use the Batch provided environment variable (`https://learn.microsoft.com/azure/batch/batch-compute-node-environment-variables `_). Required.
  - name: containerSettings
    description: |
      The settings for the container under which the Task runs. If the Pool that will run this Task has containerConfiguration set, this must be set as well. If the Pool that will run this Task doesn't have containerConfiguration set, this must not be set. When this is specified, all directories recursively below the AZ_BATCH_NODE_ROOT_DIR (the root of Azure Batch directories on the node) are mapped into the container, all Task environment variables are mapped into the container, and the Task command line is executed in the container. Files produced in the container outside of AZ_BATCH_NODE_ROOT_DIR might not be reflected to the host disk, meaning that Batch file APIs will not be able to access those files.
    value:
      containerRunOptions: "{{ containerRunOptions }}"
      imageName: "{{ imageName }}"
      registry:
        username: "{{ username }}"
        password: "{{ password }}"
        registryServer: "{{ registryServer }}"
        identityReference:
          resourceId: "{{ resourceId }}"
      workingDirectory: "{{ workingDirectory }}"
      containerHostBatchBindMounts:
        - source: "{{ source }}"
          isReadOnly: {{ isReadOnly }}
  - name: resourceFiles
    description: |
      A list of files that the Batch service will download to the Compute Node before running the command line. For multi-instance Tasks, the resource files will only be downloaded to the Compute Node on which the primary Task is executed. There is a maximum size for the list of resource files. When the max size is exceeded, the request will fail and the response error code will be RequestEntityTooLarge. If this occurs, the collection of ResourceFiles must be reduced in size. This can be achieved using .zip files, Application Packages, or Docker Containers.
    value:
      - autoStorageContainerName: "{{ autoStorageContainerName }}"
        storageContainerUrl: "{{ storageContainerUrl }}"
        httpUrl: "{{ httpUrl }}"
        blobPrefix: "{{ blobPrefix }}"
        filePath: "{{ filePath }}"
        fileMode: "{{ fileMode }}"
        identityReference:
          resourceId: "{{ resourceId }}"
  - name: outputFiles
    description: |
      A list of files that the Batch service will upload from the Compute Node after running the command line. For multi-instance Tasks, the files will only be uploaded from the Compute Node on which the primary Task is executed.
    value:
      - filePattern: "{{ filePattern }}"
        destination:
          container:
            path: "{{ path }}"
            containerUrl: "{{ containerUrl }}"
            identityReference:
              resourceId: "{{ resourceId }}"
            uploadHeaders:
              - name: "{{ name }}"
                value: "{{ value }}"
        uploadOptions:
          uploadCondition: "{{ uploadCondition }}"
  - name: environmentSettings
    description: |
      A list of environment variable settings for the Task.
    value:
      - name: "{{ name }}"
        value: "{{ value }}"
  - name: affinityInfo
    description: |
      A locality hint that can be used by the Batch service to select a Compute Node on which to start the new Task.
    value:
      affinityId: "{{ affinityId }}"
  - name: constraints
    description: |
      The execution constraints that apply to this Task. If you do not specify constraints, the maxTaskRetryCount is the maxTaskRetryCount specified for the Job, the maxWallClockTime is infinite, and the retentionTime is 7 days.
    value:
      maxWallClockTime: "{{ maxWallClockTime }}"
      retentionTime: "{{ retentionTime }}"
      maxTaskRetryCount: {{ maxTaskRetryCount }}
  - name: requiredSlots
    value: {{ requiredSlots }}
    description: |
      The number of scheduling slots that the Task required to run. The default is 1. A Task can only be scheduled to run on a compute node if the node has enough free scheduling slots available. For multi-instance Tasks, this must be 1.
  - name: userIdentity
    description: |
      The user identity under which the Task runs. If omitted, the Task runs as a non-administrative user unique to the Task.
    value:
      username: "{{ username }}"
      autoUser:
        scope: "{{ scope }}"
        elevationLevel: "{{ elevationLevel }}"
  - name: multiInstanceSettings
    description: |
      An object that indicates that the Task is a multi-instance Task, and contains information about how to run the multi-instance Task.
    value:
      numberOfInstances: {{ numberOfInstances }}
      coordinationCommandLine: "{{ coordinationCommandLine }}"
      commonResourceFiles:
        - autoStorageContainerName: "{{ autoStorageContainerName }}"
          storageContainerUrl: "{{ storageContainerUrl }}"
          httpUrl: "{{ httpUrl }}"
          blobPrefix: "{{ blobPrefix }}"
          filePath: "{{ filePath }}"
          fileMode: "{{ fileMode }}"
          identityReference:
            resourceId: "{{ resourceId }}"
  - name: dependsOn
    description: |
      The Tasks that this Task depends on. This Task will not be scheduled until all Tasks that it depends on have completed successfully. If any of those Tasks fail and exhaust their retry counts, this Task will never be scheduled. If the Job does not have usesTaskDependencies set to true, and this element is present, the request fails with error code TaskDependenciesNotSpecifiedOnJob.
    value:
      taskIds:
        - "{{ taskIds }}"
      taskIdRanges:
        - start: {{ start }}
          end: {{ end }}
  - name: applicationPackageReferences
    description: |
      A list of Packages that the Batch service will deploy to the Compute Node before running the command line. Application packages are downloaded and deployed to a shared directory, not the Task working directory. Therefore, if a referenced package is already on the Node, and is up to date, then it is not re-downloaded; the existing copy on the Compute Node is used. If a referenced Package cannot be installed, for example because the package has been deleted or because download failed, the Task fails.
    value:
      - applicationId: "{{ applicationId }}"
        version: "{{ version }}"
  - name: timeOut
    value: {{ timeOut }}
    description: The maximum time that the server can spend processing the request, in seconds. The default is 30 seconds. If the value is larger than 30, the default will be used instead.". Default value is None.
    description: The maximum time that the server can spend processing the request, in seconds. The default is 30 seconds. If the value is larger than 30, the default will be used instead.". Default value is None.
  - name: ocp-date
    value: "{{ ocp-date }}"
    description: The time the request was issued. Client libraries typically set this to the current system clock time; set it explicitly if you are calling the REST API directly. Default value is None.
    description: The time the request was issued. Client libraries typically set this to the current system clock time; set it explicitly if you are calling the REST API directly. Default value is None.

DELETE examples

delete_task

Deletes a Task from the specified Job. When a Task is deleted, all of the files in its directory on the Compute Node where it ran are also deleted (regardless of the retention time). For multi-instance Tasks, the delete Task operation applies synchronously to the primary task; subtasks and their files are then deleted asynchronously in the background.

DELETE FROM azure.batch_dataplane.tasks
WHERE job_id = '{{ job_id }}' --required
AND task_id = '{{ task_id }}' --required
AND endpoint = '{{ endpoint }}' --required
AND timeOut = '{{ timeOut }}'
AND ocp-date = '{{ ocp-date }}'
AND If-Modified-Since = '{{ If-Modified-Since }}'
AND If-Unmodified-Since = '{{ If-Unmodified-Since }}'
;