Modifying the Description of a Development Environment Instance

Function

This API is used to modify the description of a development environment instance or information about the auto stop function.

URI

PUT /v1/{project_id}/demanager/instances/{instance_id}

Table 1 describes the required parameters.

Table 1 Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see Obtaining a Project ID and Name.

instance_id

Yes

String

Instance ID

Request Body

Table 2 describes the request parameters.

Table 2 Parameters

Parameter

Mandatory

Type

Description

description

No

String

Configuration description. The value contains a maximum of 512 characters and cannot contain the following special characters: &<>"'/.

spec

No

Object

Instance definition. For details, see Table 3.

Table 3 spec parameters

Parameter

Mandatory

Type

Description

auto_stop

No

Object

Auto stop parameter. For details, see Table 4.

Table 4 auto_stop parameters

Parameter

Mandatory

Type

Description

enable

No

Boolean

Whether to enable the auto stop function. The value true indicates that the function is enabled and the instance will automatically stop when the running duration is reached. The value false indicates that the function is disabled. The default value is false.

duration

No

Integer

Running duration, in seconds. The value ranges from 3,600 to 86,400. After this parameter is set, it is valid for each startup. This parameter is mandatory when enable is set to true. If the current instance status is Running, the modifications of this parameter take effect only after the next startup.

prompt

No

Boolean

Whether to display a prompt again. This parameter is provided for the console to determine whether to display a prompt again. The default value is true.

Response Body

Table 5 describes the response parameters.

Table 5 Response parameters

Parameter

Type

Description

id

String

Instance ID

name

String

Instance name

description

String

Instance description

status

String

Instance status

creation_timestamp

String

Time when an instance is created

latest_update_timestamp

String

Time when an instance is modified

profile

Object

Configurations. For details, see Table 12.

flavor

String

Instance flavor

flavor_details

Object

Flavor details. For details, see Table 16.

pool

Object

Dedicated resource pool. For details, see Table 17.

spec

Object

Instance specifications. For details about notebook, see Table 14.

workspace

Object

Workspace. For details, see Table 7.

ai_project

Object

AI project. For details, see Table 12.

error_code

String

Error code. For details, see Error Codes.

queuing_info

Object

Queuing information. For details, see Table 26.

user

Object

User information. For details, see Table 27.

repository

Object

Git repository. For details, see Table 28. This parameter cannot be used. It is automatically returned when the API is called.

Table 6 profile parameters

Parameter

Type

Description

id

String

Configuration ID

name

String

Configuration name

description

String

Configuration description

de_type

String

Development environment type. Only Notebook is supported.

provision

Object

Deployment information. For details, see Table 4.

labels

Map<String,String>

Labels

flavor_type

String

Hardware, which can be Ascend

Table 7 provision parameters

Parameter

Type

Description

type

String

Deployment type. Only Docker is supported.

spec

Object

Deployment details. For details, see Table 8.

Table 8 spec parameters

Parameter

Type

Description

engine

String

Deployment engine. Only CCE is supported.

params

Object

Deployment parameters. Only Docker is supported. For details, see Table 9.

Table 9 Docker deployment parameters

Parameter

Type

Description

namespace

String

SWR organization name, which is globally unique

image_name

String

Image name

image_tag

String

Image tag

annotations

Map<String,String>

Label information, which can be extended. By default, this parameter is left blank.

Table 10 flavor_details parameters

Parameter

Type

Description

name

String

Flavor name

status

String

Flavor sales status. Options:

  • onSale

  • soldOut

queuing_num

Integer

Mandatory when promo_type is set to Free and status is set to soldOut

queue_left_time

Integer

Remaining time for being queued, in seconds

Mandatory when promo_type is set to Free and status is set to soldOut

storage_list

Array< storageType >

Supported storage types, which default to all

  • obs

is_permitted

Boolean

Whether the current user has the permission to use this flavor

type

String

Flavor type. Options:

  • ASCEND

params

Dict

Parameters that describe flavors

promo_type

String

Promotion type. Options:

  • Free

  • NoDiscount

instance_num

Integer

Number of instances of this flavor created by the current user

duration

Integer

Auto stop time after startup, in seconds

store_time

Integer

Maximum retention period of an inactive instance of this flavor in the database, in hours

The default value is -1, indicating that the instance can be permanently saved.

billing_flavor

String

Billing specifications. If this field is left blank, the specification name is used for billing.

billing_params

Integer

Billing ratio. This parameter is mandatory if billing_flavor is specified.

Table 11 pool parameters

Parameter

Type

Description

id

String

ID of a resource pool

name

String

Name of a resource pool

type

String

Type of a resource pool. USER_DEFINED indicates a dedicated resource pool.

owner

Object

This parameter is mandatory when type is set to USER_DEFINED. For details, see Table 13.

Table 12 AIProject parameters

Parameter

Type

Description

id

String

AI project ID.

Table 13 owner parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID

Table 14 notebook parameters

Parameter

Type

Description

log_path

String

Path for storing custom image logs

custom_script_path

String

Path for storing custom initialization scripts used when a notebook instance is started

storage

Object

Storage path. For details, see Table 4.

credential

Object

AK and SK for accessing OBS. For details, see Table 30.

repository

Object

Git repository information. For details, see Table 28. This parameter cannot be used. It is automatically returned when the API is called.

resource_reserved_timestamp

Integer

Time when the resource is reserved

auto_stop

Object

Auto stop parameter. For details, see Table 6.

failed_reasons

Object

Cause for a creation or startup failure. For details, see Table 22.

