Querying Notebook Instances
Function
This API is used to obtain information about notebook instances that meet specific conditions.
This API applies to the following scenarios: When you manage multiple notebook instances or view notebook instances in a specified status, you can use this API to obtain related information. Before using this API, ensure that you have created a notebook instance and have the query permission. After the API is successfully called, the system returns the list of notebook instances that meet the search criteria. Details such as the instance ID, status, and creation time can be obtained. If you do not have the access permission or the query conditions are unclear, the API will return an error message or an empty list.
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
GET /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 |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
feature |
No |
String |
Definition: Instance type Constraints: N/A Range: Enums: Default Value: NOTEBOOK |
limit |
No |
Integer |
Definition: Number of instances displayed on each page Constraints: N/A Range: [10,20,50] Default Value: 10 |
name |
No |
String |
Definition: Instance name. Fuzzy match is supported. Constraints: N/A Range: The value can contain a maximum of 128 characters. Letters, digits, hyphens (-), and underscores (_) are allowed. Default Value: N/A |
pool_id |
No |
String |
Definition: Dedicated resource pool ID Constraints: N/A Range: This value contains 4 to 64 characters. Lowercase letters, digits, and hyphens (-) are allowed. It must start with a lowercase letter and end with a lowercase letter or digit. Default Value: N/A |
offset |
No |
Integer |
Definition: Start offset of the records on each page Constraints: N/A Range: N/A Default Value: 0 |
owner |
No |
String |
Definition: User ID of the instance. This parameter is valid only when the account is a big account or has the admin permission. Generally, the value is the ID of the current login user. Constraints: N/A Range: This value contains 32 characters. Lowercase letters and digits are allowed. Default Value: N/A |
sort_dir |
No |
String |
Definition: Instance sorting mode Constraints: N/A Range: Enums: Default Value: DESC |
sort_key |
No |
String |
Definition: Sorting field. Separate multiple fields with commas (,). Constraints: N/A Range: The value can contain a maximum of 128 characters. Letters, digits, hyphens (-), underscores (_), and commas (,) are allowed. Default Value: N/A |
status |
No |
String |
Definition: Instance status Constraints: N/A Range: Enums: Default Value: N/A |
workspaceId |
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: N/A Default Value: 0 |
Request Parameters
None
Response Parameters
Status code: 200
Parameter |
Type |
Description |
---|---|---|
current |
Integer |
Definition: Current page number. Range: Positive integers |
data |
Array of NotebookResp objects |
Definition: Notebook instance data. |
pages |
Integer |
Definition: Total number of pages. Range: Positive integers |
size |
Integer |
Definition: Number of records on each page. Range: Positive integers |
total |
Long |
Definition: Total number of records. Range: Non-negative integers |
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 |
Example Requests
GET https://{endpoint}/v1/{project_id}/notebooks
Example Responses
Status code: 200
OK
{ "current" : 0, "data" : [ { "description" : "api-test", "feature" : "DEFAULT", "flavor" : "modelarts.vm.cpu.free", "id" : "f9937afa-ca78-45b6-bc12-7ecf42553c48", "image" : { "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", "type" : "BUILD_IN" }, "lease" : { "create_at" : 1638841805439, "duration" : 3600000, "enable" : true, "update_at" : 1638841805439 }, "name" : "notebook_5ee4bf0e", "status" : "CREATING", "token" : "58ba50c6-e8ff-245c-4840-49e51aa70737", "volume" : { "category" : "EVS", "ownership" : "MANAGED", "mount_path" : "/home/ma-user/work/", "capacity" : 50 }, "workspace_id" : "0" }, { "description" : "api-test", "feature" : "NOTEBOOK", "flavor" : "modelarts.vm.cpu.2u", "id" : "f9937afa-4451-42db-a76b-72d624749f66", "image" : { "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", "type" : "BUILD_IN" }, "lease" : { "create_at" : 1638841744515, "duration" : 3600000, "enable" : true, "update_at" : 1638841744515 }, "name" : "notebooks_test", "status" : "CREATING", "token" : "3eff13f2-3d70-5456-6dc7-e3f99f562022", "volume" : { "category" : "EVS", "ownership" : "MANAGED", "mount_path" : "/home/ma-user/work/", "capacity" : 50 }, "workspace_id" : "0" } ], "pages" : 1, "size" : 10, "total" : 2 }
Status Codes
Status Code |
Description |
---|---|
200 |
OK |
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