Webservice Class

Reference

Defines base functionality for deploying models as web service endpoints in Azure Machine Learning.

Webservice constructor is used to retrieve a cloud representation of a Webservice object associated with the provided Workspace. Returns an instance of a child class corresponding to the specific type of the retrieved Webservice object. The Webservice class allows for deploying machine learning models from either a Model or Image object.

For more information about working with Webservice, see Deploy models with Azure Machine Learning.

Initialize the Webservice instance.

The Webservice constructor retrieves a cloud representation of a Webservice object associated with the provided workspace. It will return an instance of a child class corresponding to the specific type of the retrieved Webservice object.

Inheritance: ABC

Webservice

Constructor

Webservice(workspace, name)

Parameters

Name	Description
workspace Required	Workspace The workspace object containing the Webservice object to retrieve.
name Required	str The name of the of the Webservice object to retrieve.
workspace Required	Workspace The workspace object containing the Webservice object to retrieve.
name Required	str The name of the of the Webservice object to retrieve.

Remarks

The following sample shows the recommended deployment pattern where you first create a configuration object with the deploy_configuration method of the child class of Webservice (in this case AksWebservice) and then use the configuration with the deploy method of the Model class.


   # Set the web service configuration (using default here)
   aks_config = AksWebservice.deploy_configuration()

   # # Enable token auth and disable (key) auth on the webservice
   # aks_config = AksWebservice.deploy_configuration(token_auth_enabled=True, auth_enabled=False)

The following sample shows how to find an existing AciWebservice in a workspace and delete it if it exists so the name can be reused.


   from azureml.core.model import InferenceConfig
   from azureml.core.webservice import AciWebservice


   service_name = 'my-custom-env-service'

   inference_config = InferenceConfig(entry_script='score.py', environment=environment)
   aci_config = AciWebservice.deploy_configuration(cpu_cores=1, memory_gb=1)

   service = Model.deploy(workspace=ws,
                          name=service_name,
                          models=[model],
                          inference_config=inference_config,
                          deployment_config=aci_config,
                          overwrite=True)
   service.wait_for_deployment(show_output=True)

There are a number of ways to deploy a model as a webservice, including with the:

deploy method of the Model for models already registered in the workspace.
deploy_from_image method of Webservice for images already created from a model.
deploy_from_model method of Webservice for models already registered in the workspace. This method will create an image.
deploy method of the Webservice, which will register a model and create an image.

For information on working with webservices, see

The Variables section lists attributes of a local representation of the cloud Webservice object. These variables should be considered read-only. Changing their values will not be reflected in the corresponding cloud object.

Variables

Name	Description
auth_enabled	bool Whether or not the Webservice has auth enabled.
compute_type	str What type of compute the Webservice is deployed to.
created_time	datetime When the Webservice was created.
azureml.core.Webservice.description	A description of the Webservice object.
azureml.core.Webservice.tags	A dictionary of tags for the Webservice object.
azureml.core.Webservice.name	The name of the Webservice.
azureml.core.Webservice.properties	Dictionary of key value properties for the Webservice. These properties cannot be changed after deployment, however new key value pairs can be added.
created_by	str The user that created the Webservice.
error	str If the Webservice failed to deploy, this will contain the error message for why it failed.
azureml.core.Webservice.state	The current state of the Webservice.
updated_time	datetime The last time the Webservice was updated.
azureml.core.Webservice.workspace	The Azure Machine Learning Workspace which contains this Webservice.
token_auth_enabled	bool Whether or not the Webservice has token auth enabled.

Methods

