支持控制台（Console）开发人员开始试用联系人

15.6. 子集合

15.6.1. 磁盘子集合

15.6.1.1. 磁盘子集合

disks 子集合代表了虚拟机上的所有虚拟硬盘。一个 disk 表述包括以下项：
表 15.2. 虚拟机磁盘的项
项类型描述属性
link rel="statistics"关系虚拟机磁盘统计数据的 statistics 子集合链接。
link rel="permissions"关系到 permissions 子集合的链接。
alias字符串磁盘的唯一 ID。使用 alias 而不是使用 name。
image_id字符串保存在所定义的存储域中的虚拟机镜像标识。
storage_domains复杂数据与磁盘相关联的存储域。每个 storage_domain 项都包括一个带有存储域 GUID 的 id 属性。使用 POST 更新这个项可以执行从一个数据存储域到另一个数据存储域的磁盘实时迁移操作。 [a]
size整数磁盘大小（以字节为单位）。已被 provisioned_size 所替代。
provisioned_size整数配置的磁盘大小（以字节为单位）
actual_size整数磁盘的实际大小（以字节为单位）
statusillegal、invalid、locked 或 ok磁盘设备的状态。capabilities 下的 disk_states 列出了它的值。
interface列举连接到磁盘设备的接口驱动类型。capabilities 包括了有效的值。 
format列举底层的存储格式。capabilities 包括了有效的值。使用 Copy On Write（COW）可以创建快照，但对系统性能会有一些影响；Raw 不能创建快照，但可以提供更好的性能。
sparse布尔值：true 或 falsetrue：磁盘所使用的物理存储无法被预先分配。
bootable布尔值：true 或 falsetrue：磁盘被设为可引导。 
--shareable布尔值：true 或 falsetrue：磁盘可以被多个虚拟机共享。 
wipe_after_delete布尔值：true 或 false如果为 true，在磁盘被删除后，这个磁盘的底层物理存储会被清零。此选项会增加数据的安全性，但同时会消耗大量的操作资源，并会增加删除过程所需的时间。 
propagate_errors布尔值：true 或 falsetrue：当磁盘出现错误时，不会导致虚拟机暂停，而是把磁盘错误传递给虚拟机的 OS。 
vm id=GUID包括虚拟机的 ID。
quota id=GUID为磁盘设置一个配额。 
lun_storage复杂数据为存储使用的直接 LUN 的标识。需要一个包括 iSCSI 或 FCP 设备详情的 logical_unit 项。
active布尔值（Boolean）指定磁盘是否连接到虚拟机。
read_only布尔值（Boolean）定义磁盘是否为只读。
link rel="disk_profile"关系到 disk_profile 子集合的链接。
[a] 这个项只有在磁盘被添加到虚拟机，而不是通过虚拟机模板创建时才需要

例 15.10. 磁盘设备的 XML 表述

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>
    <link rel="permissions"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/permissions"/>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399"/> 
    <alias>Classic_VM</alias>
    <image_id>cac69a29-ccff-49d4-8a26-e4cdacd83e34</image_id> 
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>12884901888</size>
    <provisioned_size>12884901888</provisioned_size>
    <actual_size>1073741824</actual_size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <wipe_after_disk>true</wipe_after_disk>
    <propagate_errors>false</propagate_errors>
    <active>true</active>
    <read_only>false</read_only>
    <disk_profile id="23fb2e0d-3062-4819-8165-3be88f2f587e"
      href="/api/diskprofiles/23fb2e0d-3062-4819-8165-3be88f2f587e"/>
    <lun_storage>
        <logical_unit id="lun1">
                ...
        </logical_unit>
    </lun_storage>
</disk>
添加一个新虚拟磁盘。添加新虚拟磁盘需要 provisioned_size 项。使用 storage_domains 项指定磁盘要在哪个存储域中创建。同一个虚拟机的多个磁盘可以存在于不同的存储域中。

例 15.11. 在虚拟机上创建一个新磁盘设备

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <provisioned_size>8589934592</provisioned_size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>
为虚拟机添加一个新的外部（direct LUN）磁盘。这个调用需要 lun_storage 和 logical_unit 项来包括 iSCSI 或 FCP 设备的详细信息。

例 15.12. 在虚拟机上创建一个新的 direct LUN 磁盘设备

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
		
<disk>
    <interface>virtio</interface>
    <lun_storage>
        <type>iscsi</type>
        <logical_unit id="lun1">
            <address>iscsi.example.com</address>
            <port>3260</port>
            <target>iqn.2010.05.com.example:iscsi.targetX</target>
        </logical_unit>
    </lun_storage>
</disk>
在创建完成后，alias、description、storage_domains、provisioned_size、interface、bootable、shareable、wipe_after_delete 和 propagate_errors 项都可以被更新。
用户可以在不需要暂停、休眠、重启虚拟机的情况下调整虚拟磁盘的大小。

例 15.13. 更新虚拟机磁盘

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <bootable>false</bootable>
    <shareable>false</shareable>
</disk>

例 15.14. 把虚拟机磁盘的大小改为 20GB。

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <provisioned_size>21474836480</provisioned_size>
</disk>

注意

以上实例中的磁盘大小是通过以下公式计算的：
20480MB * 1024 2 = 21474836480 字节

例 15.15. 重新命名一个虚拟机磁盘

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <alias>Classic_VM2</alias>
</disk>
删除虚拟机磁盘需要一个 DELETE 请求。

例 15.16. 删除虚拟机磁盘

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1

HTTP/1.1 204 No Content

15.6.1.2. 磁盘克隆

使用带有 clone 项的模板克隆磁盘。在创建虚拟机时，把 disks 子集合的 clone 项设置为 true。这会使用基本模板克隆磁盘，并把它附加到虚拟机上。

例 15.17. 使用模板克隆一个磁盘

以下实例在创建虚拟机时使用模板克隆一个磁盘。 
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
        
<vm>
    <name>cloned_vm</name>
    <template id="64d4aa08-58c6-4de2-abc4-89f19003b886"/>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
    <disks>
        <clone>true</clone>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b">
            <format>COW</format>
        </disk>
        <disk id="42aef10d-3dd5-4704-aa73-56a023c1464c">
            <format>COW</format>
        </disk>
    </disks>
</vm>

重要

基于磁盘名称对虚拟机磁盘进行搜索需要 alias 搜索参数，而不是 name。

15.6.1.3. 磁盘统计数据子集合

每个虚拟机都包括一个 statistics 子集合来提供与磁盘相关的统计数据。每个 statistic 包括以下项：
表 15.3. 虚拟机磁盘统计数据的项
项类型描述
name字符串统计数据记录的唯一标识。
description字符串统计数据的描述。
unit字符串统计数据值所使用的单位。
typeGAUGE 或 COUNTER统计数据类型。
values type=INTEGER 或 DECIMAL统计数据值的数据类型。
value复杂数据包括 datum 的数据集。
datum请参阅 values typevalue 中的一条数据。
disk id=关系与包括 disk 资源的关系。
下表列出了虚拟机磁盘的统计数据类型信息。
表 15.4. 虚拟机磁盘统计数据类型
名称
描述
data.current.read
读磁盘操作的数据传输频率（字节/每秒）
data.current.write
写磁盘操作的数据传输频率（字节/每秒）

例 15.18. 虚拟机统计数据子集合的 XML 表述

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/disks/
      f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
      33b9212b-f9cb-3fd0-b364-248fb61e1272">
        <name>data.current.read</name>
        <description>Read data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" 
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>

注意

这个 statistics 子集合是只读的。

15.6.1.4. 附加浮动磁盘和取消附加浮动磁盘的操作

使用 POST 请求在虚拟机的 disks 子集合中附加主 rel="disks" 集合中的一个磁盘。包括被附加的磁盘 id。

例 15.19. 附加浮动磁盘

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk id="d135f1c5-b5e1-4238-9381-b3277f5a3742">
</disk>
使用对磁盘资源的 DELETE 请求来从虚拟机的 disks 子集合中取消附加一个磁盘，但需要包括一个 detach 项来确保磁盘不会被破坏。

例 15.20. 从虚拟机上取消附加的磁盘

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  d135f1c5-b5e1-4238-9381-b3277f5a3742 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <detach>true</detach>
</action>

15.6.1.5. 激活和取消激活操作

每个虚拟机磁盘都提供了一组 activate 和 deactivate 操作来为虚拟机添加磁盘，或从虚拟机上删除磁盘。

例 15.21. 激活虚拟机磁盘操作

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

例 15.22. 取消激活虚拟机磁盘操作

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
使用这些操作来为虚拟机“热插”磁盘，并激活新添加的磁盘。

重要

“热插”功能只支持 VirtIO 磁盘，虚拟机操作系统必须支持“热插”操作。支持这个功能的操作系统包括：
  • Red Hat Enterprise Linux 6；
  • Red Hat Enterprise Linux 5；
  • Windows Server 2008； 和
  • Windows Server 2003。

15.6.2. 网络接口子集合

15.6.2.1. 网络接口子集合

nics 子集合代表了虚拟机上的所有网络接口设备。一个 nics 表述包括以下项：
表 15.5. 虚拟机网络接口项
项类型描述属性
link rel="statistics"关系虚拟机网络接口统计数据的 statistics 子集合链接。
network id=GUID接口需要连接到的网络标识。可以是一个空的网络 ID
interface列举nic 使用的驱动类型。capabilities 包括了有效的值。 
mac address=字符串接口的 MAC 地址。
port_mirroring复杂数据指定 NIC 是否接收镜像的网络数据。使用一组 network id= 来定义 networks 项。
plugged布尔值指定 NIC 是否被插到虚拟机上。
linked布尔值指定 NIC 是否被连接到虚拟机上。

例 15.23. 网络接口的 XML 表述

<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e" 
  ref="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
  7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics/
      7a3cff5e-3cc4-47c2-8388-9adf16341f5e/statistics"/>   
    <name>nic1</name>
    <interface>virtio</interface>
    <mac address="00:1a:4a:16:84:07"/>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/api/networks/00000000-0000-0000-0000-000000000009"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    <port_mirroring>
        <networks>
            <network id="56087282-d7a6-11e1-af44-001a4a400e0c"
              href="/api/networks/56087282-d7a6-11e1-af44-001a4a400e0c"/>
        </networks>
    </port_mirroring>
</nic>
当添加一个网络接口时，name 和 network 项是必需的。使用 id 属性或 name 项来指定 network 项。

例 15.24. 创建一个虚拟机 NIC

POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic1</name>
    <network id="00000000-0000-0000-0000-000000000009"/>
</nic>
API 用户可以使用 PUT 请求修改网络接口。

例 15.25. 更新虚拟机 NIC

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic2</name>
    <network id="00000000-0000-0000-0000-000000000010"/>
    <type>e1000</type>
</nic>
API 用户可以使用 DELETE 请求删除网络接口。

例 15.26. 删除虚拟机 NIC

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1

HTTP/1.1 204 No Content

重要

“热插”功能只在虚拟机操作系统支持“热插”操作时才被支持。支持这个功能的操作系统包括：
  • Red Hat Enterprise Linux 6；
  • Red Hat Enterprise Linux 5；
  • Windows Server 2008 和
  • Windows Server 2003。

15.6.2.2. 网络接口统计数据子集合

每个虚拟机网络接口都有一个提供网络接口统计数据的 statistics 子集合。每个 statistic 都包括以下项：
表 15.6. 虚拟机网络接口统计数据项
项类型描述
name字符串统计数据记录的唯一标识。
description字符串统计数据的描述。
unit字符串统计数据值所使用的单位。
typeGAUGE 或 COUNTER统计数据类型。
values type=INTEGER 或 DECIMAL统计数据值的数据类型。
value复杂数据包括 datum 的数据集。
datum请参阅 values typevalue 中的一条数据。
nic id=关系与包括 nic 资源的关系。
下表列出了虚拟机网络接口的统计数据类型。
表 15.7. 虚拟机 NIC 统计数据类型
名称
描述
data.current.rx
数据接收频率（字节/每秒）
data.current.tx
数据传输频率（字节/每秒）
errors.total.rx
接收数据中的错误总数
errors.total.tx
传输数据中的错误总数

例 15.27. 虚拟机 NIC 统计数据子集合的 XML 表述

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/nics/
      6cd08e76-57c0-41ba-a728-7eba46ae1e36/statistics/
      ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
        <name>data.current.rx</name>
        <description>Receive data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <nic id="6cd08e76-57c0-41ba-a728-7eba46ae1e36"
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
    </statistic>
    ...
</statistics>

注意

这个 statistics 子集合是只读的。

15.6.3. 虚拟 NUMA 节点子集合

numanodes 子集合代表了一个虚拟机上的所有虚拟 NUMA 节点。一个 vm_numa_node 会包括以下项：
表 15.8. 虚拟 NUMA 节点的项
项类型描述属性
index整数虚拟 NUMA 节点的索引号。
memory整数分配给虚拟 NUMA 节点的内存数量（以 MB 为单位）。
cpu复杂数据与这个虚拟 NUMA 节点相关联的 CPU 拓扑。每个 core 项包括一个 index 属性代表相关联的内核索引号。
vm id=GUID包括虚拟机的 ID。
numa_node_pins复杂数据把虚拟 NUMA 节点固定到一个主机的 NUMA 节点。每个 numa_node_pin 项包括一个 pinned="true" 布尔值，以及主机 NUMA 节点的 index 号。 

例 15.28. 一个虚拟 NUMA 节点的 XML 表述

<vm_numa_node href="/api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50" id="3290b973-ed3e-4f0b-bbf5-9be10d229e50">
        <index>0</index>
        <memory>1024</memory>
        <cpu>
            <cores>
                <core index="0"/>
            </cores>
        </cpu>
        <vm href="/api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b" id="c7ecd2dc-dbd3-4419-956f-1249651c0f2b"/>
        <numa_node_pins>
            <numa_node_pin pinned="true" index="0">
                <host_numa_node id="417cdefb-8c47-4838-87f3-dd0498fdf6c7"/>
            </numa_node_pin>
        </numa_node_pins>
</vm_numa_node>
在添加一个新虚拟 NUMA 节点时，需要 index、memory 和 cpu 项。

例 15.29. 把一个新的虚拟 NUMA 节点添加到一个虚拟机

POST /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm_numa_node>
  <index>0</index>
  <memory>1024</memory>
  <cpu>
    <cores>
      <core index="0"/>
    </cores>
  </cpu>
</vm_numa_nodes>
使用 PUT 请求来更新一个虚拟 NUMA 节点。您可以使用一个 PUT 请求来把一个虚拟 NUMA 节点固定到一个主机上的一个物理 NUMA 节点上。

例 15.30. 更新一个虚拟 NUMA 节点

PUT /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm_numa_node>
  <numa_node_pins>
    <numa_node_pin pinned="true" index="0">
      <host_numa_node id="417cdefb-8c47-4838-87f3-dd0498fdf6c7"/>
    </numa_node_pin>
  </numa_node_pins>
</vm_numa_node>
使用 DELETE 请求删除一个虚拟 NUMA 节点。

例 15.31. 删除一个虚拟 NUMA 节点

DELETE /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1

HTTP/1.1 204 No Content

15.6.4. CD-ROM 子集合

cdroms 子集合代表了虚拟机上的 CD-ROM 设备。一个 cdrom 表述包括以下项：
表 15.9. 虚拟机 CD-ROM 项
项类型描述属性
file id=字符串/文件名ISO 镜像的标识。 

例 15.32. CD-ROM 设备的 XML 表述

<cdrom id="00000000-0000-0000-0000-000000000000"
  href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/
  00000000-0000-0000-0000-000000000000">
    <file id="rhel-server-6.0-x86_64-dvd.iso"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>
使用带有 file id 项的 PUT 请求来添加一个新 CD-ROM 资源。

例 15.33. 添加一个新 CD-ROM 文件

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
API 使用 PUT 请求更换 CD-ROM：

例 15.34. 更换 CD-ROM 文件

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
API 使用一个带有额外 current URI 参数的 PUT 请求来更换当前会话中使用的 CD-ROM：

例 15.35. 更换当前会话中的 CD-ROM 文件

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
要临时弹出 CD-ROM，发送一个到虚拟机的 cdroms 子集合的 PUT 请求，这个请求中需要使用 current=true 参数：

例 15.36. 在当前会话中弹出 CD-ROM 文件

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>

注意

重启虚拟机后会自动连接到 CD-ROM。
要永久弹出 CD-ROM，向虚拟机的 cdroms 子集合发送 PUT 请求：

例 15.37. 永久弹出 CD-ROM 文件

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>

注意

虚拟机只包括一个 CD-ROM 设备。

15.6.5. 快照子集合

15.6.5.1. 快照子集合

虚拟机使用快照来保存和恢复磁盘的状态。和其它集合相似，用户可以使用 rel="snapshot" 子集合表述和管理快照。
每个虚拟机快照都由一个单独的、带有以下项的 snapshot 项来表述：
表 15.10. 虚拟机快照的项
项类型描述属性
vm id=GUID快照所属虚拟机的 ID 和 URI。
link rel="restore"关系到恢复虚拟机快照的一个链接。
link rel="prev"关系虚拟机前一个快照的标识。
type字符串快照的类型。例如，active 或 regular。
datexsd:dateTime 格式：YYYY-MM-DDThh:mm:ss快照被创建的日期和时间。
snapshot_status字符串快照的当前状态。
persist_memorystate布尔值指定在进行快照时，是否在快照中包括虚拟机内存的状态。

注意

不能使用 PUT 修改快照。

例 15.38. 虚拟机快照的 XML 表述

<snapshot id="00000000-0000-0000-0000-000000000000"
  href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
  00000000-0000-0000-0000-000000000000">
    <actions>
      <link rel="restore"
      href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
      00000000-0000-0000-0000-000000000000/restore"/>
    <link rel="prev"
      href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
    </actions>
    <vm id="00000000-0000-0000-0000-000000000000"
      href="/api/vms/00000000-0000-0000-0000-000000000000"/>
    <description>Virtual Machine 1 - Snapshot A</description>
    <type>active</type>
    <date>2010-08-16T14:24:29</date>
    <snapshot_status>ok</snapshot_status>
    <persist_memorystate>false</persist_memorystate>
</snapshot>
使用带有 All-Content: true 头的、对虚拟机快照的 GET 请求可以获得包括额外的、代表快照的 OVF 数据。
如果 Accept 头为空，它会被默认设置为 application/xml，数据由 HTML 项来代表，因此不会影响到 XML tag。如果指定 Accept: application/json 头，返回的数据会使用标准的 XML tag。这个示例使用标准块格式构成。

例 15.39. 代表一个快照的 ovf 数据的 XML

GET /api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots HTTP/1.1
All-Content: true
	
