Help Center/ ModelArts/ API Reference/ Historical APIs/ DevEnviron (Old Version)/ Obtaining Development Environment Instances
Updated on 2024-05-30 GMT+08:00

Obtaining Development Environment Instances

Function

This API is used to obtain the development environment instances that meet the search criteria.

URI

GET /v1/{project_id}/demanager/instances?de_type={de_type}&provision_type={provision_type}&status={status}&sortby={sortby}&order={order}&offset={offset}&limit={limit}

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.

Table 2 query parameters

Parameter

Mandatory

Type

Description

de_type

Yes

String

Development environment type. Only Notebook is supported. The first letter must be capitalized.

provision_type

No

String

Deployment type. Only Docker is supported.

status

No

String

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

  • CREATE_QUEUING: The instance is queuing for creating free resources.
  • CREATING: The instance is being created.
  • CREATE_FAILED: The instance fails to be created.
  • START_QUEUING: The instance is queuing for starting free resources.
  • READY_TO_START: The free resources are waiting to be started.
  • STARTING: The instance is being started.
  • RESTARTING: The instance is being restarted.
  • START_FAILED: The instance fails to be started.
  • RUNNING: The instance is running.
  • STOPPING: The instance is being stopped.
  • STOPPED: The instance has been stopped.
  • UNAVAILABLE: The instance is unavailable.
  • DELETED: The instance has been deleted.
  • RESIZING: The instance specifications are being changed.
  • RESIZE_FAILED: The instance specifications fail to be changed.

sortby

No

String

Classification standard. The value can be name or creation_timestamp. The default value is name.

order

No

String

Sorting mode. The value can be asc or desc. The default value is asc.

offset

No

Integer

Start index. The default value is 0.

limit

No

Integer

Number of returned result records. The value range is (0, ∞). The default value is 0, which indicates that all results are returned.

workspace_id

No

String

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

show_self

No

String

Only the user is displayed. The default value is true.

ai_project

No

String

AI project ID

pool_id

No

String

ID of a dedicated resource pool. This parameter can be used to obtain all instances in a dedicated resource pool.

Request Body

None

Response Body

Table 3 describes the response parameters.
Table 3 Parameters

Parameter

Type

Description

total_count

Integer

Total number of development environments.

instances

Array

Configuration list. For details, see Table 4.

Table 4 instances 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

profile

Object

Configuration information. For details, see Table 5.

flavor

String

Instance flavor

spec

Object

Instance definition. For details about parameters of a notebook instance, see Table 13.

workspace

Object

Workspace. For details, see Table 18.

latest_update_timestamp

String

Time when an instance is modified

flavor_details

Object

Flavor details. For details, see Table 9.

pool

Object

Dedicated resource pool. For details, see Table 10.

ai_project

Object

AI project. For details, see Table 11.

error_code

String

Error code. For details, see Error Codes.

queuing_info

Object

Queuing information. For details, see Table 19.

user

Object

User information. For details, see Table 20.

repository

Object

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

Table 5 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 6.

labels

Map<String,String>

Label information, which can be extended

flavor_type

String

Hardware, which can be CPU, GPU, or Ascend.

Table 6 provision parameters

Parameter

Type

Description

type

String

Deployment type. Only Docker is supported.

spec

Object

Deployment details. For details, see Table 7.

annotations

Map<String,String>

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

Table 7 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 8.

Table 8 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 9 flavor_details parameters

Parameter

Type

Description

name

String

Flavor name

status

String

Flavor sales status. Options:

  • onSale
  • soldOut

queuing_num

Integer

This parameter is mandatory when promo_type is set to Free and status is set to soldOut.

queue_left_time

Integer

Left queuing time, in seconds

This parameter is mandatory when promo_type is set to Free and status is set to soldOut.

storage_list

Array<Storage type>

Supported storage type. The options are obs, evs, and efs.

is_permitted

Boolean

Whether the current user has the permission to use this flavor

type

String

Flavor type. Options:

  • GPU
  • CPU
  • ASCEND

params

Dict

Parameters that describing flavor

promo_type