check_for_existing_webservice	Check webservice exists.
delete	Delete this Webservice from its associated workspace. This function call is not asynchronous. The call runs until the resource is deleted. A WebserviceException is raised if there is a problem deleting the model from the Model Management Service.
deploy	Deploy a Webservice from zero or more Model objects. This function will register any models files provided and create an image in the process, all associated with the specified Workspace. Use this function when you have a directory of models to deploy that haven't been previously registered. The resulting Webservice is a real-time endpoint that can be used for inference requests. For more information, see Consume a model deployed as a web service.
deploy_from_image	Deploy a Webservice from an Image object. Use this function if you already have an Image object created for a model. The resulting Webservice is a real-time endpoint that can be used for inference requests. For more information, see Consume a model deployed as a web service.
deploy_from_model	Deploy a Webservice from zero or more Model objects. This function is similar to deploy, but does not register the models. Use this function if you have model objects that are already registered. This will create an image in the process, associated with the specified Workspace. The resulting Webservice is a real-time endpoint that can be used for inference requests. For more information, see Consume a model deployed as a web service.
deploy_local_from_model	Build and deploy a LocalWebservice for testing. Requires Docker to be installed and configured.
deserialize	Convert a Model Management Service response JSON object into a Webservice object. Will fail if the provided workspace is not the workspace the Webservice is registered under.
get_keys	Retrieve auth keys for this Webservice.
get_logs	Retrieve logs for this Webservice.
get_token	Retrieve auth token for this Webservice, scoped to the current user.
list	List the Webservices associated with the corresponding Workspace. The results returned can be filtered using parameters.
regen_key	Regenerate one of the Webservice's keys, either the 'Primary' or 'Secondary' key. A WebserviceException is raised if `key` is not specified or is not 'Primary' or 'Secondary'.
run	Call this Webservice with the provided input. Abstract method implemented by child classes of Webservice.
serialize	Convert this Webservice object into a JSON serialized dictionary. Use deserialize to convert back into a Webservice object.
update	Update the Webservice parameters. This is an abstract method implemented by child classes of Webservice. Possible parameters to update vary based on Webservice child type. For example, for Azure Container Instances webservices, see update for specific parameters.
update_deployment_state	Refresh the current state of the in-memory object. Perform an in-place update of the properties of the object based on the current state of the corresponding cloud object. Primarily useful for manual polling of creation state.
wait_for_deployment	Automatically poll on the running Webservice deployment. Wait for the Webservice to reach a terminal state. Will throw a WebserviceException if it reaches a non-successful terminal state or exceeds the provided timeout.

check_for_existing_webservice

Check webservice exists.

static check_for_existing_webservice(workspace, name, overwrite=False, request_func=None, check_func=None)

Parameters

Name	Description
workspace Required	Workspace
name Required	str
overwrite	bool Default value: False
request_func	<xref:function> function to request service to check if service name exists Default value: None
check_func	<xref:function> function to check response content of request_func Default value: None

Exceptions

Type	Description
WebserviceException

delete

Delete this Webservice from its associated workspace.

This function call is not asynchronous. The call runs until the resource is deleted. A WebserviceException is raised if there is a problem deleting the model from the Model Management Service.

delete()

Exceptions

Type	Description
WebserviceException

deploy

Deploy a Webservice from zero or more Model objects.

This function will register any models files provided and create an image in the process, all associated with the specified Workspace. Use this function when you have a directory of models to deploy that haven't been previously registered.

The resulting Webservice is a real-time endpoint that can be used for inference requests. For more information, see Consume a model deployed as a web service.

static deploy(workspace, name, model_paths, image_config, deployment_config=None, deployment_target=None, overwrite=False)

Parameters

Name	Description
workspace Required	Workspace A Workspace object to associate the Webservice with.
name Required	str The name to give the deployed service. Must be unique to the workspace, only consist of lowercase letters, numbers, or dashes, start with a letter, and be between 3 and 32 characters long.
model_paths Required	list[str] A list of on-disk paths to model files or folder. Can be an empty list.
image_config Required	ImageConfig An ImageConfig object used to determine required Image properties.
deployment_config	WebserviceDeploymentConfiguration A WebserviceDeploymentConfiguration used to configure the webservice. If one is not provided, an empty configuration object will be used based on the desired target. Default value: None
deployment_target	ComputeTarget A ComputeTarget to deploy the Webservice to. As Azure Container Instances has no associated ComputeTarget, leave this parameter as None to deploy to Azure Container Instances. Default value: None
overwrite	bool Overwrite the existing service if service with name already exists. Default value: False

Returns

Type	Description
Webservice	A Webservice object corresponding to the deployed webservice.

Exceptions

Type	Description
WebserviceException

deploy_from_image

Deploy a Webservice from an Image object.

Use this function if you already have an Image object created for a model.

The resulting Webservice is a real-time endpoint that can be used for inference requests. For more information, see Consume a model deployed as a web service.

static deploy_from_image(workspace, name, image, deployment_config=None, deployment_target=None, overwrite=False)

Parameters

