Creating a Notebook Instance
Function
This API is used to create a notebook instance based on specified parameters.
This API applies to the following scenario: When you need to create a notebook instance for a specific task or project, you can use this API to specify the instance specifications, AI engine images, and storage configurations. Before using this API, ensure that you have logged in to the system, have the permission to create a notebook instance, and provide valid creation parameters. After this API is called, the system asynchronously creates a notebook instance. You can obtain the instance status by calling the query API. After the notebook instance is created, you can access the notebook instance through the web page or SSH client. If you do not have the permission to create an instance or the parameters are invalid, the API will return an error message. Other exceptions include insufficient system resources and creation failure. The API will return the corresponding error message.
Constraints
No constraints
Debugging
You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.
URI
POST /v1/{project_id}/notebooks
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Definition: Project ID. For details, see Obtaining a Project ID and Name. Constraints: N/A Range: N/A Default Value: N/A |
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
description |
No |
String |
Definition: Instance description. Constraints: N/A Range: The value can contain up to 512 characters and cannot contain these special characters (&<>"'/). Default Value: N/A |
duration |
No |
Long |
Definition: Running duration calculated from the current time, in milliseconds. The instance automatically stops when the duration expires. It is recommended that this parameter be set in leaseReq. If this parameter is set here, the value set in leaseReq is ignored and the instance is stopped as scheduled. Constraints: N/A Range: 3600000 to 259200000 Default Value: 3600000 |
endpoints |
No |
Array of EndpointsReq objects |
Definition: Only a local IDE (such as PyCharm or VS Code) or SSH client can be used to access a notebook instance. Constraints: Configurations are only required for remotely accessing a notebook instance via SSH on a local IDE (such as PyCharm or VS Code) or SSH client. |
feature |
No |
String |
Definition: Instance type. Constraints: N/A Range: Default Value: NOTEBOOK |
flavor |
Yes |
String |
Definition: Instance flavor. The following flavors are for reference only. Obtain the flavors displayed on the console in the target region.
Constraints: N/A Range: N/A Default Value: N/A |
image_id |
Yes |
String |
Definition: ID of the image used for creating notebook instances. The ID is in the format of a Universally Unique Identifier (UUID). For details, see Querying Supported Images. Constraints: N/A Range: Valid image IDs obtained by calling the API for Querying Supported Images. Default Value: N/A |
name |
Yes |
String |
Definition: Instance name. Constraints: N/A Range: The value can contain a maximum of 128 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. The name can be duplicate. Default Value: N/A |
pool_id |
No |
String |
Definition: ID of a dedicated resource pool. This parameter is mandatory if a dedicated resource pool is used to create an instance. The dedicated resource pool ID can be obtained by calling the API for [Obtaining Resource Pools] (https://support.huaweicloud.com/intl/en-us/api-modelarts/ListPools.html). Constraints: N/A Range: Valid resource pool IDs obtained by calling the API for querying the resource pool list (https://support.huaweicloud.com/intl/en-us/api-modelarts/ListPools.html) Default Value: N/A |
volume |
Yes |
VolumeReq object |
Definition: Storage configuration. Constraints: N/A |
workspace_id |
No |
String |
Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value. Constraints: N/A Range: This value is a string of 0 or 32 characters. Only digits or lowercase letters are allowed. Default Value: 0 |
hooks |
No |
CustomHooks object |
Definition: Hook configuration of a custom boot script. Constraints: N/A |
lease |
No |
LeaseReq object |
Definition: Instance lease configuration. Constraints: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
allowed_access_ips |
No |
Array of strings |
Definition: Public IP addresses that can remotely access the notebook instance. A maximum of five public IP addresses are supported. Constraints: N/A |
service |
No |
String |
Definition: Supported services. Constraints: N/A Range: Default Value: N/A |
key_pair_names |
No |
Array of strings |
Definition: Name of the SSH key pair, which can be created and viewed on the Key Pair page of the Elastic Cloud Server (ECS) console. Constraints: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
capacity |
No |
Integer |
Definition: Storage capacity, in GB. Constraints: This attribute takes effect when category is set to EVS. Range: 5 to 4096 Default Value: 5 |
category |
Yes |
String |
Definition: Supported storage type. For details about the differences between the storage types, see Selecting Storage in DevEnviron. Constraints: N/A Range: Default Value: EVS |
ownership |
Yes |
String |
Definition: Resource owner. Constraints: N/A Range:
Default Value: N/A |
uri |
No |
String |
Definition: URI of the EFS dedicated storage disk or path of the OBS parallel file system. Perform the following steps:
Constraints: This parameter is mandatory only when category is set to EFS, OBS, or OBSFS and ownership is set to DEDICATED. Range: N/A Default Value: N/A |
id |
No |
String |
Disk ID of the EFS. This parameter is mandatory only when the instance category is EFS and the ownership is DEDICATED. This parameter is mandatory. To obtain the parameter value, log in to the SFS console. In the file system list, click the file system name to go to the file system details page. ID is the value of this parameter. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
container_hooks |
No |
ContainerHooks object |
Definition: Container hook configuration. Constraints: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
post_start |
No |
Config object |
Definition: Script configuration after the service is started. Constraints: N/A |
pre_start |
No |
Config object |
Definition: Script configuration before the service is started. Constraints: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
script |
No |
String |
Definition: Custom script (Base64 encoding) or absolute path of a script. Constraints: N/A Range: N/A Default Value: N/A |
type |
No |
String |
Definition: Script type. Constraints: N/A Range: Default Value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
duration |
No |
Long |
Definition: The instance stops as scheduled. Its runtime is measured in milliseconds starting now. Constraints: N/A Range: 3600000 to 259200000 Default Value: 3600000 |
type |
No |
String |
Definition: Auto stop type. Constraints: N/A Range: Default Value: TIMING |
Response Parameters
Status code: 200
Parameter |
Type |
Description |
---|---|---|
action_progress |
Array of JobProgress objects |
Definition: Initialization progress of the instance. |
description |
String |
Definition: Instance description. Range: N/A |
endpoints |
Array of EndpointsRes objects |
Definition: Local IDE (such as PyCharm and VS Code) or SSH client for remotely accessing a notebook instance through SSH. |
fail_reason |
String |
Definition: Instance failure cause. Range: N/A |
flavor |
String |
Definition: Instance flavor. Range: N/A |
id |
String |
Definition: Instance ID. Range: N/A |
image |
Image object |
Definition: Instance image information. |
lease |
Lease object |
Definition: Countdown to auto stop of an instance. |
name |
String |
Definition: Instance name. Range: N/A |
pool |
Pool object |
Definition: Basic information about the dedicated pool, which is returned by the instance created in the dedicated pool. |
status |
String |
Definition: Instance status. Range: |
token |
String |
Description: Token used for notebook authentication. Range: N/A |
url |
String |
Definition: URL for accessing the instance. Range: N/A |
volume |
VolumeRes object |
Definition: Instance storage information. |
workspace_id |
String |
Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value. Range: N/A |
feature |
String |
Definition: Instance type. Range: |
billing_items |
Array of strings |
Definition: Billing resource type. Range: |
user |
user object |
Description: Account information. |
Parameter |
Type |
Description |
---|---|---|
notebook_id |
String |
Definition: Instance ID. Range: N/A |
status |
String |
Definition: Job status in a specified step. Range: |
step |
Integer |
Definition: Job step. Range: |
step_description |
String |
Definition: Job description in a specified step. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
allowed_access_ips |
Array of strings |
Definition: Whitelisted public IP addresses that are allowed to access notebook instances through SSH. By default, all public IP addresses can access the notebook instances. If IP addresses are specified, only the clients with the specified IP addresses can access the notebook instances. |
dev_service |
String |
Definition: Method for accessing the notebook instance. Range: |
ssh_keys |
Array of strings |
Definition: List of SSH key pairs. You can set multiple key pairs to access an SSH instance at the same time. |
service |
String |
Definition: Method for accessing the notebook instance. Range: |
uri |
String |
Definition: Private IP address of the instance. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
arch |
String |
Definition: Processor architecture supported by the image. Range: |
create_at |
Long |
Definition: UTC time when the image is created, accurate to millisecond. Range: N/A |
description |
String |
Definition: Image description. Range: Up to 512 characters |
dev_services |
Array of strings |
Definition: Services supported by the image. Range: |
id |
String |
Definition: ID of the image used for creating notebook instances. The ID is in Universally Unique Identifier (UUID) format. For details, see Querying Supported Images. Range: N/A |
name |
String |
Definition: Image name. Range: The name can contain a maximum of 512 characters. Lowercase letters, digits, hyphens (-), underscores (_), and periods (.) are allowed. |
namespace |
String |
Definition: Organization to which the image belongs. You can create and view an organization on the Organization Management page of the SWR console. Range: N/A |
origin |
String |
Definition: Image source. Range: |
resource_categories |
Array of strings |
Definition: Flavors supported by the image. Range: |
service_type |
String |
Definition: Supported image types. Range: |
size |
Long |
Definition: Image size, in KB. Range: N/A |
status |
String |
Definition: Image status. Range: |
status_message |
String |
Definition: Build information during image saving. Range: N/A |
support_res_categories |
Array of strings |
Definition: Flavors supported by the image. Range: |
swr_path |
String |
Definition: SWR image path. Range: N/A |
tag |
String |
Definition: Image tag. Range: N/A |
type |
String |
Definition: Image type. Range: |
update_at |
Long |
Definition: Time (UTC) when the image was last updated, accurate to millisecond. Range: N/A |
visibility |
String |
Definition: Image visibility. Range: |
workspace_id |
String |
Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value. Range: N/A |
flavor_type |
String |
Definition: Resource type of the image. Range: |
Parameter |
Type |
Description |
---|---|---|
create_at |
Long |
Definition: UTC time when the instance is created, accurate to millisecond. Range: N/A |
duration |
Long |
Definition: Instance runtime, which is calculated based on the instance creation time. If the instance creation time plus the runtime is greater than the current time, the system automatically stops the instance. Range: N/A |
enable |
Boolean |
Definition: Specifies whether to enable auto stop. Range: Boolean |
type |
String |
Definition: Auto stop type. Range: |
update_at |
Long |
Definition: Time (UTC) when the instance is last updated (excluding liveness check), accurate to millisecond. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition: Dedicated resource pool ID. Range: N/A |
name |
String |
Definition: Dedicated resource pool name. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
capacity |
Integer |
Definition: Storage capacity. Range: The default value is 5 GB for EVS and 50 GB for EFS. The maximum value is 4,096 GB. |
category |
String |
Definition: Supported storage type. For details about the differences between the storage types, see Selecting Storage in DevEnviron. Range: |
mount_path |
String |
Definition: Directory of the notebook instance to which the storage is mounted. Currently, the directory is /home/ma-user/work/. Range: N/A |
ownership |
String |
Definition: Resource owner. Range: |
status |
String |
Definition: EVS disk capacity expansion status, which is RESIZING during capacity expansion and does not affect the instance. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
domain |
domain object |
Description: Domain information of the account. |
id |
String |
Definition: IAM user ID. For details, see Obtaining a Username and ID. Range: N/A |
name |
String |
Definition: IAM username. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition: Account ID. Range: N/A |
name |
String |
Definition: Account name. Range: N/A |
Status code: 201
Created
Example Requests
The following is an example of how to create a notebook instance whose flavor is modelarts.vm.cpu.2u, storage type is evs, ownership is MANAGED, and storage capacity is 50 GB.
{ "name" : "notebooks_test", "feature" : "NOTEBOOK", "workspace_id" : "0", "description" : "api-test", "flavor" : "modelarts.vm.cpu.2u", "image_id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090", "volume" : { "category" : "evs", "ownership" : "managed", "capacity" : 50 } }
Example Responses
Status code: 200
OK
{ "description" : "api-test", "feature" : "NOTEBOOK", "flavor" : "modelarts.vm.cpu.2u", "id" : "f9937afa-4451-42db-a76b-72d624749f66", "image" : { "description" : "description", "id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090", "name" : "notebook2.0-mul-kernel-cpu-cp36", "swr_path" : "swr.xxxxx.com/atelier/notebook2.0-mul-kernel-cpu-cp36:3.3.2-release_v1", "tag" : "3.3.2-release_v1", "type" : "BUILD_IN" }, "lease" : { "create_at" : 1638841744515, "duration" : 3600000, "enable" : true, "type" : "TIMING", "update_at" : 1638841744515 }, "name" : "notebooks_test", "status" : "CREATING", "token" : "3eff13f2-3d70-5456-6dc7-e3f99f562022", "workspace_id" : "0" }
Status Codes
Status Code |
Description |
---|---|
200 |
OK |
201 |
Created |
401 |
Unauthorized |
403 |
Forbidden |
404 |
Not found |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot