Liệt kê VM

GET/v2.1/servers

Để liệt kê tất cả máy ảo (VM) trong project, bạn gửi request GET đến endpoint /v2.1/servers của service compute. Request này cần token xác thực, và bạn cần đưa token vào header của request.

Request

Tham số

namestringbắt buộc

Lọc theo tên server; hỗ trợ regex (ví dụ ?name=bob khớp cả bob và bobb; dùng regex đặc thù của DB nếu chỉ muốn khớp bob). Alias display_name đã deprecated.

access_ip_v4stringbắt buộc

Lọc theo địa chỉ IPv4 dùng để truy cập server.

access_ip_v6stringbắt buộc

Lọc theo địa chỉ IPv6 dùng để truy cập server.

all_tenantsbooleanbắt buộc

Liệt kê instance từ tất cả project; mặc định chỉ admin. Nếu không truyền giá trị, mặc định là true. Giá trị true: 1,t,true,on,y,yes. Giá trị false: 0,f,false,off,n,no (không phân biệt hoa thường).

auto_disk_configstringbắt buộc

Lọc theo disk_config. Giá trị hợp lệ: AUTO, MANUAL. Chỉ admin.

availability_zonestringbắt buộc

Lọc theo availability zone. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

changes-beforestringbắt buộc

Lọc các server thay đổi tại hoặc trước mốc thời gian ISO 8601 này (CCYY-MM-DDThh:mm±hh). Nếu đặt cả hai, phải lớn hơn changes-since. Mới trong 2.66.

changes-sincestringbắt buộc

Lọc các server thay đổi tại hoặc sau mốc thời gian ISO 8601 này (CCYY-MM-DDThh:mm±hh). Nếu đặt cả hai, phải nhỏ hơn changes-before.

config_drivestringbắt buộc

Lọc theo thiết lập config-drive. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

created_atstringbắt buộc

Lọc theo thời điểm tạo (ISO 8601 CCYY-MM-DDThh:mm±hh). Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

deletedbooleanbắt buộc

Chỉ hiển thị các item đã xoá. Dùng cẩn thận. Giá trị true: 1,t,true,on,y,yes (không phân biệt hoa thường). Các giá trị khác được coi là false. Chỉ admin.

flavorstringbắt buộc

Lọc theo UUID flavor.

imagestringbắt buộc

Lọc theo UUID image. Alias image_ref đã deprecated.

ipstringbắt buộc

Lọc theo địa chỉ IPv4.

ip6stringbắt buộc

Lọc theo địa chỉ IPv6. Chỉ admin đến 2.4; mọi user dùng được từ 2.5.

kernel_idstringbắt buộc

Lọc theo UUID kernel image (AMI). Chỉ admin.

key_namestringbắt buộc

Lọc theo tên keypair. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

launch_indexintegerbắt buộc

Lọc theo thứ tự server được khởi tạo. Chỉ admin.

launched_atstringbắt buộc

Lọc theo thời điểm khởi tạo (ISO 8601 CCYY-MM-DDThh:mm±hh). Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

limitintegerbắt buộc

Số item mỗi trang. Dùng kèm marker để phân trang.

lockedbooleanbắt buộc

Liệt kê instance đang khoá hoặc không khoá. Giá trị true: 1,t,true,on,y,yes. Giá trị false: 0,f,false,off,n,no (không phân biệt hoa thường). Giá trị không hợp lệ sẽ gây lỗi. Mới trong 2.73.

locked_bystringbắt buộc

Lọc theo người khoá server (admin hoặc owner). Chỉ admin.

markerstringbắt buộc

ID của item cuối cùng đã thấy, dùng để phân trang.

descriptionstringbắt buộc

Lọc theo description. Chỉ admin. Alias display_description đã deprecated.

hoststringbắt buộc

Lọc theo tên compute host. Chỉ admin.

hostnamestringbắt buộc

Lọc theo host name của server. Chỉ admin.

nodestringbắt buộc

Lọc theo node. Chỉ admin.

power_stateintegerbắt buộc

Lọc theo trạng thái nguồn. 0 NOSTATE, 1 RUNNING, 3 PAUSED, 4 SHUTDOWN, 6 CRASHED, 7 SUSPENDED, 8 SHUTDOWN_ACTIVE. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