Name	Description
workspace Required	Workspace A Workspace object to associate the Webservice with.
name Required	str The name to give the deployed service. Must be unique to the workspace, only consist of lowercase letters, numbers, or dashes, start with a letter, and be between 3 and 32 characters long.
image Required	Image An Image object to deploy.
deployment_config	WebserviceDeploymentConfiguration A WebserviceDeploymentConfiguration used to configure the webservice. If one is not provided, an empty configuration object will be used based on the desired target. Default value: None
deployment_target	ComputeTarget A ComputeTarget to deploy the Webservice to. As Azure Container Instances has no associated ComputeTarget, leave this parameter as None to deploy to Azure Container Instances. Default value: None
overwrite	bool Overwrite the existing service if service with name already exists. Default value: False

Returns

Type	Description
Webservice	A Webservice object corresponding to the deployed webservice.

Exceptions

Type	Description
WebserviceException

deploy_from_model

Deploy a Webservice from zero or more Model objects.

This function is similar to deploy, but does not register the models. Use this function if you have model objects that are already registered. This will create an image in the process, associated with the specified Workspace.

The resulting Webservice is a real-time endpoint that can be used for inference requests. For more information, see Consume a model deployed as a web service.

static deploy_from_model(workspace, name, models, image_config, deployment_config=None, deployment_target=None, overwrite=False)

Parameters

Name	Description
workspace Required	Workspace A Workspace object to associate the Webservice with.
name Required	str The name to give the deployed service. Must be unique to the workspace, only consist of lowercase letters, numbers, or dashes, start with a letter, and be between 3 and 32 characters long.
models Required	list[Model] A list of model objects. Can be an empty list.
image_config Required	ImageConfig An ImageConfig object used to determine required Image properties.
deployment_config	WebserviceDeploymentConfiguration A WebserviceDeploymentConfiguration used to configure the webservice. If one is not provided, an empty configuration object will be used based on the desired target. Default value: None
deployment_target	ComputeTarget A ComputeTarget to deploy the Webservice to. As ACI has no associated ComputeTarget, leave this parameter as None to deploy to ACI. Default value: None
overwrite	bool Overwrite the existing service if service with name already exists. Default value: False

Returns

Type	Description
Webservice	A Webservice object corresponding to the deployed webservice.

Exceptions

Type	Description
WebserviceException

deploy_local_from_model

Build and deploy a LocalWebservice for testing.

Requires Docker to be installed and configured.

static deploy_local_from_model(workspace, name, models, image_config, deployment_config=None, wait=False)

Parameters

Name	Description
workspace Required	Workspace A Workspace object with which to associate the Webservice.
name Required	str The name to give the deployed service. Must be unique on the local machine.
models Required	list[Model] A list of model objects. Can be an empty list.
image_config Required	ImageConfig An ImageConfig object used to determine required service image properties.
deployment_config	LocalWebserviceDeploymentConfiguration A LocalWebserviceDeploymentConfiguration used to configure the webservice. If one is not provided, an empty configuration object will be used. Default value: None
wait	bool Whether to wait for the LocalWebservice's Docker container to report as healthy. Throws an exception if the container crashes. The default is False. Default value: False

Returns

Type	Description
LocalWebservice

Exceptions

Type	Description
WebserviceException

deserialize

Convert a Model Management Service response JSON object into a Webservice object.

Will fail if the provided workspace is not the workspace the Webservice is registered under.

deserialize(workspace, webservice_payload)

Parameters

Name	Description
cls Required	Indicates that this is a class method.
workspace Required	Workspace The workspace object the Webservice is registered under.
webservice_payload Required	dict A JSON object to convert to a Webservice object.

Returns

Type	Description
Webservice	The Webservice representation of the provided JSON object.

Exceptions

Type	Description
WebserviceException

get_keys

Retrieve auth keys for this Webservice.

get_keys()

Returns

Type	Description
(str, str)	The auth keys for this Webservice.

Exceptions

Type	Description
WebserviceException

get_logs

Retrieve logs for this Webservice.

get_logs(num_lines=5000, init=False)

Parameters

Name	Description
num_lines	int The maximum number of log lines to retrieve. Default value: 5000
init	bool Get logs of init container Default value: False

Returns

Type	Description
str	The logs for this Webservice.

Exceptions

Type	Description
WebserviceException

get_token

Retrieve auth token for this Webservice, scoped to the current user.

get_token()

Returns

Type	Description
str, datetime	The auth token for this Webservice and when it should be refreshed after.

Exceptions

Type	Description
WebserviceException

list

List the Webservices associated with the corresponding Workspace.

The results returned can be filtered using parameters.

static list(workspace, compute_type=None, image_name=None, image_id=None, model_name=None, model_id=None, tags=None, properties=None, image_digest=None)

Parameters

Name	Description
workspace Required	Workspace The Workspace object to list the Webservices in.
compute_type	str Filter to list only specific Webservice types. Options are 'ACI', 'AKS'. Default value: None
image_name	str Filter list to only include Webservices deployed with the specific image name. Default value: None
image_id	str Filter list to only include Webservices deployed with the specific image ID. Default value: None
model_name	str Filter list to only include Webservices deployed with the specific model name. Default value: None
model_id	str Filter list to only include Webservices deployed with the specific model ID. Default value: None
tags	list Filter based on the provided list, by either 'key' or '[key, value]'. Ex. ['key', ['key2', 'key2 value']] Default value: None
properties	list Filter based on the provided list, by either 'key' or '[key, value]'. Ex. ['key', ['key2', 'key2 value']] Default value: None
image_digest	str Filter list to only include Webservices deployed with the specific image digest. Default value: None

Returns

Type	Description
list[Webservice]	A filtered list of Webservices in the provided Workspace.

Exceptions

Type	Description
WebserviceException

regen_key

Regenerate one of the Webservice's keys, either the 'Primary' or 'Secondary' key.

A WebserviceException is raised if key is not specified or is not 'Primary' or 'Secondary'.

regen_key(key, set_key=None)

Parameters

Name	Description
key Required	str The key to regenerate. Options are 'Primary' or 'Secondary'.
set_key	str A user specified value allowing for manual specification of the key's value Default value: None

Exceptions

Type	Description
WebserviceException

run

Call this Webservice with the provided input.

Abstract method implemented by child classes of Webservice.

abstract run(input)

Parameters

Name	Description
input Required	<xref:varies> The input data to call the Webservice with. This is the data your machine learning model expects as an input to run predictions.

Returns

Type	Description
dict	The result of calling the Webservice. This will return predictions run from your machine learning model.

Exceptions

Type	Description
WebserviceException

serialize

Convert this Webservice object into a JSON serialized dictionary.

Use deserialize to convert back into a Webservice object.

serialize()

Returns

Type	Description
dict	The JSON representation of this Webservice.

Exceptions

Type	Description
WebserviceException

update

Update the Webservice parameters.

This is an abstract method implemented by child classes of Webservice. Possible parameters to update vary based on Webservice child type. For example, for Azure Container Instances webservices, see update for specific parameters.

abstract update(*args)

Parameters

Name	Description
args Required	<xref:varies> Values to update.

Exceptions

Type	Description
WebserviceException

update_deployment_state

Refresh the current state of the in-memory object.

Perform an in-place update of the properties of the object based on the current state of the corresponding cloud object. Primarily useful for manual polling of creation state.

update_deployment_state()

Exceptions

Type	Description
WebserviceException

wait_for_deployment

Automatically poll on the running Webservice deployment.

Wait for the Webservice to reach a terminal state. Will throw a WebserviceException if it reaches a non-successful terminal state or exceeds the provided timeout.

wait_for_deployment(show_output=False, timeout_sec=None)

Parameters

Name	Description
show_output	bool Indicates whether to print more verbose output. Default value: False
timeout_sec	float Raise an exception if deployment exceeds the given timeout. Default value: None

Exceptions

Type	Description
WebserviceException

Share via

Webservice Class

Constructor

Parameters

Remarks

Variables

Methods

check_for_existing_webservice

Parameters

Exceptions

delete

Exceptions

deploy

Parameters

Returns

Exceptions

deploy_from_image

Parameters

Returns

Exceptions

deploy_from_model

Parameters

Returns

Exceptions

deploy_local_from_model

Parameters

Returns

Exceptions

deserialize

Parameters

Returns

Exceptions

get_keys

Returns

Exceptions

get_logs

Parameters

Returns

Exceptions

get_token

Returns

Exceptions

list

Parameters

Returns

Exceptions

regen_key

Parameters

Exceptions

run

Parameters

Returns

Exceptions

serialize

Returns

Exceptions

update

Parameters

Exceptions

update_deployment_state

Exceptions

wait_for_deployment

Parameters

Exceptions

Feedback

Additional resources