<?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf=\"http://schemas.dmtf.org/ovf/envelope/1/\" 
  xmlns:rasd=\"http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData\" 
  xmlns:vssd=\"http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData\" 
  xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" ovf:version=\"3.5.0.0\"> 
  <References>
  <File ovf:href=\"ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459\" 
    ovf:id=\"40456d92-3687-4a85-bab3-87b4cc7af459\" ovf:size=\"10737418240\" 
    ovf:description=\"Active VM\"/>
  <Nic ovf:id=\"be14bfc8-3dbd-4ac1-ba02-c6dfa7fc707c\"/>
  </References>
  <Section xsi:type=\"ovf:NetworkSection_Type\"> 
    <Info>List of networks</Info><Network ovf:name=\"Network 1\"/>
  </Section>
  <Section 
    xsi:type=\"ovf:DiskSection_Type\"> 
    <Info>List of Virtual Disks</Info>
    <Disk ovf:diskId=\"40456d92-3687-4a85-bab3-87b4cc7af459\" 
    ovf:size=\"10\" ovf:actual_size=\"0\" 
    ovf:vm_snapshot_id=\"a209216d-2909-4802-8886-02aad55dccc8\" 
    ovf:parentRef=\"\" 
    ovf:fileRef=\"ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459\" 
    ovf:format=\"http://www.vmware.com/specifications/vmdk.html#sparse\" 
    ovf:volume-format=\"RAW\" 
    ovf:volume-type=\"Preallocated\" 
    ovf:disk-interface=\"VirtIO\" 
    ovf:boot=\"true\" 
    ovf:disk-alias=\"VM_01_Disk1\" 
    ovf:wipe-after-delete=\"false\"/>
  </Section>
  <Content 
    ovf:id=\"out\" 
    xsi:type=\"ovf:VirtualSystem_Type\"> 
    <CreationDate>2015/02/09 13:53:53</CreationDate> 
    <ExportDate>2015/02/10 00:39:24</ExportDate> 
    <DeleteProtected>false</DeleteProtected> 
    <SsoMethod>guest_agent</SsoMethod> 
    <IsSmartcardEnabled>false</IsSmartcardEnabled> 
    <TimeZone>Etc/GMT</TimeZone><default_boot_sequence>0</default_boot_sequence> 
    <Generation>1</Generation> 
    <VmType>1</VmType> 
    <MinAllocatedMem>1024</MinAllocatedMem> 
    <IsStateless>false</IsStateless> 
    <IsRunAndPause>false</IsRunAndPause> 
    <AutoStartup>false</AutoStartup> 
    <Priority>1</Priority> 
    <CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId> 
    <IsBootMenuEnabled>false</IsBootMenuEnabled> 
    <IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled> 
    <IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled> 
    <Name>VM_01</Name> 
    <TemplateId>00000000-0000-0000-0000-000000000000</TemplateId> 
    <TemplateName>Blank</TemplateName> 
    <IsInitilized>true</IsInitilized> 
    <Origin>3</Origin> 
    <DefaultDisplayType>1</DefaultDisplayType> 
    <TrustedService>false</TrustedService> 
    <OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId> 
    <OriginalTemplateName>Blank</OriginalTemplateName> 
    <UseLatestVersion>false</UseLatestVersion>
    <Section ovf:id=\"42ec2621-7ad6-4ca2-bd68-973a44b2562e\" ovf:required=\"false\" xsi:type=\"ovf:OperatingSystemSection_Type\"> 
      <Info>Guest Operating System</Info> 
      <Description>other</Description>
    </Section>
    <Section xsi:type=\"ovf:VirtualHardwareSection_Type\"> 
      <Info>1 CPU, 1024 Memeory</Info> 
      <System>
        <vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
      </System> 
      <Item> 
        <rasd:Caption>1 virtual cpu</rasd:Caption> 
        <rasd:Description>Number of virtual CPU</rasd:Description> 
        <rasd:InstanceId>1</rasd:InstanceId> 
        <rasd:ResourceType>3</rasd:ResourceType> 
        <rasd:num_of_sockets>1</rasd:num_of_sockets> 
        <rasd:cpu_per_socket>1</rasd:cpu_per_socket>
      </Item> 
      <Item> 
        <rasd:Caption>1024 MB of memory</rasd:Caption> 
        <rasd:Description>Memory Size</rasd:Description> 
        <rasd:InstanceId>2</rasd:InstanceId> 
        <rasd:ResourceType>4</rasd:ResourceType> 
        <rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits> 
        <rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
      </Item> 
      <Item> 
        <rasd:Caption>VM_01_Disk1</rasd:Caption> 
        <rasd:InstanceId>40456d92-3687-4a85-bab3-87b4cc7af459</rasd:InstanceId> 
        <rasd:ResourceType>17</rasd:ResourceType> 
        <rasd:HostResource>ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459</rasd:HostResource> 
        <rasd:Parent>00000000-0000-0000-0000-000000000000</rasd:Parent> 
        <rasd:Template>00000000-0000-0000-0000-000000000000</rasd:Template> 
        <rasd:ApplicationList></rasd:ApplicationList> 
        <rasd:StoragePoolId>00000002-0002-0002-0002-000000000255</rasd:StoragePoolId> 
        <rasd:CreationDate>2015/02/09 13:54:41</rasd:CreationDate> 
        <rasd:LastModified>1970/01/01 00:00:00</rasd:LastModified> 
        <rasd:last_modified_date>2015/02/10 00:39:22</rasd:last_modified_date> 
        <Type>disk</Type> 
        <Device>disk</Device> 
        <rasd:Address>{slot=0x06, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>1</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>virtio-disk0</Alias>
      </Item> 
      <Item> 
        <rasd:Caption>Ethernet adapter on ovirtmgmt</rasd:Caption> 
        <rasd:InstanceId>be14bfc8-3dbd-4ac1-ba02-c6dfa7fc707c</rasd:InstanceId> 
        <rasd:ResourceType>10</rasd:ResourceType> 
        <rasd:OtherResourceType>ovirtmgmt</rasd:OtherResourceType> 
        <rasd:ResourceSubType>3</rasd:ResourceSubType> 
        <rasd:Connection>ovirtmgmt</rasd:Connection> 
        <rasd:Linked>true</rasd:Linked> 
        <rasd:Name>nic1</rasd:Name> 
        <rasd:MACAddress>00:1a:4a:87:cb:00</rasd:MACAddress> 
        <rasd:speed>1000</rasd:speed> 
        <Type>interface</Type> 
        <Device>bridge</Device> 
        <rasd:Address>{slot=0x03, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>net0</Alias>
      </Item> 
      <Item> 
        <rasd:Caption>USB Controller</rasd:Caption> 
        <rasd:InstanceId>3</rasd:InstanceId> 
        <rasd:ResourceType>23</rasd:ResourceType> 
        <rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
      </Item> 
      <Item> 
        <rasd:Caption>Graphical Controller</rasd:Caption> 
        <rasd:InstanceId>17bbf0db-7cf0-4529-9b53-dee6dee41cfd</rasd:InstanceId> 
        <rasd:ResourceType>20</rasd:ResourceType> 
        <rasd:VirtualQuantity>1</rasd:VirtualQuantity> 
        <rasd:SinglePciQxl>false</rasd:SinglePciQxl> 
        <Type>video</Type> 
        <Device>qxl</Device> 
        <rasd:Address>{slot=0x02, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>true</IsReadOnly> 
        <Alias>video0</Alias> 
        <SpecParams>  
          <vram>32768</vram> 
          <heads>1</heads>
        </SpecParams>
      </Item> 
      <Item> 
        <rasd:Caption>CDROM</rasd:Caption> 
        <rasd:InstanceId>7ce1bd14-d98a-43ba-beee-520bdfd9c698</rasd:InstanceId> 
        <rasd:ResourceType>15</rasd:ResourceType> 
        <Type>disk</Type> 
        <Device>cdrom</Device> 
        <rasd:Address>{bus=1, controller=0, type=drive, target=0, unit=0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>true</IsReadOnly> 
        <Alias>ide0-1-0</Alias></Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>8758c42f-7523-461b-82bb-41d91e46fd36</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>usb</Device> 
        <rasd:Address>{slot=0x01, bus=0x00, domain=0x0000, type=pci, function=0x2}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>usb0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>58f1a596-553e-4e95-9331-64b5d8cebe2e</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>ide</Device> 
        <rasd:Address>{slot=0x01, bus=0x00, domain=0x0000, type=pci, function=0x1}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>ide0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>2f4f8aa5-25eb-4a31-b841-50dc48fce4a7</rasd:InstanceId> 
        <Type>channel</Type> 
        <Device>unix</Device> 
        <rasd:Address>{bus=0, controller=0, type=virtio-serial, port=1}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>channel0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>edaac3ed-2ab6-48b1-ae77-cc98f8b45bd8</rasd:InstanceId> 
        <Type>channel</Type> 
        <Device>unix</Device> 
        <rasd:Address>{bus=0, controller=0, type=virtio-serial, port=2}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>channel1</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>8dfed248-5164-41d3-8b6e-46aef9798d84</rasd:InstanceId> 
        <Type>channel</Type> 
        <Device>spicevmc</Device> 
        <rasd:Address>{bus=0, controller=0, type=virtio-serial, port=3}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>channel2</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>d184185e-ee19-442a-88f5-6a48f14164e1</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>virtio-scsi</Device> 
        <rasd:Address>{slot=0x04, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>scsi0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>374d219e-e2ff-4755-a544-d537c87e82df</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>virtio-serial</Device> 
        <rasd:Address>{slot=0x05, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>virtio-serial0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>cf3d7121-9db0-4fd1-bd12-50ce4e1ce379</rasd:InstanceId> 
        <Type>balloon</Type> 
        <Device>memballoon</Device> 
        <rasd:Address>{slot=0x07, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>true</IsReadOnly> 
        <Alias>balloon0</Alias> 
        <SpecParams> 
          <model>virtio</model>
        </SpecParams>
      </Item>
    </Section>
  </Content>
</ovf:Envelope>
您可以为正在运行的主机进行快照（实时快照），或使用 POST 来关闭虚拟机：

例 15.40. 创建一个虚拟机的快照

POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/ HTTP/1.1
Accept: application/xml
Content-type: application/xml

<snapshot>
<description>Snapshot description</description>
</snapshot>
您可以在快照表述中使用 rel="restore" 操作链接来恢复虚拟机快照：

例 15.41. 恢复虚拟机快照

POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/00000000-0000-0000-0000-000000000000/restore HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.6.5.2. 通过快照克隆虚拟机

API 提供了一个使用其它虚拟机快照创建虚拟机的功能。API 用户可以在创建新虚拟机时保留原始虚拟机的所有快照。
使用快照创建虚拟机需要在标准的虚拟机表述中添加一个 snapshots 项。用户需要向 vms 集合发送一个 POST 请求。
snapshots 项包括了一个 snapshot id= 项来指定创建虚拟机需要基于的快照。

例 15.42. 从快照克隆虚拟机

POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
  ...
  <snapshots>
    <snapshot id="3f68ee63-0016-4f8c-9b8a-11d9f28f7c9e"/>
  </snapshots>
  ...
</vm>

15.6.6. 统计数据子集合

每个虚拟机都包括一个 statistics 子集合来提供与虚拟机相关的统计数据。每个 statistic 包括以下项：
表 15.11. 虚拟机磁盘统计数据的项
项类型描述
name字符串统计数据记录的唯一标识。
description字符串统计数据的描述。
unit字符串统计数据值所使用的单位。
typeGAUGE 或 COUNTER统计数据类型。
values type=INTEGER 或 DECIMAL统计数据值的数据类型。
value复杂数据包括 datum 的数据集。
datum请参阅 values typevalue 中的一条数据。
vm id=关系与包括 vm 资源的关系。
下表列出了虚拟机的统计数据类型。
表 15.12. 虚拟机统计数据类型
名称
描述
memory.installed
为虚拟机使用分配的总内存数量（以字节为单位）。
memory.used
虚拟机当前使用的内存（以字节为单位）。
cpu.current.guest
虚拟机使用的 CPU 百分数。
cpu.current.hypervisor
hypervisor 消耗的 CPU 百分数。
cpu.current.total
当前使用的 CPU 百分比。

例 15.43. 虚拟机统计数据子集合 XML 表述

<statistics>
    <statistic id="ef802239-b74a-329f-9955-be8fea6b50a4"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/
      statistics/ef802239-b74a-329f-9955-be8fea6b50a4">
        <name>memory.installed</name>
        <description>Total memory configured</description>
        <unit>BYTES</unit>
        <type>GUAGE</type>
        <values type="DECIMAL">
            <value>
                <datum>1073741824<datum>
            </value>
        </values>
        <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
          href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    </statistic>
    ...
</statistics>

注意

虚拟机的 statistics 子集合是只读的。

15.6.7. 显示虚拟机对话信息

为虚拟机发一个 GET 请求并使用 session 子集合来查看初始 SPICE 控制台会话的用户的会话信息，以及登录到这个虚拟机的用户的会话信息。
虚拟机的 session 信息作为子集合被列出：

例 15.44. 显示一个虚拟机的会话信息

GET /api/roles/a1a701f1-aa06-4f02-af17-158be31489b3/sessions HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<sessions>
  <session id="37a6259c-c0c1-dae2-99a7-866489dff0bd"
    href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd">
  <vm href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
  <ip address="192.0.2.0"/>
  <user href= "/api/users/fdfc627c-d875-11e0-90f0-83df133b58cc" id="fdfc627c-d875-11e0-90f0-83df133b58cc">
    <domain href= "/api/domains/696e7465-726e-616c-696e-7465726e616c" id="696e7465-726e-616c-696e-7465726e616c">
      <name>internal</name>
    </domain>
    <user_name>admin</user_name>
    </user>
    <console_user>true</console_user>
  </session>
  <session id="37a6259c-c0c1-dae2-99a7-866489dff0bd"
    href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd" >
    <vm href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
    <user>
      <user_name>root</user_name>
    </user>
  </session>
</sessions>
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

© 2024 Red Hat, Inc.