String

Promotion type. Options:

  • Free
  • NoDiscount

instance_num

Integer

Number of instances of this flavor the current created

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 specifications name is used for billing.

billing_params

Integer

Billing ratio This parameter is mandatory when billing_flavor is specified.

Table 10 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 12.

Table 11 AIProject parameters

Parameter

Type

Description

id

String

AI project ID

Table 12 owner parameters

Parameter

Type

Description

project_id

String

Project ID

Table 13 notebook parameters

Parameter

Type

Description

extend_storage

Array<Storage>

Extended storage list. For details, see Table 14. Extended storage supports only obsfs and is available only for certain dedicated resource pools.

storage

Object

Storage path. For details, see Table 14.

auto_stop

Object

Auto stop parameter. For details, see Table 17.

annotations

Map<String,String>

Annotations

The generated URL cannot be directly accessed.

failed_reasons

Object

Cause for a creation or startup failure. See Table 16.

extend_params

Map<String,String>

Extended parameter

Table 14 storage parameters

Parameter

Mandatory

Type

Description

type

Yes

String

Storage type. Only obs, obsfs, and evs are supported. Additionally, obsfs can only be used in certain dedicated resource pools. To mount an OBS parallel file system, submit a service ticket.

location

No

Object

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

Table 15 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.
  • If type is set to obsfs, the parameter value must be a valid bucket name of the OBS parallel file system. (CCE does not support subdirectory mounting.)
  • If type is set to evs, this parameter does not need to be set.

volume_size

No

Integer

EVS disk size. The minimum size is 5 GB and the maximum size is 4,096 GB. The default value is 5 GB. If type is set to obs, this parameter does not need to be set.

mount_path

No

String

Mount path in a notebook instance. This parameter is valid only when type is set to obsfs.

The default value is /home/ma-user/work.

To mount the file system to a specified path, set the value to the subdirectory of /home/ma-user/work. Otherwise, the mounting may fail or read/write exceptions may occur due to permission issues.

access_modes

No

String

Access permission for the mounted file or folder. The permission can be read/write or read-only. This parameter is valid only when type is set to obsfs. Options:

  • ReadOnlyMany: read-only mode
  • ReadWriteMany: read/write mode (default value)
Table 16 failed_reasons parameters

Parameter

Type

Description

code

String

Error code

message

String

Error message

detail

Map<String,String>

Error details

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 workspace parameters

Parameter

Type

Description

id

String

Workspace ID

Table 19 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. Options:

  • modelarts.vm.cpu.free
  • modelarts.vm.gpu.free

flavor_details

Object

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

status

String

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

  • CREATE_QUEUING
  • START_QUEUING

begin_timestamp

Integer

Time when an instance starts queuing. The value is a 13-digit timestamp.

remain_time

Integer

Left queuing time, in seconds

end_timestamp

Integer

Time when an instance completes queuing. The value is a 13-digit timestamp.

rank

Integer

Ranking of an instance in a queue

Table 20 user parameters

Parameter

Type

Description

id

String

User ID

name

String

Username

Table 21 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. The options are CodeClub and GitHub.

connection_info

Object

Repository link information. For details, see Table 22.

Table 22 connection_info parameters

Parameter

Type

Description

protocol

String

Repository link protocol. The options are ssh and https.

url

String

Repository link address

credential

Object

Certificate information. For details, see Table 23.

Table 23 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 obtain the list of Notebook development environments.
GET https://endpoint/v1/{project_id}/demanager/instances?de_type=Notebook