annotations

Map<String,String>

Annotations

The generated URL cannot be directly accessed.

extend_params

Map<String,String>

Extended parameters

Table 15 storage parameters

Parameter

Type

Description

type

String

Storage type. Only obs is supported.

location

Object

Storage location. If type is set to obs, this parameter is mandatory. See Table 16. By default, this parameter is left blank.

Table 16 location parameters

Parameter

Mandatory

Type

Description

path

No

String

Storage path

  • If type is set to obs, this parameter is mandatory. The value must be a valid OBS bucket path and end with a slash (/). The value must be a specific directory in an OBS bucket rather than the root directory of an OBS bucket.

Table 17 auto_stop parameters

Parameter

Type

Description

enable

Boolean

Whether to enable the auto stop function

duration

Integer

Running duration, in seconds

prompt

Boolean

Whether to display a prompt again. This parameter is provided for the console to use.

stop_timestamp

Integer

Time when the instance stops. The value is a 13-digit timestamp.

remain_time

Integer

Remaining time before actual stop, in seconds

Table 18 failed_reasons parameters

Parameter

Type

Description

code

String

Error code

message

String

Error message

detail

Map<String,String>

Error details

Table 19 workspace parameters

Parameter

Type

Description

id

String

Workspace ID If no workspace is created, the default value is 0. If a workspace is created and used, use the actual value.

Table 20 queuing_info parameters

Parameter

Type

Description

id

String

Instance ID

name

String

Instance name

de_type

String

Development environment type. By default, all types are returned.

Only Notebook is supported.

flavor

String

Instance flavor. By default, all types are returned.

flavor_details

Object

Flavor details, which display the flavor information and whether the flavor is sold out. For details, see Table 16.

status

String

Instance status. By default, all statuses are returned. Options:

  • CREATE_QUEUING

  • START_QUEUING

begin_timestamp

Integer

Time when an instance starts queuing, which is a 13-digit timestamp

remain_time

Integer

Remaining time for being queued, in seconds

end_timestamp

Integer

Time when an instance completes queuing, which is a 13-digit timestamp

rank

Integer

Ranking of an instance in a queue

Table 21 user parameters

Parameter

Type

Description

id

String

User ID

name

String

Username

Table 22 repository parameters

Parameter

Type

Description

id

String

Repository ID

branch

String

Repository branch

user_name

String

Repository username

user_email

String

Repository user mailbox

type

String

Repository type, which can be CodeClub or GitHub

connection_info

Object

Repository connection. For details, see Table 29.

Table 23 connection_info parameters

Parameter

Type

Description

protocol

String

Repository link protocol, which can be ssh or https

url

String

Repository link address

credential

Object

Certificate information. For details, see Table 30.

Table 24 credential parameters

Parameter

Type

Description

ssh_private_key

String

SSH private certificate

access_token

String

OAuth token of GitHub

Sample Request

The following shows how to modify the details about instance 6fa459ea-ee8a-3ca4-894e-db77e160355e.

{"description":"This is for test."}

Sample Response

  • Successful response

    {
      "ai_project": {
        "id": "default-ai-project"
      },
      "creation_timestamp": "1614669154682",
      "description": "This is for test.",
      "flavor": "modelarts.kat1.xlarge",
      "flavor_details": {
        "name": "modelarts.kat1.xlarge",
        "params": {
          "CPU": 24,
          "NPU": 1,
          "graphics_memory": "32GiB",
          "memory": "96GiB",
          "type": "Ascend 910"
        },
        "status": "onSale",
        "storage_list": [
          "obs",
          "efs"
        ],
        "type": "Ascend"
      },
      "id": "DE-a970f5d4-7b26-11eb-91ca-0255ac10003b",
      "latest_update_timestamp": "1614671231851",
      "name": "notebook-d115",
      "profile": {
        "de_type": "Notebook",
        "description": "Ascend 910, python 3.7/3.6 for notebook",
        "flavor_type": "Ascend",
        "id": "efa847c0-7359-11eb-b34f-0255ac100057",
        "name": "Ascend-Powered-Engine 1.0 (python3)",
        "provision": {
          "spec": {
            "engine": "CCE",
            "params": {
              "annotations": null,
              "image_name": "mul-kernel-d910-arm-cp37",
              "image_tag": "3.1.0-c76-2-test",
              "namespace": "atelier"
            }
          },
          "type": "Docker"
        }
      },
      "spec": {
        "annotations": {
          "target_domain": "https://notebook-modelarts.cn-xxxxx-222.pcl.ac.cn",
          "url": "https://10.176.46.12:32000/modelarts/internal/hub/notebook/user/DE-a970f5d4-7b26-11eb-91ca-0255ac10003b"
        },
        "auto_stop": {
          "duration": 3600,
          "enable": true,
          "prompt": true,
          "remain_time": 1536,
          "stop_timestamp": 1614672767697
        },
        "extend_params": null,
        "extend_storage": null,
        "failed_reasons": null,
        "repository": null,
        "storage": {
          "location": {
            "path": "/aaaaaaaaa/output/"
          },
          "type": "obs"
        }
      },
      "status": "RUNNING",
      "user": {
        "id": "f3779708b547462dbca12a70555d0690",
        "name": "modelarts_manage_admin"
      },
      "workspace": {
        "id": "0"
      }
    }
    
  • Failed response

    {
        "error_message": "The instance does not exist.",
        "error_code": "ModelArts.6309"
    }
    

Status Code

For details about the status code, see Status Code.