Share via

JobOperations Class

  • Reference

Initiates an instance of JobOperations

This class should not be instantiated directly. Instead, use the jobs attribute of an MLClient object.

Inheritance
azure.ai.ml._scope_dependent_operations._ScopeDependentOperations
JobOperations

Constructor

JobOperations(operation_scope: OperationScope, operation_config: OperationConfig, service_client_02_2023_preview: AzureMachineLearningWorkspaces, all_operations: OperationsContainer, credential: TokenCredential, **kwargs: Any)

Parameters

Name Description
operation_scope
Required
<xref:azure.ai.ml._scope_dependent_operations.OperationScope>

Scope variables for the operations classes of an MLClient object.
operation_config
Required
<xref:azure.ai.ml._scope_dependent_operations.OperationConfig>

Common configuration for operations classes of an MLClient object.
service_client_02_2023_preview
Required
<xref:azure.ai.ml._restclient.v2023_02_01_preview.AzureMachineLearningWorkspaces>

Service client to allow end users to operate on Azure Machine Learning Workspace resources.
all_operations
Required
<xref:azure.ai.ml._scope_dependent_operations.OperationsContainer>

All operations classes of an MLClient object.
credential
Required
TokenCredential

Credential to use for authentication.

Methods

archive

Archives a job.
begin_cancel

Cancels a job.
create_or_update

Creates or updates a job. If entities such as Environment or Code are defined inline, they'll be created together with the job.
download

Downloads the logs and output of a job.
get

Gets a job resource.
list

Lists jobs in the workspace.
restore

Restores an archived job.
show_services

Gets services associated with a job's node.
stream

Streams the logs of a running job.
validate

Validates a Job object before submitting to the service. Anonymous assets may be created if there are inline defined entities such as Component, Environment, and Code. Only pipeline jobs are supported for validation currently.

archive

Archives a job.

archive(name: str) -> None

Parameters

Name Description
name
Required
str

The name of the job.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Archiving a job.


   ml_client.jobs.archive(name=job_name)

begin_cancel

Cancels a job.

begin_cancel(name: str, **kwargs: Any) -> LROPoller[None]

Parameters

Name Description
name
Required
str

The name of the job.

Returns

Type Description
LROPoller[None]

A poller to track the operation status.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Canceling the job named "iris-dataset-job-1" and checking the poller for status.


   cancel_poller = ml_client.jobs.begin_cancel(job_name)
   print(cancel_poller.result())

create_or_update

Creates or updates a job. If entities such as Environment or Code are defined inline, they'll be created together with the job.

create_or_update(job: Job, *, description: str | None = None, compute: str | None = None, tags: dict | None = None, experiment_name: str | None = None, skip_validation: bool = False, **kwargs: Any) -> Job

Parameters

Name Description
job
Required
Job

The job object.

Keyword-Only Parameters

Name Description
description
Optional[str]

The job description.
compute
Optional[str]

The compute target for the job.
tags
Optional[dict]

The tags for the job.
experiment_name
Optional[str]

The name of the experiment the job will be created under. If None is provided, job will be created under experiment 'Default'.
skip_validation
bool

Specifies whether or not to skip validation before creating or updating the job. Note that validation for dependent resources such as an anonymous component will not be skipped. Defaults to False.

Returns

Type Description
Job

Created or updated job.

Exceptions

Type Description
Union
UserErrorException
ValidationException

Raised if Job cannot be successfully validated. Details will be provided in the error message.
AssetException

Raised if Job assets (e.g. Data, Code, Model, Environment) cannot be successfully validated. Details will be provided in the error message.
ModelException

Raised if Job model cannot be successfully validated. Details will be provided in the error message.
JobException

Raised if Job object or attributes correctly formatted. Details will be provided in the error message.
EmptyDirectoryError

Raised if local path provided points to an empty directory.
DockerEngineNotAvailableError

Raised if Docker Engine is not available for local job.

Examples

Creating a new job and then updating its compute.


   from azure.ai.ml import load_job

   created_job = ml_client.jobs.create_or_update(
       name=job_name,
       job=load_job(
           "./sdk/ml/azure-ai-ml/tests/test_configs/command_job/command_job_test_local_env.yml",
           params_override=[{"name": job_name}, {"compute": "cpucluster"}],
       ),
   )

download

Downloads the logs and output of a job.

download(name: str, *, download_path: PathLike | str = '.', output_name: str | None = None, all: bool = False) -> None

Parameters

Name Description
name
Required
str

The name of a job.

Keyword-Only Parameters

Name Description
download_path
Union[<xref:PathLike>, str]

The local path to be used as the download destination. Defaults to ".".
output_name
Optional[str]

The name of the output to download. Defaults to None.
all
bool

Specifies if all logs and named outputs should be downloaded. Defaults to False.

Exceptions

Type Description
JobException

Raised if Job is not yet in a terminal state. Details will be provided in the error message.
MlException

Raised if logs and outputs cannot be successfully downloaded. Details will be provided in the error message.

Examples

Downloading all logs and named outputs of the job "job-1" into local directory "job-1-logs".


   ml_client.jobs.download(name=job_name, download_path="./job-1-logs", all=True)

get

Gets a job resource.

get(name: str) -> Job

Parameters

Name Description
name
Required
str

The name of the job.

Returns

Type Description
Job

Job object retrieved from the service.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.
UserErrorException

Raised if the name parameter is not a string.

Examples

Retrieving a job named "iris-dataset-job-1".


   retrieved_job = ml_client.jobs.get(job_name)

list

Lists jobs in the workspace.

list(*, parent_job_name: str | None = None, list_view_type: ListViewType = ListViewType.ACTIVE_ONLY, **kwargs: Any) -> Iterable[Job]

Keyword-Only Parameters

Name Description
parent_job_name
Optional[str]

When provided, only returns jobs that are children of the named job. Defaults to None, listing all jobs in the workspace.
list_view_type
ListViewType

The view type for including/excluding archived jobs. Defaults to ~azure.mgt.machinelearningservices.models.ListViewType.ACTIVE_ONLY, excluding archived jobs.

Returns

Type Description
ItemPaged[Job]

An iterator-like instance of Job objects.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Retrieving a list of the archived jobs in a workspace with parent job named "iris-dataset-jobs".


   from azure.ai.ml._restclient.v2023_04_01_preview.models import ListViewType

   list_of_jobs = ml_client.jobs.list(parent_job_name=job_name, list_view_type=ListViewType.ARCHIVED_ONLY)

restore

Restores an archived job.

restore(name: str) -> None

Parameters

Name Description
name
Required
str

The name of the job.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Restoring an archived job.


   ml_client.jobs.restore(name=job_name)

show_services

Gets services associated with a job's node.

show_services(name: str, node_index: int = 0) -> Dict[str, ServiceInstance] | None

Parameters

Name Description
name
Required
str

The name of the job.
node_index
Required
int

The node's index (zero-based). Defaults to 0.

Returns

Type Description
dict[str, ServiceInstance]

The services associated with the job for the given node.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Retrieving the services associated with a job's 1st node.


   job_services = ml_client.jobs.show_services(job_name)

stream

Streams the logs of a running job.

stream(name: str) -> None

Parameters

Name Description
name
Required
str

The name of the job.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Streaming a running job.


   running_job = ml_client.jobs.create_or_update(
       load_job(
           "./sdk/ml/azure-ai-ml/tests/test_configs/command_job/command_job_test_local_env.yml",
           params_override=[{"name": job_name}, {"compute": "cpucluster"}],
       )
   )
   ml_client.jobs.stream(running_job.name)

validate

Validates a Job object before submitting to the service. Anonymous assets may be created if there are inline defined entities such as Component, Environment, and Code. Only pipeline jobs are supported for validation currently.

validate(job: Job, *, raise_on_failure: bool = False, **kwargs: Any) -> ValidationResult

Parameters

Name Description
job
Required
Job

The job object to be validated.

Keyword-Only Parameters

Name Description
raise_on_failure
bool

Specifies if an error should be raised if validation fails. Defaults to False.

Returns

Type Description
ValidationResult

A ValidationResult object containing all found errors.

Exceptions

Type Description
ResourceNotFoundError

Raised if no job with the given name can be found.

Examples

Validating a PipelineJob object and printing out the found errors.


   from azure.ai.ml import load_job
   from azure.ai.ml.entities import PipelineJob

   pipeline_job: PipelineJob = load_job(
       "./sdk/ml/azure-ai-ml/tests/test_configs/pipeline_jobs/invalid/combo.yml",
       params_override=[{"name": job_name}, {"compute": "cpucluster"}],
   )
   print(ml_client.jobs.validate(pipeline_job).error_messages)