Tạo bản ghi image

POST/v2/images

Tạo một bản ghi image. Bạn phải cung cấp tên và chỉ định container_format và disk_format. Sau khi tạo bản ghi, upload dữ liệu image theo luồng "Upload dữ liệu image".

info

Nguồn: Create Image (OpenStack Image API v2)

Request

Tham số

container_formatenum

Định dạng container của image. Giá trị có thể khác nhau tùy cấu hình của từng cloud OpenStack. Ví dụ: ami, ari, aki, bare, ovf, ova hoặc docker. Giá trị có thể là null (kiểu JSON null).

disk_formatenum

Định dạng disk. Giá trị có thể khác nhau tùy cấu hình của từng cloud OpenStack. Xem response Image Schema của cloud để biết các giá trị hợp lệ. Ví dụ: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop hoặc iso. Giá trị có thể là null (kiểu JSON null).

idstring

UUID image do người dùng tự đặt, theo định dạng nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn, trong đó n là chữ số hex từ 0 đến f hoặc F. Ví dụ: b2173dd3-7ad6-4362-baa6-a68bce3565cb. Nếu bỏ trống, API tự sinh UUID cho image. Nếu chỉ định giá trị đã tồn tại, request thất bại với mã 409.

min_diskinteger

Dung lượng disk tối thiểu (GB) cần để boot image.

min_raminteger

Dung lượng RAM tối thiểu (MB) cần để boot image.

namestring

Tên image.

protectedboolean

Bảo vệ image khỏi bị xoá. Giá trị hợp lệ là true hoặc false. Mặc định là false.

tagsarray

Danh sách tag cho image. Mỗi tag là chuỗi tối đa 255 ký tự. Số tag tối đa trên một image do operator quy định.

visibilitystring

Mức hiển thị của image. Giá trị hợp lệ: public, private, shared hoặc community. Ở hầu hết site, chỉ admin mới có thể đặt image thành public. Một số site giới hạn việc đặt image thành community. Một số site giới hạn thao tác member trên image shared. Từ Image API v2.5, giá trị mặc định là shared.

Ví dụ

curl -ks -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: gAAAAA<...>' \
  -d '{
    "container_format": "bare",
    "disk_format": "qcow2",
    "name": "alpine"
    }' \
  https://api.vietnix.cloud:9292/v2/images

Response

Tham số

Locationstringbắt buộcheader

URL để truy cập file image từ external store.

OpenStack-image-import-methodsstringheader

Danh sách phương thức import, phân tách bằng dấu phẩy. Chỉ có khi cloud bật tính năng image import. Mới trong phiên bản 2.6

OpenStack-image-store-idsstringheader

Danh sách store ID khả dụng, phân tách bằng dấu phẩy. Nếu thiếu header này, cloud không hỗ trợ nhiều backend store.

checksumstringbắt buộcbody

Hash dùng cho dữ liệu image. Image service dùng giá trị này để kiểm tra. Có thể là null (kiểu JSON null).

container_formatenumbắt buộcbody

Định dạng container của image. Giá trị có thể khác nhau tùy cấu hình cloud OpenStack. Ví dụ: ami, ari, aki, bare, ovf, ova hoặc docker. Có thể là null.

created_atstringbắt buộcbody

Ngày giờ tạo tài nguyên, định dạng ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. Ví dụ 2015-08-27T09:49:58-05:00. Giá trị ±hh:mm là offset múi giờ so với UTC.

disk_formatenumbắt buộcbody

Định dạng disk. Giá trị có thể khác nhau tùy cấu hình cloud. Xem Image Schema để biết giá trị hợp lệ. Ví dụ: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop hoặc iso. Có thể là null.

filestringbắt buộcbody

URL của file image máy ảo.

idstringbắt buộcbody

UUID image do người dùng tự đặt, theo định dạng nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. Nếu bỏ trống, API tự sinh UUID.

min_diskintegerbắt buộcbody

Dung lượng disk tối thiểu (GB) cần để boot image. Có thể là null.

min_ramintegerbắt buộcbody

Dung lượng RAM tối thiểu (MB) cần để boot image. Có thể là null.

namestringbắt buộcbody

Tên image. Có thể là null.

os_hash_algostringbắt buộcbody

