JobOperations Class

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)