New-AzureBatchTask

Creates a Batch task under a job.

Warning

The AzureRM PowerShell module has been officially deprecated as of February 29, 2024. Users are advised to migrate from AzureRM to the Az PowerShell module to ensure continued support and updates.

Although the AzureRM module may still function, it's no longer maintained or supported, placing any continued use at the user's discretion and risk. Please refer to our migration resources for guidance on transitioning to the Az module.

Syntax

New-AzureBatchTask
   -JobId <String>
   -Id <String>
   [-DisplayName <String>]
   [-CommandLine <String>]
   [-ResourceFiles <IDictionary>]
   [-EnvironmentSettings <IDictionary>]
   [-AuthenticationTokenSettings <PSAuthenticationTokenSettings>]
   [-UserIdentity <PSUserIdentity>]
   [-AffinityInformation <PSAffinityInformation>]
   [-Constraints <PSTaskConstraints>]
   [-MultiInstanceSettings <PSMultiInstanceSettings>]
   [-DependsOn <TaskDependencies>]
   [-ApplicationPackageReferences <PSApplicationPackageReference[]>]
   [-OutputFile <PSOutputFile[]>]
   [-ExitConditions <PSExitConditions>]
   [-ContainerSettings <PSTaskContainerSettings>]
   -BatchContext <BatchAccountContext>
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
New-AzureBatchTask
   -JobId <String>
   [-Tasks <PSCloudTask[]>]
   -BatchContext <BatchAccountContext>
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
New-AzureBatchTask
   [-Job <PSCloudJob>]
   [-Tasks <PSCloudTask[]>]
   -BatchContext <BatchAccountContext>
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]
New-AzureBatchTask
   [-Job <PSCloudJob>]
   -Id <String>
   [-DisplayName <String>]
   [-CommandLine <String>]
   [-ResourceFiles <IDictionary>]
   [-EnvironmentSettings <IDictionary>]
   [-AuthenticationTokenSettings <PSAuthenticationTokenSettings>]
   [-UserIdentity <PSUserIdentity>]
   [-AffinityInformation <PSAffinityInformation>]
   [-Constraints <PSTaskConstraints>]
   [-MultiInstanceSettings <PSMultiInstanceSettings>]
   [-DependsOn <TaskDependencies>]
   [-ApplicationPackageReferences <PSApplicationPackageReference[]>]
   [-OutputFile <PSOutputFile[]>]
   [-ExitConditions <PSExitConditions>]
   [-ContainerSettings <PSTaskContainerSettings>]
   -BatchContext <BatchAccountContext>
   [-DefaultProfile <IAzureContextContainer>]
   [<CommonParameters>]

Description

The New-AzureBatchTask cmdlet creates an Azure Batch task under the job specified by the JobId parameter or the Job parameter.

Examples

Example 1: Create a Batch task

PS C:\>New-AzureBatchTask -JobId "Job-000001" -Id "Task23" -CommandLine "cmd /c dir /s" -BatchContext $Context

This command creates a task that has the ID Task23 under the job that has the ID Job-000001. The task runs the specified command. Use the Get-AzureRmBatchAccountKeys cmdlet to assign a context to the $Context variable.

Example 2: Create a Batch task

PS C:\> $autoUser = New-Object Microsoft.Azure.Commands.Batch.Models.PSAutoUserSpecification -ArgumentList @("Task", "Admin")
PS C:\> $userIdentity = New-Object Microsoft.Azure.Commands.Batch.Models.PSUserIdentity $autoUser
PS C:\>Get-AzureBatchJob -Id "Job-000001" -BatchContext $Context | New-AzureBatchTask -Id "Task26" -CommandLine "cmd /c echo hello > newFile.txt" -UserIdentity $userIdentity -BatchContext $Context

This command gets the Batch job that has the ID Job-000001 by using the Get-AzureBatchJob cmdlet. The command passes that job to the current cmdlet by using the pipeline operator. The command creates a task that has the ID Task26 under that job. The task runs the specified command by using elevated permissions.

Example 3: Add a collection of tasks to the specified job by using the pipeline

PS C:\>$Context = Get-AzureRmBatchAccountKeys -AccountName "ContosoBatchAccount"
PS C:\> $Task01 = New-Object Microsoft.Azure.Commands.Batch.Models.PSCloudTask("Task23", "cmd /c dir /s")
PS C:\> $Task02 = New-Object Microsoft.Azure.Commands.Batch.Models.PSCloudTask("Task24", "cmd /c dir /s")
PS C:\> Get-AzureBatchJob -Id "Job-000001" -BatchContext $Context | New-AzureBatchTask -Tasks @($Task01, $Task02) -BatchContext $Context

The first command creates an object reference to the account keys for the batch account named ContosoBatchAccount by using Get-AzureRmBatchAccountKeys. The command stores this object reference in the $Context variable. The next two commands create PSCloudTask objects by using the New-Object cmdlet. The commands store the tasks in the $Task01 and $Task02 variables. The final command gets the Batch job that has the ID Job-000001 by using Get-AzureBatchJob. Then the command passes that job to the current cmdlet by using the pipeline operator. The command adds a collection of tasks under that job. The command uses the context stored in $Context.

Example 4: Add a collection of tasks to the specified job

PS C:\>$Context = Get-AzureRmBatchAccountKeys -AccountName "ContosoBatchAccount"
PS C:\> $Task01 = New-Object Microsoft.Azure.Commands.Batch.Models.PSCloudTask("Task23", "cmd /c dir /s")
PS C:\> $Task02 = New-Object Microsoft.Azure.Commands.Batch.Models.PSCloudTask("Task24", "cmd /c dir /s")
PS C:\> New-AzureBatchTask -JobId "Job-000001" -Tasks @($Task01, $Task02) -BatchContext $Context