Thuật toán dùng để tính hash bảo mật cho dữ liệu image. Kết quả hiển thị ở os_hash_value. Giá trị có thể là null. Thuật toán do operator của cloud chọn, người dùng không cấu hình được. Mới trong phiên bản 2.7

os_hash_valuestringbắt buộcbody

Hexdigest của hash bảo mật, tính bằng thuật toán ở os_hash_algo. Có thể là null nếu chưa có dữ liệu image hoặc image được tạo bằng API trước phiên bản 2.7. Mới trong phiên bản 2.7

os_hiddenbooleanbắt buộcbody

Kiểm soát việc image có hiển thị trong danh sách mặc định hay không. Image "hidden" là image đã cũ (ví dụ thiếu bản cập nhật mới nhất) nên không phải lựa chọn đầu tiên, nhưng không bị xoá vì có thể cần cho rebuild máy ảo. Ẩn khỏi danh sách giúp người dùng dễ tìm phiên bản mới hơn. Mới trong phiên bản 2.7

ownerstringbắt buộcbody

ID của chủ sở hữu image, thường là project (tenant) ID. Có thể là null.

protectedbooleanbắt buộcbody

Giá trị boolean; nếu là true thì image không thể bị xoá.

schemastringbắt buộcbody

URL của schema mô tả image máy ảo.

selfstringbắt buộcbody

URL của image máy ảo.

sizeintegerbắt buộcbody

Kích thước dữ liệu image, tính bằng byte. Có thể là null.

statusstringbắt buộcbody

Trạng thái image.

tagsarraybắt buộcbody

Danh sách tag của image, có thể rỗng.

updated_atstringbắt buộcbody

Ngày giờ cập nhật tài nguyên. Nếu chưa từng cập nhật, trường này là null. Định dạng ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm.

virtual_sizeintegerbắt buộcbody

Kích thước ảo của image. Có thể là null.

visibilitystringbắt buộcbody

Mức hiển thị của image, tức quyền truy cập image.

direct_urlstringbody

URL truy cập file image trong external store. Chỉ có khi show_image_direct_url được bật trong cấu hình Image service. Vì có rủi ro bảo mật, tùy chọn này mặc định tắt.

locationsarraybody

Danh sách object mô tả vị trí image. Mỗi object có url và metadata (dict key). Chỉ xuất hiện khi show_multiple_locations được bật trong cấu hình Image service. Vì có rủi ro bảo mật, tùy chọn này mặc định tắt.

Response mẫu

JSON body

{
    "name": "alpine",
    "disk_format": "qcow2",
    "container_format": "bare",
    "visibility": "shared",
    "size": null,
    "virtual_size": null,
    "status": "queued",
    "checksum": null,
    "protected": false,
    "min_ram": 0,
    "min_disk": 0,
    "owner": "f33507157a634f1cac71e06a70fb558e",
    "os_hidden": false,
    "os_hash_algo": null,
    "os_hash_value": null,
    "id": "9775d86a-8bf8-4200-a4b5-d892e931e8f6",
    "created_at": "2025-10-22T08:40:44Z",
    "updated_at": "2025-10-22T08:40:44Z",
    "tags": [],
    "self": "/v2/images/9775d86a-8bf8-4200-a4b5-d892e931e8f6",
    "file": "/v2/images/9775d86a-8bf8-4200-a4b5-d892e931e8f6/file",
    "schema": "/v2/schemas/image"
}

Mã trạng thái

Thành công

Mã	Mô tả
201 - Created	Tài nguyên đã được tạo và sẵn sàng sử dụng.

Lỗi

Mã	Mô tả
400 - Bad Request	Nội dung request không hợp lệ.
401 - Unauthorized	Cần 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.
409 - Conflict	Thao tác xung đột với một thao tác khác trên tài nguyên.
413 - Request Entity Too Large	Request lớn hơn mức server có thể xử lý.
415 - Unsupported Media Type	Media type của request không được server hoặc tài nguyên hỗ trợ.

Request​

Tham số​

Ví dụ​

Response​

Tham số​

Response mẫu​

Mã trạng thái​

Thành công​

Lỗi​

Request

Tham số

Ví dụ

Response

Tham số

Response mẫu

Mã trạng thái

Thành công

Lỗi