Update online deployment API

You can use this API to update an existing online deployment’s metadata.

HTTP method and URI path

PATCH /v3/published_models/{published_model_id}/deployments/{deployment_id}

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Authorization: <Bearer token>

Required authorizations

The user ID associated with the token which is specified in the request header needs to be granted with one of the following roles:

  • sysadm
  • mladm
  • apiuser (only if the deployment was created by the user)

Request body

The request content is expected to contain a JSON object, with the update operation specified in the key-value format. See Table 1 for the description of the fields.
Table 1. Supported parameters for the Update online deployment API

In this table, the Parameter column lists the supported parameters; the Type column lists the data type for the parameter, the Required or optional column indicates whether the parameter is required or optional for this request; and the Description column provides a brief description of the parameter.
Parameter Type Required or optional Description
op String Required

Specify the operation of the update.

Set to replace for updating existing fields.

Set to add for adding new fields.
path String Required

Specify the paths of the fields to be updated. The supported fields for op replace are:

  • " /deploy_info/artifactVersionHref"
  • " /name"
  • " /deploy_info/engineType"
  • " /deploy_info/scoringGroupId"
  • " /deploy_info/zaiu"
  • " /deploy_info/telum2"
  • " /deploy_info/batching"
  • " /deploy_info/maxLatencyInMs"
  • " /deploy_info/maxBatchSize"
  • " /deploy_info/conventionality"
  • " /deploy_info/timeout "
Note: With the " /deploy_info/timeout " optional input, you can:
  • Add a new timeout setting if one does not already exist. For example, "value": 60000
  • Replace an existing timeout setting with a new value. For example, "value": 30000
  • Remove an existing setting timeout.
value JSON object Optional Specify the values for the updated fields. For example, for artifactVersionHref update, users can specify the value for artifactVersionHref as the following: 
[
    {
       "op": "replace",
       "path": "/deploy_info/artifactVersionHref",
       "value": "/v3/ml_assets/models/7710a037-91b4-46b7-a00d-dc82dae085a9/versions/46c21a5c-0576-41e7-a6ee-b2a4af6dad35"
        }
    }
]

Example of request body:

Update the deployment with another model version

[
    {
       "op": "replace",
       "path": "/deploy_info/artifactVersionHref",
      "value": "/v3/ml_assets/models/7710a037-91b4-46b7-a00d-dc82dae085a9/versions/46c21a5c-0576-41e7-a6ee-b2a4af6dad35"   
     }
]

In this example, we update the existing deployment with a new model version. The request body indicates the artifactVersionHref field will be updated. The updated value is the model version href.

Expected response

On completion, the service returns an HTTP response, which includes a status code that indicates whether your request is completed. Status code 200 indicates a successful completion. The response from a successful request returns the completed updated model version metadata. See the Get deployment detail API for the response details.

HTTP status codes

For unsuccessful requests, the service returns the status codes that are described in Table 2.

Table 2. HTTP error response
HTTP status code Error response Description
400 patch_path_not_allowed Path is not allowed in the request body. Check the supported path list in the introduction of request body for path.
400 path_error The value specified for patch is not valid for the new metadata json fields. Check the value.
400 Duplicate deployment name The deployment name already exists. Select another name.
400 Invalid model version href The model version href is invalid.
400 timeout_not_supported The timeout value must be an integer greater than 0 and is supported only for the online deployment type with the PMML engine only.
500 Update failed Failed to update the deployment.
Important:

Machine Learning for IBM z/OS® delivers exceptional throughput and performance for inferencing tasks. However, in rare scenarios, an inferencing request may take longer than expected. To handle this, use the scoring timeout option to cancel the long-running inferencing requests automatically.

Set a reasonable timeout value. A low timeout might reject most incoming inferencing requests, causing real-time online scoring failures.

Timeout introduces a minor performance overhead. Enable it only when necessary.