Sample Response

  • Successful response
    {
        "instances": [
            {
                "ai_project": {
                    "id": "default-ai-project"
                },
                "creation_timestamp": "1594887749962",
                "description": "",
                "flavor": "modelarts.bm.gpu.v100NV32",
                "flavor_details": {
                    "name": "modelarts.bm.gpu.v100NV32",
                    "params": {
                        "CPU": 8,
                        "GPU": 1,
                        "gpu_type": "v100NV32",
                        "memory": "64GiB"
                    },
                    "status": "onSale",
                    "type": "GPU"
                },
                "id": "DE-7d558ef8-c73d-11ea-964c-0255ac100033",
                "latest_update_timestamp": "1594887749962",
                "name": "notebook-c6fd",
                "profile": {
                    "de_type": "Notebook",
                    "description": "multi engine, gpu, python 3.6 for notebook",
                    "flavor_type": "GPU",
                    "id": "Multi-Engine 1.0 (python3)-gpu",
                    "name": "Multi-Engine 1.0 (python3)-gpu",
                    "provision": {
                        "annotations": {
                            "category": "Multi-Engine 1.0 (python3)",
                            "type": "system"
                        },
                        "spec": {
                            "engine": "CCE",
                            "params": {
                                "annotations": null,
                                "image_name": "mul-kernel-gpu-cuda-cp36",
                                "image_tag": "2.0.5-B003",
                                "namespace": "atelier"
                            }
                        },
                        "type": "Docker"
                    }
                },
                "spec": {
                    "annotations": {
                        "target_domain": "https://modelarts-notebook-2.xxxxxx.com",
                        "url": "https://modelarts-lvs-common-lb.xxxxxx.com:32000/modelarts/hubv100/notebook/user/DE-7d558ef8-c73d-11ea-964c-0255ac100033"
                    },
                    "auto_stop": {
                        "duration": 3600,
                        "enable": true,
                        "prompt": true,
                        "remain_time": 3450,
                        "stop_timestamp": 1594891408723
                    },
                    "extend_params": null,
                    "failed_reasons": null,
                    "extend_storage": null,
                    "storage": {
                        "location": {
                            "path": "/home/ma-user/work",
                            "volume_size": 5
                        },
                        "type": "evs"
                    }
                },
                "status": "RUNNING",
                "user": {
                    "id": "15dda26361214ca2a5953917d2f48ffb",
                    "name": "ops_dev_env"
                },
                "workspace": {
                    "id": "0"
                }
            },
            {
                "ai_project": {
                    "id": "default-ai-project"
                },
                "creation_timestamp": "1594883877728",
                "description": "",
                "flavor": "modelarts.vm.cpu.2u",
                "flavor_details": {
                    "name": "modelarts.vm.cpu.2u",
                    "params": {
                        "CPU": 2,
                        "GPU": 0,
                        "memory": "8GiB"
                    },
                    "status": "onSale",
                    "type": "CPU"
                },
                "id": "DE-7936a360-c734-11ea-a72b-0255ac100033",
                "latest_update_timestamp": "1594883877728",
                "name": "notebook-b1b8",
                "profile": {
                    "de_type": "Notebook",
                    "description": "multi engine, cpu, python 3.6 for notebook",
                    "flavor_type": "CPU",
                    "id": "Multi-Engine 1.0 (python3)-cpu",
                    "name": "Multi-Engine 1.0 (python3)-cpu",
                    "provision": {
                        "annotations": {
                            "category": "Multi-Engine 1.0 (Python3, Recommended)",
                            "type": "system"
                        },
                        "spec": {
                            "engine": "CCE",
                            "params": {
                                "annotations": null,
                                "image_name": "mul-kernel-cpu-cp36",
                                "image_tag": "2.0.5-B003",
                                "namespace": "atelier"
                            }
                        },
                        "type": "Docker"
                    }
                },
                "spec": {
                    "annotations": {
                        "target_domain": "https://modelarts-notebook.xxxxxx.com",
                        "url": ""
                    },
                    "auto_stop": {
                        "duration": 3600,
                        "enable": true,
                        "prompt": true
                    },
                    "extend_params": null,
                    "failed_reasons": null,
                    "storage": {
                        "location": {
                            "path": "/home/ma-user/work",
                            "volume_size": 5
                        },
                        "type": "evs"
                    }
                },
                "status": "STOPPED",
                "user": {
                    "id": "15dda26361214ca2a5953917d2f48ffb",
                    "name": "ops_dev_env"
                },
                "workspace": {
                    "id": "0"
                }
            }],
        "total_count": 2
    }

Status Code

For details about the status code, see Status Code.