progressintegerbắt buộc

Lọc theo tiến độ (0–100). Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

project_idstringbắt buộc

Lọc theo project ID. Cần dùng kèm all_tenants. Alias tenant_id đã deprecated.

ramdisk_idstringbắt buộc

Lọc theo UUID ramdisk image (AMI). Chỉ admin.

reservation_idstringbắt buộc

Lọc theo reservation id từ multi-create.

root_device_namestringbắt buộc

Lọc theo tên root device. Chỉ admin.

soft_deletedbooleanbắt buộc

Lọc theo trạng thái SOFT_DELETED; chỉ hợp lệ khi deleted=true.

sort_dirstringbắt buộc

Chiều sắp xếp: asc hoặc desc (mặc định desc). Có thể lặp nhiều lần cùng sort_key.

sort_keystringbắt buộc

Sắp xếp theo attribute (mặc định created_at). Các giá trị được phép: access_ip_v4, access_ip_v6, auto_disk_config, availability_zone, config_drive, created_at, display_description, display_name, host, hostname, image_ref, instance_type_id, kernel_id, key_name, launch_index, launched_at, locked (mới trong 2.73), locked_by, node, power_state, progress, project_id, ramdisk_id, root_device_name, task_state, terminated_at, updated_at, user_id, uuid, vm_state. host và node yêu cầu quyền admin; user không phải admin nhận 403.

statusstringbắt buộc

Lọc theo trạng thái server (ví dụ ACTIVE). Đến 2.37, status không hợp lệ trả về danh sách rỗng; từ 2.38 trả 400.

task_statestringbắt buộc

Lọc theo task state. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

terminated_atstringbắt buộc

Lọc theo thời điểm kết thúc (ISO 8601 CCYY-MM-DDThh:mm±hh). Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

user_idstringbắt buộc

Lọc theo user ID. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

uuidstringbắt buộc

Lọc theo UUID server. Chỉ admin.

vm_statestringbắt buộc

Lọc theo trạng thái VM. Một trong: ACTIVE, BUILDING, DELETED, ERROR, PAUSED, RESCUED, RESIZED, SHELVED, SHELVED_OFFLOADED, SOFT_DELETED, STOPPED, SUSPENDED. Chỉ admin đến microversion 2.83; bị bỏ qua với user không phải admin trước 2.83.

not-tagsstringbắt buộc

Trả về các server không khớp tất cả tag trong danh sách (NOT (t1 AND t2)); phân tách bằng dấu phẩy. Mới trong 2.26.

not-tags-anystringbắt buộc

Trả về các server không khớp bất kỳ tag nào trong danh sách (NOT (t1 OR t2)); phân tách bằng dấu phẩy. Mới trong 2.26.

tagsstringbắt buộc

Trả về các server khớp tất cả tag trong danh sách (t1 AND t2); phân tách bằng dấu phẩy. Mới trong 2.26.

tags-anystringbắt buộc

Trả về các server khớp bất kỳ tag nào trong danh sách (t1 OR t2); phân tách bằng dấu phẩy. Mới trong 2.26.

Request mẫu

Dùng curl

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://api.vietnix.cloud:8774/v2.1/servers

HTTP request

GET https://api.vietnix.cloud:8774/v2.1/servers

Response

Response 200

{
    "servers": [
        {
            "id": "393210ad-152b-4ac3-a0f0-798ee4e93620",
            "name": "Ubuntu22",
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.vietnix.cloud:8774/v2.1/servers/393210ad-152b-4ac3-a0f0-798ee4e93620"
                },
                {
                    "rel": "bookmark",
                    "href": "https://api.vietnix.cloud:8774/servers/393210ad-152b-4ac3-a0f0-798ee4e93620"
                }
            ]
        }
    ]
}

Mã trạng thái

Thành công

Mã	Mô tả
200 - OK	Request thành công.

Lỗi

Mã	Mô tả
400 - Bad Request	Nội dung trong request không hợp lệ.
401 - Unauthorized	User phải xác thực trước khi gửi request.
403 - Forbidden	Policy không cho phép user hiện tại thực hiện thao tác này.