Workspace class

Definition

Defines an Azure Machine Learning resource for managing training and deployment artifacts.

A Workspace is a fundamental resource for machine learning in Azure Machine Learning. You use a workspace to experiment, train, and deploy machine learning models. Each workspace is tied to an Azure subscription and resource group, and has an associated SKU.

For more information about workspaces, see:

Workspace(subscription_id, resource_group, workspace_name, auth=None, _location=None, _disable_service_check=False, _workspace_id=None, sku='basic')
Inheritance
builtins.object
Workspace

Parameters

subscription_id
str

The Azure subscription ID containing the workspace.

resource_group
str

The resource group containing the workspace.

workspace_name
str

The existing workspace name.

auth
ServicePrincipalAuthentication or InteractiveLoginAuthentication

The authentication object. For more details, see https://aka.ms/aml-notebook-auth. If None, the default Azure CLI credentials will be used or the API will prompt for credentials.

_location
str

Internal use only.

_disable_service_check
bool

Internal use only.

_workspace_id
str

Internal use only.

sku
str

The workspace SKU, which can be "basic" or "enterprise". For more information see Azure Machine Learning SKUs.

Remarks

The following sample shows how to create a workspace.


   from azureml.core import Workspace
   ws = Workspace.create(name='myworkspace',
               subscription_id='<azure-subscription-id>',
               resource_group='myresourcegroup',
               create_resource_group=True,
               location='eastus2'
               )

Set create_resource_group to False if you have an existing Azure resource group that you want to use for the workspace.

To use the same workspace in multiple environments, create a JSON configuration file. The configuration file saves your subscription, resource, and workspace name so that it can be easily loaded. To save the configuration use the write_config(path=None, file_name=None) method.


   ws.write_config(path="./file-path", file_name="ws_config.json")

To load the workspace from the configuration file, use the from_config(path=None, auth=None, _logger=None, _file_name=None) method.


   ws = Workspace.from_config()
   ws.get_details()

Alternatively, use the get(name, auth=None, subscription_id=None, resource_group=None) method to load an existing workspace without using configuration files.


   ws = Workspace.get(name="myworkspace",
               subscription_id='<azure-subscription-id>',
               resource_group='myresourcegroup')

The samples above may prompt you for Azure authentication credentials using an interactive login dialog. For other use cases, including using the Azure CLI to authenticate and authentication in automated workflows, see Authentication in Azure Machine Learning.

Methods

create(name, auth=None, subscription_id=None, resource_group=None, location=None, create_resource_group=True, sku='basic', friendly_name=None, storage_account=None, key_vault=None, app_insights=None, container_registry=None, default_cpu_compute_target=None, default_gpu_compute_target=None, exist_ok=False, show_output=True)

Create a new Azure Machine Learning Workspace.

Throws an exception if the workspace already exists or any of the workspace requirements are not satisfied.
delete(delete_dependent_resources=False, no_wait=False)

Delete the Azure Machine Learning Workspace resource.
from_config(path=None, auth=None, _logger=None, _file_name=None)

Return a workspace object from an existing Azure Machine Learning Workspace.

Reads workspace configuration from a file. Throws an exception if the config file can't be found.

The method provides a simple way to reuse the same workspace across multiple Python notebooks or projects. Users can save the workspace Azure Resource Manager (ARM) properties using the write_config(path=None, file_name=None) method, and use this method to load the same workspace in different Python notebooks or projects without retyping the workspace ARM properties.
get(name, auth=None, subscription_id=None, resource_group=None)

Return a workspace object for an existing Azure Machine Learning Workspace.

Throws an exception if the workspace does not exist or the required fields do not uniquely identify a workspace.
get_default_compute_target(type)

Get the default compute target for the workspace.
get_default_datastore()

Get the default datastore for the workspace.
get_default_keyvault()

Get the default key vault object for the workspace.
get_details()

Return the details of the workspace.
list(subscription_id, auth=None, resource_group=None)

List all workspaces that the user has access to within the subscription specified by subscription_id.

The list of workspaces can be filtered based on the resource group.
set_default_datastore(name)

Set the default datastore for the workspace.
setup()

Create a new workspace or retrieve an existing workspace.
write_config(path=None, file_name=None)

Write the workspace Azure Resource Manager (ARM) properties to a config file.

Workspace ARM properties can be loaded later using the from_config(path=None, auth=None, _logger=None, _file_name=None) method. The path defaults to '.azureml/' in the current working directory and file_name defaults to 'config.json'.

The method provides a simple way of reusing the same workspace across multiple Python notebooks or projects. Users can save the workspace ARM properties using this function, and use from_config to load the same workspace in different Python notebooks or projects without retyping the workspace ARM properties.