The first command creates an object reference to the account keys for the batch account named ContosoBatchAccount by using Get-AzureRmBatchAccountKeys. The command stores this object reference in the $Context variable. The next two commands create PSCloudTask objects by using the New-Object cmdlet. The commands store the tasks in the $Task01 and $Task02 variables. The final command adds the tasks stored in $Task01 and $Task02 under the job that has the ID Job-000001.

Example 5: Add a task with output files

PS C:\>New-AzureBatchTask -JobId "Job-000001" -Id "Task23" -CommandLine "cmd /c dir /s" -BatchContext $Context
PS C:\>$blobContainerDestination = New-Object Microsoft.Azure.Commands.Batch.Models.PSOutputFileBlobContainerDestination "https://myaccount.blob.core.windows.net/sascontainer?sv=2015-04-05&st=2015-04-29T22%3A18%3A26Z&se=2015-04-30T02%3A23%3A26Z&sr=b&sp=rw&spr=https&sig=Z%2FRHIX5Xcg0Mq2rqI3OlWTjEg2tYkboXr1P9ZUXDtkk%3D"
PS C:\>$destination = New-Object Microsoft.Azure.Commands.Batch.Models.PSOutputFileDestination $blobContainerDestination
PS C:\>$uploadOptions = New-Object Microsoft.Azure.Commands.Batch.Models.PSOutputFileUploadOptions "TaskSuccess"
PS C:\>$outputFile = New-Object Microsoft.Azure.Commands.Batch.Models.PSOutputFile "*.txt", $blobContainerDestination, $uploadOptions

PS C:\>New-AzureBatchTask -JobId "Job-000001" -Id "Task23" -CommandLine "cmd /c dir /s" -OutputFile $outputFile -BatchContext $Context

Example 6: Add a task with authentication token settings

PS C:\>$authSettings = New-Object Microsoft.Azure.Commands.Batch.Models.PSAuthenticationTokenSettings
PS C:\>$authSettings.Access = "Job"
PS C:\>New-AzureBatchTask -JobId "Job-000001" -Id "Task23" -CommandLine "cmd /c dir /s" -AuthenticationTokenSettings $authSettings -BatchContext $Context

Example 7: Add a task which runs in a container

PS C:\>New-AzureBatchTask -JobId "Job-000001" -Id "Task23" -CommandLine "cmd /c dir /s" -ContainerSettings New-Object Microsoft.Azure.Commands.Batch.Models.PSTaskContainerSettings "containerImageName"

Parameters

-AffinityInformation

Specifies a locality hint that the Batch service uses to select a node on which to run the task.

Type:PSAffinityInformation
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationPackageReferences

Type:PSApplicationPackageReference[]
Aliases:ApplicationPackageReference
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AuthenticationTokenSettings

The settings for an authentication token that the task can use to perform Batch service operations. If this is set, the Batch service provides the task with an authentication token which can be used to authenticate Batch service operations without requiring an account access key. The token is provided via the AZ_BATCH_AUTHENTICATION_TOKEN environment variable. The operations that the task can carry out using the token depend on the settings. For example, a task can request job permissions in order to add other tasks to the job, or check the status of the job or of other tasks.

Type:PSAuthenticationTokenSettings
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-BatchContext

Specifies the BatchAccountContext instance that this cmdlet uses to interact with the Batch service. If you use the Get-AzureRmBatchAccount cmdlet to get your BatchAccountContext, then Microsoft Entra authentication will be used when interacting with the Batch service. To use shared key authentication instead, use the Get-AzureRmBatchAccountKeys cmdlet to get a BatchAccountContext object with its access keys populated. When using shared key authentication, the primary access key is used by default. To change the key to use, set the BatchAccountContext.KeyInUse property.

Type:BatchAccountContext
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-CommandLine

Specifies the command line for the task.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Constraints

Specifies the execution constraints that apply to this task.

Type:PSTaskConstraints
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ContainerSettings

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.

Type:PSTaskContainerSettings
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with azure.

Type:IAzureContextContainer
Aliases:AzureRmContext, AzureCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DependsOn

Specifies that the task depends on other tasks. The task will not be scheduled until all depended-on tasks have completed successfully.

Type:TaskDependencies
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DisplayName

Specifies the display name of the task.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EnvironmentSettings

Specifies the environment settings, as key/value pairs, that this cmdlet adds to the task. The key is the environment setting name. The value is the environment setting.

Type:IDictionary
Aliases:EnvironmentSetting
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ExitConditions

Type:PSExitConditions
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Id

Specifies the ID of the task.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Job

Specifies the job under which this cmdlet creates the task. To obtain a PSCloudJob object, use the Get-AzureBatchJob cmdlet.

Type:PSCloudJob
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-JobId

Specifies the ID of the job under which this cmdlet creates the task.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-MultiInstanceSettings

Specifies information about how to run a multi-instance task.

Type:PSMultiInstanceSettings
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputFile

Gets or sets 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.

Type:PSOutputFile[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ResourceFiles

Specifies resource files, as key/value pairs, that the task requires. The key is the resource file path. The value is the resource file blob source.

Type:IDictionary
Aliases:ResourceFile
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Tasks

Specifies the collection of tasks to be added. Each task must have a unique ID.

Type:PSCloudTask[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UserIdentity

The user identity under which the task runs.

Type:PSUserIdentity
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

PSCloudJob

Parameters: Job (ByValue)

BatchAccountContext

Parameters: BatchContext (ByValue)

Outputs

Void