create(name, auth=None, subscription_id=None, resource_group=None, location=None, create_resource_group=True, sku='basic', friendly_name=None, storage_account=None, key_vault=None, app_insights=None, container_registry=None, default_cpu_compute_target=None, default_gpu_compute_target=None, exist_ok=False, show_output=True)

Create a new Azure Machine Learning Workspace.

Throws an exception if the workspace already exists or any of the workspace requirements are not satisfied.

create(name, auth=None, subscription_id=None, resource_group=None, location=None, create_resource_group=True, sku='basic', friendly_name=None, storage_account=None, key_vault=None, app_insights=None, container_registry=None, default_cpu_compute_target=None, default_gpu_compute_target=None, exist_ok=False, show_output=True)

Parameters

name
str

The new workspace name. The name must be between 2 and 32 characters long. The first character of the name must be alphanumeric (letter or number), but the rest of the name may contain alphanumerics, hyphens, and underscores. Whitespace is not allowed.

auth
ServicePrincipalAuthentication or InteractiveLoginAuthentication

The authentication object. For more details, see https://aka.ms/aml-notebook-auth. If None, the default Azure CLI credentials will be used or the API will prompt for credentials.

default value: None
subscription_id
str

The subscription ID of the containing subscription for the new workspace. The parameter is required if the user has access to more than one subscription.

default value: None
resource_group
str

The Azure resource group that contains the workspace. The parameter defaults to a mutation of the workspace name.

default value: None
location
str

The location of the workspace. The parameter defaults to the resource group location. The location has to be a supported region for Azure Machine Learning.

default value: None
create_resource_group
bool

Indicates whether to create the resource group if it doesn't exist.

default value: True
sku
str

The SKU name, which can be "basic" or "enterprise" (also referred as edition). The parameter defaults to "basic" if not specified. For more information see Azure Machine Learning SKUs.

default value: basic
friendly_name
str

A friendly name for the workspace that can be displayed in the UI.

default value: None
storage_account
str

An existing storage account in the Azure resource ID format. The storage will be used by the workspace to save run outputs, code, logs etc. If None, a new storage account will be created.

default value: None
key_vault
str

An existing key vault in the Azure resource ID format. See example code below for details of the Azure resource ID format. The key vault will be used by the workspace to store credentials added to the workspace by the users. If None, a new key vault will be created.

default value: None
app_insights
str

An existing Application Insights in the Azure resource ID format. See example code below for details of the Azure resource ID format. The Application Insights will be used by the workspace to log webservices events. If None, a new Application Insights will be created.

default value: None
container_registry
str

An existing container registry in the Azure resource ID format (see example code below for details of the Azure resource ID format). The container registry will be used by the workspace to pull and push both experimentation and webservices images. If None, a new container registry will be created only when needed and not along with workspace creation.

default value: None
default_cpu_compute_target
AmlComputeProvisioningConfiguration

A configuration that will be used to create a CPU compute. The parameter defaults to {min_nodes=0, max_nodes=2, vm_size="STANDARD_DS2_V2", vm_priority="dedicated"} If None, no compute will be created.

default value: None
default_gpu_compute_target
AmlComputeProvisioningConfiguration

A configuration that will be used to create a GPU compute. The parameter defaults to {min_nodes=0, max_nodes=2, vm_size="STANDARD_NC6", vm_priority="dedicated"} If None, no compute will be created.

default value: None
exist_ok
bool

Indicates whether this method succeeds if the workspace already exists. If False, this method fails if the workspace exists.

default value: False
show_output
bool

Indicates whether this method will print out incremental progress.

default value: True

Returns

The workspace object.

Return type

Workspace

Remarks

This first example requires only minimal specification, and all dependent resources as well as the resource group will be created automatically.


   from azureml.core import Workspace
   ws = Workspace.create(name='myworkspace',
                         subscription_id='<azure-subscription-id>',
                         resource_group='myresourcegroup',
                         create_resource_group=True,
                         location='eastus2')

The following example shows how to reuse existing Azure resources by making use of all parameters utilizing the Azure resource ID format. The specific Azure resource IDs can be retrieved through the Azure Portal or SDK. This assumes that the resource group, storage account, key vault, App Insights and container registry already exist.


   import os
   from azureml.core import Workspace
   from azureml.core.authentication import ServicePrincipalAuthentication

   service_principal_password = os.environ.get("AZUREML_PASSWORD")

   service_principal_auth = ServicePrincipalAuthentication(
       tenant_id="<tenant-id>",
       username="<application-id>",
       password=service_principal_password)

   ws = Workspace.create(name='myworkspace',
                         auth=service_principal_auth,
                         subscription_id='<azure-subscription-id>',
                         resource_group='myresourcegroup',
                         create_resource_group=False,
                         location='eastus2',
                         friendly_name='My workspace',
                         storage_account='subscriptions/<azure-subscription-id>/resourcegroups/myresourcegroup/providers/microsoft.storage/storageaccounts/mystorageaccount',
                         key_vault='subscriptions/<azure-subscription-id>/resourcegroups/myresourcegroup/providers/microsoft.keyvault/vaults/mykeyvault',
                         app_insights='subscriptions/<azure-subscription-id>/resourcegroups/myresourcegroup/providers/microsoft.insights/components/myappinsights',
                         container_registry='subscriptions/<azure-subscription-id>/resourcegroups/myresourcegroup/providers/microsoft.containerregistry/registries/mycontainerregistry',
                         exist_ok=False,
                         sku='enterprise')

delete(delete_dependent_resources=False, no_wait=False)

Delete the Azure Machine Learning Workspace resource.

delete(delete_dependent_resources=False, no_wait=False)

Parameters

delete_dependent_resources
bool

Set delete_dependent_resources=True for deleting workspace associated resources, i.e. container registry, storage account, key vault and application insights.

default value: False
no_wait
bool

Do not wait for the workspace deletion to complete.

default value: False

Returns

None if successful; otherwise, throws an error.

Return type

None

from_config(path=None, auth=None, _logger=None, _file_name=None)

Return a workspace object from an existing Azure Machine Learning Workspace.

Reads workspace configuration from a file. Throws an exception if the config file can't be found.

The method provides a simple way to reuse the same workspace across multiple Python notebooks or projects. Users can save the workspace Azure Resource Manager (ARM) properties using the write_config(path=None, file_name=None) method, and use this method to load the same workspace in different Python notebooks or projects without retyping the workspace ARM properties.

from_config(path=None, auth=None, _logger=None, _file_name=None)

Parameters

path
str

The path to the config file or starting directory to search. The parameter defaults to starting the search in the current directory.

default value: None
auth
ServicePrincipalAuthentication or InteractiveLoginAuthentication

The authentication object. For more details, see https://aka.ms/aml-notebook-auth. If None, the default Azure CLI credentials will be used or the API will prompt for credentials.

default value: None
_logger
Logger

Allows overriding the default logger.

default value: None
_file_name
str

Allows overriding the config file name to search for when path is a directory path.

default value: None

Returns

The workspace object for an existing Azure ML Workspace.

Return type

Workspace

get(name, auth=None, subscription_id=None, resource_group=None)

Return a workspace object for an existing Azure Machine Learning Workspace.

Throws an exception if the workspace does not exist or the required fields do not uniquely identify a workspace.

get(name, auth=None, subscription_id=None, resource_group=None)

Parameters

name
str

The name of the workspace to get.

auth
ServicePrincipalAuthentication or InteractiveLoginAuthentication

The authentication object. For more details refer to https://aka.ms/aml-notebook-auth. If None, the default Azure CLI credentials will be used or the API will prompt for credentials.

default value: None
subscription_id
str

The subscription ID to use. The parameter is required if the user has access to more than one subscription.

default value: None
resource_group
str

The resource group to use. If None, the method will search all resource groups in the subscription.

default value: None

Returns

The workspace object.

Return type

Workspace

get_default_compute_target(type)

Get the default compute target for the workspace.

get_default_compute_target(type)

Parameters

type
str

The type of compute. Possible values are 'CPU' or 'GPU'.

Returns

The default compute target for given compute type.

Return type

ComputeTarget

get_default_datastore()

Get the default datastore for the workspace.

get_default_datastore()

Returns

The default datastore.

Return type

Datastore

get_default_keyvault()

Get the default key vault object for the workspace.

get_default_keyvault()

Returns

The KeyVault object associated with the workspace.

Return type

Keyvault

get_details()

Return the details of the workspace.

get_details()

Returns

Workspace details in dictionary format.

Return type

dict[str, str]

Remarks

The returned dictionary contains the following key-value pairs.

  • id: URI pointing to this workspace resource, containing subscription ID, resource group, and workspace name.

  • name: The name of this workspace.

  • location: The workspace region.

  • type: A URI of the format "{providerName}/workspaces".

  • tags: Not currently used.

  • workspaceid: The ID of this workspace.

  • description: Not currently used.

  • friendlyName: A friendly name for the workspace displayed in the UI.

  • creationTime: Time this workspace was created, in ISO8601 format.

  • containerRegistry: The workspace container registry used to pull and push both experimentation and webservices images.

  • keyVault: The workspace key vault used to store credentials added to the workspace by the users.

  • applicationInsights: The Application Insights will be used by the workspace to log webservices events.

  • identityPrincipalId:

  • identityTenantId

  • identityType

  • storageAccount: The storage will be used by the workspace to save run outputs, code, logs, etc.

  • sku: The workspace SKU (also referred as edition). For more information see Azure Machine Learning SKUs.

For more information on these key-value pairs, see create(name, auth=None, subscription_id=None, resource_group=None, location=None, create_resource_group=True, sku='basic', friendly_name=None, storage_account=None, key_vault=None, app_insights=None, container_registry=None, default_cpu_compute_target=None, default_gpu_compute_target=None, exist_ok=False, show_output=True).

list(subscription_id, auth=None, resource_group=None)

List all workspaces that the user has access to within the subscription specified by subscription_id.

The list of workspaces can be filtered based on the resource group.

list(subscription_id, auth=None, resource_group=None)

Parameters

subscription_id
str

The subscription ID for which to list workspaces.

auth
ServicePrincipalAuthentication or InteractiveLoginAuthentication

The authentication object. For more details refer to https://aka.ms/aml-notebook-auth. If None, the default Azure CLI credentials will be used or the API will prompt for credentials.

default value: None
resource_group
str

A resource group to filter the returned workspaces. If None, the method will list all the workspaces within the specified subscription.

default value: None

Returns

A dictionary, where the key is workspace name, and the value is a list of Workspace objects.

Return type

dict

set_default_datastore(name)

Set the default datastore for the workspace.

set_default_datastore(name)

Parameters

name
str

The name of the Datastore to set as default.

setup()

Create a new workspace or retrieve an existing workspace.

setup()

Returns

A Workspace object.

Return type

Workspace

write_config(path=None, file_name=None)

Write the workspace Azure Resource Manager (ARM) properties to a config file.

Workspace ARM properties can be loaded later using the from_config(path=None, auth=None, _logger=None, _file_name=None) method. The path defaults to '.azureml/' in the current working directory and file_name defaults to 'config.json'.

The method provides a simple way of reusing the same workspace across multiple Python notebooks or projects. Users can save the workspace ARM properties using this function, and use from_config to load the same workspace in different Python notebooks or projects without retyping the workspace ARM properties.

write_config(path=None, file_name=None)

Parameters

path
str

User provided location to write the config.json file. The parameter defaults to '.azureml/' in the current working directory.

default value: None
file_name
str

Name to use for the config file. The parameter defaults to config.json.

default value: None

Attributes

compute_targets

List all compute targets in the workspace.

Returns

Dictionary with key as compute target name and value as a azureml.core.ComputeTarget object.

Return type

dict[str, ComputeTarget]

datasets

List all datasets in the workspace.

Returns

A dictionary where key is a dataset name and value is a Dataset object.

Return type

dict[str, Dataset]

datastores

List all datastores in the workspace. This operation does not return credentials of the datastores.

Returns

A dictionary where key is a datastore name and value is a Datastore object.

Return type

dict[str, Datastore]

environments

List all environments in the workspace.

Returns

Dictionary with key as environment name and value as the azureml.core.Environment object.

Return type

dict[str, Environment]

experiments

List all experiments in the workspace.

Returns

Dictionary with key as experiment name and value as an azureml.core.Experiment object.

Return type

dict[str, Experiment]

images

Return the list of images in the workspace.

Raises a WebserviceException if there was a problem interacting with model management service.

Returns

A dictionary where key is an image name and value is an Image object.

Return type

dict[str, Image]

location

Return the location of this workspace.

Returns

The location of this workspace.

Return type

str

models

Return a dictionary where the key is model name, and value is a Model object.

Raises a WebserviceException if there was a problem interacting with model management service.

Returns

A dictionary of models.

Return type

dict[str, Model]

name

Return the workspace name.

Returns

The workspace name.

Return type

str

resource_group

Return the resource group name for this workspace.

Returns

The resource group name.

Return type

str

service_context

Return the service context for this workspace.

Returns

Returns the ServiceContext object.

Return type

azureml._restclient.service_context.ServiceContext

sku

Return the SKU of this workspace.

Returns

The SKU of this workspace.

Return type

str

subscription_id

Return the subscription ID for this workspace.

Returns

The subscription ID.

Return type

str

webservices

Return a list of webservices in the workspace.

Raises a WebserviceException if there was a problem returning the list.

Returns

A list of webservices in the workspace.

Return type

dict[str, Webservice]

DEFAULT_CPU_CLUSTER_CONFIGURATION 

DEFAULT_CPU_CLUSTER_CONFIGURATION = <azureml.core.compute.amlcompute.AmlComputeProvisioningConfiguration object>

DEFAULT_CPU_CLUSTER_NAME 

DEFAULT_CPU_CLUSTER_NAME = 'cpu-cluster'

DEFAULT_GPU_CLUSTER_CONFIGURATION 

DEFAULT_GPU_CLUSTER_CONFIGURATION = <azureml.core.compute.amlcompute.AmlComputeProvisioningConfiguration object>

DEFAULT_GPU_CLUSTER_NAME 

DEFAULT_GPU_CLUSTER_NAME = 'gpu-cluster'