搜索

版本 3 REST API 指南

download PDF
Red Hat Virtualization 4.1

使用 Red Hat Virtualization 版本 3 REST 应用程序编程接口

摘要

Red Hat Virtualization Manager 的版本 4 支持表述性状态转移 API 的版本 3 和 4。本指南中的信息和示例适用于 REST API 版本 3。

第 1 章 简介

Red Hat Virtualization Manager 提供了一个 Representational State Transfer (REST) API。API 为软件开发人员和系统管理员提供在标准 Web 界面之外对 Red Hat Virtualization 环境进行控制。REST API 适用于旨在将 Red Hat Virtualization 环境的功能与通过标准 Hypertext 传输协议(HTTP)访问 API 的自定义脚本或外部应用程序集成的开发人员和管理员。
REST API 的优点是:
  • 广泛的客户端支持 - 任何支持 HTTP 协议的编程语言、框架或系统都可以使用 API;
  • 自我描述性 - 客户端应用程序需要对虚拟化基础架构的了解最少,因为运行时发现许多详细信息;
  • 基于资源的模型 - 基于资源的 REST 模型提供了管理虚拟化平台的自然方法。
这为开发人员和管理员提供以下功能:
  • 与企业 IT 系统集成.
  • 与第三方虚拟化软件集成.
  • 执行自动化维护或错误检查任务。
  • 使用脚本在 Red Hat Virtualization 环境中实现重复性任务的自动化。
本文档充当 Red Hat Virtualization Manager REST API 的参考。它旨在为开发人员和管理员提供说明和示例,以帮助通过 REST API 直接或使用提供的 Python 库利用其 Red Hat Virtualization 环境的功能。

1.1. Representational State Transfer

表述性状态转移(REST) 是一种设计架构,专注于特定服务的资源及其表示法。资源表示是信息的一个关键抽象,对应于服务器上的特定受管元素。客户端将请求发送到位于统一资源标识符(URI)的服务器元素,并使用标准 HTTP 方法(如 GETPOSTPUTDELETE )执行操作。这提供了客户端和服务器之间的无状态通信,每个请求都独立于任何其他请求,并且包含完成该请求所需的所有信息。

1.2. Red Hat Virtualization REST API 先决条件

Red Hat Virtualization REST API 先决条件

  • Red Hat Virtualization Manager 的联网安装,其中包括 REST API。
  • 用于从 REST API 发起和接收 HTTP 请求的客户端或编程库。例如:
    • Python 软件开发套件(SDK)
    • Java 软件开发套件(SDK)
    • curl 命令行工具
    • select,用于 RESTful Web 服务的 debugger
  • 了解 Hypertext 传输协议(HTTP),这是用于 REST API 交互的协议。Internet 工程任务 Force 提供了一个 Request for Comments (RFC)解释了 Hypertext Transfer Protocol :http://www.ietf.org/rfc/rfc2616.txt。
  • 了解可扩展标记语言(XML)或 JavaScript 对象表示法(JSON),API 用来构建资源表示法。W3C 在 http://www.w3.org/TR/xml/ 提供了完整的 XML 规格。ECMA International 在 http://www.ecma-international.org 上提供 JSON 的免费发布。

第 2 章 身份验证和安全性

2.1. TLS/SSL 认证

Red Hat Virtualization Manager API 需要 Hypertext Transfer Protocol Secure (HTTPS) [1] 用于与客户端软件进行安全交互,如管理器的 SDK 和 CLI 组件。这包括从 Red Hat Virtualization Manager 获取证书并将其导入到客户端的证书存储中的过程。
重要
使用安全网络连接从 Red Hat Virtualization Manager 获取您的证书。

过程 2.1. 获取证书

您可以从 Red Hat Virtualization Manager 获取证书,并使用以下三种方法之一将其传送到客户端机器:
  1. 方法 1 - 使用命令行工具从管理器下载证书。命令行工具示例包括 cURLWget,这两个工具均在多个平台上可用。
    1. 如果使用 cURL
      $ curl -o rhvm.cer http://[manager-fqdn]/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
    2. 如果使用 Wget
      $ wget -O rhvm.cer http://[manager-fqdn]/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
  2. 方法 2 - 使用 Web 浏览器导航到位于以下证书:
    http://[manager-fqdn]/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
    根据所选的浏览器,证书下载或导入到浏览器的密钥存储。
    1. 如果浏览器下载证书: 将文件保存为 rhvm.cer
      如果浏览器导入证书: 将其从浏览器的认证选项导出,并将它保存为 rhvm.cer
  3. 方法 3 - 登录到 Manager,从信任存储中导出证书并将其复制到您的客户端机器中。
    1. root 用户身份登录 Manager。
    2. 使用 Java keytool 管理工具从信任存储中导出证书:
      $ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhvm.cer
      这会创建一个名为 rhvm.cer 的证书文件。
    3. 使用 scp 命令将证书复制到客户端机器中:
      $ scp rhvm.cer [username]@[client-machine]:[directory]
每个方法都会在客户端计算机上生成名为 rhvm.cer 的证书文件。API 用户将此文件导入到客户端的证书存储中。

过程 2.2. 将证书导入到客户端

  • 将证书导入到客户端依赖于客户端本身存储和解释证书的方式。本指南包含导入证书的一些示例。有关导入证书的更多信息,对于不使用网络安全服务(NSS)或 Java KeyStore (JKS)的客户端,请参阅您的客户端文档。

2.2. HTTP 身份验证

具有 Red Hat Virtualization 帐户的任何用户可以访问 REST API。API 用户通过对 API 的所有请求提交强制的 Red Hat Virtualization Manager 用户名和密码。每个请求都使用 HTTP 基本身份验证 [2] 对这些凭证进行编码。如果请求不包含适当的 Authorization 标头,API 会发送 所需的 401 Authorization

例 2.1. 在没有适当的凭证的情况下访问 REST API

HEAD [base] HTTP/1.1
Host: [host]

HTTP/1.1 401 Authorization Required
请求通过指定域的 Authorization 标头发出。API 用户使用 username@domain:password 约定对提供的凭证中的相应 Red Hat Virtualization Manager 域和用户进行编码。
下表显示了 base64 中编码凭据的流程。
表 2.1. API 访问的编码凭证
用户名 rhevmadmin
domain domain.example.com
密码 123456
取消编码的凭证 rhevmadmin@domain.example.com:123456
base64 编码凭证 cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
API 用户提供 base64 编码凭证,如下所示:

例 2.2. 使用适当的凭证访问 REST API

HEAD [base] HTTP/1.1
Host: [host]
Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK
...
重要
基本身份验证涉及潜在的敏感信息,如密码,以纯文本形式发送。REST API 需要 Hypertext 传输协议安全(HTTPS)进行纯文本请求的传输级别加密。
重要
有些 base64 库将结果分解成多行,并使用换行符终止每行。这会破坏标头,并导致有故障的请求。Authorization 标头需要在标头中的一行中编码的凭据。

2.3. 身份验证会话

API 还提供身份验证会话支持的功能。API 用户发送带有身份验证详细信息的初始请求,然后使用会话 Cookie 发送所有后续请求以进行身份验证。以下步骤演示了如何使用经过身份验证的会话。

过程 2.3. 请求经过身份验证的会话

  1. 使用 AuthorizationPrefer: persistent-auth发送请求
    HEAD [base] HTTP/1.1
    Host: [host]
    Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
    Prefer: persistent-auth
    
    HTTP/1.1 200 OK
    ...
    
    这会返回带有以下标头的响应:
    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure
    
    注意 JSESSIONID= 值。在本例中,值为 JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
  2. 使用 Prefer: persistent-authcookie 标头发送所有后续请求,值为 JSESSIONID=。使用经过身份验证的会话时,不再需要 授权
    HEAD [base] HTTP/1.1
    Host: [host]
    Prefer: persistent-auth
    cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
    
    HTTP/1.1 200 OK
    ...
    
  3. 当不再需要会话时,如果没有 Prefer: persistent-auth 标头,向其执行请求。
    HEAD [base] HTTP/1.1
    Host: [host]
    Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
    
    HTTP/1.1 200 OK
    ...
    


[1] RFC 2818 HTTP Over TLS 中描述了 HTTPS。

第 3 章 REST API 快速入门示例

本章介绍了一个示例,它演示了 REST API 能够设置基本的 Red Hat Virtualization 环境并创建虚拟机。
除了标准先决条件外,此示例还需要以下内容:
  • A networked and configured Red Hat Virtualization Host;
  • 包含要安装的所需虚拟机操作系统的 ISO 文件。本章使用 Red Hat Enterprise Linux Server 6 进行我们的安装 ISO 示例;以及
  • Red Hat Virtualization 的 engine-iso-uploader 工具上传您选择的操作系统 ISO 文件。
本例使用 cURL 来通过客户端应用程序演示 REST 请求。请注意,任何支持 HTTP 请求的应用程序都可以替换 cURL
重要的
为简单起见,本例中的 HTTP 请求标头省略 Host:Authorization: 字段。但是,这些字段是必须的,需要特定于您的 Red Hat Virtualization Manager 安装的数据。
重要的
所有 cURL 示例包括身份验证详细信息的占位符(USER:PASS)和证书位置(CERT)。确保通过 cURL 执行的所有请求均满足认证和身份验证要求。
备注
Red Hat Virtualization Manager 为每个资源的 id 属性生成全局唯一标识符(GUID)。本例中的标识符代码可能与 Red Hat Virtualization 环境中的标识符代码不同。

3.1. 示例:访问 API 条目点

以下请求检索 API 版本 3 的主入口点的表示。

例 3.1. 访问 API v3 入口点

Request (带有标头):

GET /ovirt-engine/api HTTP/1.1
Version: 3
Accept: application/xml

请求(不带标头):

GET /ovirt-engine/api/v3 HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] https://[RHEVM Host]:443/ovirt-engine/api

结果:

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

<api>
    <link rel="capabilities" href="/ovirt-engine/api/capabilities"/>
    <link rel="clusters" href="/ovirt-engine/api/clusters"/>
    <link rel="clusters/search" href="/ovirt-engine/api/clusters?search={query}"/>
    <link rel="datacenters" href="/ovirt-engine/api/datacenters"/>
    <link rel="datacenters/search" href="/ovirt-engine/api/datacenters?search={query}"/>
    <link rel="events" href="/ovirt-engine/api/events"/>
    <link rel="events/search" href="/ovirt-engine/api/events?search={query}"/>
    <link rel="hosts" href="/ovirt-engine/api/hosts"/>
    <link rel="hosts/search" href="/ovirt-engine/api/hosts?search={query}"/>
    <link rel="networks" href="/ovirt-engine/api/networks"/>
    <link rel="roles" href="/ovirt-engine/api/roles"/>
    <link rel="storagedomains" href="/ovirt-engine/api/storagedomains"/>
    <link rel="storagedomains/search" href="/ovirt-engine/api/storagedomains?search={query}"/>
    <link rel="tags" href="/ovirt-engine/api/tags"/>
    <link rel="templates" href="/ovirt-engine/api/templates"/>
    <link rel="templates/search" href="/ovirt-engine/api/templates?search={query}"/>
    <link rel="users" href="/ovirt-engine/api/users"/>
    <link rel="groups" href="/ovirt-engine/api/groups"/>
    <link rel="domains" href="/ovirt-engine/api/domains"/>
    <link rel="vmpools" href="/ovirt-engine/api/vmpools"/>
    <link rel="vmpools/search" href="/ovirt-engine/api/vmpools?search={query}"/>
    <link rel="vms" href="/ovirt-engine/api/vms"/>
    <link rel="vms/search" href="/ovirt-engine/api/vms?search={query}"/>
    <special_objects>
        <link rel="templates/blank"
          href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"/>
        <link rel="tags/root"
          href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000"/>
    </special_objects>
    <product_info>
        <name>Red Hat Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="0" major="4"/>
    </product_info>
    <summary>
        <vms>
            <total>5</total>
            <active>0</active>
        </vms>
        <hosts>
            <total>1</total>
            <active>1</active>
        </hosts>
        <users>
            <total>1</total>
            <active>1</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</ovirt-engine/api>

重要
如果没有使用标头和 URL 前缀,服务器会自动选择版本。默认为版本 4。您可以使用 ENGINE_API_DEFAULT_VERSION 参数更改默认版本:
# echo "ENGINE_API_DEFAULT_VERSION=3" > \
  /etc/ovirt-engine/engine.conf.d/99-set-default-version.conf
# systemctl restart ovirt-engine
更改此参数会影响未明确指定版本的管理器的所有用户。
该入口点为用户提供了到虚拟化环境中的集合的链接。每个集合链接的 rel= 属性为每个链接提供一个参考点。本示例中的下一步将检查 datacenter 集合,该集合可通过 rel="datacenter" 链接获得。
入口点还包含其他数据,如 product_infospecial_objectssummary。该数据在本示例之外的章节中阐述。

3.2. 示例:列出数据中心集合

Red Hat Virtualization Manager 在安装时会创建一个 Default 数据中心。这个示例使用 Default 数据中心作为我们虚拟环境的基础。
以下请求检索数据中心集合的表示:

例 3.2. 列出数据中心集合

request:

GET /ovirt-engine/api/datacenters HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/ovirt-engine/api/datacenters

结果:

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

<data_centers>
    <data_center href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab" id="00000002-0002-0002-0002-0000000003ab">
        <name>Default</name>
        <description>The default Data Center</description>
        <link rel="storagedomains"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/storagedomains"
        <link rel="clusters"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/clusters" 
        <link rel="networks"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/networks" 
        <link rel="permissions"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/permissions" 
        <link rel="quotas"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/quotas" 
        <link rel="iscsibonds"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/iscsibonds" 
        <link rel="qoss"/>
          href="/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000003ab/qoss" 
        <local>false</local>
        <storage_format>v3</storage_format>
        <version major="4" minor="0"/>
        <supported_versions>
            <version major="4" minor="0"/>
        </supported_versions>
        <status>
            <state>up</state>
        </status>
    </data_center>
</data_centers>

请注意 Default 数据中心的 id 代码。此代码标识了此数据中心与虚拟环境的其他资源相关。
数据中心还包含指向 storagedomains 子集合的链接。数据中心使用此子集合从 storagedomains 主集合中附加存储域,本例将在以后介绍。

3.3. 示例:列出主机集群集合

Red Hat Virtualization Manager 在安装时会创建一个 Default 主机集群。这个示例使用 Default 集群对 Red Hat Virtualization 环境中的资源进行分组。
以下请求检索集群集合的表示:

例 3.3. 列出主机集群集合

request:

GET /ovirt-engine/api/clusters HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/ovirt-engine/api/clusters

结果:

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

<clusters>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
        <name>Default</name>
        <description>The default server cluster</description>
        <link rel="networks"
          href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
        <link rel="permissions"
          href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
        <cpu id="Intel Penryn Family"/>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <memory_policy>
            <overcommit percent="100"/>
            <transparent_hugepages>
                <enabled>false</enabled>
            </transparent_hugepages>
        </memory_policy>
        <scheduling_policy/>
        <version minor="0" major="4"/>
        <error_handling>
            <on_error>migrate</on_error>
        </error_handling>
    </cluster>
</clusters>

记录下您的 Default 主机集群的 id 代码。此代码标识此主机集群与虚拟环境的其他资源相关。
Default 集群使用 data_center 元素的 idhref 属性通过关系与 Default 数据中心关联。
networks 子集合包含此集群的关联网络资源列表。下一小节将更加详细地 检查网络 集合。

3.4. 示例:列出逻辑网络集合

Red Hat Virtualization Manager 在安装时会创建一个默认的 ovirtmgmt 网络。此网络充当 Red Hat Virtualization Manager 的管理网络来访问主机。
此网络与我们的 Default 集群关联,是 Default 数据中心的成员。这个示例使用 ovirtmgmt 网络来连接我们的虚拟机。
以下请求检索逻辑网络集合的表示:

例 3.4. 列出逻辑网络集合

request:

GET /ovirt-engine/api/networks HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/ovirt-engine/api/networks

结果:

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

<networks>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009">
        <name>ovirtmgmt</name>
        <description>Management Network</description>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <stp>false</stp>
        <status>
            <state>operational</state>
        </status>
        <display>false</display>
    </network>
</networks>

ovirtmgmt 网络使用数据中心的 id 代码通过关系附加到 Default 数据中心。
ovirtmgmt 网络还通过集群网络子集合中的关系附加到 Default 集群。

3.5. 示例:列出主机集合

这个示例使用 Red Hat Virtualization Host。Red Hat Virtualization Manager 会自动注册任何配置的 Red Hat Virtualization 主机。这个示例检索主机集合的表示,并显示使用虚拟化环境注册的名为 hypervisor 的 Red Hat Virtualization 主机。

例 3.5. 列出主机集合

request:

GET /ovirt-engine/api/hosts HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/ovirt-engine/api/hosts

结果:

HTTP/1.1 200 OK
Accept: application/xml

<hosts>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
        <name>hypervisor</name>
        <actions>
            <link rel="install"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/install"/>
            <link rel="activate"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/activate"/>
            <link rel="fence"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/fence"/>
            <link rel="deactivate"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/deactivate"/>
            <link rel="approve"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve"/>
            <link rel="iscsilogin"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsilogin"/>
            <link rel="iscsidiscover"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsidiscover"/>
            <link rel="commitnetconfig"
              href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/
              commitnetconfig"/>
        </actions>
        <link rel="storage"
          href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/storage"/>
        <link rel="nics"
          href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/nics"/>
        <link rel="tags"
          href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/tags"/>
        <link rel="permissions"
          href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/permissions"/>
        <link rel="statistics"
          href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/statistics"/>
        <address>10.64.14.110</address>
        <status>
            <state>non_operational</state>
        </status>
        <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
          href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
        <port>54321</port>
        <storage_manager>true</storage_manager>
        <power_management>
            <enabled>false</enabled>
            <options/>
        </power_management>
        <ksm>
            <enabled>false</enabled>
        </ksm>
        <transparent_hugepages>
            <enabled>true</enabled>
        </transparent_hugepages>
        <iscsi>
            <initiator>iqn.1994-05.com.example:644949fe81ce</initiator>
        </iscsi>
        <cpu>
            <topology cores="2"/>
            <name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
            <speed>2993</speed>
        </cpu>
        <summary>
            <active>0</active>
            <migrating>0</migrating>
            <total>0</total>
        </summary>
    </host>
</hosts>

记录您的 Default 主机的 id 代码。此代码标识此主机与虚拟环境的其他资源相关。
此主机是 Default 集群的成员,访问 nics 子集合显示此主机与 ovirtmgmt 网络的连接。

3.6. 示例:列出 CPU 配置文件

以下请求检索 CPU 配置集的表示:

例 3.6. 列出 CPU 配置集

request:

GET /ovirt-engine/api/cpuprofiles HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM Host]:443/ovirt-engine/api/cpuprofiles

结果:

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

<cpu_profiles>
    <cpu_profile href="0000001a-001a-001a-001a-00000000035e" id="0000001a-001a-001a-001a-00000000035e">
        <name>Default</name>
        <link href="/ovirt-engine/api/cpuprofiles/0000001a-001a-001a-001a-00000000035e/permissions" rel="permissions"/>
        <cluster href= "/ovirt-engine/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
    </cpu_profile>
    <cpu_profile href="fc4b9188-f87f-44f9-b9c5-c7665e10e0a2" id="fc4b9188-f87f-44f9-b9c5-c7665e10e0a2">
        <name>Premium</name>
        <description>Full service available</description>
        <link href="/ovirt-engine/api/cpuprofiles/fc4b9188-f87f-44f9-b9c5-c7665e10e0a2/permissions" rel="permissions"/>
        <qos href= "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-0000000000f7/qoss/5afe49e3-aac4-4b7b-bb83-11b9aef285e1" id="5afe49e3-aac4-4b7b-bb83-11b9aef285e1"/>
        <cluster href= "/ovirt-engine/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
    </cpu_profile>
    <cpu_profile href="48c600f4-6768-49ca-9c16-a877d0e586e5" id="48c600f4-6768-49ca-9c16-a877d0e586e5">
        <name>Budget</name>
        <description>Limited CPU</description>
        <link href="/ovirt-engine/api/cpuprofiles/48c600f4-6768-49ca-9c16-a877d0e586e5/permissions" rel="permissions"/>
        <cluster href= "/ovirt-engine/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
    </cpu_profile>
    <cpu_profile href="48c600f4-6768-49ca-9c16-a877d0e586e5" id="48c600f4-6768-49ca-9c16-a877d0e586e5">
        <name>Backup</name>
        <link href="/ovirt-engine/api/cpuprofiles/d510b042-42f0-4cb2-9d2e-25fcc28d6c5f/permissions" rel="permissions"/>
        <cluster href= "/ovirt-engine/api/clusters/668cab0c-9185-4eaa-9942-658284eeecdd" id="668cab0c-9185-4eaa-9942-658284eeecdd"/>
    </cpu_profile>
</cpu_profiles>

3.7. 示例:创建 NFS 数据存储

NFS 数据存储域是附加到数据中心导出的 NFS 共享,并为虚拟化客户机镜像提供存储。创建新存储域需要 POST 请求,其中包含存储域表示,发送到存储域集合的 URL。
您可以在存储域中默认启用 wipe after delete 选项。要配置此功能,请在 POST 请求中指定 < wipe_after_delete >。可以在创建域后编辑此选项,但是这样做不会在删除已存在的磁盘属性后更改擦除。

例 3.7. 创建 NFS 数据存储域

request:

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>data1</name>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>192.168.0.10</address>
    <path>/data1</path>
  </storage>
  <host>
    <name>hypervisor</name>
  </host>
</storage_domain>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>data1</name><type>data</type> \
    <storage><type>nfs</type><address>192.168.0.10</address> \
    <path>/data1</path></storage> \ 
    <host><name>hypervisor</name></host></storage_domain>" \
    https://[RHEVM Host]:443/ovirt-engine/api/storagedomains

API 创建一个称为 data1 的 NFS 数据存储域,其导出路径为 192.168.0.10:/data1,并通过 虚拟机监控程序主机 设置对存储域的访问。API 也返回新创建的存储域资源的以下表示。

结果:

HTTP/1.1 200 OK
Accept: application/xml

<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"
  href="/ovirt-engine/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac">
    <name>data1</name>
    <link rel="permissions"
      href="/ovirt-engine/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/
      permissions"/>
    <link rel="files"
      href="/ovirt-engine/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/files"/>
    <type>data</type>
    <master>false</master>
    <storage>
        <type>nfs</type>
        <address>192.168.0.10</address>
        <path>/data1</path>
    </storage>
    <available>175019917312</available>
    <used>27917287424</used>
    <committed>10737418240</committed>
    <storage_format>v1</storage_format>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>

3.8. 示例:创建 NFS ISO 存储

NFS ISO 存储域是附加到数据中心挂载的 NFS 共享,并为 DVD/CD-ROM ISO 和虚拟软盘磁盘(VFD)镜像文件提供存储。创建新存储域需要 POST 请求,其中包含存储域表示,发送到存储域集合的 URL。
您可以在存储域中默认启用 wipe after delete 选项。要配置此功能,请在 POST 请求中指定 < wipe_after_delete >。可以在创建域后编辑此选项,但是这样做不会在删除已存在的磁盘属性后更改擦除。

例 3.8. 创建 NFS ISO 存储域

request:

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>iso1</name>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>192.168.0.10</address>
    <path>/iso1</path>
  </storage>
  <host>
    <name>hypervisor</name>
  </host>
</storage_domain>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>iso1</name><type>iso</type> \
    <storage><type>nfs</type><address>192.168.0.10</address> \
    <path>/iso1</path></storage> \
    <host><name>hypervisor</name></host></storage_domain>" \
    https://[RHEVM Host]:443/ovirt-engine/api/storagedomains

API 创建一个称为 iso1 的 NFS iso 存储域,其导出路径为 192.168.0.10:/iso1,并通过 虚拟机监控程序主机 访问存储域。API 也返回新创建的存储域资源的以下表示。

结果:

HTTP/1.1 200 OK
Accept: application/xml

<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
  href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da">
    <name>iso1</name>
    <link rel="permissions"
      href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
      permissions"/>
    <link rel="files"
      href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files"/>
    <type>iso</type>
    <host id="" href="">
    <master>false</master>
    <storage>
        <type>nfs</type>
        <address>192.168.0.10</address>
        <path>/iso1</path>
    </storage>
    <available>82678120448</available>
    <used>18253611008</used>
    <committed>0</committed>
    <storage_format>v1</storage_format>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">        
</storage_domain>

3.9. 示例:将存储域连接到数据中心

以下示例将 data1iso1 存储域附加到 Default 数据中心。

例 3.9. 将 data1 存储域附加到 Default 数据中心

request:

POST /ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>data1</name>
</storage_domain>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>data1</name></storage_domain>" \
    https://[RHEVM Host]:443/ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains

例 3.10. 将 iso1 存储域附加到 Default 数据中心

request:

POST /ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>iso1</name>
</storage_domain>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>iso1</name></storage_domain>" \
    https://[RHEVM Host]:443/ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains

这些 POST 请求将两个新的 storage_domain 资源放在 Default 数据中心的 storagedomains 子集合中。这意味着 storagedomains 子集合包含数据中心的附加存储域。

3.10. 示例:激活存储域

这个示例激活 Red Hat Virtualization Manager 使用的 data1iso1 存储域。

例 3.11. 激活 data1 存储域

request:

POST /ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
9ca7cb40-9a2a-4513-acef-dc254af57aac/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>" \
    https://[RHEVM Host]:443/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/activate

例 3.12. 激活 iso1 存储域

request:

POST /ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>"
    https://[RHEVM Host]:443/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate

这会激活两个存储域以用于数据中心。

3.11. 示例:创建虚拟机

以下示例将使用虚拟化环境的 Blank 模板作为基础,在 Default 集群上创建一个名为 vm1 的虚拟机。该请求还将 虚拟机的内存 定义为 512 MB,并将 引导设备 设置为虚拟硬盘。

例 3.13. 创建虚拟机

request:

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

<vm>
    <name>vm1</name>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <memory>536870912</memory> 
    <os>
        <boot dev="hd"/>
    </os>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os><cpu_profile id='0000001a-001a-001a-001a-00000000035e'/></vm>" https://[RHEVM Host]:443/ovirt-engine/api/vms

结果:

HTTP/1.1 200 OK
Accept: application/xml    

<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
  href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
    <name>vm1</name>
    <actions>
        <link rel="shutdown"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
        <link rel="start"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
        <link rel="stop"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
        <link rel="reboot"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/reboot"/>
        <link rel="suspend"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/>
        <link rel="detach"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/>
        <link rel="export"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/>
        <link rel="move"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/>
        <link rel="ticket"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/>
        <link rel="migrate"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/>
        <link rel="undo_snapshot"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/undo_snapshot"/>
        <link rel="commit_snapshot"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/commit_snapshot"/>
        <link rel="preview_snapshot"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/preview_snapshot"/>
        <link rel="logon"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/logon"/>
        <link rel="cancelmigration"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cancelmigration"/>
        <link rel="maintenance"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/maintenance"/>
        <link rel="clone"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/clone"/>
    </actions>
    <link rel="applications"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/applications"/>
    <link rel="disks"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/>
    <link rel="nics"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/>
    <link rel="cdroms"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/>
    <link rel="snapshots"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/>
    <link rel="tags"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/>
    <link rel="permissions"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/>
    <link rel="statistics"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/>
    <link rel="reporteddevices"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/reporteddevices"/>
    <link rel="watchdogs"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/watchdogs"/>
    <link rel="sessions"
      href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/sessions"/>
    <type>desktop</type>
    <status>
        <state>down</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os type="Unassigned">
        <boot dev="cdrom"/>
    </os>
    <high_availability>
        <enabled>false</enabled>
        <priority>0</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
        <single_qxl_pci>false</single_qxl_pci>
        <allow_override>false</allow_override>
        <smartcard_enabled>false</smartcard_enabled>
        <file_transfer_enabled>true</file_transfer_enabled>
        <copy_paste_enabled>true</copy_paste_enabled>
    </display>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"/>
    <stop_time>2011-06-15T04:48:02.167Z</stop_time>
    <creation_time>2011-06-15T14:48:02.078+10:00</creation_time>
    <origin>rhev</origin>
    <stateless>false</stateless>
    <delete_protected>false</delete_protected>
    <sso>
        <methods>
            <method id="GUEST_AGENT"/>
        </methods>
    </sso>
    <console enabled="false"/>
    <timezone>Etc/GMT</timezone>
    <initialization>
        <configuration>
            <type>ovf</type>
            <data>...</data>
        </configuration> 
    </initialization>
    <placement_policy>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>536870912</guaranteed>
        <ballooning>true</ballooning>
    </memory_policy>
    <usb>
        <enabled>false</enabled>
    </usb>
    <soundcard_enabled>true</soundcard_enabled>
    <migration_downtime>-1</migration_downtime>
    <virtio_scsi enabled="true"/>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
    <next_run_configuration_exists>false</next_run_configuration_exists>
    <numa_tune_mode>interleave</numa_tune_mode>
</vm>

3.12. 示例:创建虚拟机 NIC

以下示例创建一个虚拟网络接口,将示例虚拟机连接到 ovirtmgmt 网络。

例 3.14. 创建虚拟机 NIC

request:

POST /ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
  <interface>virtio</interface>
  <name>nic1</name>
  <network>
    <name>ovirtmgmt</name>
  </network>
</nic>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<nic><name>nic1</name><network><name>ovirtmgmt</name></network></nic>" \
    https://[RHEVM Host]:443/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics

3.13. 示例:创建虚拟机存储磁盘

以下示例为 example 虚拟机创建一个 8 GB Copy-On-Write 存储磁盘。

例 3.15. 创建虚拟机存储磁盘

request:

POST /ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"/>  
    </storage_domains>    
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<disk><storage_domains> \
    <storage_domain id='9ca7cb40-9a2a-4513-acef-dc254af57aac'/> \
    </storage_domains><size>8589934592</size><type>system</type> \
    <interface>virtio</interface><format>cow</format> \
    <bootable>true</bootable></disk>" \
    https://[RHEVM Host]:443/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks

storage_domain 元素告知 API 将磁盘存储在 data1 存储域中。

3.14. 示例:将 ISO 镜像附加到虚拟机

示例虚拟机的引导介质需要用于操作系统安装的 CD-ROM 或者 DVD ISO 镜像。这个示例使用 Red Hat Enterprise Server 6 ISO 镜像进行安装。
ISO 镜像必须在 iso1 ISO 域中可用,供虚拟机使用。Red Hat Virtualization Platform 提供了一个上传程序工具,用于确保 ISO 镜像以正确的用户权限上传到正确的目录路径中。
上传 ISO 后,API 用户请求 ISO 存储域 的文件 子集合来查看 file 资源:

例 3.16. 查看 ISO 存储域中的文件子集合

request:

GET /ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] \
    https://[RHEVM Host]:443/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files

API 返回文件子集合的以下表示:
<files>
    <file id="rhel-server-6.0-x86_64-dvd.iso"
      href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
      files/rhel-server-6.0-x86_64-dvd.iso.iso">
        <name>rhel-server-6.0-x86_64-dvd.iso.iso</name>
        <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>
API 用户将 rhel-server-6.0-x86_64-dvd.iso 附加到我们的 example 虚拟机。连接 ISO 镜像等同于使用管理门户中的 Change CD 按钮。

例 3.17. 将 ISO 镜像附加到虚拟机

request:

POST /ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cdrom>
  <file id="rhel-server-6.0-x86_64-dvd.iso"/>
</cdrom>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>" \
    https://[RHEVM Host]:443/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms

3.15. 示例:启动虚拟机

虚拟环境已完成,虚拟机包含所有必要的组件才能正常工作。这个示例使用 start 操作启动虚拟机。

例 3.18. 启动虚拟机

request:

POST /ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <vm>
    <os>
      <boot dev="cdrom"/>
    </os>
  </vm>
</action>

curl 命令:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action><vm><os><boot dev='cdrom'/></os></vm></action>" \
    https://[RHEVM Host]:443/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start

其他消息实体仅将虚拟机的引导设备设置为 CD-ROM。这可让虚拟机从附加的 ISO 镜像安装 Red Hat Enterprise Server 6。引导设备会恢复到 磁盘 以便以后进行所有引导。

3.16. 示例:检查系统事件

vm1start 操作会在 events 集合中创建多个条目。本例列出了事件集合,并标识特定于启动虚拟机的 API 的事件。

例 3.19. 列出事件集合

request:

GET /ovirt-engine/api/events HTTP/1.1
Accept: application/xml

curl 命令:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/ovirt-engine/api/events

结果:

<events>
    ...
    <event id="103" href="/ovirt-engine/api/events/103">
        <description>User admin logged out.</description>
        <code>31</code>
        <severity>normal</severity>
        <time>2011-06-29T17:42:41.544+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73" 
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="102" href="/ovirt-engine/api/events/102">
        <description>vm1 was started by admin (Host: hypervisor).</description>
        <code>153</code>
        <severity>normal</severity>
        <time>2011-06-29T17:42:41.499+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
        <vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
          href="/ovirt-engine/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"/>
        <host id="0656f432-923a-11e0-ad20-5254004ac988"
          href="/ovirt-engine/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"/>
    </event>
    <event id="101" href="/ovirt-engine/api/events/101">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-06-29T17:42:40.505+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    ...
</events>

发生以下事件:
  • id="101" - API 使用 admin 用户的用户名和密码进行身份验证。
  • ID="102" - 作为 admin 用户的 API,在 虚拟机监控程序 主机上启动 vm1
  • id="103" - API 注销 admin 用户帐户。

第 4 章 入口点

用户开始通过由 主机和 基础 组成的入口点 URI 上的 GET 请求与 API 交互。

例 4.1. 访问 API 条目点

如果主机是 www.example.com 且 基础 是 /ovirt-engine/api,则入口点会出现有以下请求:
GET /ovirt-engine/api HTTP/1.1
Accept: application/xml
Host: www.example.com
Authorization: [base64 encoded credentials]

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

<api>
    <link rel="hosts" href="/ovirt-engine/api/hosts"/>
    <link rel="vms" href="/ovirt-engine/api/vms"/>
    ...
    <product_info>
        <name>Red Hat Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="0" major="4"/>
    </product_info>    
    <special_objects>
        <link rel="templates/blank" href="..."/>
        <link rel="tags/root" href="..."/>
    </special_objects>
    <summary>
        <vms>
            <total>10</total>
            <active>3</active>
        </vms>
        <hosts>
            <total>2</total>
            <active>2</active>
        </hosts>
        <users>
            <total>8</total>
            <active>2</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</ovirt-engine/api>
注意
为简单起见,所有其他示例都省略 Host:Authorization: 请求标头,并假定 base 是默认的 /ovirt-engine/api 路径。这个基础路径根据您的实施而有所不同。

4.1. 产品信息

入口点包含一个 product_info 元素,用于帮助 API 用户决定 Red Hat Virtualization 环境的 legitimacy。这包括产品 的名称vendorversion

例 4.2. 验证 genuine Red Hat Virtualization 环境

以下元素标识了 Red Hat Virtualization 4.0 环境:
<api>
    ...
    <product_info>
        <name>Red Hat Virtualization</name>
        <vendor>Red Hat</vendor>
				<version>
						<build>2</build>
						<full_version>4.0.2.3-0.1.el7ev</full_version>
						<major>4</major>
						<minor>0</minor>
						<revision>0</revision>
				</version>
    </product_info>
    ...
</ovirt-engine/api>

4.3. 特殊对象元素

特殊对象元素定义在虚拟化环境中特殊固定资源的关系。
表 4.3. 特殊对象
关系 Description
templates/blank 虚拟化环境的默认 空白 虚拟机模板。此模板与每个集群中都存在,而不是标准的模板,该模板仅存在于单个集群中。
tags/root 作为虚拟化环境中标签层次结构的基础的 root 标签。

4.4. 摘要元素

summary 元素显示系统统计数据的高级摘要。
表 4.4. 摘要元素
元素 Description
vms 虚拟机总数和活动虚拟机总数.
主机 主机总数和活动主机总数。
users 用户总数和活动用户总数.
storage_domains 存储域总数和活跃存储域总数。

4.5. RESTful 服务描述语言(RSDL)

RESTful 服务描述语言(RSDL)提供了整个 XML 规范中 REST API 中的结构和元素的说明。使用以下请求调用 RSDL:
GET /ovirt-engine/api?rsdl HTTP/1.1
Accept: application/xml
这会以以下格式生成 XML 文档:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/ovirt-engine/api?rsdl" rel="rsdl">
    <description>...</description>
    <version major="4" minor="0" build="0" revision="0"/>
    <schema href="/ovirt-engine/api?schema" rel="schema">
        <name>...</name>
        <description>...</description>
    </schema>
    <links>
        <link href="/ovirt-engine/api/capabilities" rel="get">
            ...
        </link>
        ...
    </links>
</rsdl>
表 4.5. RSDL 结构元素
元素 Description
description RSDL 文档的纯文本描述。
version API 版本,包括 主发行版本次版本构建和 修订
schema XML 模式(XSD)文件的链接。
links 定义 API 中的每个 链接
每个 link 元素都包含以下结构:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/ovirt-engine/api?rsdl" rel="rsdl">
    ...
    <links>
        <link href="/ovirt-engine/api/..." rel="...">
            <request>
                <http_method>...</http_method>
                <headers>
                    <header>
                        <name>...</name>
                        <value>...</value>
                    </header>
                    ...
                </headers>
                <body>
                    <type>...</type>
                    <parameters_set>
                        <parameter required="..." type="...">
                            <name>...</name>
                        </parameter>
                        ...
                    </parameters_set>
                </body>
            </request>
            <response>
                <type>...</type>
            </response>
        </link>
        ...
    </links>
</rsdl>
表 4.6. RSDL 链接结构元素
元素 Description
link API 请求的 URI。包含 URI 属性(href)和关系类型属性(rel)。
request 定义链接所需的请求属性。
http_method 用于访问此链接的方法类型。包含用于 REST API 访问的标准 HTTP 方法: GETPOSTPUTDELETE
标头 定义 HTTP 请求的标头。包含一系列 标头 元素,它们各自包含用于定义标头的标头名称和值。
正文(body) 定义 HTTP 请求的正文。包含 资源类型和 parameter _set,它包含一组带有属性的参数元素,用于定义请求是否需要以及 数据类型参数 元素还包括一个 name 元素,用于定义 Red Hat Virtualization Manager 属性来修改以及进一步的 parameter_set 子集(如果 type 设置为 collection )。
response 定义 HTTP 请求的输出。包含 type 元素,用于定义要输出的资源结构。
使用应用程序中的 RSDL 作为映射控制 Red Hat Virtualization 环境的所有链接和参数要求的方法。

4.6. Red Hat Virtualization Windows Guest VSS 支持

Red Hat Virtualization Backup 和 Restore API 提供了使用 qemu-ga 与 Microsoft Windows Volume Shadow Copy Service (VSS)集成。VSS 提供程序注册在客户机级别上进行,作为客户机工具部署的一部分。
QEMU-ga 提供 VSS 支持和实时快照,尽可能尝试静止。

4.7. QEMU 客户机代理概述

在 Red Hat Enterprise Linux 6.4 中,QEMU 客户机代理(QEMU GA)为 Linux 客户机虚拟机的损坏提供了保护。在发出快照请求或创建磁盘备份副本之前,管理堆栈(libvirt)通过 virtio-serial 端口向 QEMU GA 发送 guest-fsfreeze-freeze QMP 命令。此命令通过 FIFREEZE ioctl() 内核功能导致客户机代理冻结所有客户虚拟机的文件系统。这个 ioctl() 功能是由客户端虚拟机中的 Linux 内核实现的。此函数清除客户机虚拟机内核中的文件系统缓存,使文件系统进入一致的状态,并拒绝所有用户空间线程对文件系统进行写入访问。
只有在 QEMU GA 报告成功后,libvirt 才会继续执行快照。完成后,libvirt 通过 virtio-serial 端口将 guest-fsfreeze-thaw QMP 命令发送到 QEMU GA。此命令告知 QEMU GA 发布 FITHAW ioctl (),它会取消阻止之前被拒绝的写入访问的用户空间线程,并恢复正常处理。当执行虚拟磁盘快照时,这个过程不会确保应用程序级别数据处于一致的状态。如果 fsck 实用程序从快照恢复了文件系统时没有发现问题,这很明显,但应用程序无法从拍摄快照的时间和用户空间进程时恢复处理,而用户空间进程可能没有将其内部缓冲区写入磁盘上的文件。
Red Hat Enterprise Linux 6.5 确保完成文件和应用程序级同步(清空)。客户机系统管理员可以编写和安装特定于应用程序的空闲和解放 hook 脚本。在冻结文件系统前,QEMU GA 会调用主 hook 脚本(包括在 QEMU GA 软件包中)。主钩子脚本反过调用各个应用特定脚本(由客户机系统管理员准备),该脚本会临时停用所有客户虚拟机应用程序。当模式更改为"冻结"时,所有这些操作都会发生。
在文件系统被冻结之前,客户机系统管理员的脚本会导致数据库和其他文件系统应用程序将其工作缓冲区刷新到虚拟磁盘,并停止接受进一步的客户端连接。然后,应用程序将其数据文件置于一致状态,在恢复处理时,使用重新激活(或全新启动)应用程序实例(从备份中恢复虚拟磁盘后)。当所有脚本都进行各自的应用程序不活跃时,主 hook 脚本返回时,QEMU GA 会进入冻结文件系统,管理堆栈会获取快照。完成所有操作后,并确认拍摄快照,文件系统将恢复以提供写入请求。这个过程被称为 thawing。
解封是以相反的顺序释放的。由 libvirt 的指示,QEMU GA 分解客户虚拟机的文件系统。然后,它会调用单独的钩子脚本(通过主 hook 脚本)恢复或重新启动在冻结过程中激活的应用程序。

4.8. VSS 事务流

在处理备份时,请求者和作者协调执行一些操作:提供稳定的系统镜像,以便从备份数据(影子复制卷)以分组文件,并在保存的数据上存储信息。这必须通过写入器的正常工作流的最小中断来完成。
请求者(在我们的备份供应商中)查询写入器获取其元数据,处理此数据,在影子副本和备份操作开始前通知写入器,然后在影子副本和备份操作结束时再次通知写入器。
以下是在 guest 工具安装后,QEMU VSS 供应商如何在 Windows OS 中注册:
C:\Users\Administrator>vssadmin list providers
vssadmin 1.1 - Volume Shadow Copy Service administrative command-line tool
(C) Copyright 2001-2005 Microsoft Corp.

Provider name: 'QEMU Guest Agent VSS Provider'
   Provider type: Software
   Provider Id: {3629d4ed-ee09-4e0e-9a5c-6d8ba2872aef}
   Version: 0.12.1

第 5 章 兼容性级别版本

连接到 Red Hat Virtualization Manager 的每个主机都包含 VDSM 版本。VDSM 是虚拟化基础架构中在虚拟机监控程序或主机上运行的代理,并为虚拟机、网络和存储提供本地管理。Red Hat Virtualization Manager 使用当前或更早版本的 VDSM 控制 hypervisor 和主机。
管理器将虚拟机从主机迁移到集群内的主机。这意味着,管理器从当前版本的 VDSM 中排除某些功能,直到集群中安装了相同的 VDSM 版本或最新的主机。
API 将这个概念表示为 每个主机的兼容性级别,对应于安装的 VDSM 版本。version 元素包含 主要和次要 属性,用于描述兼容性级别。
当管理员将集群中的所有主机升级到特定级别时,版本 级别会出现在 supported_versions 元素下。这表示 集群的版本 现在对那个级别是 updatable。当管理员将数据中心中的所有集群更新至给定级别后,数据中心就可以进入这个级别。

5.1. 升级兼容性等级

例 5.1. 升级兼容性级别

API 报告 Red Hat Enterprise Virtualization Manager 3.4 实例的以下兼容性级别:
<host ...>
    ...
    <version major="4" minor="14" build="11" revision="0" full_version="vdsm-4.14.11-5.el6ev"/>
    ...
</host>

<cluster ...>
    ...
    <version major="3" minor="4"/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="4"/>
    </supported_versions>
    ...
</data_center>

集群中的所有主机都更新至 VDSM 3.5 和 API 报告:
<host ...>
    ...
    <version major="4" minor="16" build="7" revision="4" full_version="vdsm-4.16.7.4-1.el6ev"/>
    ...
</host>

<cluster ...>
    ...
    <version major="3" minor="4"/>
    <supported_versions>
        <version major="3" minor="5"/>
    </supported_versions>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="4"/>
    <supported_versions/>
    ...
</data_center>
集群现在最多为 3.5。更新集群时,API 报告:
<cluster ...>
    ...
    <version major="3" minor="5"/>
    <supported_versions/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="4"/>
    <supported_versions>
        <version major="3" minor="5"/>
    </supported_versions>
    ...
</data_center>
API 用户将数据中心更新为 3.5。升级后,API 会公开此数据中心的 Red Hat Enterprise Virtualization 3.5 中提供的功能。

第 6 章 功能

capabilities 集合提供有关 Red Hat Virtualization 支持的功能信息。这些功能包括活动的功能,以及特定属性的可用枚举值。
要从 3.2 检索所有版本的 Red Hat Enterprise Virtualization 功能的完整列表,请提交以下请求:
GET /ovirt-engine/api/capabilities/ HTTP/1.1
Content-Type: application/xml
Accept: application/xml

6.1. version-Dependent Capabilities

capabilities 元素包含各种 版本 元素,它们描述功能依赖于兼容性级别。
version 元素包括 主版本和次版本 号的属性。这表示当前版本级别。
以下表示显示特定于 Red Hat Enterprise Virtualization Manager 3.53.64.0 的功能:
<capabilities>
    <version major="3" minor="5">
        ...
    </version>
    <version major="3" minor="6">
        ...
    </version>
    <version major="4" minor="0">
        ...
    </version>
    ...
</capabilities>
每个版本都 包含一系列功能,具体取决于指定的版本。

6.2. 当前版本

当前 元素表示 指定的版本 是最新支持的兼容性级别。该值是一个布尔值 truefalse
<capabilities>
    <version major="4" minor="0">
        ...
        <current>true</current>
        ...
    </version>
</capabilities>

6.3. 功能

每个版本都包含兼容功能列表。下表列出了与 Red Hat Virtualization 4.0 兼容的功能。
表 6.1. 功能类型
功能 Description
透明大内存页内存策略 允许您为主机定义透明巨页的可用性。可接受值为 truefalse
Gluster 支持 此功能提供对将 Gluster 卷和 Bricks 用作存储的支持。
POSIX-FS 存储类型 此功能提供对 POSIX-FS 存储类型的支持。
端口镜像 允许您为虚拟网络接口卡定义端口镜像的可用性。可接受值为 truefalse
显示服务器时间 API 中显示当前日期和时间。
显示主机内存 显示特定主机的总内存。
显示主机套接字 允许您定义主机 CPU 的拓扑。取三个属性 - 套接字线程 和内核 - 定义显示的主机套接字数量、线程数和每个插槽的内核数。
搜索问题单敏感度 允许您通过提供 case-sensitive=true|false URL 参数来指定搜索查询是否区分大小写。
GET 请求的最大结果 允许您指定从 GET 请求返回的最大结果数。
JSON 内容类型 允许您定义一个标头,使它能够为 POSTPUT 请求设置关联 ID。
激活和取消激活磁盘 允许您在特定虚拟磁盘上指定 激活或取消激活 作为操作来激活或取消激活磁盘。
激活和停用网络接口卡 允许您指定激活或停用特定网卡上的操作,来 激活或取消激活 网卡。
快照重构 允许您为虚拟机重构快照。
从指定的存储域中删除模板磁盘 允许您使用 DELETE 请求从特定存储域中删除虚拟机模板磁盘。
浮动磁盘 浮动磁盘是未附加到任何虚拟机的磁盘。借助此功能,此类磁盘也会出现在 root 集合中,而不是在特定的虚拟机中。
异步删除 允许您指定通过指定 async URL 参数来异步执行 DELETE 请求。
基于会话的身份验证 允许您通过提供适当的标头来维护客户端-服务器会话,无需使用每个请求登录。
虚拟机应用程序 允许您查看在特定虚拟机上安装的应用程序列表。此列表位于特定虚拟机的 apps 元素中。
virtio-SCSI 支持 此功能提供对半虚拟化 SCSI 控制器设备的支持。
自定义资源注释 允许您在数据中心和其他资源中添加自定义注释。
刷新主机功能 允许您同步主机上的数据,并刷新可用于特定主机的网络接口列表。
内存快照 允许您包含内存状态作为虚拟机快照的一部分。
watchdog 设备 允许您为虚拟机创建 watchdog 设备。
SSH 验证方法 允许您使用管理用户密码或 SSH 公钥通过 SSH 使用主机进行身份验证。
强制选择 SPM 允许您强制选择主机作为 SPM
控制台设备 允许您控制虚拟机中的控制台设备的附加。
存储域的存储服务器连接 允许您查看到特定存储域或特定存储域的存储服务器连接。
附加和分离存储服务器连接 允许您向特定存储域附加或分离存储服务器连接。
单个 PCI 用于 Qxl 允许您通过单一 PCI 客户机设备查看多个视频设备。
OVF 配置添加虚拟机 允许您从提供的 OVF 配置中添加虚拟机。
虚拟网络接口卡配置集 允许您配置一个配置集,为特定虚拟网络接口卡定义服务质量、自定义属性和端口镜像。
镜像存储域(技术预览) 允许您从镜像导入镜像,并将其导出到 OpenStack 镜像服务(Glance)等镜像存储域。
虚拟机完全限定域名 允许您检索特定虚拟机的完全限定域名。
将磁盘快照附加到虚拟机 此功能支持将磁盘快照附加到虚拟机。
Cloud-Init 允许您使用 Cloud Init 初始化虚拟机。
Gluster brick 管理 允许您使用操作 migrateDELETE 删除带有数据迁移的 gluster brick。migrate 操作和 stopmigrate 操作允许您迁移数据并重复利用 brick。
复制和移动后端磁盘 允许您在额外上下文中复制和移动磁盘。
网络标签 允许您使用标签在主机上调配网络。
重启虚拟机 允许您通过单一操作重新引导虚拟机。
功能元素及其属性的完整列表位于相关版本的部分的顶部:
<capabilities>
    <version major="4" minor="0">
        ...
        <features>
            <feature>
            	<name>Transparent-Huge-Pages Memory Policy</name>
            	<transparent_huepages/>
            </feature>
        </features>
        ...
    </version>
</capabilities>

第 7 章 常见功能

7.1. 元素属性图标

备注
在本指南中,每个资源的元素在表格中详细介绍。这些表包含一个 properties 列,显示图标描述元素属性。这些图标的含义在 表 7.1 “元素属性图标” 中显示。
表 7.1. 元素属性图标
属性 Description 图标
创建所需 这些元素必须包含在创建资源的客户端提供的表示中,但更新资源时并不是必须的。
non-updatable 这些元素在更新资源时无法更改它们的值。只有在 API 用户没有更改其值时,仅在更新的客户端提供表示中包括这些元素。如果更改,API 会报告错误。
只读 这些元素是只读的。只读元素的值不会被创建或修改。

7.2. 表示

7.2.1. 表示

以下 XML 文档结构中的 API 结构资源表示:
<resource id="resource_id" href="/ovirt-engine/api/collection/resource_id">
    <name>Resource-Name</name>
    <description>A description of the resource</description>
    ...
</resource>
在虚拟机上下文中,表示如下所示:
<vm id="5b9bbce5-0d72-4f56-b931-5d449181ee06"
  href="/ovirt-engine/api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
    <name>RHEL6-Machine</name>
    <description>Red Hat Enterprise Linux 6 Virtual Machine</description>
    ...
</vm>

7.2.2. 资源代表的常见属性

所有资源表示都包含一组通用属性
表 7.2. 资源表示法的通用属性
属性 类型 Description Properties
id GUID 虚拟化基础架构中的每个资源都包含一个 id,它充当全局唯一标识符(GUID)。GUID 是资源识别的主要方法。
href 字符串 资源规范位置作为绝对路径。

7.2.3. 到资源代表的常见元素

所有资源表示都包含一组通用元素。
表 7.3. 资源表示的常见元素
元素 类型 Description Properties
name 字符串 用户提供的人类可读名称。名称 在其类型的所有资源中是唯一的。
description 字符串 由用户提供的、自由格式的人类可读描述。 

7.3. 集合

7.3.1. 集合

集合是一组相同类型的资源。API 提供顶层集合和子集合。顶级集合的示例是包含环境中所有虚拟化主机的 主机集合。子集合的示例是 host.nics 集合,其中包含附加到主机资源的所有网络接口卡的资源。

7.3.2. 列出集合中的所有资源

在从入口点获取的集合 URI 上,获取集合中带有 GET 请求的资源列表。
包括一个 Accept HTTP 标头来为响应格式定义 MIME 类型。
GET /ovirt-engine/api/[collection] HTTP/1.1
Accept: [MIME type]

7.3.3. 列出扩展的资源子-Collections

Accept 标头包含 detail 参数时,API 会扩展集合表示法,使其包含子集合。
GET /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml; detail=subcollection
这包括使用任一独立 详情 参数的多个子集合请求:
GET /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2
或者一个将子集合与 + operator 分隔的 detail 参数:
GET /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
API 支持下列主要集合的扩展子集合:
表 7.4. 使用扩展子集合的集合
集合 延长的子组件支持
主机 statistics
vms 统计信息,nics,磁盘

例 7.1. vms 集合中扩展统计、NIC 和磁盘子集合的请求

GET /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks

7.3.4. 使用 Queries 搜索集合

"collection/search" 链接上的 GET 请求会导致该集合的搜索查询。API 仅返回满足搜索查询约束的集合中的资源。
GET /ovirt-engine/api/collection?search={query} HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>

7.3.5. 最大结果参数

使用 max URL 参数来限制结果列表。没有指定 max 参数的 API 搜索查询将返回所有值。建议指定 max 参数,以防止 API 搜索查询减慢 UI 性能。
GET /ovirt-engine/api/collection;max=1 HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
</collection>

7.3.6. case Sensitivity

所有搜索查询默认为区分大小写。URL 语法提供了一个布尔值选项,用于切换问题单敏感度。

例 7.2. 不区分大小写的搜索查询

GET /ovirt-engine/api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml

7.3.7. 查询语法

API 使用 URI 模板来执行带有 GET 请求的搜索查询:
GET /ovirt-engine/api/collection?search={query} HTTP/1.1
Accept: application/xml
query 模板值引用 API 定向到 集合的 搜索查询。这个 查询 使用与 Red Hat Virtualization Query Language 相同的格式:
(criteria)[sortby (element) asc|desc]
sortby 子句是可选的,仅在排序结果时才需要。
表 7.5. 搜索查询示例
集合 标准 结果
主机 vms.status=up 显示所有运行状态为 up 的虚拟机的主机的列表。
vms domain=qa.company.com 显示在指定域中运行的所有虚拟机的列表。
vms users.name=mary 显示属于用户名为 mary 的所有虚拟机的列表。
events severity> 常规排序时间 显示所有严重性高于 normal 的事件 的列表,并根据 time element 值进行排序。
events severity>normal sortby time desc 显示所有严重性高于 normal事件列表,并按 时间 元素值降序排列。
API 要求 查询 模板为 URL 编码,才能转换保留字符,如 operators 和空格。

例 7.3. URL 编码的搜索查询

GET /ovirt-engine/api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml

7.3.8. 通配符

搜索查询将值的一部分替换为星号作为通配符。

例 7.4. name=vm* 的通配符搜索查询

GET /ovirt-engine/api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
此查询将生成名称以 vm 开头的所有虚拟机,如 vm 1、vm2、 vm avm-webserver

例 7.5. name=v*1 的通配符搜索查询

GET /ovirt-engine/api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml
此查询将生成名称以 v 开头的所有虚拟机,并以 1 结尾,如 vm1、vr1 virtualmachine1

7.3.9. 分页

一些 Red Hat Virtualization 环境包含大量资源集合。但是,API 仅显示一个对集合搜索查询的默认资源数量。要显示多于默认值,API 通过包含 page 命令的搜索查询将集合分开到 页面中

例 7.6. 分页资源

这个示例在集合中分页资源。URL 编码的请求为:
GET /ovirt-engine/api/collection?search=page%201 HTTP/1.1
Accept: application/xml
增加 page 值以查看结果的下一页:
GET /ovirt-engine/api/collection?search=page%202 HTTP/1.1
Accept: application/xml
在搜索查询中使用 page 命令和其他命令。例如:
GET /ovirt-engine/api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml
此查询在由所选元素排序的集合列表中显示第二个页面。
重要的
REST API 是无状态的;因此无法在不同请求之间保持状态,因为所有请求都相互独立。因此,如果您的请求间更改了状态,则页面结果可能是不一致的。
例如,如果您从虚拟机列表请求特定页面,且在请求下一页前发生状态更改,那么您的结果可能会缺少条目或包含重复的条目。

7.3.10. 在集合中创建资源

使用 POST 请求创建新资源到集合 URI,其中包含新资源的表示。
POST 请求需要 Content-Type 标头。这会通知正文内容中表示 MIME 类型的 API 作为请求的一部分。
包括一个 Accept HTTP 标头来为响应格式定义 MIME 类型。
每个资源类型都有自己的特定必要属性。客户端在创建新资源时提供这些属性。如需了解更多详细信息,请参阅单独的资源类型文档。
如果没有所需的属性,则创建会失败,并显示指示缺失元素的表示。
POST /ovirt-engine/api/[collection] HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]

7.3.11. 异步请求

API 执行异步 POST 请求,除非用户用 Expect: 201-created 标头覆盖它们。
例如,某些资源(如虚拟机、磁盘、快照和模板)会异步创建。创建异步资源的请求会导致 202 Accepted 状态。202 Accepted 资源的初始文档结构还包含 creation_status 元素和创建状态更新的链接。例如:
POST /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <name>Resource-Name</name>
</resource>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<resource id="resource_id" href="/ovirt-engine/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/ovirt-engine/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>
creation_status 链接的 GET 请求提供创建状态更新:
GET /ovirt-engine/api/collection/resource_id/creation_status/creation_status_id HTTP/1.1
Accept: application/xml

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

<creation id="creation_status_id"
  href="/ovirt-engine/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>
覆盖异步资源创建需要一个 Expect: 201-created 标头:
POST /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<resource>
    <name>Resource-Name</name>
</resource>

7.4. Resources

7.4.1. Resources

资源是 RESTful Web 服务中的数据源。每种资源类型包含一组常见参数,REST API 抽象以形成 资源表示,通常采用 XML 或 JSON。用户可以查看资源表示,然后编辑参数,并将表示返回至 API 中的资源 URL,以修改资源。用户还可以通过 REST 删除单个资源。
RESTful Web 服务还会将资源分组到 集合中。用户可以查看集合中所有资源的表示。用户还会向特定集合发送资源表示,以便在该特定集合中创建新资源。

7.4.2. 检索资源

在从集合列表中获取的 URI 上通过 GET 请求获取资源状态。
包括一个 Accept HTTP 标头来为响应格式定义 MIME 类型。
GET /ovirt-engine/api/[collection]/[resource_id] HTTP/1.1
Accept: [MIME type]
您可以使用 All-Content: true 标头从某些资源获取更多信息。RESTful 服务描述语言描述了哪个链接支持此标头。
GET /ovirt-engine/api/[collection]/[resource_id] HTTP/1.1
Accept: [MIME type]
All-Content: true

7.4.3. 更新资源

使用 PUT 请求修改资源属性,其中包含之前 GET 请求中针对资源 URI 更新的描述。有关可修改属性的详情,请参考单独的资源类型文档。
PUT 请求需要 Content-Type 标头。这会通知正文内容中表示 MIME 类型的 API 作为请求的一部分。
包括一个 Accept HTTP 标头来为响应格式定义 MIME 类型。
PUT /ovirt-engine/api/collection/resource_id HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]
这不包括 API 用户尝试修改的不可变资源属性。如果尝试修改 严格的不可变资源属性,API 会报告与响应正文中的错误消息表示冲突。
在表示中省略的属性将被忽略,且不会更改。

7.4.4. 删除资源

删除使用发送到其 URI 的 DELETE 请求的资源。
包括一个 Accept HTTP 标头来为响应格式定义 MIME 类型。
DELETE /ovirt-engine/api/[collection]/[resource_id] HTTP/1.1
Accept: [MIME type]
有些情况需要 DELETE 请求中的可选正文内容来指定额外的属性。带有可选正文内容的 DELETE 请求需要 Content-Type 标头来通知正文内容中表示 MIME 类型的 API。如果 DELETE 请求不包含正文内容,请省略 Content-Type 标头。

7.4.5. sub-Collection relationships

子集合关系定义资源和子集合之间的分层链接。子集合存在,或者在父资源上下文中有一些含义。例如,虚拟机包含网络接口,这意味着 API 映射虚拟机资源和网络接口子集合之间的关系。
子集合用于对以下关系类型建模:
  • 一个父资源可以包含多个子资源,反之亦然。例如,虚拟机可以包含多个磁盘,一些磁盘由多个虚拟机共享。
  • 映射的资源依赖于父资源。如果没有父资源,则依赖的资源不存在。例如,虚拟机和快照之间的链接。
  • 其中映射的资源独立于父资源存在,但数据仍然与关系关联。例如,集群和网络之间的链接。
API 使用 link rel= 属性定义资源和子集合之间的关系:
GET /ovirt-engine/api/collection/resource_id HTTP/1.1
Accept: application/xml

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

<resource id="resource_id" href="/ovirt-engine/api/collection/resource_id">
    ...
    <link rel="subcollection"
      href="/ovirt-engine/api/collection/resource_id/subcollection"/>
    ...
</resource>
API 用户现在查询 sub-collection。
GET /ovirt-engine/api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml

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

<subcollection>
    <subresource id="subresource_id"
      href="/ovirt-engine/api/collection/resource_id/subcollection/subresource_id">
        ...
    </subresource>
    ...
</subcollection>

7.4.6. XML 元素关系

XML 元素链接充当子集合的替代选择,以表达资源之间的关系。XML 元素链接只是包含指向链接元素的"href"属性的元素。
XML 元素链接用于对资源间的简单 1:N 映射,而无需依赖项,且没有与关系关联的数据。例如,主机和集群之间的关系。
这种关系的示例包括:
  • 从子集合中的资源重新链接到父资源;或者
  • 具有任意关系的资源之间的链接。

例 7.7. 使用 XML 元素将子集合资源链接到资源

GET /ovirt-engine/api/collection/resource_id/subcollection/subresource_id HTTP/1.1

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

<subcollection>
    <subresource id="subresource_id"
      href="/ovirt-engine/api/collection/resource_id/subcollection/subresource_id">
        <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/>
        ...
    </subresource>
</subcollection>

7.4.7. Actions

大多数资源都包括一种操作链接,用于提供不是通过标准 HTTP 方法实现的功能。
<resource>
    ...
    <actions>
        <link rel="start" href="/ovirt-engine/api/collection/resource_id/start"/>
        <link rel="stop" href="/ovirt-engine/api/collection/resource_id/stop"/>
        ...
    </actions>
    ...
</resource>
API 通过 POST 请求调用提供的 URI 的操作。POST 正文需要一个 操作 表示封装通用和任务特定参数。
表 7.6. 常见操作参数
元素 Description
async 如果服务器 立即响应使用 202 Accepted,且操作表示包含 href 链接,则需要轮询完成。
grace_period 以毫秒为单位的宽限期,必须在启动操作前过期。
各个操作及其参数记录在单独的资源类型的文档中。某些参数对于具体操作来说是必需的,它们没有表示有故障 响应
操作还需要 Content-Type: application/xml 标头,因为 POST 请求需要在正文内容中有一个 XML 表示。
当异步启动该操作时,立即 202 Accepted 响应提供一个链接来监控任务的状态:
POST /ovirt-engine/api/collection/resource_id/action HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<action>
    <async>true</async>
</action>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<action id="action_id"
  href="/ovirt-engine/api/collection/resource_id/action/action_id">
    <async>true</async>
    ...
</action>
操作 URI 上的后续 GET 提供异步任务的状态。
表 7.7. 操作状态
状态 Description
待定 任务尚未启动。
in_progress 任务处于操作状态。
complete 任务成功完成。
失败 任务失败。返回的 操作 表示会包含 描述 失败的错误。
任务完成后,会在确定周期内保留该操作。过期后,后续的 GETs 为 301 movesd Permanently 重新重定向到目标资源。
GET /ovirt-engine/api/collection/resource_id/action/action_id HTTP/1.1
Accept: application/xml

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

<action id="action_id"
  href="/ovirt-engine/api/collection/resource_id/action/action_id">
    <status>
        <state>pending</state>
    </status>
    <link rel="parent" /ovirt-engine/api/collection/resource_id"/>
    <link rel="replay" href="/ovirt-engine/api/collection/resource_id/action"/>
</action>
操作表示还包括一些由 rel 属性标识的链接:
表 7.8. 操作关系
类型 Description
parent 这个操作的资源的链接。
replay 到原始操作 URI 的链接。发布到此 URI 会导致重新发起操作。

7.4.8. 权限

每个资源都包含 权限 子集合。每个 权限都 包含用户、分配 的角色和 指定资源。例如:
GET /ovirt-engine/api/collection/resource_id/permissions HTTP/1.1
Accept: application/xml

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

<permissions>
    <permission id="permission-id"
      href="/ovirt-engine/api/collection/resource_id/permissions/permission_id">
        <role id="role_id" href="/ovirt-engine/api/roles/role_id"/>
        <user id="user_id" href="/ovirt-engine/api/users/user_id"/>
        <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/>
    </permission>
    ...
</permissions>
当 API 用户使用权限表示和 Content-Type: application/xml 标头向 资源的权限 子集合发送 POST 请求时,资源会获取新权限。每个新权限都需要一个 角色 和用户
POST /ovirt-engine/api/collection/resource_id/permissions HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<permission>
    <role id="role_id"/>
    <user id="user_id"/>
</permission>

HTTP/1.1 201 Created
Content-Type: application/xml

<permission id="permission_id"
  href="/ovirt-engine/api/resources/resource_id/permissions/permission_id">
    <role id="role_id" href="/ovirt-engine/api/roles/role_id"/>
    <user id="user_id" href="/ovirt-engine/api/users/user_id"/>
    <resource id="resource_id" href="/ovirt-engine/api/collection/resource_id"/>
</permission>

7.4.9. 处理错误

除了标准 HTTP 状态代码外,有些错误需要进一步解释。例如,API 报告资源状态更新失败,或者响应实体正文中带有错误表示的操作。故障包含 原因 和详细 字符串。根据响应状态代码,客户端必须通过提取 错误或 预期的资源表示来容纳失败的请求。此类情况在单独的资源文档中明确指明。
PUT /ovirt-engine/api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <id>id-update-test</id>
</resource>

HTTP/1.1 409 Conflict
Content-Type: application/xml

<fault>
    <reason>Broken immutability constraint</reason>
    <detail>Attempt to set immutable field: id</detail>
</fault>

第 8 章 备份和恢复 API

备份和恢复 API 是一个功能集合,允许您对虚拟机执行完整或文件级备份和恢复。API 结合了 Red Hat Virtualization 的多个组件,如实时快照和 REST API,用于创建和处理可附加到包含独立软件供应商提供的备份软件的临时卷。
有关支持的第三方备份供应商,请参阅 Red Hat Virtualization 生态系统

8.1. 备份虚拟机

使用备份和恢复 API 备份虚拟机。此流程假设您有两个虚拟机:要备份的虚拟机,以及安装用于管理备份的软件的虚拟机。

过程 8.1. 备份虚拟机

  1. 使用 REST API 创建虚拟机的快照来备份:
    POST /ovirt-engine/api/vms/11111111-1111-1111-1111-111111111111/snapshots/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <snapshot>
        <description>BACKUP</description>
    </snapshot>
    注意
    当您对虚拟机执行快照时,生成快照时虚拟机的配置数据副本将存储在快照下的 初始化时,配置属性的 data 属性中。
    重要
    您不能获取标记为可共享或者基于直接 LUN 磁盘的磁盘快照。
  2. 从快照下的 data 属性检索虚拟机的配置数据:
    GET /ovirt-engine/api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
  3. 识别快照的磁盘 ID 和快照 ID:
    GET /ovirt-engine/api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111/disks HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
  4. 将快照附加到备份虚拟机并激活磁盘:
    POST /ovirt-engine/api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <disk id="11111111-1111-1111-1111-111111111111">
        <snapshot id="11111111-1111-1111-1111-111111111111"/>
        <active>true</active>
    </disk>
    
  5. 使用备份虚拟机上的备份软件备份快照磁盘中的数据。
  6. 从备份虚拟机中分离快照磁盘:
    DELETE /ovirt-engine/api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <action>
        <detach>true</detach>
    </action>
    
  7. 另外,还可删除快照:
    DELETE /ovirt-engine/api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
已使用在独立虚拟机上安装的备份软件,以固定时间点备份虚拟机状态。

8.2. 恢复虚拟机

恢复使用备份和恢复 API 备份的虚拟机。此流程假设您有一个备份虚拟机,在其中安装用于管理之前备份的软件。

过程 8.2. 恢复虚拟机

  1. 将磁盘附加到备份虚拟机:
    POST /ovirt-engine/api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <disk id="11111111-1111-1111-1111-111111111111">
    </disk>
    
  2. 使用备份软件将备份恢复到磁盘。
  3. 从备份虚拟机中分离磁盘:
    DELETE /ovirt-engine/api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <action>
        <detach>true</detach>
    </action>
    
  4. 使用正在恢复的虚拟机的配置数据创建新虚拟机:
    POST /ovirt-engine/api/vms/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <vm>
        <cluster>
            <name>cluster_name</name>
        </cluster>
        <name>NAME</name>
        ...
    </vm>
  5. 将磁盘附加到新虚拟机:
    POST /ovirt-engine/api/vms/33333333-3333-3333-3333-333333333333/disks/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <disk id="11111111-1111-1111-1111-111111111111">
    </disk>
    
您已使用备份和恢复 API 创建的备份恢复虚拟机。

第 9 章 数据中心

9.1. 数据中心元素

datacenters 集合提供有关 Red Hat Virtualization 环境中数据中心的信息。API 用户通过从入口点 URI 获取的 rel="datacenters" 链接访问此信息。
下表显示了数据中心资源表示法中包含的特定元素。
表 9.1. 数据中心元素
元素 类型 Description Properties
name 字符串 数据中心的纯文本、人类可读名称。该名称在 所有数据中心资源中是唯一的。
description 字符串 数据中心的纯文本、人类可读的描述  
link rel="storagedomains" 关系 附加到此数据中心的存储域的子集合。 
link rel="clusters" 关系 附加到此数据中心的集群的子集合链接。 
link rel="networks" 关系 到子集合(用于可用于此数据中心的网络)的链接。 
link rel="permissions" 关系 到数据中心权限的子集合的链接。 
link rel="quotas" 关系 到与此数据中心关联的配额的子集合的链接。 
local 布尔值: true 或 false 指定数据中心是一个本地数据中心,如在 all-in-one 实例中创建。
storage_format Enumerated 描述数据中心的存储格式版本。功能 中提供了枚举的值的列表。
version major= minor= complex 数据中心的兼容性级别。
supported_versions complex 数据中心可能的版本级别列表,包括 版本 major= minor=
mac_pool 字符串 与数据中心关联的 MAC 地址池。如果没有指定 MAC 地址池,则使用默认的 MAC 地址池。
status 请参见以下 数据中心状态。
该状态 包含以下枚举的值之一: 未初始化upmaintenancenot_operationalproblematiccontend。这些状态列在 capabilities 下的 data_center_states 中。

9.2. 数据中心的 XML 表述

例 9.1. 数据中心的 XML 表示

<data_center href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/storagedomains" rel="storagedomains"/>
  <link href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/networks" rel="networks"/>
  <link href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/quotas" rel="quotas"/>
  <local>false</local>
  <storage_format>v3</storage_format>
  <version major="4" minor="0"/>
  <supported_versions>
    <version major="4" minor="0"/>
  </supported_versions>
  <status>
    <state>up</state>
  </status>
  <mac_pool href="/ovirt-engine/api/macpools/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
</data_center>

9.3. 数据中心的 JSON 表

例 9.2. 数据中心的 JSON 表示

{
  "data_center" : [ {
    "local" : "false",
    "storage_format" : "v3",
    "version" : {
      "major" : "4",
      "minor" : "0"
    },
    "supported_versions" : {
      "version" : [ {
        "major" : "4",
        "minor" : "0"
      } ]
    },
    "status" : {
      "state" : "up"
    },
    "mac_pool":
            {
                "href": "/ovirt-engine/api/macpools/00000000-0000-0000-0000-000000000000",
                "id": "00000000-0000-0000-0000-000000000000"
            },
    "name" : "Default",
    "description" : "The default Data Center",
    "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255",
    "id" : "00000002-0002-0002-0002-000000000255",
    "link" : [ {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/storagedomains",
      "rel" : "storagedomains"
    }, {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/clusters",
      "rel" : "clusters"
    }, {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/networks",
      "rel" : "networks"
    }, {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/quotas",
      "rel" : "quotas"
    }, {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/iscsibonds",
      "rel" : "iscsibonds"
    }, {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255/qoss",
      "rel" : "qoss"
    } ]
  } ]
}

9.4. Methods

9.4.1. 创建新数据中心

创建新数据中心需要 namelocal 元素。

例 9.3. 创建数据中心

POST /ovirt-engine/api/datacenters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>NewDatacenter</name>
    <local>false</local>
</data_center>

9.4.2. 更新数据中心

名称,description,storage_type,version,storage_formatmac_pool 元素在创建后是 updatable。

例 9.4. 更新数据中心

PUT /ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>UpdatedName</name>
    <description>An updated description for the data center</description>
</data_center>

9.4.3. 删除数据中心

删除数据中心需要 DELETE 请求。

例 9.5. 删除数据中心

DELETE /ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

9.5. sub-Collections

9.5.1. Storage Domains Sub-Collection

9.5.1.1. Storage Domains Sub-Collection
每个数据中心包含一个附加存储域的子集合。API 用户使用标准的 REST 方法与此子集合交互。
连接的存储域与顶级存储域类似,但有一个特定于数据中心的 状态和 一组操作。status 元素的状态列在 capabilities 下的 storage_domain_states 中。
重要的
如本节所述的 API 是实验性的,可能随时更改。它不包含在向后兼容声明中。
9.5.1.2. 附加和分离存储域
数据中心仅在至少附加一个存储域时使用,API 用户 POST到数据中心的存储域子集合。
在附加存储域时,必须提供其 idname。将存储域附加到数据中心的示例:

例 9.6. 将存储域附加到数据中心

POST /ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>

HTTP/1.1 201 Created
Location: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
  fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>images0</name>
    <type>data</type>
    <status>
        <state>inactive</state>
    </status>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <actions>
        <link rel="activate"
          href="/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
        <link rel="deactivate"
          href="/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
    </actions>
</storage_domain>
使用 DELETE 请求从数据中心分离存储域。包括一个可选的 async 元素,此请求是异步的。

例 9.7. 将存储域从数据中心分离

DELETE /ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <async>true</async>
</action>
9.5.1.3. Actions
9.5.1.3.1. 激活存储域操作
使用前,连接的存储域需要在数据中心上激活。激活操作不会采取任何具体操作的参数。

例 9.8. 在数据中心上激活存储域的操作

POST /ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
9.5.1.3.2. 取消激活存储域操作
在删除前,在数据中心上取消激活附加的存储域。deactivate 操作不会采取任何具体操作的参数。

例 9.9. 停用数据中心的存储域的操作

POST /ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

9.5.2. 网络 Sub-Collection

9.5.2.1. 网络子注入
与数据中心关联的网络通过网络子集合表示。数据中心的 网络 子集合的表示包含以下元素:
表 9.2. 网络元素
元素 类型 描述
name 字符串 网络的纯文本,人类可读的名称。
description 字符串 网络的纯文本、人类可读的描述。
rel="permissions" 关系 网络权限 子集合的链接。
rel="vnicprofiles" 关系 到网络的 vnicprofiles 子集合的链接。
rel="labels" 关系 到网络 的标签 子集合的链接。
data_center id= 关系 对网络所属的数据中心的引用。
stp 布尔值: true 或 false 指定是否为网络启用跨树协议。
mtu 整数 指定网络的最大传输单元。
usages complex 定义网络的一组 使用 元素。用户可以将网络定义为 vm,并在此级别上 显示网络
在 REST API 中,您可以使用标准的 REST 方法操作 网络 子集合。例如,POST 方法可用于更新网络 ID 或名称

例 9.10. 将网络资源与数据中心关联

POST /ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>ovirtmgmt</name>
</network>

HTTP/1.1 201 Created
Location: http://{host}/clusters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000
Content-Type: application/xml

<network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000">
  <name>Network_001</name>
  <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/permissions"
    rel="permissions"/>
  <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/vnicprofiles"
    rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/labels"
    rel="labels"/>
  <data_center href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000"/>
  <stp>false</stp>
  <mtu>0</mtu>
  <usages>
    <usage>vm</usage>
  </usages>
</network>
使用 PUT 请求更新资源。网络的最大传输单元使用 PUT 请求来设置,以指定 mtu 元素的整数值。

例 9.11. 设置网络最大传输单元

PUT /ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <mtu>1500</mtu>
</network>
将关联与 DELETE 请求删除到集合中适当的元素。

例 9.12. 从数据中心中删除网络关联

DELETE /ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

9.5.3. Quota Sub-Collection

9.5.3.1. Quota Sub-Collection
配额子集合列出了 Red Hat Virtualization Manager 对资源实施的限制。API 用户使用 GET 方法查看此子集合及其资源。

例 9.13. 配额的 XML 表示

<quota href="/ovirt-engine/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c
  /quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe" 
  id="e13ff85a-b2ba-4f7b-8010-e0d057c03dfe">
    <name>MyQuota</name>
    <description>A quota for my Red Hat Enterprise
      Virtualization environment</description>
    <data_center href= "/ovirt-engine/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c" 
    id="56087282-d7a6-11e1-af44-001a4a400e0c"/>
</quota>
创建新配额需要 namedescription 元素。

例 9.14. 创建配额

POST /ovirt-engine/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1
Accept: application/xml
Content-type: application/xml

<quota>
    <name>VMQuota</name>
    <description>My new quota for virtual machines</description>
</quota>
删除配额需要 DELETE 请求。

例 9.15. 删除配额

DELETE /ovirt-engine/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe HTTP/1.1

HTTP/1.1 204 No Content

9.6. Actions

9.6.1. 强制删除数据中心操作

API 用户强制在存储域中遇到无法解析的问题时删除数据中心,例如在删除存储域时丢失与 master 存储域的连接或缺少可用主机。API 包括针对这些情况的帮助 强制 操作。
此操作会在 API 从 Red Hat Virtualization 环境中删除与所选数据中心关联的数据库条目。这意味着,无论关联的存储域是什么,API 都会删除数据中心。
此操作需要 DELETE 方法。请求正文包含将 force 参数设置为 true 的操作 表示。请求还需要额外的 Content-type: application/xml 标头来处理正文中的 XML 表示。

例 9.16. 对数据中心强制删除操作

DELETE /ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <force>true</force>
</action>
此操作:
  • 删除与数据中心关联的 数据存储域 的所有数据库信息 ;
  • 删除与数据中心关联的 数据存储域 中资源的所有数据库信息,如虚拟机和模板;
  • iso 和导出存储域 从数据中心分离;以及
  • 删除数据中心的数据库信息。
此操作会覆盖在删除前数据中心为空的要求。
重要的
此操作只删除与数据中心关联的资源的数据库条目。与数据中心关联的 数据存储域 需要在重复使用前手动格式。在另一个数据中心上使用之前,iso导出域 的元数据需要手动清理。

第 10 章 集群

10.1. 集群元素

集群 集合提供有关 Red Hat Virtualization 环境中集群的信息。API 用户通过从入口点 URI 获取的 rel="clusters" 链接访问此信息。
下表显示了集群资源表示法中包含的特定元素。
表 10.1. 集群元素
元素 类型 Description Properties
name 字符串 用户提供的、人类可读的名称。该名称在 所有集群资源中都是唯一的。
description 字符串 集群的自由格式、用户提供的、人类可读的描述。 
link rel="networks" 关系 与此集群关联的网络的子集合的链接。 
link rel="permissions" 关系 集群权限的子集合链接。 
link rel="glustervolumes" 关系 与此集群关联的 Red Hat Gluster Storage 卷的子集合链接。 
link rel="glusterhooks" 关系 与此集群关联的 Red Hat Gluster Storage 卷 hook 的子集合链接。 
link rel="affinitygroups" 关系 与此集群关联的虚拟机关联性组的链接。 
cpu id= complex 定义所有主机所有主机的服务器 CPU 引用必须在集群中支持。
data_center id= GUID 对这个集群的数据中心成员资格的引用。
memory_policy complex 定义主机内存使用率上的集群策略。
scheduling_policy complex 为集群中的主机定义负载平衡或节能模式。
version major= minor= complex 集群的兼容性级别。
supported_versions complex 集群的可能 版本 级别列表。
error_handling complex/enumerated 定义当集群中的主机无法正常运行时处理虚拟机。需要一个 on_error 元素,其中包含在 capabilities 中列出的枚举类型属性。 
virt_service 布尔值 定义是否为此集群公开虚拟化服务。 
gluster_service 布尔值 定义是否为此集群公开 Red Hat Gluster Storage 服务。 
threads_as_cores 布尔值 定义主机是否可以运行的虚拟机,其处理器内核总数大于主机中的内核数。 
tunnel_migration 布尔值 定义虚拟机在迁移过程中是否使用 libvirt-to-libvirt 隧道。 
trusted_service 布尔值 定义是否使用 OpenAttestation 服务器来验证主机。 
ballooning_enabled 布尔值 定义是否为集群启用气球功能。 
ksm 布尔值 定义是否为集群启用 ksm。 
注意
当主机的可用内存低于 20% 时,像 mom.Controllers.Balloon - INFO Ballooning guest:half1 from 1096400 to 1991580 等气球命令会记录到 /etc/vdsm/mom.conf/etc/vdsm/mom.conf 是 Memory Overcommit Manager 日志文件。如果虚拟机没有遵循气球功能,也会将事件添加到事件日志中。

10.2. 内存策略元素

memory_policy 元素包含以下元素:
表 10.2. 内存策略元素
元素 类型 Description Properties
overcommit percent= complex 在主机上没有更多虚拟机启动前允许使用的主机内存百分比。由于 KSM 下的内存共享,虚拟机可以使用超过可用内存。建议的值包括 100 (None), 150 (Server Load)和 200 (Desktop Load)。
transparent_hugepages complex 定义 Transparent Hugepages 的 启用状态。状态可以是 true 或 false。检查 功能 功能集,以确保您的版本支持 透明巨页

10.3. 调度策略元素

scheduling_policy 元素包含以下元素:
表 10.3. 调度策略元素
元素 类型 Description Properties
policy Enumerated 集群中的主机的虚拟机调度模式。功能 中列出了枚举的类型列表。
阈值低= high= duration= complex 定义主机的 CPU 限值。high 属性控制主机在被视为超载前可以具有的最高 CPU 用量百分比。low 属性控制主机在被视为使用率不足前可以拥有的最小 CPU 用量百分比。duration 属性指的是在调度程序启动并将负载移到另一主机前需要超载的主机的秒数。

10.4. 一个集群的 XML 代表

例 10.1. 集群的 XML 表示

<cluster id="00000000-0000-0000-0000-000000000000"
  href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000">
    <name>Default</name>
    <description>The default server cluster</description>
    <link rel="networks"
      href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/networks"/>
    <link rel="permissions"
      href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/permissions"/>
          <link rel="glustervolumes"
      href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/glustervolumes"/>
          <link rel="glusterhooks"
      href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/glusterhooks"/>
          <link rel="affinitygroups"
      href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups"/>
    <cpu id="Intel Penryn Family"/>
        <architecture>X86_64<architecture/>
    <data_center id="00000000-0000-0000-0000-000000000000"
      href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000"/>
    <memory_policy>
        <overcommit percent="100"/>
        <transparent_hugepages>
            <enabled>false</enabled>
        </transparent_hugepages>
    </memory_policy>
    <scheduling_policies>
      <policy>evenly_distributed</policy>
      <thresholds low="10" high="75" duration="120"/>
    </scheduling_policies>
    <version major="4" minor="0"/>
    <supported_versions>
        <version major="4" minor="0"/>
    </supported_versions>
    <error_handling>
        <on_error>migrate</on_error>
    </error_handling>
    <virt_service>true</virt_service>
    <gluster_service>false</gluster_service>
    <threads_as_cores>false</threads_as_cores>
    <tunnel_migration>false</tunnel_migration>
    <trusted_service>false</trusted_service>
    <ha_reservation>false</ha_reservation>
    <ballooning_enabled>false</ballooning_enabled>
    <ksm>
        <enabled>true</enabled>
    </ksm>
</cluster>

10.5. 集群的 JSON 代表

例 10.2. 集群的 JSON 表示

{
  "cluster" : [ {
    "cpu" : {
      "architecture" : "X86_64",
      "id" : "Intel Penryn Family"
    },
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255",
      "id" : "00000002-0002-0002-0002-000000000255"
    },
    "memory_policy" : {
      "overcommit" : {
        "percent" : "100"
      },
      "transparent_hugepages" : {
        "enabled" : "true"
      }
    },
    "scheduling_policy" : {
      "policy" : "none",
      "name" : "none",
      "href" : "/ovirt-engine/api/schedulingpolicies/b4ed2332-a7ac-4d5f-9596-99a439cb2812",
      "id" : "b4ed2332-a7ac-4d5f-9596-99a439cb2812"
    },
    "version" : {
      "major" : "4",
      "minor" : "0"
    },
    "error_handling" : {
      "on_error" : "migrate"
    },
    "virt_service" : "true",
    "gluster_service" : "false",
    "threads_as_cores" : "false",
    "tunnel_migration" : "false",
    "trusted_service" : "false",
    "ha_reservation" : "false",
    "optional_reason" : "false",
    "ballooning_enabled" : "false",
    "ksm" : {
      "enabled" : "true"
    },
    "required_rng_sources" : { },
    "name" : "Default",
    "description" : "The default server cluster",
    "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb",
    "id" : "00000001-0001-0001-0001-0000000002fb",
    "link" : [ {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb/networks",
      "rel" : "networks"
    }, {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb/glustervolumes",
      "rel" : "glustervolumes"
    }, {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb/glusterhooks",
      "rel" : "glusterhooks"
    }, {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb/affinitygroups",
      "rel" : "affinitygroups"
    }, {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb/cpuprofiles",
      "rel" : "cpuprofiles"
    } ]
  } ]
}

10.6. Methods

10.6.1. 创建集群

创建新集群需要 名称cpu id=datacenter 元素。使用 id 属性或 name 元素识别 数据中心

例 10.3. 创建集群

POST /ovirt-engine/api/clusters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <name>cluster1</name>
    <cpu id="Intel Penryn Family"/>
    <data_center id="00000000-0000-0000-0000-000000000000"/>
</cluster>

10.6.2. 更新集群

名称描述cpu id=error_handling 元素在创建后是 updatable。

例 10.4. 更新集群

PUT /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <description>Cluster 1</description>
</cluster>

10.6.3. 删除集群

删除集群需要 DELETE 请求。

例 10.5. 删除集群

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

10.7. sub-Collections

10.7.1. 网络子注入

10.7.1.1. 网络子注入
与集群关联的网络通过网络子集合表示。集群中的每个主机都连接到这些关联的网络。
集群的网络子集合的表示与标准 网络资源 相同,但以下附加元素除外:
表 10.4. 额外网络元素
元素 类型 Description Properties
cluster id= 关系 对这个网络所属的集群的引用。
required 布尔值 定义必填或可选网络状态。 
显示 布尔值 定义显示网络状态。用于向后兼容。 
usages complex 定义网络的一组 使用 元素。用户可以在此级别上将网络定义为 VMDISPLAY 网络。 
API 用户使用标准的 REST 方法操作 网络 子集合。向 网络 子集合的 POSTing a network idname 引用将网络与集群相关联。

例 10.6. 将网络资源与集群关联

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>ovirtmgmt</name>
</network>

HTTP/1.1 201 Created
Location: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"
  href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
  da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>ovirtmgmt</name>
    <status>
        <state>operational</state>
    </status>
    <description>Display Network</description>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <required>true</required>
    <usages>
        <usage>VM</usage>
    </usages>
</network>
使用 PUT 请求更新资源。

例 10.7. 设置显示网络状态

PUT /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <required>false</required>
    <usages>
        <usage>VM</usage>
        <usage>DISPLAY</usage>
    </usages>
</network>
使用 PUT 请求设置所需的或可选网络状态,以指定 所需 元素的布尔值(true 或 false)。

例 10.8. 设置可选网络状态

PUT /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <required>false</required>
</network>
将关联与 DELETE 请求删除到集合中适当的元素。

例 10.9. 从集群中移除网络关联

DELETE /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1

HTTP/1.1 204 No Content

10.7.2. Storage Volumes Sub-Collection

10.7.2.1. Red Hat Gluster Storage Volumes Sub-Collection
Red Hat Virtualization 提供了创建和管理 Red Hat Gluster Storage 卷的方法。Red Hat Gluster Storage 卷与集群关联,并使用 glustervolumes 子集合表示。
glustervolumes 子集合中的 Red Hat Gluster Storage 卷资源的表示使用以下元素定义:
表 10.5. Gluster 卷元素
元素 类型 Description Properties
volume_type Enumerated 定义卷类型。有关卷类型列表,请参阅 能力 集合。
bricks 关系 红帽 Gluster 存储 brick 的子集合。在创建新卷时,请求需要一组 brick 元素来在此集群中创建和管理。需要 Red Hat Gluster Storage 服务器的 server_id,以及 brick 目录的 brick_dir 元素
transport_types complex 定义一组卷 transport_type 元素。有关可用传输类型的列表,请查看 capabilities 集合。
replica_count 整数 定义复制卷的文件复制数。
stripe_count 整数 定义条状卷的条带数
选项 complex 组额外的红帽 Gluster 存储选项 元素。每个 选项 都包括一个选项 name一个值

例 10.10. Red Hat Gluster Storage 卷的 XML 表示

<gluster_volume id="99408929-82cf-4dc7-a532-9d998063fa95"
  href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
  /glustervolume/e199f877-900a-4e30-8114-8e3177f47651">
    <name>GlusterVolume1</name>
    <link rel="bricks"
      href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
      /glustervolume/e199f877-900a-4e30-8114-8e3177f47651/bricks"/>
    <volume_type>DISTRIBUTED_REPLICATE</volume_type>
    <transport_types>
        <transport_type>TCP</transport_type>
    </transport_types>
    <replica_count>2</replica_count>
    <stripe_count>1</stripe_count>
    <options>
        <option>
            <name>cluster.min-free-disk</name>
            <value>536870912</value>
        </option>
    </options>   
</gluster_volume>
通过 POST 请求创建 Red Hat Gluster Storage,其名称为、volume_typebricks 到 sub-collection。

例 10.11. 创建 Red Hat Gluster Storage 卷

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<gluster_volume>
    <name>GlusterVolume1</name>
    <volume_type>DISTRIBUTED_REPLICATE</volume_type>
    <bricks>
        <brick>
            <server_id>server1</server_id>
            <brick_dir>/exp1</brick_dir>
        </brick>
    <bricks>
</gluster_volume>
删除具有 DELETE 请求的 Red Hat Gluster Storage 卷。

例 10.12. 删除 Red Hat Gluster Storage 卷

DELETE /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1

HTTP/1.1 204 No Content
重要
glustervolumes 子集合中的资源无法更新。
10.7.2.2. bricks Sub-Collection
glustervolumes 子集合包含自己的 brick 子集合,用于在 Red Hat Gluster Storage 卷中定义各个 brick。可以使用 All-Content: true 标头检索 GET 请求的其他信息。
卷的 brick 子集合的表示使用以下元素定义:
表 10.6. Brick 元素
元素 类型 Description Properties
server_id 字符串 对 Red Hat Gluster 存储服务器的引用。
brick_dir 字符串 定义 Red Hat Gluster Storage 服务器上的 brick 目录。
replica_count 整数 定义卷中 brick 的文件复制数。
stripe_count 整数 定义卷中 brick 的条带数
利用所需的 server_idbrick_dir 到子集合,通过 POST 请求创建新 brick。

例 10.13. 添加 brick

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<brick>
    <server_id>server1</server_id>
    <brick_dir>/exp1</brick_dir>
</brick>
使用 DELETE 请求删除 brick。

例 10.14. 删除 brick

DELETE /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks/0a473ebe-01d2-444d-8f58-f565a436b8eb HTTP/1.1

HTTP/1.1 204 No Content
重要
bricks 子集合中的资源无法更新。
10.7.2.3. Actions
10.7.2.3.1. 开始操作
start 操作使得 Gluster 卷可供使用。

例 10.15. 启动一个卷

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>
使用可选的 force boolean 元素强制对正在运行的卷执行操作。这可用于在正在运行的卷中启动禁用的 brick 进程。
10.7.2.3.2. 停止操作
stop 操作取消激活 Gluster 卷。

例 10.16. 停止卷

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>
使用可选的 force boolean 元素来暴力强制停止操作。
10.7.2.3.3. 设置选项操作
setoption 操作设定卷选项。

例 10.17. 设置选项

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
    <option>
        <name>cluster.min-free-disk</name>
        <value>536870912</value>
    </option>
</action>
10.7.2.3.4. 重置选项操作
resetoption 操作重置卷选项。

例 10.18. 重置选项

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
        <option>
            <name>cluster.min-free-disk</name>
        </option>
</action>
10.7.2.3.5. 重置所有选项操作
resetalloptions 操作重置所有卷选项。

例 10.19. 重置所有选项

POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetalloptions HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>

10.7.3. 关联性组子集合

10.7.3.1. 关联性组 Sub-Collection
affinitygroups 子集合中的虚拟机关联性组资源的表示使用以下元素定义:
表 10.7. 关联性组元素
元素 类型 Description Properties
name 字符串 affinity 组的纯文本可读名称。
cluster 关系 对 affinity 组应用到的集群的引用。 
positive 布尔值: true 或 false 指定关联性组是否将正关联性或负关联性应用到该关联性组成员的虚拟机。 
enforcing 布尔值: true 或 false 指定关联性组是否使用应用到该关联性组成员的关联性的硬或软实施。 

例 10.20. 虚拟机关联性组的 XML 表示

<affinity_group href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <name>AF_GROUP_001</name>
  <cluster href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000"/>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
通过带有 required name 属性的 POST 请求创建虚拟机关联性组。

例 10.21. 创建虚拟机关联性组

POST https://XX.XX.XX.XX/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<affinity_group>
  <name>AF_GROUP_001</name>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
使用 DELETE 请求删除虚拟机关联性组。

例 10.22. 删除虚拟机关联性组

DELETE https://XX.XX.XX.XX/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

第 11 章 网络

11.1. 网络元素

网络 集合提供有关 Red Hat Virtualization 环境中的逻辑网络的信息。API 用户通过从入口点 URI 获取的 rel="networks" 链接访问此信息。
下表显示了网络资源表示法中包含的特定元素。
表 11.1. 网络元素
元素 类型 Description Properties
link rel="vnicprofiles" 关系 附加到此逻辑网络的 VNIC 配置集的子集合链接。 
link rel="labels" 关系 附加到此逻辑网络的标签的子集合链接。 
data_center id= GUID 对这个集群所属的数据中心的引用。
vlan id= 整数 VLAN 标签。
stp 布尔值: true 或 false 如果在此网络上启用了生成树协议,则为 true
mtu 整数 设置逻辑网络的最大传输单元。如果省略,则逻辑网络将使用默认值。
status 操作 或非操作之一 网络的状态。这些状态列在 capabilities 下的 network_states 中。
usages complex 定义网络的一组 使用 元素。用户可以在此级别上定义网络作为 虚拟机网络 
重要的
如本节所述的 API 是实验性的,可能随时更改。它不包含在向后兼容声明中。

11.2. XML 代表网络资源

例 11.1. 网络资源的 XML 表示

<network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000"
  id="00000000-0000-0000-0000-000000000000">
  <name>ovirtmgmt</name>
  <description>Management Network</description>
  <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/vnicprofiles" rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/labels" rel="labels"/>
  <data_center href="/ovirt-engine/api/datacenters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000"/>
  <stp>false</stp>
  <mtu>0</mtu>
  <usages>
    <usage>vm</usage>
  </usages>
</network>

11.3. 网络资源的 JSON 表示

例 11.2. 网络资源的 JSON 表示

{
  "network" : [ {
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/00000002-0002-0002-0002-000000000255",
      "id" : "00000002-0002-0002-0002-000000000255"
    },
    "stp" : "false",
    "mtu" : "0",
    "usages" : {
      "usage" : [ "vm" ]
    },
    "name" : "ovirtmgmt",
    "description" : "Management Network",
    "href" : "/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009",
    "id" : "00000000-0000-0000-0000-000000000009",
    "link" : [ {
      "href" : "/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009/vnicprofiles",
      "rel" : "vnicprofiles"
    }, {
      "href" : "/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009/labels",
      "rel" : "labels"
    } ]
  } ]
}

11.4. Methods

11.4.1. 创建网络资源

创建新网络需要 namedatacenter 元素。

例 11.3. 创建网络资源

POST /ovirt-engine/api/networks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network>
    <name>network 1</name>
    <data_center id="00000000-0000-0000-0000-000000000000"/>
</network>

11.4.2. 更新网络资源

名称,description,ip,vlan,stpdisplay 元素在创建后是 updatable。

例 11.4. 更新网络资源

PUT /ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network>
    <description>Network 1</description>
</network>

11.4.3. 删除网络资源

删除网络需要 DELETE 请求。

例 11.5. 删除网络

DELETE /ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

11.5. 子集合

11.5.1. 网络 VNIC Profile Sub-Collection

VNIC (虚拟网络接口控制器)配置集(也称为虚拟机接口配置集)是应用于用户和组的自定义配置集来限制网络带宽。每个 vnicprofile 都包含以下元素:
表 11.2. vnic 配置集的元素
元素 类型 描述
name 字符串 配置集的唯一标识符。
description 字符串 配置集的纯文本描述。
network 字符串 配置集应用到的逻辑网络的唯一标识符。
port_mirroring 布尔值: truefalse 默认值为 false

例 11.6. 网络的 vnicprofile 子集合的 XML 表示

<vnic_profile href= "/ovirt-engine/api/vnicprofiles/f9c2f9f1-3ae2-4100-a9a5-285ebb755c0d" id="f9c2f9f1-3ae2-4100-a9a5-285ebb755c0d">
	<name>Peanuts</name>
	<description>shelled</description>
	<network href= "/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
	<port_mirroring>false</port_mirroring>
	</vnic_profile>
</vnic_profiles>

11.5.2. Network Labels Sub-Collection

网络标签是纯文本、人类可读的标签,允许您自动关联逻辑网络和物理主机网络接口。每个 标签 都包含以下元素:
表 11.3. 标签的元素
元素 类型 Description
network 字符串 标签附加到的网络的 hrefid

例 11.7. 网络标签子集合的 XML 表示

<labels>
  <label href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/labels/eth0" id="eth0">
    <network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000"
      id="00000000-0000-0000-0000-000000000000"/>
  </label>
</labels>

11.5.3. Methods

11.5.3.1. 将标签附加到逻辑网络操作
您可以将标签附加到逻辑网络,以自动化将该逻辑网络与附加相同标签的物理主机网络接口关联。

例 11.8. 将标签附加到逻辑网络的操作

POST /ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/labels/ HTTP/1.1
Accept: application/xml
Content-type: application/xml

<label id="Label_001" />
11.5.3.2. 从逻辑网络中删除标签
从逻辑网络中删除标签需要 DELETE 请求。

例 11.9. 从逻辑网络中删除标签

DELETE /ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000/labels/[label_id] HTTP/1.1

HTTP/1.1 204 No Content

第 12 章 存储域

12.1. 存储域元素

storagedomains 集合提供有关 Red Hat Virtualization 环境中存储域的信息。API 用户通过从入口点 URI 获取的 rel="storagedomains" 链接访问此信息。
下表显示了存储域资源表示法中包含的特定元素。
表 12.1. 存储域元素
元素 类型 Description Properties
link rel="permissions" 关系 到存储域权限的子集合的链接。 
link rel="files" 关系 到这个存储域 的文件 子集合的链接。 
link rel="vms" 关系 vms 子集合的链接,用于 类型为 export 的存储域。 
link rel="templates" 关系 类型为 export 的存储域的 templates 子集合的链接。 
type Enumerated 存储域类型。功能 中提供了枚举的值的列表。
external_status complex/enumerated 外部系统和插件报告的存储域健康状况。state 元素包含 okinfowarningerrorfailure 的枚举值。 
master 布尔值: true 或 false 如果这是数据中心的 master 存储域,则为 true
主机 complex 对应初始化此存储域的主机的引用。此主机的唯一限制是它应当有权访问指定的物理存储。
storage complex 描述存储域的底层存储。
可用 整数 以字节为单位的可用空间。
使用的 整数 以字节为单位使用的空间。
已提交 整数 以字节为单位提交的空间。
storage_format Enumerated 描述存储域的存储格式版本。功能 中提供了枚举的值的列表。
wipe_after_delete 布尔值: true 或 false 在存储域中默认设置 wipe after delete 选项。可以在创建域后编辑此选项,但是这样做不会在删除已存在的磁盘属性后更改擦除。 
warning_low_space_indicator 整数 设置警告低空间指示符选项的百分比值。如果存储域中的可用空间低于这个百分比,则会向用户显示警告消息并记录日志。 
critical_space_action_blocker 整数 以 GB 为单位的值,用于设置 critical space action blocker 选项。如果存储域中可用的可用空间低于此值,则会向用户和记录错误消息显示,并且任何占用空间的新操作(即便是临时使用)都会被阻止。 
重要的
如本章所述的 API 是实验性的,可能随时更改。它不包含在向后兼容声明中。

12.2. 存储域的 XML 表

例 12.1.  存储域的 XML 表示

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>data0</name>
    <link rel="permissions"
      href="/ovirt-engine/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
    <link rel="files"
      href="/ovirt-engine/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/files"/>
    <type>data</type>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <available>156766306304</available>
    <used>433791696896</used>
    <committed>617401548800</committed>
    <storage_format>v1</storage_format>
    <wipe_after_delete>true</wipe_after_delete>
    <warning_low_space_indicator>10</warning_low_space_indicator>
    <critical_space_action_blocker>5</critical_space_action_blocker>
</storage_domain>

12.3. 存储域的 JSON 代表

例 12.2. 存储域的 JSON 表示

{
  "storage_domain" : [ {
    "type" : "data",
    "master" : "false",
    "storage" : {
      "address" : "192.0.2.0",
      "type" : "nfs",
      "path" : "/storage/user/nfs"
    },
    "available" : 193273528320,
    "used" : 17179869184,
    "committed" : 0,
    "storage_format" : "v3",
    "name" : "NFS_01",
    "href" : "/ovirt-engine/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba",
    "id" : "8827b158-6d2e-442d-a7ee-c6fd4718aaba",
    "link" : [ {
      "href" : "/ovirt-engine/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/disks",
      "rel" : "disks"
    }, {
      "href" : "/ovirt-engine/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/storageconnections",
      "rel" : "storageconnections"
    }, {
      "href" : "/ovirt-engine/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/disksnapshots",
      "rel" : "disksnapshots"
    }, {
      "href" : "/ovirt-engine/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/diskprofiles",
      "rel" : "diskprofiles"
    } ]
  } ]
}

12.4. Methods

12.4.1. 创建存储域

创建新存储域需要 名称类型主机和存储 元素。使用 id 属性或 name 元素识别 host 元素。
您可以通过在 POST 请求中指定 <wipe _after_delete> 来默认在存储域上启用 wipe after delete 选项。可以在创建域后编辑此选项,但是这样做不会在删除已存在的磁盘属性后更改擦除。

例 12.3.  创建存储域

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>
API 用户在创建后将存储域附加到数据中心。

12.4.2. 更新存储域

只有 删除元素后 的名称和 擦除 才是创建后的 updatable。在删除元素后更改擦除,在删除已存在的磁盘属性后不会改变擦除。

例 12.4.  更新存储域

PUT /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data2</name>
    ...
    <wipe_after_delete>true</wipe_after_delete>
    ...
</storage_domain>

12.4.3. 删除存储域

删除存储域需要 DELETE 请求。

例 12.5. 删除存储域

DELETE /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1

HTTP/1.1 204 No Content

12.5. 存储类型

12.5.1. 存储类型

storage 元素包含一个 type 元素,这是在 capabilities 集合下找到的枚举值。
storage 元素还包含特定于每种 存储类型 的额外元素。接下来的几个部分将检查这些额外的 存储类型 元素。

12.5.2. NFS 存储

下表包含 存储 描述中的 nfs 特定元素。
表 12.2. 特定于 NFS 的元素
元素 类型 Description Properties
address 字符串 NFS 服务器的主机名或 IP 地址。
path 字符串 服务器上可挂载的 NFS 挂载目录的路径。

12.5.3. PosixFS 存储

下表包含 存储 描述中的 posixfs 特定的元素。
表 12.3. 特定于 PosixFS 的元素
元素 类型 Description Properties
address 字符串 PosixFS 服务器的主机名或 IP 地址。
path 字符串 服务器上可挂载的 PosixFS 挂载目录的路径。
vfs_type 字符串 Linux 支持的 PosixFS 共享的文件系统类型。
mount_options 字符串 挂载 PosixFS 共享的选项。

12.5.4. iSCSI 和 FCP 存储

下表包含存储描述中的 iscsifcp 特定的元素。
表 12.4. iSCSI 和 FCP 特定元素
元素 类型 Description Properties
logical_unit id= complex 逻辑单元的 id。存储域也接受多个 iSCSI 或 FCP 逻辑单元。
override_luns 布尔值 定义是否将所有逻辑单元设置替换为新设置。设置为 true 以覆盖。
logical_unit 包含一组子元素。
表 12.5. 逻辑单元元素
元素 类型 Description Properties
address 字符串 包含存储设备的服务器地址。
port 整数 服务器的端口号。
target 字符串 存储设备的目标 IQN。
用户名 字符串 用于登录到目标的 CHAP 用户名。
密码 字符串 用于登录到目标的 CHAP 密码。
serial 字符串 目标的串行 ID。
vendor_id 字符串 目标的供应商名称。
product_id 字符串 目标的产品代码。
lun_mapping 整数 目标的逻辑单元号设备映射。
如果是 iSCSI,如果 logical_unit 描述还包含涉及 LUN 的 iSCSI 目标的详细信息,则目标会在创建存储域时执行自动登录。

12.5.5. LocalFS Storage

存储描述中的 localfs 特定的元素有:
表 12.6. localfs 特定的元素
元素 类型 Description Properties
path 字符串 主机上本地存储域的路径。
localfs 存储域需要一个数据中心,其 storage_type 设为 localfs。此数据中心仅包含单个主机集群,主机集群仅包含单个主机。

12.6. 导出存储域

12.6.1. 导出存储域

注意
导出存储域已弃用。存储数据域可以从数据中心取消附加,并导入到同一环境中或不同环境中的其他数据中心。然后,可以将虚拟机、浮动虚拟磁盘镜像和模板从导入的存储域上传到附加的数据中心。有关 导入存储域 的信息,请参阅 Red Hat Virtualization 管理指南中的 导入现有存储域部分。
设置为 export 的存储域包含 vmstemplates 子集合,它列出了存储在该特定存储域上的导入候选虚拟机和模板。

例 12.6. 列出导出存储域的虚拟机子集合

GET /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml

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

<vms>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/
      vms/082c794b-771f-452f-83c9-b2b5a19c0399">
        <name>vm1</name>
        ...
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
          href="/ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
        <actions>
            <link rel="import" href="/ovirt-engine/api/storagedomains/
              fabe0451-701f-4235-8f7e-e20e458819ed/vms/
              082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        </actions>
    </vm>
</vms>
这些集合中的虚拟机和模板在顶级虚拟机和模板集合中对应部分具有相似的表示,但它们还包含 storage_domain 引用和 导入操作
导入操作导出存储域 导入虚拟机或模板。目标集群和存储域使用 clusterstorage_domain 引用来指定。
包括一个可选 name 元素,为虚拟机或模板指定特定名称。

例 12.7. 从导出存储域导入虚拟机的操作

POST /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
</action>

例 12.8. 从导出存储域导入模板的操作

POST /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/templates/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
</action>
包含可选的 克隆 布尔值元素,以导入虚拟机为新实体。

例 12.9. 将虚拟机导入为新实体的操作

POST /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
    <clone>true</clone>
    <vm>
        <name>MyVM</name>
    </vm>
    ...
</action>
包括一个可选的 disk 元素,用于选择使用独立磁盘 id 元素导入的 磁盘

例 12.10. 为导入操作选择磁盘

POST /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <cluster>
        <name>Default</name>
    </cluster>
    <vm>
        <name>MyVM</name>
    </vm>
    ...
    <disks>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b"/>
    </disks>
</action>
使用 DELETE 请求从 导出存储域中 删除虚拟机或模板。

例 12.11. 从导出存储域中删除虚拟机

DELETE /ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml

HTTP/1.1 204 No Content

12.7. Glance 镜像存储域

12.7.1. Glance 镜像存储域

类型为 Image 的存储域代表作为外部提供程序添加到 Red Hat Virtualization 环境中的 OpenStack 镜像服务实例。这些 Glance 镜像存储域包含一个 镜像 子集合,其中包含已导出到的虚拟机镜像,或者从该 Glance 镜像存储域导入。

例 12.12. 列出 Glance 镜像存储域的镜像子集合

GET /ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000/images
Accept: application/xml

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<images>
  <image href="/ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
    00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <actions>
      <link href="/ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
        00000000-0000-0000-0000-000000000000/import" rel="import"/>
    </actions>
    <name>RHEL_65_Disk_001</name>
    <storage_domain href="/ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000"
      id="00000000-0000-0000-0000-000000000000"/>
  </image>
  <image href="/ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
    00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <actions>
      <link href="/ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
        00000000-0000-0000-0000-000000000000/import" rel="import"/>
    </actions>
    <name>RHEL_65_Disk_002</name>
    <storage_domain href="/ovirt-engine/api/storagedomains/00000000-0000-0000-0000-000000000000"
      id="00000000-0000-0000-0000-000000000000"/>
  </image>
</images>
导入操作 从 Glance 镜像存储域导入虚拟机映像。目标存储域使用 storage_domain 引用和带有集群引用的目标集群指定。
包括一个可选 name 元素,为虚拟机或模板指定特定名称。

例 12.13. 从 Glance 镜像存储域导入虚拟机的操作

POST /ovirt-engine/api/storagedomains/00000000-0000-0000-000000000000/images/
00000000-0000-0000-000000000000/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>images0</name>
    </cluster>
</action>
您还可以通过指定 import_as_template 参考来将镜像导入为模板:

例 12.14. 作为模板从 Glance 镜像存储域导入虚拟机的操作

POST /ovirt-engine/api/storagedomains/00000000-0000-0000-000000000000/images/
00000000-0000-0000-000000000000/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>images0</name>
    </cluster>
    </import_as_template>true</import_as_template>
</action>

12.8. 导入块存储域

12.8.1. 导入块存储域

可以使用 REST API 将 type 设置为 iscsifcp 的现有块存储域导入到引擎中。通过导入存储域,您可以在引擎数据库中故障时恢复数据,并将数据从一个数据中心或环境迁移到另一个数据中心。
此流程假设存储域没有附加到任何环境中的数据中心或主机。要导入并附加现有的块存储域到数据中心,必须初始化目标数据中心。

过程 12.1. 导入块存储域

  1. 在 iSCSI 存储服务器中发现目标:
    POST /ovirt-engine/api/hosts/052a880a-53e0-4fe3-9ed5-01f939d1df66/iscsidiscover
    Accept: application/xml
    Content-Type: application/xml
    
    <action>
        <iscsi>
            <address>192.0.2.0</address>
            <port>3260</port>
        </iscsi>
    </action>
    
  2. 使用上一步中发现的 iSCSI 目标,获取导入候选的存储域列表:
    POST /ovirt-engine/api/hosts/052a880a-53e0-4fe3-9ed5-01f939d1df66/unregisteredstoragedomainsdiscover HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <action>
        <iscsi>
            <address>192.0.2.0</address>
        </iscsi>
        <iscsi_target>iqn.name1.120.01</iscsi_target>
        <iscsi_target>iqn.name2.120.02</iscsi_target>
        <iscsi_target>iqn.name3.120.03</iscsi_target>
    </action>
    
    响应显示没有与主机关联的存储域列表,如下所示:
    <action>
        <iscsi>
            <address>192.0.2.0</address>
        </iscsi>
        <storage_domains>
            <storage_domain id="6ab65b16-0f03-4b93-85a7-5bc3b8d52be0">
                <name>scsi4</name>
                <type>data</type>
                <external_status>
                  <state>ok</state>
                </external_status>
                <master>false</master>
                <storage>
                    <type>iscsi</type>
                    <volume_group id="OLkKwa-VmEM-abW7-hPiv-BGrw-sQ2E-vTdAy1"/>
                </storage>
                <available>0</available>
                <used>0</used>
                <committed>0</committed>
                <storage_format>v3</storage_format>
            </storage_domain>
        <status>
            <state>complete</state>
        </status>
        <iscsi_target>iqn.name1.120.01</iscsi_target>
        <iscsi_target>iqn.name2.120.02</iscsi_target>
        <iscsi_target>iqn.name3.120.03</iscsi_target>
    </action>
    
    
  3. 将 iSCSI 存储域导入到主机:
    POST /ovirt-engine/api/storagedomains/ HTTP/1.1
      Accept: application/xml
      Content-type: application/xml
    
    <storage_domain id="6ab65b16-0f03-4b93-85a7-5bc3b8d52be0">
        <import>true</import>
        <host id="052a880a-53e0-4fe3-9ed5-01f939d1df66" />
        <type>data</type>
        <storage>
            <type>iscsi</type>
        </storage>
    </storage_domain>
    
您现在已将块存储域导入到主机。
现在,您可能想要将存储域附加到主机,并查找任何未注册的磁盘。按照以下步骤附加存储域和相关磁盘:

过程 12.2. 附加块存储域

  1. 将存储域附加到数据中心:
    POST /ovirt-engine/api/datacenters/01a45ff0-915a-45e0-8d56-5253234ac988/storagedomains
    Accept: application/xml
    Content-Type: application/xml
    
    <storage_domain>
        <name>scsi4</name>
    </storage_domain>
    
  2. 在存储域中查找未注册的磁盘:
    GET /ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0/disks;unregistered
    Accept: application/xml
    Content-Type: application/xml
    
    这将返回有关存储域中任何未注册磁盘的信息,其响应如下:
    <disk href= "/ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0/disks/b662f6da-3e97-4bb6-8a50-bda9980a6e83" id="b662f6da-3e97-4bb6-8a50-bda9980a6e83">
      <actions>
          <link href= "/ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0/disks/b662f6da-3e97-4bb6-8a50-bda9980a6e83/export" rel="export"/>
      </actions>
      <name>disk1</name>
      <description/>
      <link href= "/ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0/disks/b662f6da-3e97-4bb6-8a50-bda9980a6e83/permissions" rel="permissions"/>
      <link href= "/ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0/disks/b662f6da-3e97-4bb6-8a50-bda9980a6e83/statistics" rel="statistics"/>
      <alias>disk1</alias>
      <image_id>930d653e-2a11-45ce-8042-9935584a3f87</image_id>
      <storage_domain href= "/ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0" id="8ac10ec5-7cc9-4b1c-9c97-f121a9e4679a"/>
      <storage_domains>
          <storage_domain id="6ab65b16-0f03-4b93-85a7-5bc3b8d52be0"/>
      </storage_domains>
      <size>10737418240</size>
      <provisioned_size>10737418240</provisioned_size>
      <actual_size>10737418240</actual_size>
      <status>
          <state>ok</state>
      </status>
      <interface>ide</interface>
      <format>raw</format>
      <sparse>false</sparse>
      <bootable>false</bootable>
      <shareable>false</shareable>
      <wipe_after_delete>false</wipe_after_delete>
      <propagate_errors>false</propagate_errors>
      <storage_type>image</storage_type>
    </disk>
    
  3. 将磁盘附加到存储域:
    POST /ovirt-engine/api/storagedomains/6ab65b16-0f03-4b93-85a7-5bc3b8d52be0/disks;unregistered
    Accept: application/xml
    Content-Type: application/xml
    
    <disk id='b662f6da-3e97-4bb6-8a50-bda9980a6e83'></disk>
    
磁盘现在附加到导入的块存储域。

12.9. sub-Collections

12.9.1. files Sub-Collection

每个存储域下的 文件 子集合提供了一种方式,供客户端列出可用的文件。此子集合专门针对 ISO 存储域,其中包含管理员通过 Red Hat Virtualization Manager 上传的 ISO 镜像和虚拟软盘磁盘(VFD)。
向虚拟机添加 CD-ROM 设备需要 ISO 镜像,来自 ISO 存储域 的文件 子集合。

例 12.15. 列出 ISO 存储域的文件子集合

GET /ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml

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

<files>
    <file id="en_winxp_pro_with_sp2.iso"
      href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
      en_winxp_pro_with_sp2.iso">
        <name>en_winxp_pro_with_sp2.iso</name>
        <type>iso</type>
        <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
    <file id="boot.vfd"
      href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
      boot.vfd">
        <name>boot.vfd</name>
        <type>vfd</type>
        <storage_doman id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/ovirt-engine/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>
与其他资源一样,文件具有不透明 IDhref 属性。name 元素包含 filename。

12.10. Actions

12.10.1. 导入现有存储域

注意
导出存储域已弃用。存储数据域可以从数据中心取消附加,并导入到同一环境中或不同环境中的其他数据中心。然后,可以将虚拟机、浮动虚拟磁盘镜像和模板从导入的存储域上传到附加的数据中心。有关 导入存储域 的信息,请参阅 Red Hat Virtualization 管理指南中的 导入现有存储域部分。
API 为用户提供一个 Red Hat Virtualization Manager 实例中删除 ISO 或导出存储域的功能,而无需重新格式化底层存储并将其导入到另一个实例。除了指定名称外,导入与添加新存储域类似。

例 12.16. 导入现有的导出存储域

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<storage_domain>
    <type>export</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/export-domain</path>
    </storage>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</storage_domain>

HTTP/1.1 201 Created
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/ovirt-engine/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>export1</name>
    ...
</storage_domain>

12.10.2. 删除存储域

storage_domain 引用在存储域的 DELETE 请求正文中传递。storage_domain 引用采用以下格式:
<storage_domain>
    <host id="..."/>
</storage_domain>
<storage_domain>
    <host>
        <name>...</name>
    </host>
</storage_domain>

格式化存储域

API 用户提供了一个可选 格式 元素,用于指定在删除后是否格式化存储域。

例 12.17. 删除后格式化存储域

<storage_domain>
    <host id="..."/>
    <format>true</format>
</storage_domain>
如果没有传递 格式 元素,则存储域将保持未格式化。

存储域的逻辑删除

API 还提供用于逻辑删除存储域的功能。这会保留存储域的数据来导入。使用 destroy 元素以逻辑方式删除存储域并保留数据。

例 12.18. 对存储域进行逻辑删除

<storage_domain>
    <host id="..."/>
    <destroy>true</destroy>
</storage_domain>

12.10.3. 刷新 LUN 大小

用户可以在增大存储服务器上底层 LUN 的大小后刷新 LUN 大小。refreshluns 操作会强制重新扫描提供的 LUN,并在需要时使用新大小更新数据库。

例 12.19. 刷新 LUN 大小

POST /ovirt-engine/api/storagedomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
   <logical_units>
      <logical_unit id="1IET_00010001"/>
      <logical_unit id="1IET_00010002"/>
   </logical_units>
</action>

第 13 章 存储连接

13.1. 存储连接元素

表 13.1. 存储连接基础元素
元素 类型 Description Properties
type nfs 之一posixfslocaliscsi 存储域的类型。
address 字符串 存储域的主机名或 IP 地址。
(仅 NFS 和 iSCSI 需要)
主机 字符串 hypervisor 的 idname主机 是可选的。提供它将尝试通过主机连接到存储;不提供它会导致数据库中保留存储详细信息。
表 13.2. 存储连接基于文件的存储元素
元素 类型 Description Properties
path 字符串 存储域挂载的文件路径。该路径 不能更新为存储连接已使用的路径。
mount_options 字符串 挂载 PosixFS 共享的选项。 
vfs_type 字符串 Linux 支持的 PosixFS 共享的文件系统类型。
nfs_version 字符串 使用的 NFS 版本。 
nfs_timeo 整数 NFS 客户端将等待请求完成的时间(以秒为单位)。 
nfs_retrans 整数 NFS 客户端重新传输的请求数量将尝试完成请求。 
表 13.3. 存储连接 iSCSI 元素
元素 类型 Description Properties
port 整数 用于 iSCSI 存储域的 TCP 端口。
target 字符串 存储设备的目标 IQN。
用户名 字符串 用于登录到目标的 CHAP 用户名。 
密码 字符串 用于登录到目标的 CHAP 密码。 

13.2. 存储连接资源的 XML 表示

例 13.1. 存储连接资源的 XML 表示

<storage_connections>
  <storage_connection href= "/ovirt-engine/api/storageconnections/608c5b96-9939-4331-96b5-197f28aa2e35"    id="608c5b96-9939-4331-96b5-197f28aa2e35">
    <address>domain.example.com</address>
    <type>nfs</type>
    <path>/var/lib/exports/iso</path>
  </storage_connection>
  <storage_connection href= "/ovirt-engine/api/storageconnections/2ebb3f78-8c22-4666-8df4-e4bb7fec6b3a" id="2ebb3f78-8c22-4666-8df4-e4bb7fec6b3a">
    <address>domain.example.com</address>
    <type>posixfs</type>
    <path>/export/storagedata/username/data</path>
    <vfs_type>nfs</vfs_type>
  </storage_connection>
</storage_connections>

13.3. Methods

13.3.1. 创建新存储连接

创建新存储连接需要 POST 请求。
可以在不添加存储域的情况下创建新的存储连接。主机 idname 是可选的;提供它将尝试通过主机连接到存储。

例 13.2. 创建新存储连接

POST /ovirt-engine/api/storageconnections HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection>
   <type>nfs</type>
   <address>domain.example.com</address>
   <path>/export/storagedata/username/data</path>
   <host>
     <name>Host_Name</name>
   </host>
</storage_connection>

13.3.2. 删除存储连接

删除存储连接需要 DELETE 请求。只有存储域和 LUN 磁盘都引用它时,才能删除存储连接。
主机名或 id 是可选的;提供它从该主机卸载连接。

例 13.3. 删除存储连接

DELETE /ovirt-engine/api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
  <name>Host_Name</name>
</host>

13.3.3. 更新存储连接

更新现有存储连接需要 PUT 请求。存储域必须处于维护模式或未附加才能成功更新连接。
提供 主机名或 id 是可选的;如果提供,主机会尝试与更新的存储详细信息的连接。

例 13.4. 更新存储连接

PUT /ovirt-engine/api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection>   
  <address>updated.example.domain.com</address>
  <host>
      <name>Host_name</name>
   </host>
</storage_connection>

13.3.4. 更新 iSCSI 存储连接

更新现有 iSCSI 存储连接需要 PUT 请求。iSCSI 存储域必须处于维护模式或未附加才能成功更新连接。

例 13.5. 更新存储连接

PUT /ovirt-engine/api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection>   
  <port>3456</port>
</storage_connection>

13.3.5. 使用现有存储连接添加新存储域

使用现有存储连接添加新存储域需要 POST 请求。这仅适用于基于文件的存储域: NFSPOSIX 和本地

例 13.6. 使用现有存储连接添加新存储域

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>New_Domain</name>
  <type>data</type>
 <storage id="Storage_Connection_ID"/>
  <host>
    <name>Host_Name</name>
  </host>
</storage_domain>

13.3.6. 将额外的存储连接附加到 iSCSI 存储

将额外的存储连接附加到 iSCSI 存储域需要 POST 请求。

例 13.7. 将额外的存储连接附加到 iSCSI 存储

POST /ovirt-engine/api/storagedomains/iSCSI_Domain_ID/storageconnections HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection id="Storage_Connection_ID">
</storage_connection>

13.3.7. 从 iSCSI 存储分离存储连接

从 iSCSI 存储域中分离存储连接需要 DELETE 请求。

例 13.8. 从 iSCSI 存储分离存储连接

DELETE /ovirt-engine/api/storagedomains/iSCSI_Domain_ID/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

13.3.8. 定义到 iSCSI 目标的凭证

使用管理门户添加 iSCSI 存储域时,只能为该域指定单个用户名和密码。但是,一些设置要求集群中的每个主机都使用单独的用户名和密码。可以使用 storageconnectionextensions 元素将特定凭证应用到每个主机的每个 iSCSI 目标。

例 13.9. 为 iSCSI 目标定义凭证

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storageconnectionextensions HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storageconnectionextension>
    <target>iqn.2010.05.com.example:iscsi.targetX</target>
    <username>jimmy</username>
    <password>p@55w0Rd!</password>
</storageconnectionextension>

第 14 章 主机

14.1. 主机元素

主机集合 提供有关 Red Hat Virtualization 环境中主机的信息。API 用户通过从入口点 URI 获取的 rel="hosts" 链接访问此信息。
可以使用 All-Content: true 标头检索 GET 请求的其他信息。
下表显示了主机资源表示法中包含的特定元素。
表 14.1. 主机元素
元素 类型 Description Properties
link rel="storage" 关系 到主机存储的 storage 子集合的链接。
link rel="nics" 关系 到主机网络接口的 nics 子集合的链接。 
link rel="numanodes" 关系 主机 NUMA 节点的 numanodes 子集合的链接。 
link rel="tags" 关系 到主机标签 标签 子集合的链接。 
link rel="permissions" 关系 到主机 权限权限 子集合的链接。 
link rel="statistics" 关系 到主机 统计数据的统计信息 子集合的链接。
link rel="hooks" 关系 到主机 hook 的 hook 子集合的链接。
link rel="fenceagents" 关系 到主机隔离代理的 fenceagents 子集合的链接。
link rel="katelloerrata" 关系 到主机勘误表的 katelloerrata 子集合的链接。
link rel="devices" 关系 主机设备的 devices 子集合的链接。
link rel="networkattachments" 关系 到 host 网络配置的 networkattachments 子集合的链接。
link rel="unmanagednetworks" 关系 到主机上非受管网络的 unmanagednetworks 子集合的链接。
link rel="storageconnectionextensions" 关系 到 host 存储连接扩展的 storageconnectionextensions 子集合的链接。
name 字符串 主机的唯一标识符。 
root_password 字符串 此主机的 root 密码仅包含在客户端提供的主机表示法中。
注释 字符串 有关主机的任何注释。 
address 字符串 主机的 IP 地址或主机名。
certificate complex 对主机证书详细信息的引用,包括 组织 和主题
status 请参见以下 主机状态。
external_status complex/enumerated 外部系统和插件报告的主机健康状态。state 元素包含 okinfowarningerrorfailure 的枚举值。 
cluster id= GUID 对包含此主机的集群的引用。 
port 整数 在此主机上运行的 VDSM 守护进程的监听端口。
type rhelovirt_node之一 主机类型。
storage_manager priority= 布尔值: true 或 false 指定主机是否为存储管理器。
version major= minor= build= revision= full_version= complex 主机的兼容性级别。
hardware_information complex 有关主机硬件的信息,包括 制造商,版本,serial_number,product_name,uuid, 和 family 
power_management type= complex 主机电源管理的配置选项,包括 启用选项kdump_detectionauto_pm_enabled代理。有关主机电源管理选项的更多信息,请参阅 第 14.4 节 “电源管理元素” 
ksm 布尔值: true 或 false 如果启用了内核同页合并(KSM),则为 true 
transparent_hugepages 布尔值: true 或 false 如果启用了 Transparent Hugepages,则为 true 
iscsi complex 主机的 SCSI 启动器
ssh complex 有关与主机 SSH 连接的详细信息,包括 端口和 指纹 
cpu complex 主机 CPU 的统计信息。包括 CPU 名称、拓扑内核=、拓扑 socket=拓扑 threads=速度的子元素拓扑 cores=拓扑 socket= 聚合总内核时聚合了总核。虚拟机可用的内核总数等于插槽的数量乘以每个插槽的内核。
内存 整数 主机内存量(以字节为单位)。
max_scheduling_memory 整数 可以字节为单位使用的最大内存量。
summary complex 主机上虚拟机的摘要统计信息。包括 活动迁移 和虚拟机 总数的子元素
os type= complex 主机上安装的操作系统的详细信息,包括 版本 full_version=
libvirt_version major= minor= build= revision= full_version= complex 主机的 libvirt 兼容性级别。
status 包含以下枚举的值之一: downerror、initialize、Installing、install_failedmaintenancenon_operationalnon_responsivePending_approval、preparing_ for_maintenance、connect、boott assigned 和 up 这些状态列在 capabilities 下的 host_states 中。

14.2. 主机的 XML 表述

例 14.1. 主机的 XML 表示

<host href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <actions>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/upgrade" rel="upgrade"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/setupnetworks" rel="setupnetworks"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/fence" rel="fence"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/refresh" rel="refresh"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/install" rel="install"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/activate" rel="activate"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/deactivate" rel="deactivate"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/approve" rel="approve"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/forceselectspm" rel="forceselectspm"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/enrollcertificate" rel="enrollcertificate"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/iscsilogin" rel="iscsilogin"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/unregisteredstoragedomainsdiscover" rel="unregisteredstoragedomainsdiscover"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/iscsidiscover" rel="iscsidiscover"/>
        <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/commitnetconfig" rel="commitnetconfig"/>
    </actions>
    <name>host1</name>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/storage" rel="storage"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics" rel="nics"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/numanodes" rel="numanodes"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/tags" rel="tags"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/statistics" rel="statistics"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/hooks" rel="hooks"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/fenceagents" rel="fenceagents"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/katelloerrata" rel="katelloerrata"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/devices" rel="devices"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/networkattachments" rel="networkattachments"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/unmanagednetworks" rel="unmanagednetworks"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/storageconnectionextensions" rel="storageconnectionextensions"/>
    <address>host1.example.com</address>
    <certificate>
        <organization>exampleorg</organization>
        <subject>O=exampleorg,CN=XX.XX.XX.XX</subject>
    </certificate>
    <status>
        <state>up</state>
    </status>
    <external_status>
        <state>ok</state>
    </external_status>
    <cluster href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <port>54321</port>
    <type>rhel</type>
    <storage_manager priority="2">false</storage_manager>
    <spm>
        <priority>2</priority>
        <status>
            <state>none</state>
        </status>
    </spm>
    <version major="4" minor="17" build="20" revision="0" full_version="vdsm-4.17.20-0.el7ev"/>
    <power_management>
        <enabled>false</enabled>
        <pm_proxies/>
        <automatic_pm_enabled>true</automatic_pm_enabled>
        <kdump_detection>true</kdump_detection>
    </power_management>
    <ksm>
        <enabled>true</enabled>
    </ksm>
    <transparent_hugepages>
        <enabled>true</enabled>
    </transparent_hugepages>
    <iscsi>
        <initiator>iqn.2001-04.com.example:diskarrays-sn-a8675309</initiator>
    </iscsi>
    <ssh>
        <port>22</port>
        <fingerprint>00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00</fingerprint>
    </ssh>
    <cpu>
        <topology cores="2" sockets="1"/>
        <name>Intel(R) Xeon(R) CPU E5430 @ 2.66GHz</name>
        <speed>2656</speed>
    </cpu>
    <memory>12430868480</memory>
    <max_scheduling_memory>12026118144</max_scheduling_memory>
    <summary>
        <active>2</active>
        <migrating>0</migrating>
        <total>3</total>
    </summary>
    <protocol>stomp</protocol>
    <os type="RHEL">
        <version full_version="7.2-9.el7_2.1"/>
    </os>
    <libvirt_version major="1" minor="2" build="17" revision="0" full_version="libvirt-1.2.17-13.el7_2.2"/>
    <kdump_status>disabled</kdump_status>
    <selinux>
        <mode>enforcing</mode>
    </selinux>
    <auto_numa_status>disable</auto_numa_status>
    <numa_supported>false</numa_supported>
    <live_snapshot_support>true</live_snapshot_support>
    <update_available>false</update_available>
    <device_passthrough>
        <enabled>true</enabled>
    </device_passthrough>
</host>

14.3. 主机的 JSON 代表

例 14.2. 主机的 JSON 表示

{
  "host" : [ {
    "address" : "198.51.100.0",
    "certificate" : {
      "organization" : "example.com",
      "subject" : "O=example.com,CN=192.0.2.0"
    },
    "status" : {
      "state" : "up"
    },
    "cluster" : {
      "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb",
      "id" : "00000001-0001-0001-0001-0000000002fb"
    },
    "port" : "54321",
    "type" : "rhel",
    "storage_manager" : {
      "value" : "true",
      "priority" : "5"
    },
    "spm" : {
      "priority" : "5"
    },
    "version" : {
      "major" : "4",
      "minor" : "16",
      "build" : "8",
      "revision" : "1",
      "full_version" : "vdsm-4.16.8.1-6.el6ev"
    },
    "hardware_information" : {
      "manufacturer" : "System Manufacturer To Be Filled By O.E.M.",
      "version" : "System Version To Be Filled By O.E.M.",
      "serial_number" : "Serial Number To Be Filled By O.E.M.",
      "product_name" : "Product Name To Be Filled By O.E.M.",
      "uuid" : "9fa0a1a2-a3a4-a5a6-a7a8-a9aaabacadae",
      "family" : "Family To Be Filled By O.E.M.",
      "supported_rng_sources" : {
        "source" : [ "RANDOM" ]
      }
    },
    "power_management" : {
      "enabled" : "false",
      "options" : {
        "option" : [ {
          "name" : "secure",
          "value" : "false"
        } ]
      },
      "automatic_pm_enabled" : "true",
      "kdump_detection" : "true",
      "type" : "apc"
    },
    "ksm" : {
      "enabled" : "false"
    },
    "transparent_hugepages" : {
      "enabled" : "true"
    },
    "iscsi" : {
      "initiator" : "iqn.1994-05.com.example:795610ff2632"
    },
    "ssh" : {
      "port" : "22",
      "fingerprint" : "77:27:38:25:8f:60:8d:93:9c:2c:b0:cb:5e:19:f4:53"
    },
    "cpu" : {
      "topology" : {
        "sockets" : "1",
        "cores" : "4",
        "threads" : "1"
      },
      "name" : "Intel(R) Core(TM)2 Quad CPU    Q9550  @ 2.83GHz",
      "speed" : 2833
    },
    "memory" : 2989490176,
    "max_scheduling_memory" : 2584739840,
    "summary" : {
      "active" : "0",
      "migrating" : "0",
      "total" : "0"
    },
    "protocol" : "stomp",
    "os" : {
      "version" : {
        "full_version" : "6Server - 6.6.0.2.el6"
      },
      "type" : "RHEL"
    },
    "libvirt_version" : {
      "major" : "0",
      "minor" : "10",
      "build" : "2",
      "revision" : "0",
      "full_version" : "libvirt-0.10.2-46.el6_6.2"
    },
    "kdump_status" : "disabled",
    "selinux" : {
      "mode" : "enforcing"
    },
    "auto_numa_status" : "unknown",
    "numa_supported" : "false",
    "live_snapshot_support" : "true",
    "actions" : {
      "link" : [ {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/fence",
        "rel" : "fence"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/approve",
        "rel" : "approve"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/forceselectspm",
        "rel" : "forceselectspm"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/iscsilogin",
        "rel" : "iscsilogin"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/iscsidiscover",
        "rel" : "iscsidiscover"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/commitnetconfig",
        "rel" : "commitnetconfig"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/deactivate",
        "rel" : "deactivate"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/install",
        "rel" : "install"
      }, {
        "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/activate",
        "rel" : "activate"
      } ]
    },
    "name" : "Host-07",
    "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe",
    "id" : "ea7aa772-d2af-4a5c-9350-d86f005c93fe",
    "link" : [ {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/storage",
      "rel" : "storage"
    }, {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/nics",
      "rel" : "nics"
    }, {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/numanodes",
      "rel" : "numanodes"
    }, {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/tags",
      "rel" : "tags"
    }, {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/statistics",
      "rel" : "statistics"
    }, {
      "href" : "/ovirt-engine/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/hooks",
      "rel" : "hooks"
    } ]
  } ]
}

14.4. 电源管理元素

power_management 元素允许用户设置电源管理配置,这是主机隔离所需要的。配置 power_management 时,需要特定的子元素。
表 14.2. 电源管理选项
元素 类型 Description Properties
type= 隔离设备代码 capabilities 集合中提供了有效的隔离设备代码列表。
enabled 布尔值: true 或 false 指明是否启用或禁用电源管理配置。
address 字符串 主机的主机名或 IP 地址。
用户名 字符串 电源管理的有效用户名。 
密码 字符串 用于电源管理的有效、强大的密码。 
选项 complex 所选 type= 的隔离选项使用选项 name=""value="" 字符串指定。 
agents complex 当使用多个隔离时指定隔离代理选项。使用 order 子元素来对隔离代理进行优先排序。代理会根据顺序运行,直到隔离操作成功为止。当两个或多个隔离代理具有相同的 顺序 时,它们会同时运行。其他子元素包括 类型ipuserpasswordoptions 
automatic_pm_enabled 布尔值: true 或 false 切换主机的自动电源控制,以节省能源。当设置为 true 时,如果集群的负载较低,则主机将自动关闭,并在需要时再次开机。当创建主机时,这设置为 true,除非由用户禁用。 
kdump_detection 布尔值: true 或 false 在关闭前,切换决定是否在主机上运行 kdump。当设置为 true 时,主机不会在 kdump 过程中关闭。当主机启用了电源管理时,这设置为 true,除非由用户禁用。 
options 元素需要 选项 子元素列表。每个 选项 都需要一个 名称和类型 属性。某些选项仅适用于功能集合中定义的特定隔离类型。
新主机在 POST到主机资源时包括可选的 power_management 配置。power_management 配置使用 PUT 请求。

例 14.3. 主机的电源管理配置的 XML 表示

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    ...
    <power_management type="ilo">
        <enabled>true</enabled>
        <address>192.168.1.107</address>
        <username>admin</username>
        <password>p@55w0Rd!</password>
        <options>
            <option name="secure" value="true"/>
            <option name="port" value="54345"/>
            <option name="slot" value="3"/>
        </options>
        <agents>
            <agent id="07f0b9ce-923a-4a96-a532-3c898fa8b6da">
                <type>apc</type>
                <order>1</order>
                <ip>192.168.1.111</ip>
                <user>example</user>
                <password>p@55w0rd!</password>
                <port>9</port>
                <options>
                    <option name="power_wait" value="5"/> 
                    <option name="secure" value="false"/>
                </options>
            </agent>
            <agent id="50c71ba2-8495-11e0-b931-e20e458819ed">
                <type>rsa</type>
                <order>2</order>
                <ip>192.168.1.112</ip>
                <user>example</user>
                <password>p@55w0rd!</password>
                <port>9</port>
                <options>
                    <option name="power_wait" value="5"/> 
                    <option name="secure" value="false"/>
                </options>
            </agent>
        </agents>
        <automatic_pm_enabled>true</automatic_pm_enabled>
        <kdump_detection>true</kdump_detection>
    </power_management>
    ...
</host>

14.5. 内存管理元素

API 为主机的内存管理提供了两个配置设置。
内核同页合并(KSM) 可减少从多个相同页面到单个页面参考对内存页面的引用。这有助于优化内存密度。KSM 使用 ksm 元素。

例 14.4. 设置 KSM 内存管理

PUT /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <ksm>true</ksm>
</host>
透明巨页支持将内存页 的大小扩展到标准 4kB 限制之外。这可减少内存消耗并增加主机性能。透明巨页支持使用 transparent_hugepages 元素。

例 14.5. 设置透明巨页内存管理

PUT /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <transparent_hugepages>true</transparent_hugepages>
</host>
Transparent Hugepage 支持的可用性包括在 功能 集合中。

14.6. Methods

14.6.1. 创建主机

创建新主机需要 名称、address root_password 元素。

例 14.6. 创建主机

POST /ovirt-engine/api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
    <name>host2</name>
    <address>host2.example.com</address>
    <root_password>p@55w0Rd!</root_password>
</host>
root_password 元素仅包含在客户端提供的初始表示中,它不在从后续请求返回的表示中公开。

14.6.2. 更新主机

name,description,cluster,power_management,transparent_hugepagesksm 元素是创建后的 updatable。

例 14.7. 更新主机

PUT /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
    <name>host3</name>
</host>

14.6.3. 删除主机

删除主机需要 DELETE 请求。

例 14.8. 删除主机

DELETE /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

14.7. sub-Collections

14.7.1. Host Network Attachments Sub-Collection

network_attachments 子集合表示主机的网络配置。每个 network_attachment 元素代表附加到主机的网络,包含以下元素:
表 14.3. 主机网络附加的元素
元素
类型
Description
Properties
network id=
GUID
对主机附加到的网络的引用。
host_nic id=
GUID
对网络附加到的主机网络接口的引用。
ip_address_assignments
complex
网络的 IP 配置。每个 ip_address_assignment 包含 assignment_methodip address= netmask= gateway= 子元素。
 
属性
complex
定义网络的自定义属性键。每个属性 都包含 namevalue 子元素。请参阅 第 14.7.2.3.2 节 “网络附加自定义属性”
 
reported_configurations
complex
网络附加的配置属性的只读列表。当网络附加与数据中心的逻辑网络定义不同步时,in_sync 布尔值为 false。每个 reported_configuration 包含 名称,expected_value,actual_value, 和 in_sync 子元素。
host id=
GUID
对主机的引用。

例 14.9. 主机上网络附加的 XML 表示

<network_attachment href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
    <host_nic href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <ip_address_assignments>
        <ip_address_assignment>
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
            <assignment_method>dhcp</assignment_method>
        </ip_address_assignment>
    </ip_address_assignments>
    <reported_configurations>
        <in_sync>true</in_sync>
        <reported_configuration>
            <name>mtu</name>
            <expected_value>1500</expected_value>
            <actual_value>1500</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>bridged</name>
            <expected_value>true</expected_value>
            <actual_value>true</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>vlan</name>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>boot_protocol</name>
            <expected_value>DHCP</expected_value>
            <actual_value>DHCP</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
    </reported_configurations>
    <host href="/ovirt-engine/api/hosts/f59a29cd-587d-48a3-b72a-db537eb21957" id="f59a29cd-587d-48a3-b72a-db537eb21957"/>
</network_attachment>
将网络附加到主机时,需要使用 idname网络和 host_nic 元素。host_nic ID 可以引用未使用的网络接口卡或绑定。

例 14.10. 将网络附加到主机

POST /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network_attachment>
    <network id="00000000-0000-0000-0000-000000000000"/>
    <host_nic id="00000000-0000-0000-0000-000000000000"/>
</network_attachment>
host_nicip_address_assignmentsproperties 元素是创建后的 updatable。更改 host_nic ID 将网络移动到不同的网络接口卡。

例 14.11. 修改主机网络附加

PUT /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network_attachment>
    <host_nic id="00000000-0000-0000-0000-000000000000"/>
    <ip_address_assignments>
        <ip_address_assignment> 
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
	    <assignment_method>static</assignment_method>
	</ip_address_assignment>
    </ip_address_assignments>
    <properties>
        <property>
	    <name>bridge_opts</name>
	    <value>
	        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
	    </value>
        </property>
    </properties>
</network_attachment>
在网络附加上使用 DELETE 请求从主机分离网络。

例 14.12. 从主机中分离网络

DELETE /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

HTTP/1.1 204 No Content
重要
必须明确提交对网络附加配置的更改。请参阅 第 14.8.8 节 “提交主机网络配置操作”

14.7.2. 主机网络接口子检测

14.7.2.1. 主机网络接口子检测
nics 子集合代表主机的物理网络接口。可以使用 All-Content: true 标头检索 GET 请求的其他信息。表示法中的每个 host_nic 元素都充当网络接口,包含以下元素:
表 14.4. 主机网络接口的元素
元素 类型 Description Properties
name 字符串 主机网络接口的名称,如 eth0 [a]
link rel="statistics" 关系 到主机网络接口 统计的统计信息 子集合的链接。
link rel="labels" 关系 到主机网络接口 标签的标签 子集合的链接。
link rel="networkattachments" 关系 到主机网络接口配置的 networkattachments 子集合的链接。 
link rel="master" 关系 如果这是从接口,则对主绑定接口的引用。
host id= GUID 对主机的引用。
network id= GUID 对网络的引用(如果有的话),该接口被附加。 [b]
mac address= 字符串 接口的 MAC 地址。
ip address= netmask= gateway= mtu= complex 接口的 IP 级别配置。 
mtu complex 接口的最大传输单元。 
boot_protocol Enumerated 主机引导时 IP 地址分配的协议。枚举的值列表包括在 能力 中。 
status Enumerated 网络接口的链接状态。这些状态列在 capabilities 下的 host_nic_states 中。
VLAN ID 整数 此接口代表的 VLAN。
绑定 complex 绑定接口 的选项 和从属 NIC 列表。 [c]
bridged 布尔值 定义网桥网络状态。对于网桥网络,设置为 true;对于无网桥网络,设置为 false 
[a] 仅在添加绑定接口时需要。其他接口是只读的,无法添加。
[b] 仅在添加绑定接口时需要。其他接口是只读的,无法添加。
[c] 仅在添加绑定接口时需要。其他接口是只读的,无法添加。

例 14.13. 主机上网络接口的 XML 表示

<host_nic id="00000000-0000-0000-0000-000000000000"
  href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
  00000000-0000-0000-0000-000000000000">
    <actions>
        <link rel="attach"
      href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
      00000000-0000-0000-0000-000000000000/attach"/>
        <link rel="detach"
      href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
      00000000-0000-0000-0000-000000000000/detach"/>
    </actions>
    <name>bond0</name>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/statistics" rel="statistics"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels" rel="labels"/>
    <link href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments" rel="networkattachments"/>
    <host href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <mac address="00:00:00:00:00:00"/>
    <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
    <boot_protocol>dhcp</boot_protocol>
    <status>
        <state>up</state>
    </status>
    <bonding>
        <options>
            <option name="mode" value="4" type="Dynamic link aggregation (802.3ad)"/>
            <option name="miimon" value="100"/>
        </options>
        <slaves>
            <host_nic id="00000000-0000-0000-0000-000000000000"/>
            <host_nic id="00000000-0000-0000-0000-000000000000"/>
        </slaves>
    </bonding>
    <mtu>1500</mtu>
    <bridged>true</bridged>
    <custom_configuration>false</custom_configuration>
</host_nic>
在 REST API 中,您只能创建绑定接口。请参阅 第 14.7.2.2 节 “绑定接口”。所有其他网络接口都包含 updatable 网络ipboot_protocol 元素。
使用 PUT 请求修改网络接口。
PUT /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host_nic>
    <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
    <boot_protocol>static</boot_protocol>
</host_nic>
删除具有 DELETE 请求的网络接口。
DELETE /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content
14.7.2.2. 绑定接口
绑定接口表示为 host_nic 资源,其中包含 bonding 元素。
表 14.5. 绑定接口属性
元素 类型 Description Properties
选项 complex 绑定接口 的选项 元素列表。每个 选项 都包含属性 namevalue 属性。 [a]
Slaves complex 绑定接口从属 host_nic id= 元素的列表。 [b]
[a] 仅在添加绑定接口时需要。其他接口是只读的,无法添加。
[b] 仅在添加绑定接口时需要。其他接口是只读的,无法添加。
在创建新 host_nic (POST)或更新 host_nic (PUT)时,API 用户创建新的绑定。使用 idname 元素来识别从属 host_nic 元素。添加新网络接口时,需要 namenetwork 元素。使用 id 属性或 name 元素标识 network 元素。

例 14.14. 创建绑定接口

POST /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<host_nic>
    <name>bond4</name>
    <network id="00000000-0000-0000-0000-000000000000"/>
    <bonding>
        <slaves>
            <host_nic id="00000000-0000-0000-0000-000000000000"/>
            <host_nic id="00000000-0000-0000-0000-000000000000"/>
        </slaves>
    </bonding>
</host_nic>
重要的
bond0bond1、 bond2、bond3bond4 是绑定接口的唯一有效名称。

例 14.15. 删除绑定接口

删除带有 DELETE 请求的绑定接口。
DELETE /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content
重要的
必须明确提交对绑定接口配置的更改。请参阅 第 14.8.8 节 “提交主机网络配置操作”
14.7.2.3. 网络接口网络附件
14.7.2.3.1. 网络接口网络附件
主机上的每个网络接口都公开一个 network_attachments 子集合,代表网卡的网络附加定义。每个 network_attachment 代表附加到网络接口的网络,并包含以下元素:
表 14.6. 主机网络接口网络附加的元素
元素
类型
Description
Properties
network id=
GUID
对接口附加到的网络的引用。
host_nic id=
GUID
对主机网络接口的引用。
ip_address_assignments
complex
网络的 IP 配置。每个 ip_address_assignment 包含 assignment_methodip address= netmask= gateway= 子元素。
 
属性
complex
定义网络的自定义属性键。每个属性 都包含 namevalue 子元素。
 
reported_configurations
complex
网络附加的配置属性的只读列表。当网络附加包含未提交的网络配置时,in_sync 布尔值为 false。每个 reported_configuration 包含 名称,expected_value,actual_value, 和 in_sync 子元素。

例 14.16. 网络接口卡中网络附加定义的 XML 表示

<network_attachment href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
    <host_nic href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <ip_address_assignments>
        <ip_address_assignment>
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
            <assignment_method>static</assignment_method>
        </ip_address_assignment>
    </ip_address_assignments>
    <reported_configurations>
        <in_sync>true</in_sync>
        <reported_configuration>
            <name>mtu</name>
            <expected_value>1500</expected_value>
            <actual_value>1500</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>bridged</name>
            <expected_value>true</expected_value>
            <actual_value>true</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>vlan</name>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>boot_protocol</name>
            <expected_value>DHCP</expected_value>
            <actual_value>DHCP</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
    </reported_configurations>
</network_attachment>
将网络附加到网卡时,需要使用 idnamenetwork 元素。

例 14.17. 将网络附加到主机网卡

POST /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments HTTP/1.1
Accept: application/xml
Content-type: application/xml

<networkattachment>
    <network id="00000000-0000-0000-0000-000000000000"/>
</networkattachment>
ip_address_assignmentsproperties 元素是创建后的 updatable。

例 14.18. 修改网络附加

PUT /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<networkattachment>
    <ip_address_assignments>
        <ip_address_assignment> 
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
	    <assignment_method>static</assignment_method>
	</ip_address_assignment>
    </ip_address_assignments>
</networkattachment>
使用网络附加上的 DELETE 请求从网卡中分离网络。

例 14.19. 从主机网络接口卡中分离网络

DELETE /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

HTTP/1.1 204 No Content
重要
必须明确提交对网络附加配置的更改。请参阅 第 14.8.8 节 “提交主机网络配置操作”
14.7.2.3.2. 网络附加自定义属性
自定义属性可应用于网络附加。每个属性都包含 namevalue 子元素。要修改自定义属性,请在网络附加上执行 PUT 请求,或使用 setupnetworks 操作执行 POST 请求。
表 14.7. 主机网络接口的自定义网桥选项的元素
元素 类型 描述
name 字符串 属性的唯一标识符。网桥选项设置 bridge_opts 的名称。
value 字符串 网桥选项,由有效键和值表示,语法如下: [key]=[value]。使用空格字符分隔多个条目。以下键有效,示例提供的值:

forward_delay=1500
gc_timer=3765 
group_addr=1:80:c2:0:0:0
group_fwd_mask=0x0
hash_elasticity=4
hash_max=512
hello_time=200
hello_timer=70
max_age=2000
multicast_last_member_count=2
multicast_last_member_interval=100
multicast_membership_interval=26000
multicast_querier=0
multicast_querier_interval=25500
multicast_query_interval=13000
multicast_query_response_interval=1000
multicast_query_use_ifaddr=0
multicast_router=1
multicast_snooping=1
multicast_startup_query_count=2
multicast_startup_query_interval=3125

例 14.20. 网络附加属性子集合的 XML 表示

<network_attachment>
  ...
  <properties>
    <property>
      <name>bridge_opts</name>
      <value>
        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
      </value>
    </property>
  </properties>
  ...
</network_attachment>
14.7.2.4. 网络接口标签
您可以将标签附加到主机网卡,以自动将该网卡与附加相同标签的逻辑网络的关联。

例 14.21. 将标签附加到网卡

POST /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels HTTP/1.1
Accept: application/xml
Content-type: application/xml

<label id="Label_001" />
从物理主机网卡中删除标签需要 DELETE 请求。

例 14.22. 从网卡中删除标签

DELETE /ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content
14.7.2.5. 网络接口统计信息
每个主机的网络接口会公开主机网络接口 统计信息的统计信息 子集合。每个统计 都包含以下元素:
表 14.8. 主机网络接口统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
host_nic id= 关系 与包含 host_nic 资源的关系。
下表列出了主机上网络接口的统计类型。
表 14.9. 主机 NIC 统计类型
名称
Description
data.current.rx
接收的数据每秒的速率(以字节/秒为单位)。
data.current.tx
传输数据的每秒速率(以字节/秒为单位)。
data.total.rx
接收的总数据。
data.total.tx
传输的总数据。
errors.total.rx
接收数据的总错误。
errors.total.tx
传输数据的总错误。

例 14.23. 主机网络接口统计子集合的 XML 表示

<statistics>
    <statistic id="00000000-0000-0000-0000-000000000000"
      href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
      00000000-0000-0000-0000-000000000000/statistics/
      00000000-0000-0000-0000-000000000000">
        <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>
        <host_nic id="00000000-0000-0000-0000-000000000000"
          href="/ovirt-engine/api/hosts/00000000-0000-0000-0000-000000000000/nics/
          00000000-0000-0000-0000-000000000000"/>
    </statistic>
    ...
</statistics>
注意
这个 统计 子集合是只读的。

14.7.3. Storage Sub-Collection

存储 子集合提供了主机上可用的 iSCSI 和 FCP 存储表示列表。此存储用于创建存储域。
子集合中的每个 存储 代表 SCSI LUN。

例 14.24. 主机上存储子集合的 XML 表示

<host_storage>
    <storage id="82fb123b-321e-40a1-9889-95dcd2654463"
      href="/ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage/
      82fb123b-321e-40a1-9889-95dcd2654463">
        <name>LUN0</name>
        <type>iscsi</type>
        <logical_unit id="LUN0">
            <address>mysan.example.com</address>
            <target>iqn.2009-08.com.example:mysan.foobar</target>
        </logical_unit>
    </storage>
</host_storage>
注意
host_storage 集合是只读的。
重要的
如本节所述的 API 是实验性的,可能随时更改。它不包含在向后兼容声明中。

14.7.4. 主机 NUMA 节点子注入

14.7.4.1. NUMA 节点子注入
numanodes 子集合表示主机的 NUMA 拓扑。子集合中的每个 host_numa_node 元素代表 NUMA 节点。

例 14.25. 主机上 numanodes 子集合的 XML 表示

<host_numa_nodes>
    <host_numa_node href="/ovirt-engine/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-699e-460b-9a70-285f651e7d68" id="91d8537c-699e-460b-9a70-285f651e7d68">
        <link href="/ovirt-engine/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-699e-460b-9a70-285f651e7d68/statistics" rel="statistics"/>
        <host href="/ovirt-engine/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2" id="f6735fa9-4ee5-47ce-b750-a87863736cc2"/>
        <index>0</index>
        <memory>8157</memory>
        <cpu>
            <cores>
                <core index="0"/>
                <core index="2"/>
                <core index="4"/>
                <core index="6"/>
            </cores>
        </cpu>
        <node_distance>10 16</node_distance>
    </host_numa_node>
    <host_numa_node href="/ovirt-engine/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/4b18926e-6faf-43f5-9fc2-0503f1531562" id="4b18926e-6faf-43f5-9fc2-0503f1531562">
        <link href="/ovirt-engine/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/4b18926e-6faf-43f5-9fc2-0503f1531562/statistics" rel="statistics"/>
        <host href="/ovirt-engine/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2" id="f6735fa9-4ee5-47ce-b750-a87863736cc2"/>
        <index>2</index>
        <memory>8175</memory>
        <cpu>
            <cores>
                <core index="1"/>
                <core index="3"/>
                <core index="5"/>
                <core index="7"/>
            </cores>
        </cpu>
        <node_distance>16 10</node_distance>
    </host_numa_node>
</host_numa_nodes>
注意
host_numa_nodes 子集合为只读。
14.7.4.2. NUMA 节点统计信息
每个主机 NUMA 节点会公开 NUMA 节点 统计的统计信息 子集合。每个统计 都包含以下元素:
表 14.10. 主机的 NUMA 节点统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
host_numa_node id= 关系 与包含 numanode 资源的关系。
下表列出了主机 NUMA 节点的统计类型。
表 14.11. 主机 NUMA 节点统计信息
名称 描述
memory.total NUMA 节点上的内存总量(以字节为单位)。
memory.used NUMA 节点上使用的内存(以字节为单位)。
memory.free NUMA 节点上可用内存(以字节为单位)。
cpu.current.user 用户的 CPU 用量百分比。
cpu.current.system 系统的 CPU 用量百分比。
cpu.current.idle 空闲 CPU 用量百分比。

例 14.26. 主机 NUMA 节点统计子集合的 XML 表示

<statistics>
    <statistic href="/ovirt-engine/api/hosts/f6745fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-689e-460b-9a70-285f651e7d68/statistics/7816602b-c05c-3dc7-a4da-3769f7ad8896" id="7816602b-c05c-3dc7-a4da-3769f7ad8896">
        <name>memory.total</name>
        <description>Total memory</description>
        <values type="INTEGER">
            <value>
                <datum>8157</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES</unit>
        <host_numa_node href="/ovirt-engine/api/hosts/f6745fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-689e-460b-9a70-285f651e7d68" id="91d8537c-689e-460b-9a70-285f651e7d68"/>
    </statistic>
    ...
</statistics>
注意
主机 NUMA 节点的 统计 子集合是只读的。

14.7.5. 主机统计信息 Sub-Collection

14.7.5.1. 主机统计信息 Sub-Collection
每个主机资源会公开特定于主机的 统计的统计 子集合。每个统计 都包含以下元素:
表 14.12. 主机统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
host id= 关系 与包含 主机资源 的关系。
下表列出了主机的统计类型。
表 14.13. 主机统计类型
名称
描述
memory.total
主机上内存总量(以字节为单位)。
memory.used
主机上使用的内存(以字节为单位)。
memory.free
主机上可用内存(以字节为单位)。
memory.shared
主机上共享的内存(以字节为单位)。
memory.buffers
I/O 缓冲区以字节为单位。
memory.cached
OS 以字节为单位缓存。
swap.total
主机上的交换内存总量(以字节为单位)。
swap.free
主机上空闲的交换内存(以字节为单位)。
swap.used
主机上使用的交换内存(以字节为单位)。
swap.cached
交换内存(以字节为单位)也缓存在主机的内存中。
ksm.cpu.current
内核同页合并的 CPU 用量百分比。
cpu.current.user
用户的 CPU 用量百分比。
cpu.current.system
系统的 CPU 用量百分比。
cpu.current.idle
空闲 CPU 用量百分比。
cpu.load.avg.5m
五分钟的平均 CPU 负载平均值。

例 14.27. 主机统计子集合的 XML 表示

<statistics>
    <statistic id="4ae97794-f56d-3f05-a9e7-8798887cd1ac"
      href="/ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/
      statistics/4ae97794-f56d-3f05-a9e7-8798887cd1ac">
        <name>memory.total</name>
        <description>Total memory</description>
        <unit>BYTES</unit>
        <type>GUAGE</type>
        <values type="INTEGER">
            <value>
                <datum>3983540224<datum>
            </value>
        </values>
        <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
          href="/ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    </statistic>
    ...
</statistics>
备注
主机 统计 子集合是只读的。

14.8. Actions

14.8.1. 安装 VDSM 操作

在主机上安装 VDSM 及相关软件。

例 14.28. 在虚拟化主机上安装 VDSM 的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <root_password>p@55w0Rd!</root_password>
</action>

14.8.2. 激活主机操作

激活主机以供使用,如正在运行的虚拟机。

例 14.29. 激活主机的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

14.8.3. 主机网络设置操作

在主机上配置多个网络设置。setupnetworks 操作可用于复杂的网络配置,如将网络从一个网络接口移动到另一个网络接口。

例 14.30. 编辑主机网络配置的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/setupnetworks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <modified_network_attachments>
        <network_attachment id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
            <host_nic id="857a46d3-5f64-68bd-f456-c70de5b2d569"/>
        </network_attachment<
        <network_attachment id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
            <network id="00000000-0000-0000-0000-000000000010"/>
            <ip address="10.35.1.247" netmask="255.255.254.0" gateway="10.35.1.254"/>
	    <properties>
		<property>
		    <name>bridge_opts</name>
		    <value>
			forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
		    </value>
		</property>
	    </properties>
        </network_attachment>
    </modified_network_attachments>
    <synchronized_network_attachments>
        <network_attachment id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
    </synchronized_network_attachments> 
    <removed_network_attachments>
        <network_attachment id="7f456dae-c57f-35d5-55a4-20b74dc53af9">
    </removed_network_attachments>
    <modified_bonds>
        <host_nic id="a56b212d-2bc4-4120-9136-53be6cacb39a">
	    <bonding>
		<slaves>
		    <host_nic id="75ac21f7-4aa3-405a-a022-341e5f525b85">
		    <host_nic id="f3dda04c-1233-41af-a111-74327b876487">
		</slaves>
	    </bonding>
        </host_nic>
    </modified_bonds>
    <removed_bonds>
        <host_nic id="36ab5c7f-647a-bc64-f5e7-ba5d74f8e4ba">
    </removed_bonds>
    <modified_labels>
        <label id="Label002">
	    <host_nic id="857a46d3-5f64-68bd-f456-c70de5b2d569"/>
        </label>
        <label>
	    <host_nic id="a56b212d-2bc4-4120-9136-53be6cacb39a"/>
	    <label id="Label003/>
        </label>
    </modified_labels>  
    <removed_labels>
        <label id="Label001">
    </removed_labels>
    <checkConnectivity>true</checkConnectivity>
    <connectivityTimeout>60</connectivityTimeout>
</action>
此操作使用标准 NIC 元素更新所有指定的主机网络资源。请求包括下表中指定的其他元素。
表 14.14. 多个主机网络接口设置的元素
元素 类型 Description
modified_bonds complex 创建或更新绑定。每个 host_nic 元素都包含标准 绑定 元素。请参阅 第 14.7.2.2 节 “绑定接口”
removed_bonds complex 要删除的绑定的 ID 列表。
modified_network_attachments complex 在主机上添加或更新网络附加。每个 network_attachment 元素都包含标准主机 network_attachment 元素。请参阅 第 14.7.1 节 “Host Network Attachments Sub-Collection”。更改 host_nic ID 将网络移动到不同的网络接口卡。
synchronized_network_attachments complex 与数据中心的逻辑网络定义同步的非同步网络附加定义的 ID 列表。
removed_network_attachments complex 要删除的网络附加的 ID 列表。
modified_labels complex 创建或修改标签。每个 标签 元素包含一个 标签 id (创建标签时),以及通过名称或 ID 标识的 host_nic。更改 host_nic ID 将标签移到不同的网卡中。
removed_labels complex 要删除的标签的 ID 列表。
checkConnectivity 布尔值 设置为 true 以验证主机和 Red Hat Virtualization Manager 之间的连接。如果连接丢失,Red Hat Virtualization Manager 会恢复设置。
connectivityTimeout 整数 定义连接丢失的超时。

14.8.4. 隔离主机操作

API 用户使用 隔离操作 控制主机的电源管理设备。capabilities 列出了可用的 fence_type 选项。

例 14.31. 隔离主机的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/fence
Accept: application/xml
Content-Type: application/xml

<action>
    <fence_type>start</fence_type>
</action>

14.8.5. 取消激活主机操作

取消激活主机来执行维护任务。

例 14.32. 取消激活主机的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

14.8.6. 主机 iSCSI 登录操作

iscsilogin 操作可让主机登录到 iSCSI 目标。登录目标可让 host_storage 集合中可用包含的 LUN。

例 14.33. 启用主机登录到 iSCSI 目标的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsilogin HTTP/1.1
Accept: application/xml
Content-Type: application/xml


<action>
    <iscsi>
        <address>mysan.example.com</address>
        <target>iqn.2009-08.com.example:mysan.foobar</target>
        <username>jimmy</username>
        <password>s3kr37</password>
    </iscsi>
</action>

14.8.7. 主机 iSCSI 发现操作

iscsidiscover 操作可让 iSCSI 门户查询其目标列表。

例 14.34. 查询 iSCSI 门户目标列表的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
    <iscsi>
        <address>mysan.example.com</address>
        <port>3260</port>
    </iscsi>
</action>

14.8.8. 提交主机网络配置操作

API 用户提交网络配置以持久保留主机网络接口附加或分离,或者持续创建和删除绑定接口。

例 14.35. 提交网络配置的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/commitnetconfig HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
重要的
只有在管理器建立主机连接后,才会提交网络配置,因为配置更改不会丢失。如果主机连接丢失,主机需要重新引导,并自动恢复到前面的网络配置。

14.8.9. 设置 SPM

手动将主机设置为存储池管理程序(SPM)。

例 14.36. 将主机设置为 SPM 的操作

POST /ovirt-engine/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/forceselectspm HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

第 15 章 虚拟机

15.1. 虚拟机元素

vms 集合提供有关 Red Hat Virtualization 环境中虚拟机的信息。API 用户通过从入口点 URI 获取的 rel="vms" 链接访问此信息。
可以使用 All-Content: true 标头检索 GET 请求的其他信息。
下表显示了虚拟机资源表示法中包含的特定元素。
表 15.1. 虚拟机元素
元素 类型 Description Properties
link rel="applications" 关系 到虚拟机资源的 applications 子集合的链接,它显示虚拟机上安装的应用程序。 
link rel="disks" 关系 与虚拟机资源 的磁盘 子集合的链接。 
link rel="nics" 关系 到虚拟机资源的 nics 子集合的链接。 
link rel="numanodes" 关系 虚拟机资源的 numanodes 子集合的链接。 
link rel="cdroms" 关系 到虚拟机资源的 cdroms 子集合的链接。 
link rel="snapshots" 关系 到虚拟机资源 的快照 子集合的链接。 
link rel="tags" 关系 到虚拟机资源的 tags 子集合的链接。 
link rel="permissions" 关系 到虚拟机 权限权限 子集合的链接。 
link rel="statistics" 关系 到虚拟机资源 统计 子集合的链接。
link rel="reporteddevices"
关系
到虚拟机资源的 reporteddevices 子集合的链接。
 
link rel="watchdogs"
关系
到虚拟机资源的 watchdogs 子集合的链接。
 
link rel="sessions"
关系
到虚拟机资源的 sessions 子集合的链接。
 
type Enumerated 虚拟机类型。功能 中提供了枚举的值的列表。
status 请参见以下 虚拟机状态。
内存 整数 分配给客户机的内存量,以字节为单位。
cpu complex
定义虚拟机的 CPU 详情。拓扑 子元素设置可用于客户机的逻辑 套接字数量,以及 每个插槽的内核数。虚拟机可用的内核总数等于插槽的数量乘以每个插槽的内核。
cputune 子元素使用一系列 vcpupin 元素将虚拟 CPU 映射到物理主机 CPU。每个 vcpupin 元素都包含虚拟 CPU 属性(vcpu)和用于定义要使用的物理(cpuset)的属性。将 cpuset 设置为单个 CPU (cpuset="0")、多个 CPU (cpuset="0,2")、CPU 范围(cpuset="0-3")或具有排除的 CPU 范围(cpuset="0-3,^2")。
cpu_mode 子元素定义虚拟 CPU 与主机 CPU 的关系。它有三个值:如果没有给出任何模式,host_model 复制主机 CPU 的最佳值,host_passthrough 会将主机的所有方面传递给客户机,即使 libvirt 无法识别这些模式。但是,host_passthrough 将阻止迁移该虚拟机。
os type= 字符串,如 RHEL5WindowsXP 客户机操作系统类型。
OS 引导 dev= Enumerated 在引导元素中 dev 属性描述的 引导设备 列表。功能 中提供了枚举的值的列表。
OS 内核 字符串 为虚拟机配置的内核镜像的路径。这个选项支持直接引导 Linux 内核,而不是通过 BIOS 引导装载程序引导。
OS initrd 字符串 与之前指定内核一起使用的 initrd 镜像的路径。这个选项支持直接引导 Linux 内核,而不是通过 BIOS 引导装载程序引导。
OS cmdline 字符串 与定义的内核一起使用的内核命令行参数字符串。这个选项支持直接引导 Linux 内核,而不是通过 BIOS 引导装载程序引导。
high_availability complex 如果虚拟机或其主机崩溃,则设置为 true优先级 元素控制虚拟机重新启动的顺序。 
显示 complex
显示 类型 ( vncspice)、port 以及 监视器 的数量。allow_reconnect 布尔值指定客户端是否可以通过显示重新连接到机器。
smartcard_enabled 子元素是一个布尔值(truefalse),用于指定附加到客户端的智能卡是否传递到虚拟机。默认值为 false
 
cluster id= GUID 对虚拟机的主机集群的引用。
template id= GUID 对此虚拟机所基于的模板的引用。
domain id= GUID 对虚拟机域的引用。
start_time xsd:dateTime 格式: YYYY-MM-DDTh:mm:ss 此虚拟机启动的日期和时间。
stop_time xsd:dateTime 格式: YYYY-MM-DDTh:mm:ss 此虚拟机停止的日期和时间。
creation_time xsd:dateTime 格式: YYYY-MM-DDTh:mm:ss 创建此虚拟机的日期和时间。
origin rhev,ovirt,vmwarexen之一 此虚拟机源自的系统。
无状态 布尔值: true 或 false 如果虚拟机无状态,则为 true。无状态虚拟机包含在启动时获取的磁盘镜像的快照,并在关机时删除。这意味着状态更改在重启后不会保留。 
delete_protected 布尔值: true 或 false 如果设置为 true,则无法删除虚拟机。 
sso 字符串 对虚拟机单点登录方法的引用。包括带有 ip 属性 的方法 元素。 
placement_policy complex 为虚拟机迁移设置放置策略。需要默认的 host=关联性 (一个可 migratableuser_migratable固定)。将 host 元素留空,以设置任何首选主机。使用多个主机元素来指定集群中首选主机的子集。 
memory_policy complex 为虚拟机设置内存策略。定义主机上 保证的 最小内存量,以便虚拟机运行。 
quota id= GUID 为虚拟机设置配额。 
custom_properties complex 一组用户定义的环境变量,作为参数传递给自定义脚本。每个 custom_property 都包含 namevalue 属性。功能 中提供了枚举的值的列表。 
usb complex 定义虚拟机的 USB 策略。要求将 enabled 元素设置为布尔值,并且 type 元素设为 nativelegacy
重要
Legacy USB 选项已弃用,并将在 Red Hat Virtualization 4.1 中删除。
 
migration_downtime 整数 代表虚拟机在实时迁移期间可以停机的最大毫秒数。值 0 表示将使用 VDSM 默认值。 
cpu_profile id= GUID 对虚拟机的 cpu 配置集的引用。 
next_run_configuration 布尔值: true 或 false 如果虚拟机下次重启时将应用对虚拟机的配置进行更改,则为 true 
numa_tune_mode 字符串 引用主机 NUMA 节点的内存分配模式(交集严格首选)。 
guest_info complex 对客户机客户端信息的引用。包含带有 address= 属性的 ip 元素。
vmpool complex 对虚拟机池的引用。这个元素仅针对池的虚拟机部分出现。
timezone tz 数据库格式: Area/Location Windows 虚拟机的 Sysprep 时区设置。 
domain complex Windows 虚拟机的 Sysprep 域设置。需要 集合中的 名称 
初始化 complex
定义在启动时应用于虚拟机的值列表,使用 Cloud-Init 用于基于 Linux 的虚拟机,或 Sysprep 为基于 Windows 的虚拟机。
  • HOST_NAME :虚拟机的主机名
  • timezone :虚拟机的时区。
  • user_name :虚拟机的用户名。
  • root_password :用户的密码,如果未指定用户,则为 root 密码。
  • authorized_ssh_keys :添加到虚拟机的授权密钥文件中的SSH 密钥。您可以通过用换行符分隔每个 SSH 密钥来输入多个 SSH 密钥。
  • regenerate_ssh_keys :是否为虚拟机重新生成 SSH 密钥。可能的值为 truefalse
  • dns_serversDNS 服务器以空格分隔的列表。
  • dns_searchDNS 搜索域以空格分隔的列表。
  • nic_configurations :为虚拟机定义网络接口控制器。网络接口控制器在这个集合下被定义为 nic_configuration 对象,每个对象都指定名称、ipboot_protocolon_boot
  • custom_script :在启动时在虚拟机上运行的自定义脚本。
  • HOST_NAME :虚拟机的主机名
  • :虚拟机所属的域。
  • authorized_ssh_keys :添加到虚拟机的授权密钥文件中的SSH 密钥。您可以通过用换行符分隔每个 SSH 密钥来输入多个 SSH 密钥。
  • regenerate_ssh_keys :是否为虚拟机重新生成 SSH 密钥。可能的值为 truefalse
  • timezone :虚拟机的时区。
  • root_password :虚拟机的 admin 用户的密码。
  • custom_script :在启动时在虚拟机上运行的自定义脚本。
  • input_locale :用户输入的区域设置。
  • ui_language :用于用户界面元素的语言,如按钮和菜单。
  • system_locale :整个系统的区域设置。
  • user_locale :用户的区域设置。
  • active_directory_ou :虚拟机所属的 Active Directory 域中的组织单元。
  • org_name :虚拟机所属组织的名称。
有效负载 complex
定义一组 有效负载 元素,以便在引导时向虚拟机提供内容。每个 有效负载 都需要 type 属性,可以是 cdromfloppy,以及一组文件元素。各个文件元素都是 name 元素,用于指定文件的名称和位置,以及定义要发送到该文件的内容的内容。
payloads 元素供 cloud-init 功能使用。当使用 cloud-init 配置虚拟机时,会自动创建一个有效负载,并将 type 属性设置为 cd-rom,以及两个文件子元素,openstack/latest/meta_data.jsonopenstack/latest/user_data,它将配置参数传递给虚拟机。
 
status 包含以下枚举的值之一: 未分配,down,up,powering_up,powered_down,paused,migrate_from,migrate_to,unknown,not_responding,wait_for_launch,reboot_in_progress, saving_state,restoring_state , suspended ,image_illegal,image_lockedpowering_down.这些状态列在 capabilities 下的 vm_states 中。

15.2. 虚拟机 XML 表述

例 15.1. 虚拟机的 XML 表示

<vm id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a">
    <actions>
        <link rel="move"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/move"/>
        <link rel="ticket"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/ticket"/>
        <link rel="reboot"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/reboot"/>
        <link rel="undo_snapshot"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/undo_snapshot"/>
        <link rel="commit_snapshot"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/commit_snapshot"/>
        <link rel="preview_snapshot"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/preview_snapshot"/>
        <link rel="logon"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/logon"/>
        <link rel="cancelmigration"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/cancelmigration"/>
        <link rel="maintenance"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/maintenance"/>
        <link rel="clone"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/clone"/>
        <link rel="migrate"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/migrate"/>
        <link rel="detach"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/detach"/>
        <link rel="export"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/export"/>
        <link rel="shutdown"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/shutdown"/>
        <link rel="start"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/start"/>
        <link rel="stop"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/stop"/>
        <link rel="suspend"
	  href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/suspend"/>
    </actions>
    <name>VM_01</name>
    <description>Testing Virtual Machine</description>
    <link rel="applications"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/applications"/>
    <link rel="disks"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/disks"/>
    <link rel="nics"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/nics"/>
    <link rel="numanodes"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/numanodes"/>
    <link rel="cdroms"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/cdroms"/>
    <link rel="snapshots"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/snapshots"/>
    <link rel="tags"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/tags"/>
    <link rel="permissions"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/permissions"/>
    <link rel="statistics"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/statistics"/>
    <link rel="reporteddevices"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/reporteddevices"/>
    <link rel="watchdogs"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/watchdogs"/>
    <link rel="sessions"
      href="/ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/sessions"/>
    <type>server</type>
    <status>
        <state>down</state>
    </status>
    <memory>1073741824</memory>
    <cpu>
        <topology sockets="1" cores="1"/>
        <architecture>X86_64</architecture>
    </cpu>
    <cpu_shares>0</cpu_shares>
    <bios>
        <boot_menu>
            <enabled>false</enabled>
        </boot_menu>
    </bios>
    <os type="other">
        <boot dev="hd"/>
    </os>
    <high_availability>
        <enabled>false</enabled>
        <priority>1</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
        <single_qxl_pci>false</single_qxl_pci>
        <allow_override>true</allow_override>
        <smartcard_enabled>false</smartcard_enabled>
        <file_transfer_enabled>true</file_transfer_enabled>
        <copy_paste_enabled>true</copy_paste_enabled>
    </display>
    <cluster href="/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb" id="00000001-0001-0001-0001-0000000002fb"/>
    <template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <stop_time>2014-12-03T14:25:45.588+10:00</stop_time>
    <creation_time>2014-12-03T14:25:45.535+10:00</creation_time>
    <origin>ovirt</origin>
    <stateless>false</stateless>
    <delete_protected>false</delete_protected>
    <sso>
        <methods>
            <method id="GUEST_AGENT"/>
        </methods>
    </sso>
    <timezone>Etc/GMT</timezone>
    <placement_policy>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>1073741824</guaranteed>
    </memory_policy>
    <usb>
        <enabled>false</enabled>
    </usb>
    <migration_downtime>-1</migration_downtime>
    <cpu_profile href="/ovirt-engine/api/cpuprofiles/0000001a-001a-001a-001a-0000000002e3" id="0000001a-001a-001a-001a-0000000002e3"/>
    <next_run_configuration_exists>false</next_run_configuration_exists>
    <numa_tune_mode>interleave</numa_tune_mode>
</vm>

15.3. 虚拟机的 XML 表表示虚拟机的额外 OVF 数据

使用带有 All-Content: true 标头的虚拟机的 GET 请求,使其包含带有虚拟机表示的额外 OVF 数据。
如果留空,则 Accept 标头默认为 application/xml,数据则以 HTML 实体表示,从而不会影响 XML 标签。指定 Accept: application/json 标头将在标准 XML 标记中返回数据。此示例表示已从标准块格式格式化,以提高 leg 可访问性。

例 15.2. 虚拟机的附加 ovf 数据的 XML 表示

GET /ovirt-engine/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a 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/> 
  <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> 
  </Section> 
  <Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type"> 
    <CreationDate>2014/12/03 04:25:45</CreationDate> 
    <ExportDate>2015/02/09 14:12: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_export</Name> 
    <TemplateId>00000000-0000-0000-0000-000000000000</TemplateId> 
    <TemplateName>Blank</TemplateName> 
    <IsInitilized>false</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="70b4d9a7-4f73-4def-89ca-24fc5f60e01a" 
      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>USB Controller</rasd:Caption> 
        <rasd:InstanceId>3</rasd:InstanceId> 
        <rasd:ResourceType>23</rasd:ResourceType> 
        <rasd:UsbPolicy>DISABLED</rasd:UsbPolicy> 
      </Item> 
    </Section> 
  </Content> 
</ovf:Envelope>

15.4. JSON 代表虚拟机

例 15.3. 虚拟机的 JSON 表示

{
  "type" : "server",
  "status" : {
    "state" : "down"
  },
  "stop_reason" : "",
  "memory" : 1073741824,
  "cpu" : {
    "topology" : {
      "sockets" : "1",
      "cores" : "1"
    },
    "architecture" : "X86_64"
  },
  "cpu_shares" : "0",
  "bios" : {
    "boot_menu" : {
      "enabled" : "false"
    }
  },
  "os" : {
    "boot" : [ {
      "dev" : "hd"
    } ],
    "type" : "other"
  },
  "high_availability" : {
    "enabled" : "false",
    "priority" : "1"
  },
  "display" : {
    "type" : "spice",
    "monitors" : "1",
    "single_qxl_pci" : "false",
    "allow_override" : "false",
    "smartcard_enabled" : "false",
    "file_transfer_enabled" : "true",
    "copy_paste_enabled" : "true"
  },
  "cluster" : {
    "href" : "/ovirt-engine/api/clusters/00000001-0001-0001-0001-0000000002fb",
    "id" : "00000001-0001-0001-0001-0000000002fb"
  },
  "template" : {
    "href" : "/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000",
    "id" : "00000000-0000-0000-0000-000000000000"
  },
  "stop_time" : 1423550982110,
  "creation_time" : 1423490033647,
  "origin" : "ovirt",
  "stateless" : "false",
  "delete_protected" : "false",
  "sso" : {
    "methods" : {
      "method" : [ {
        "id" : "GUEST_AGENT"
      } ]
    }
  },
  "timezone" : "Etc/GMT",
  "initialization" : {
    "regenerate_ssh_keys" : "false",
    "nic_configurations" : { }
  },
  "placement_policy" : {
    "affinity" : "migratable"
  },
  "memory_policy" : {
    "guaranteed" : 1073741824,
    "ballooning" : "true"
  },
  "usb" : {
    "enabled" : "false"
  },
  "migration_downtime" : "-1",
  "cpu_profile" : {
    "href" : "/ovirt-engine/api/cpuprofiles/0000001a-001a-001a-001a-0000000002e3",
    "id" : "0000001a-001a-001a-001a-0000000002e3"
  },
  "next_run_configuration_exists" : "false",
  "numa_tune_mode" : "interleave",
  "actions" : {
    "link" : [ {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/ticket",
      "rel" : "ticket"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/move",
      "rel" : "move"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/clone",
      "rel" : "clone"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/commit_snapshot",
      "rel" : "commit_snapshot"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/preview_snapshot",
      "rel" : "preview_snapshot"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/logon",
      "rel" : "logon"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/cancelmigration",
      "rel" : "cancelmigration"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/maintenance",
      "rel" : "maintenance"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/reboot",
      "rel" : "reboot"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/undo_snapshot",
      "rel" : "undo_snapshot"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/migrate",
      "rel" : "migrate"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/detach",
      "rel" : "detach"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/export",
      "rel" : "export"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/shutdown",
      "rel" : "shutdown"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/start",
      "rel" : "start"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/stop",
      "rel" : "stop"
    }, {
      "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/suspend",
      "rel" : "suspend"
    } ]
  },
  "name" : "VM_01",
  "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e",
  "id" : "42ec2621-7ad6-4ca2-bd68-973a44b2562e",
  "link" : [ {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/applications",
    "rel" : "applications"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/disks",
    "rel" : "disks"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/nics",
    "rel" : "nics"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/numanodes",
    "rel" : "numanodes"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/cdroms",
    "rel" : "cdroms"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots",
    "rel" : "snapshots"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/tags",
    "rel" : "tags"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/permissions",
    "rel" : "permissions"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/statistics",
    "rel" : "statistics"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/reporteddevices",
    "rel" : "reporteddevices"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/watchdogs",
    "rel" : "watchdogs"
  }, {
    "href" : "/ovirt-engine/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/sessions",
    "rel" : "sessions"
  } ]
}

15.5. Methods

15.5.1. 创建虚拟机

创建新虚拟机需要 名称模板cluster 元素。使用 id 属性或 name 元素识别 模板和 集群 元素。使用 cpuprofiles 属性识别 CPU 配置集 ID。

例 15.4. 创建从 CD-ROM 引导的 512 MB 的虚拟机

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

<vm>
    <name>vm2</name>
    <description>Virtual Machine 2</description>
    <type>desktop</type>
    <memory>536870912</memory>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <os>
        <boot dev="cdrom"/>
    </os>
    <cdroms>
        <cdrom>
            <file id="example_windows_7_x64_dvd_u_677543.iso"/>
        </cdrom>
    </cdroms>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>

例 15.5. 创建 512 MB 的虚拟机,该虚拟机从虚拟硬盘引导

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

<vm>
    <name>vm2</name>
    <description>Virtual Machine 2</description>
    <type>desktop</type>
    <memory>536870912</memory>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <os>
      <boot dev="hd"/>
    </os>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>
注意
以上示例中的内存使用以下公式转换为字节:
512MB * 1024 2 = 536870912 bytes

15.5.2. 更新虚拟机

name,description,cluster,type,memory,cpu,os,high_availability,display,timezone,domain,stateless,placement_policy,memory_policy,usb,payloads,origincustom_properties 元素是 updatable post-creation。

例 15.6. 更新虚拟机使其包含 1 GB 内存

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

<vm>
    <memory>1073741824</memory>
</vm>
注意
以上示例中的内存使用以下公式转换为字节:
1024MB * 1024 2 = 1073741824 bytes
注意
Red Hat Virtualization 支持内存热插。如果虚拟机的操作系统支持内存热插拔,您可以使用上例在虚拟机运行时增加内存。

例 15.7. 热插 vCPU

将虚拟 CPU 添加到正在运行的虚拟机中,而无需重新引导它。在本例中,套接字的数量更改为 2。
PUT /ovirt-engine/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <cpu>
        <topology sockets="2" cores="1"/>
    </cpu>
</vm>
注意
Red Hat Virtualization 目前不支持 CPU 热拔。

例 15.8. 将虚拟机固定到多个主机

固定至多个主机的虚拟机无法进行实时迁移,但在主机出现故障时,配置为高可用性的任何虚拟机将自动在虚拟机固定到的其他主机上重新启动。多主机固定可用于限制虚拟机到具有相同硬件配置的主机。
PUT /ovirt-engine/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <high_availability>
        <enabled>true</enabled>
        <priority>1</priority>
    </high_availability>
    <placement_policy>
        <hosts>
            <host><name>Host1</name></host>
            <host><name>Host2</name></host>
        </hosts>
        <affinity>pinned</affinity>
    </placement_policy>
</vm>

15.5.3. 删除虚拟机

删除虚拟机需要 DELETE 请求。

例 15.9. 删除虚拟机

DELETE /ovirt-engine/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1

HTTP/1.1 204 No Content

15.5.4. 删除虚拟机,而不是虚拟磁盘

在删除虚拟机前分离虚拟磁盘。这会保留虚拟磁盘。删除虚拟机需要 DELETE 请求。

例 15.10. 删除虚拟机

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

<action>
    <vm>
        <disks>
            <detach_only>true</detach_only>
        </disks>
    </vm>
</action>

15.6. sub-Collections

15.6.1. disks Sub-Collection

15.6.1.1. disks Sub-Collection
disks 子集合表示虚拟机中的所有虚拟硬盘设备。磁盘 表示包含以下元素:
表 15.2. 虚拟磁盘的元素
元素 类型 Description Properties
link rel="statistics" 关系 到虚拟机磁盘 统计的统计信息 子集合的链接。
link rel="permissions" 关系 权限 子集合的链接。
alias 字符串 磁盘的唯一标识符。使用 alias 而不是 name
image_id 字符串 对存储在定义的存储域中的虚拟机镜像的引用。
storage_domains complex 与此磁盘关联的存储域。每个 storage_domain 元素包含一个 id 属性,其中包含关联的存储域的 GUID。使用 POST 更新此元素,以执行磁盘从一个数据存储域的实时迁移到另一个数据存储域。 [a]
size 整数 磁盘大小(以字节为单位)。弃用; 被 provisioned_size 替代。
provisioned_size 整数 磁盘置备大小(以字节为单位)。
actual_size 整数 磁盘的实际大小(以字节为单位)。
status 其中一个 非法无效锁定正常 磁盘设备的状态。这些状态列在 capabilities 下的 disk_states 中。
interface Enumerated 用于连接到磁盘设备的接口驱动程序的类型。枚举的值列表包括在 能力 中。 
格式 Enumerated 底层存储格式。枚举的值列表包括在 能力 中。Copy On Write (COW)允许快照,且性能小。raw 不允许快照,但提供更好的性能。
sparse 布尔值: true 或 false 如果磁盘的物理存储不应预分配,则为 true
bootable 布尔值: true 或 false 如果此磁盘被标记为可引导,则为 true 
可共享 布尔值: true 或 false true 与多个虚拟机共享磁盘。 
wipe_after_delete 布尔值: true 或 false 如果删除磁盘时,磁盘的底层物理存储应为零为 true。这会提高安全性,但是一个更密集的操作,可能会延长删除时间。 
propagate_errors 布尔值: true 或 false 如果磁盘错误不应导致虚拟机暂停,且应该向客户端操作系统传播磁盘错误,则为 true 
vm id= GUID 包含虚拟机的 ID。
quota id= GUID 为磁盘设置配额。 
lun_storage complex 对存储使用直接 LUN 映射的引用。需要包含 iSCSI 或 FCP 设备详情的 logical_unit 元素。
active 布尔值 定义磁盘是否已连接到虚拟机。
read_only 布尔值 定义磁盘是否只读。
link rel="disk_profile" 关系 disk_profile 子集合的链接。
[a] 只有在磁盘被添加到虚拟机且没有从虚拟机模板创建时,才需要此元素。

例 15.11. 磁盘设备的 XML 表示

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/ovirt-engine/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/ovirt-engine/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>
    <link rel="permissions"
      href="/ovirt-engine/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/permissions"/>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/ovirt-engine/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="/ovirt-engine/api/diskprofiles/23fb2e0d-3062-4819-8165-3be88f2f587e"/>
    <lun_storage>
        <logical_unit id="lun1">
                ...
        </logical_unit>
    </lun_storage>
</disk>

添加新虚拟磁盘。在添加新的内部磁盘时,需要 provisioned_size 元素。使用 storage_domains 元素指定要在其中创建磁盘的存储域。同一虚拟机的多个磁盘可以驻留在不同的存储域中。

例 15.12. 在虚拟机上创建新磁盘设备

POST /ovirt-engine/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>
将新的外部(直接 LUN)磁盘添加到虚拟机。这个方法需要 lun_storage 元素和 logical_unit 元素,其中包含 iSCSI 或 FCP 设备详情。

例 15.13. 在虚拟机上创建新的直接 LUN 磁盘设备

POST /ovirt-engine/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>
别名,description,storage_domains,provisioned_size,interface,bootable,shareable,wipe_after_delete and propagate_errors 元素在创建后是 updatable。
用户可以调整一个或多个虚拟机使用的虚拟磁盘,而无需暂停、休眠或重启虚拟机。

例 15.14. 更新虚拟磁盘

PUT /ovirt-engine/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.15. 将虚拟磁盘更新为 20GB

PUT /ovirt-engine/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 bytes

例 15.16. 重命名虚拟磁盘

PUT /ovirt-engine/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.17. 删除虚拟磁盘

DELETE /ovirt-engine/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.18. 从模板克隆磁盘

以下示例在创建虚拟机期间从模板克隆磁盘。
POST /ovirt-engine/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>
重要
根据磁盘名称搜索查询需要 别名 搜索参数,而不是 名称
15.6.1.3. Disk Statistics Sub-Collection
每个虚拟机的磁盘会公开一个 统计 子集合,用于特定于磁盘的统计信息。每个统计 都包含以下元素:
表 15.3. 虚拟磁盘统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
disk id= 关系 与包含 disk 资源的关系。
下表列出了虚拟磁盘的统计类型。
表 15.4. 虚拟磁盘统计类型
名称
Description
data.current.read
从磁盘读取时,数据传输速率(以字节/秒为单位)。
data.current.write
在写入磁盘时,数据传输速率(以字节/秒为单位)。

例 15.19. 虚拟机统计子集合的 XML 表示

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/ovirt-engine/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="/ovirt-engine/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>
注意
这个 统计 子集合是只读的。
15.6.1.4. 浮动磁盘附加和分离操作
使用虚拟机磁盘子集合上的 POST 请求从主 rel=" disks " 集合中附加磁盘。包含要附加的磁盘的 id

例 15.20. 附加浮动磁盘

POST /ovirt-engine/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>
使用 disk 资源的 DELETE 请求从虚拟机的磁盘子集合 中分离磁盘,但请确保包含分离 的布尔值元素,以便磁盘不会被销毁。

例 15.21. 从虚拟机中分离磁盘

DELETE /ovirt-engine/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. 磁盘激活和取消激活操作
每个虚拟机的磁盘提供了一组 激活和停用 操作,以在虚拟机中添加和删除磁盘。

例 15.22. 激活虚拟磁盘的操作

POST /ovirt-engine/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.23. 取消激活虚拟磁盘的操作

POST /ovirt-engine/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. Network Interfaces Sub-Collection

15.6.2.1. Network Interfaces Sub-Collection
nics 子集合表示虚拟机上的所有网络接口设备。nic representation 包含以下元素:
表 15.5. 虚拟机网络接口的元素
元素 类型 Description Properties
link rel="statistics" 关系 到虚拟机网络接口 统计的统计信息 子集合的链接。
network id= GUID 对接口应该连接的网络的引用。允许空白网络 ID。
interface Enumerated 用于 nic 的驱动程序类型。枚举的值列表包括在 能力 中。 
mac address= 字符串 接口的 MAC 地址。
port_mirroring complex 定义 NIC 是否接收镜像流量。定义包含一系列 网络 id= 引用的网络元素
plugged 布尔值 定义 NIC 是否插入到虚拟机。
链接 布尔值 定义 NIC 是否链接到虚拟机。

例 15.24. 网络接口的 XML 表示

<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e" 
  ref="/ovirt-engine/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
  7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
    <link rel="statistics"
      href="/ovirt-engine/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="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/ovirt-engine/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    <port_mirroring>
        <networks>
            <network id="56087282-d7a6-11e1-af44-001a4a400e0c"
              href="/ovirt-engine/api/networks/56087282-d7a6-11e1-af44-001a4a400e0c"/>
        </networks>
    </port_mirroring>
</nic>
添加新网络接口时,需要 namenetwork 元素。使用 id 属性或 name 元素标识 network 元素。

例 15.25. 创建虚拟机 NIC

POST /ovirt-engine/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.26. 更新虚拟机 NIC

PUT /ovirt-engine/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.27. 删除虚拟机 NIC

DELETE /ovirt-engine/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. 网络接口统计信息 Sub-Collection
每个虚拟机的网络接口会公开一个 统计 子集合,用于网络接口统计信息。每个统计 都包含以下元素:
表 15.6. 虚拟机网络接口统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
nic id= 关系 与包含 nic 资源的关系。
下表列出了虚拟机上网络接口的统计类型。
表 15.7. 虚拟机 NIC 统计类型
名称
Description
data.current.rx
接收的数据每秒的速率(以字节/秒为单位)。
data.current.tx
传输数据的每秒速率(以字节/秒为单位)。
errors.total.rx
接收数据的总错误。
errors.total.tx
传输数据的总错误。

例 15.28. 虚拟机的 NIC 统计子集合的 XML 表示

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/ovirt-engine/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="/ovirt-engine/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
    </statistic>
    ...
</statistics>
注意
这个 统计 子集合是只读的。

15.6.3. 虚拟 NUMA 节点子检测

numanodes 子集合表示虚拟机上的所有虚拟 NUMA 节点。vm_numa_node 表示包含以下元素:
表 15.8. 虚拟 NUMA 节点的元素
元素 类型 Description Properties
index 整数 虚拟 NUMA 节点的索引号。
内存 整数 分配给虚拟 NUMA 节点的内存量,以 MB 为单位。
cpu complex 与此虚拟 NUMA 节点关联的 CPU 拓扑。每个 core 元素 包含一个带有 关联核心索引号的 index 属性。
vm id= GUID 包含虚拟机的 ID。
numa_node_pins complex 将虚拟 NUMA 节点固定到主机 NUMA 节点。每个 numa_node_pin 元素包含一个 pinned="true" 布尔值和主机 NUMA 节点的索引 号。 

例 15.29. 虚拟 NUMA 节点的 XML 表示

<vm_numa_node href="/ovirt-engine/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="/ovirt-engine/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 节点时,需要 索引memorycpu 元素。

例 15.30. 将新的虚拟 NUMA 节点添加到虚拟机

POST /ovirt-engine/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.31. 更新虚拟 NUMA 节点

PUT /ovirt-engine/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.32. 删除虚拟 NUMA 节点

DELETE /ovirt-engine/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-ROMs Sub-Collection

cdroms 子集合表示虚拟机上的 CD-ROM 设备。cdrom 表示包含以下元素:
表 15.9. 虚拟机 CD-ROM 的元素
元素 类型 Description Properties
file id= string/filename 对 ISO 镜像的引用。 

例 15.33. CD-ROM 设备的 XML 表示

<cdrom id="00000000-0000-0000-0000-000000000000"
  href="/ovirt-engine/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="/ovirt-engine/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>
使用 file id 元素发送 PUT 请求,以添加新的 CD-ROM 资源。

例 15.34. 添加新 CD-ROM 文件

PUT /ovirt-engine/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.35. 更改 CD-ROM 文件

PUT /ovirt-engine/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 请求和其他当前 URI 参数更改 当前会话 的 CD-ROM:

例 15.36. 在当前会话中更改 CD-ROM 文件

PUT /ovirt-engine/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 matrix 参数:

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

PUT /ovirt-engine/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.38. 永久弹出 CD-ROM 文件

PUT /ovirt-engine/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. 快照 Sub-Collection

15.6.5.1. 快照 Sub-Collection
虚拟机将磁盘状态保存并恢复为多个快照。它们通过一个 rel="snapshot" 子集合来表示和管理,它的行为与其他集合类似。
每个虚拟机快照都由一个单独的 snapshot 元素来表示,其中包含以下子元素:
表 15.10. 虚拟机快照的元素
元素 类型 Description Properties
vm id= GUID 与此快照相关的虚拟机的 ID 和 URI。
link rel="restore" 关系 恢复虚拟机快照的链接。
link rel="prev" 关系 此虚拟机之前快照的链接。
type 字符串 快照的类型。例如: activeregular
date xsd:dateTime 格式: YYYY-MM-DDTh:mm:ss 创建快照的日期和时间。
snapshot_status 字符串 快照的当前状态。
persist_memorystate 布尔值 定义快照是否还包括执行快照时虚拟机的内存状态。
注意
无法使用 PUT 修改快照元素。

例 15.39. 虚拟机快照的 XML 表示

<snapshot id="00000000-0000-0000-0000-000000000000"
  href="/ovirt-engine/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
  00000000-0000-0000-0000-000000000000">
    <actions>
      <link rel="restore"
      href="/ovirt-engine/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
      00000000-0000-0000-0000-000000000000/restore"/>
    <link rel="prev"
      href="/ovirt-engine/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
    </actions>
    <vm id="00000000-0000-0000-0000-000000000000"
      href="/ovirt-engine/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 标签。指定 Accept: application/json 标头将在标准 XML 标记中返回数据。此示例表示已从标准块格式格式化,以提高 leg 可访问性。

例 15.40. 快照的额外 ovf 数据的 XML 表示

GET /ovirt-engine/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.41. 创建虚拟机快照

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

<snapshot>
<description>Snapshot description</description>
</snapshot>
重要
在对使用 OpenStack 卷(Cinder)磁盘的虚拟机进行实时快照前,您必须手动冻结并解解客户机文件系统。如需更多信息,请参阅 第 15.7.14 节 “冻结虚拟机文件系统操作”第 15.7.15 节 “thaw 虚拟机文件系统操作”
您可以使用快照表示法中的 rel="restore" 操作链接恢复虚拟机快照:

例 15.42. 恢复虚拟机快照

POST /ovirt-engine/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 用户创建新的虚拟机,同时保留带有所有快照的原始虚拟机。
从快照创建虚拟机时,需要额外的 快照 元素到虚拟机的标准表示,用户会在 POST 请求中向 vms 集合发送。
snapshots 元素包含 快照 id= 元素,用于定义用作虚拟机基础的特定快照。

例 15.43. 从快照克隆虚拟机

POST /ovirt-engine/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 Sub-Collection

每个虚拟机资源会为特定于虚拟机的 统计 公开一个统计子集合。每个统计 都包含以下元素:
表 15.11. 虚拟机统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
vm id= 关系 与包含 vm 资源的关系。
下表列出了虚拟机的统计类型。
表 15.12. 虚拟机统计类型
名称
Description
memory.installed
为虚拟机使用分配的内存总量(以字节为单位)。
memory.used
虚拟机使用的当前内存(以字节为单位)。
cpu.current.guest
客户机使用的 CPU 百分比。
cpu.current.hypervisor
hypervisor 上的 CPU 开销百分比。
cpu.current.total
正在使用的当前 CPU 的总百分比。

例 15.44. 虚拟机统计子集合的 XML 表示

<statistics>
    <statistic id="ef802239-b74a-329f-9955-be8fea6b50a4"
      href="/ovirt-engine/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="/ovirt-engine/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    </statistic>
    ...
</statistics>
注意
虚拟机 的统计数据 子集合为只读。

15.6.7. 显示虚拟机会话信息

提交虚拟机的 GET 请求,并使用 会话 子集合来查看启动 SPICE 控制台会话的用户的会话信息,以及登录到虚拟机的用户。
虚拟机的会话信息列为子集合:

例 15.45. 显示虚拟机的会话信息

GET /ovirt-engine/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= "/ovirt-engine/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd">
  <vm href= "/ovirt-engine/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
  <ip address="192.0.2.0"/>
  <user href= "/ovirt-engine/api/users/fdfc627c-d875-11e0-90f0-83df133b58cc" id="fdfc627c-d875-11e0-90f0-83df133b58cc">
    <domain href= "/ovirt-engine/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= "/ovirt-engine/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd" >
    <vm href= "/ovirt-engine/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
    <user>
      <user_name>root</user_name>
    </user>
  </session>
</sessions>

15.7. Actions

15.7.1. 启动虚拟机操作

start 操作将启动已停止、关闭或暂停的虚拟机。

例 15.46. 启动虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
start 操作允许提供 vm 元素作为参数。如果提供了 vm 元素,虚拟机将使用提供的元素中的值,并在启动时覆盖系统设置。在 REST API 中将 start 操作与 vm 元素一起使用等同于在管理门户或用户门户中使用 Run Once 窗口。这些设置会保留,直到用户停止虚拟机。这些元素的示例包括 osdomainplacement_policycdromsstatelessdisplay 类型

例 15.47. 使用覆盖参数启动虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <pause>true</pause>
    <vm>
        <stateless>true</stateless>
        <display>
            <type>spice</type>
        </display>
        <os>
            <boot dev="cdrom"/>
        </os>
        <cdroms>
            <cdrom>
                <file id="windows-xp.iso"/>
            </cdrom>
        </cdroms>
        <floppies>
            <floppy>
                <file id="virtio-win_x86.vfd"/>
            </floppy>
       </floppies>
        <domain>
            <name>domain.example.com</name>
            <user>
                <user_name>domain_user</user_name>
                <password>domain_password</password>
            </user>
        </domain>
        <placement_policy>
            <host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>       
        </placement_policy>
    </vm>
</action>
注意
  • domain 元素仅用于 Windows 系统,用于启动时使用 start 操作覆盖参数。domain 元素决定 Windows 虚拟机加入的域。如果域集合中不存在 ,此元素需要额外的用户身份验证详细信息,包括 user _name 和密码。如果域集合中存在 ,则操作不需要额外的 用户身份验证 详情。
  • CD 镜像和软盘文件必须已经在 ISO 域中可用。如果没有,使用 ISO uploader 工具上传文件。如需更多信息,请参阅 ISO 上传工具

15.7.2. 使用 Cloud-Init Action 启动虚拟机

Cloud-Init 是自动化虚拟机初始设置的工具。您可以使用 工具配置主机名、网络接口、DNS 服务、授权密钥以及设置用户名和密码。您还可以使用 custom_script 标签指定要在启动时在虚拟机上运行的自定义脚本。
注意
cloud-init 元素只能用于启动安装有 cloud-init 软件包的虚拟机。使用 cloud-init 元素时,initialization 元素中的任何元素都会被忽略,但 cloud-init 元素以外的任何元素都会被忽略。

例 15.48. 使用 Cloud-Init 启动虚拟机的操作

本例演示了如何使用 Cloud-Init 工具启动虚拟机,以设置主机名,更改 root 密码,为 eth0 接口设置静态 IP,配置 DNS,并为 root 用户添加 SSH 密钥。
POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <vm>
       <initialization>
        <cloud_init>
          <host>
           <address>MyHost.MyDomain.com</address>
          </host>
          <users>
           <user>
            <user_name>root</user_name>
            <password>p@55w0rd!</password>
           </user>
          </users>
          <network_configuration>
           <nics>
            <nic>
              <name>eth0</name>
              <boot_protocol>static</boot_protocol>
              <network>
                <ip address="192.168.122.31" netmask="255.255.255.0" gateway="192.168.122.1"/>
              </network>
              <on_boot>true</on_boot>
            </nic>
           </nics>
           <dns>
            <servers>
              <host>
                <address>192.168.122.1</address>
              </host>
            </servers>
            <search_domains>
              <host>
                <address>MyDomain.com</address>
              </host>
            </search_domains>
          </dns>
        </network_configuration>
        <authorized_keys>
         <authorized_key>
           <user>
             <user_name>root</user_name>
           </user>
           <key>ssh-rsa AAAAB3Nza[...]75zkdD root@MyDomain.com</key>
         </authorized_key>
        </authorized_keys>
       </cloud_init>
       <custom_script><![CDATA[your script]]></custom_script>
      </initialization>
  </vm>
</action>

15.7.3. 停止虚拟机操作

stop 操作会强制虚拟机关机。

例 15.49. 停止虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.4. 关闭虚拟机操作

shutdown 操作会将关闭请求发送到虚拟机。

例 15.50. 将关闭请求发送到虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.5. 挂起虚拟机操作

suspend 操作会将虚拟机状态保存到磁盘,并停止它。启动暂停的虚拟机,并使用 start 操作恢复虚拟机状态。

例 15.51. 保存虚拟机状态并暂停虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.6. 重启虚拟机操作

reboot 操作会将重启请求发送到虚拟机。

例 15.52. 将重启请求发送到虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/reboot HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.7. 启用用户登录,从外部控制台访问虚拟机

logon 操作可让用户从 Red Hat Virtualization 环境外的控制台访问虚拟机。
此操作要求安装 ovirt-guest-agent-gdm-pluginovirt-guest-agent-pam-module 软件包,并在虚拟机上运行 ovirt-guest-agent 服务。
用户为虚拟机需要适当的用户权限,以便从外部控制台访问虚拟机。

例 15.53. 登录虚拟机

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/logon HTTP/1.1
Content-Type: application/json
Content-Length: 2

{}

15.7.8. 从池操作中分离虚拟机

分离操作从池中分离虚拟机。

例 15.54. 分离虚拟机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.9. 迁移虚拟机操作

migrate 操作将虚拟机迁移到另一个物理主机。目的地主机元素是一个可选的元素,因为 Red Hat Virtualization Manager 会自动选择默认主机进行迁移。如果 API 用户需要特定主机,用户可以使用 idname 参数指定主机。

例 15.55. 将虚拟机迁移到另一台主机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>

15.7.10. 取消虚拟机迁移操作

取消迁移操作会停止虚拟机到另一个物理主机的任何迁移。

例 15.56. 取消将虚拟机迁移到另一台主机的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.11. 导出虚拟机操作

注意
导出存储域已弃用。存储数据域可以从数据中心取消附加,并导入到同一环境中或不同环境中的其他数据中心。然后,可以将虚拟机、浮动虚拟磁盘镜像和模板从导入的存储域上传到附加的数据中心。有关 导入存储域 的信息,请参阅 Red Hat Virtualization 管理指南中的 导入现有存储域部分。
export 操作会将虚拟机 导出到 导出存储域。必须使用 storage_domain 引用来指定目标存储域。
如果目标域中存在相同名称的虚拟机,则 export 操作会报告失败的操作。将 exclusive 参数设置为 true 以更改此行为并覆盖任何现有的虚拟机。
如果导出的虚拟机没有包括虚拟机快照,请将 discard_snapshots 参数设置为 true

例 15.57. 将虚拟机导出到导出存储域的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>export1</name>
    </storage_domain>
    <exclusive>true</exclusive>
    <discard_snapshots>true</discard_snapshots>
</action>

15.7.12. 虚拟机票据操作

ticket 操作会生成一个用于访问虚拟机显示的时间敏感的身份验证令牌。客户端提供 的操作 (可选)包括了一个 ticket 表示,其中包含一个 (如果令牌字符串需要在特定表单上需要)和/或以分钟为单位 的到期时间。在任何情况下,响应都指定了实际使用的 ticket 值和到期时间。

例 15.58. 为虚拟机生成身份验证令牌的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <ticket>
        <expiry>120</expiry>
    </ticket>
</action>

200 OK
Content-Type: application/xml

<action id="94e07552-14ba-4c27-8ce6-2cc75190d3ef"
  href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
  94e07552-14ba-4c27-8ce6-2cc75190d3ef">
    <status>
        <state>complete</state>
    </status>
    <ticket>
        <value>5c7CSzK8Sw41</value>
        <expiry>120</expiry>
    </ticket>
    <link rel="parent"
      href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
    <link rel="replay"
      href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>

15.7.13. 强制删除虚拟机操作

API 用户强制使用 force 操作删除有问题的虚拟机。此操作需要 DELETE 方法。请求正文包含将 force 参数设置为 true 的操作 表示。请求还需要额外的 Content-type: application/xml 标头来处理正文中的 XML 表示。

例 15.59. 在虚拟机上强制删除操作

DELETE /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <force>true</force>
</action>

15.7.14. 冻结虚拟机文件系统操作

在对正在运行的虚拟机进行实时快照时,冻结文件系统 会冻结使用 QEMU 客户机代理的文件系统。通常,这由管理器自动执行,但必须使用 OpenStack 卷(Cinder)磁盘的虚拟机使用 REST API 手动执行。
释放客户机操作系统上的文件系统可确保快照的一致性。完成快照后,客户机文件系统必须被解封。在不使用 OpenStack 卷磁盘的虚拟机上,也可以使用 REST API 手动调用冻结和解放操作,这在快照过程中故障时很有用。

例 15.60. 冻结虚拟机的文件系统的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/freezefilesystems HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
有关快照的更多信息,请参阅 Red Hat Virtualization 虚拟机管理指南中的 第 15.6.5.1 节 “快照 Sub-Collection”快照 部分

15.7.15. thaw 虚拟机文件系统操作

在对正在运行的虚拟机执行实时快照时,thaw filesystems 操作使用 QEMU 客户机代理来解封虚拟机文件系统。通常,这由管理器自动执行,但必须使用 OpenStack 卷(Cinder)磁盘的虚拟机使用 REST API 手动执行。
释放客户机操作系统上的文件系统可确保快照的一致性。完成快照后,客户机文件系统必须被解封。在不使用 OpenStack 卷磁盘的虚拟机上,也可以使用 REST API 手动调用冻结和解放操作,这在快照过程中故障时很有用。例如,如果虚拟机在 thaw 期间变得无响应,您可以手动执行 thaw 操作;否则,虚拟机可能会保持无响应。

例 15.61. 处理虚拟机文件系统的操作

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/thawfilesystems HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
有关快照的更多信息,请参阅 Red Hat Virtualization 虚拟机管理指南中的 第 15.6.5.1 节 “快照 Sub-Collection”快照 部分

第 16 章 浮动磁盘

16.1. 浮动磁盘元素

磁盘 集合提供有关 Red Hat Virtualization 环境中所有磁盘的信息。用户从任何虚拟机中附加和分离磁盘,并在虚拟机之间进行浮点浮点。API 用户通过从入口点 URI 获取的 rel="disks" 链接访问此信息。
下表显示了 磁盘 资源表示法中包含的特定元素。
表 16.1. 浮动磁盘的元素
元素 类型 Description Properties
link rel="statistics" 关系 到虚拟机磁盘 统计的统计信息 子集合的链接。
image_id GUID 对存储在定义的存储域中的虚拟机镜像的引用。
storage_domains 复杂 与此磁盘关联的存储域。每个 storage_domain 元素包含一个 id 属性,其中包含关联的存储域的 GUID。使用 POST 更新此元素,以执行磁盘从一个数据存储域的实时迁移到另一个数据存储域。
size 整数 磁盘大小(以字节为单位)。
provisioned_size 整数 磁盘置备大小(以字节为单位)。
actual_size 整数 磁盘的实际大小(以字节为单位)。
status 其中一个 非法无效锁定正常 磁盘设备的状态。这些状态列在 capabilities 下的 disk_states 中。
interface Enumerated 用于连接到磁盘设备的接口驱动程序的类型。枚举的值列表包括在 能力 中。 
格式 Enumerated 底层存储格式。枚举的值列表包括在 能力 中。Copy On Write (COW)允许快照,且性能小。raw 不允许快照,但提供更好的性能。
sparse 布尔值: true 或 false 如果磁盘的物理存储不应预分配,则为 true
bootable 布尔值: true 或 false 如果此磁盘被标记为可引导,则为 true 
可共享 布尔值: true 或 false true 与多个虚拟机共享磁盘。 
wipe_after_delete 布尔值: true 或 false 如果删除磁盘时,磁盘的底层物理存储应为零为 true。这会提高安全性,但是一个更密集的操作,可能会延长删除时间。 
propagate_errors 布尔值: true 或 false 如果磁盘错误不应导致虚拟机暂停,且应该向客户端操作系统传播磁盘错误,则为 true 
quota id= GUID 为磁盘设置配额。 
lunStorage complex 对存储使用直接 LUN 映射的引用。需要包含 iSCSI 或 FCP 设备详情 的存储 元素。
active 布尔值 定义磁盘是否已连接到虚拟机。
重要
根据名称搜索磁盘搜索查询需要 别名 搜索参数,而不是 名称

16.2. XML 代表浮动磁盘

例 16.1. 磁盘设备的 XML 表示

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/ovirt-engine/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/ovirt-engine/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>  
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>10737418240</size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <lunStorage>
        <storage>
            <logical_unit id="lun1">
                ...
            </logical_unit>
        <storage>
    </lunStorage>
</disk>

16.3. Methods

16.3.1. 创建浮动磁盘

在创建新浮动磁盘时,API 需要 sizestorage_domains 元素。

例 16.2. 创建新的浮动磁盘设备

POST /ovirt-engine/api/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
</disk>

16.4. sub-Collections

16.4.1. statistics Sub-Collection

每个浮动磁盘会公开一个 统计 子集合,用于特定于磁盘的统计信息。每个统计 都包含以下元素:
表 16.2. 虚拟磁盘统计的元素
元素 类型 描述
name 字符串 统计条目的唯一标识符。
description 字符串 统计的纯文本描述。
unit 字符串 测量统计值的单元或率。
type GAUGECOUNTER之一 统计测量结果的类型。
values type= INTEGERDECIMAL之一 后面的统计值的数据类型。
value complex 包含 datum 的数据集。
datum 查看值类型 来自 的独立数据。
disk id= 关系 与包含 disk 资源的关系。
下表列出了浮动磁盘的统计类型。
表 16.3. 磁盘统计类型
名称
Description
data.current.read
从磁盘读取时,数据传输速率(以字节/秒为单位)。
data.current.write
在写入磁盘时,数据传输速率(以字节/秒为单位)。

例 16.3. 虚拟机统计子集合的 XML 表示

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/ovirt-engine/api/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="/ovirt-engine/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>
注意
这个 统计 子集合是只读的。

16.5. Actions

16.5.1. 复制浮动磁盘

在复制浮动磁盘时,API 需要 storage_domain 元素。可选的 name 元素指定磁盘的别名。

例 16.4. 复制浮动磁盘

POST /ovirt-engine/api/disks/54a81464-b758-495a-824b-1e7937116ae5/copy HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain id="c8e108f7-c049-40d2-ad3d-620e4638828e"/>
    <disk>
        <name>rhel_disk2</name>
    </disk>
</action>

第 17 章 模板

17.1. 虚拟机模板元素

templates 集合提供有关 Red Hat Virtualization 环境中的虚拟机模板的信息。API 用户通过从入口点 URI 获取的 rel="templates" 链接访问此信息。
可以使用 All-Content: true 标头检索 GET 请求的其他信息。
下表显示了虚拟机模板资源表示法中包含的特定元素。
表 17.1. 虚拟机模板元素
元素 类型 Description Properties
link rel="disks" 关系 到虚拟机模板 资源的 disk 子集合的链接。
link rel="nics" 关系 虚拟机模板资源的 nics 子集合的链接。 
link rel="cdroms" 关系 虚拟机模板资源的 cdroms 子集合的链接。
link rel="permissions" 关系 到虚拟机模板 权限权限 子集合的链接。 
type Enumerated 模板提供的虚拟机类型。功能 中提供了枚举的值的列表。
status 其中一个 非法锁定正常 模板状态。这些状态列在 capabilities 下的 template_states 中。
内存 整数 分配给客户机的内存量,以字节为单位。
cpu complex 可供客户机使用的 CPU 拓扑 (如 套接字内核数量)。
os type= 字符串,如 RHEL5WindowsXP 客户机操作系统类型。
OS 引导 dev= Enumerated 引导设备列表,由 引导 元素中的 dev 属性描述。功能 中提供了枚举的值的列表。
OS 内核 字符串 配置为从中引导模板的内核镜像的路径。 
OS initrd 字符串 与内核一起使用的 initrd 镜像的路径。 
OS cmdline 字符串 与上述内核一起使用的内核命令行参数字符串。 
cluster id= GUID 对模板的主机集群的引用。
vm id= GUID 对此模板所基于的虚拟机的引用。
domain id= GUID 对模板的域的引用。
creation_time xsd:dateTime 格式: YYYY-MM-DDTh:mm:ss 创建此模板的日期和时间。
origin rhev,ovirt,vmwarexen之一 此模板源自的系统。
high_availability complex 如果虚拟机在 主机崩溃时应自动重启,则设置为 truepriority 元素控制虚拟机重新启动的顺序。 
显示 complex 显示 类型 ( vncspice)、port 以及 监视器 的数量。allow_reconnect 布尔值指定客户端是否可以通过显示重新连接到机器。 
无状态 布尔值: true 或 false 无状态模板包含引导时获取的磁盘镜像的快照,并在关机时删除。这意味着状态更改在重启后不会保留。
usb complex 定义虚拟机模板的 USB 策略。要求将 enabled 元素设置为布尔值,并且 type 元素设为 nativelegacy
重要
Legacy USB 选项已弃用,并将在 Red Hat Virtualization 4.1 中删除。
 
placement_policy complex 为虚拟机迁移设置放置策略。需要默认的 host=关联性 (一个可 migratableuser_migratable固定)。将 host 元素留空,以设置任何首选主机。 
custom_properties complex 一组用户定义的环境变量,作为参数传递给自定义脚本。每个 custom_property 都包含 namevalue 属性。功能 中提供了枚举的值的列表。 
timezone tz 数据库格式: Area/Location Windows 虚拟机模板的 Sysprep 时区设置。 
domain complex Windows 虚拟机模板的 Sysprep 域设置。需要 集合中的 名称 

17.2. 虚拟机模板的 XML 表

例 17.1. 虚拟机模板的 XML 表示

<template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"
  id="00000000-0000-0000-0000-000000000000">
    <actions>
        <link href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/export"
          rel="export"/>
    </actions>
    <name>Blank</name>
    <description>Blank template</description>
    <comment>Blank template</comment>
    <link href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/disks"
      rel="disks"/>
    <link href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/nics" 
      rel="nics"/>
    <link href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/cdroms"
      rel="cdroms"/>
    <link href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/permissions" 
      rel="permissions"/>
    <link href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/watchdogs" 
      rel="watchdogs"/>
    <type>server</type>
    <status>
        <state>ok</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology sockets="1" cores="1"/>
        <architecture>X86_64<architecture/>
    </cpu>
    <cpu_shares>0</cpu_shares>
    <os type="rhel_6x64">
        <boot dev="hd"/>
        <boot dev="cdrom"/>;
    </os>
    <cluster id="00000000-0000-0000-0000-000000000000"
      href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000"/>
    <creation_time>2010-08-16T14:24:29</creation_time>
    <origin>ovirt</origin>
    <high_availability>
        <enabled>true</enabled>
        <priority>100</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
        <single_qxl_pci>false</single_qxl_pci>
        <allow_override>true</allow_override>
        <smartcard_enabled>true</smartcard_enabled>
    </display>
    <stateless>false</stateless>
    <delete_protected>false</delete_protected>
    <sso>
      <methods>
        <method id="GUEST_AGENT">true</enabled>
      </methods>
    </sso>
    <usb>
        <enabled>true</enabled>
    </usb>
    <migration_downtime>-1</migration_downtime>
    <version>
      <base_template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"
        id="00000000-0000-0000-0000-000000000000"/>
      <version_number>2</version_number>
      <version_name>RHEL65_TMPL_001</version_name>
    </version>
</template>

17.3. Methods

17.3.1. 创建新模板

创建新模板需要 namevm 元素。使用 id 属性或 name 元素识别 vm

例 17.2. 从虚拟机创建模板

POST /ovirt-engine/api/templates HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
    <name>template1</name>
    <vm id="00000000-0000-0000-0000-000000000000"/>
</template>

17.3.2. 创建新模板子版本

创建新模板子版本需要新模板的 namevm 元素,以及新模板版本的 base_templateversion_name 元素。base_template version _name 元素必须在 template 部分中包含的版本部分指定。使用 id 属性或 name 元素识别 vm

例 17.3. 从模板创建模板子版本

POST /ovirt-engine/api/templates HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
  <name>template1_001</name>
  <vm id="00000000-0000-0000-0000-000000000000"/>
  <version>
    <base_template id="00000000-0000-0000-0000-000000000000"/>
    <version_name>"template1_001"</version_name>
  </version>
</template>

17.3.3. 更新模板

在创建模板后,可以更新 名称描述typecpu 拓扑OS、OS、High_availability显示无状态usbtimezone 元素。

例 17.4. 更新虚拟机模板使其包含 1 GB 内存

PUT /ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
    <memory>1073741824</memory>
</template>

17.3.4. 更新模板子版本

只有 version_name 元素可以在模板子版本创建后更新。

例 17.5. 更新虚拟机模板子版本名称

PUT /ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
  <version>
    <version_name>template1_002</version_name>
  </version>
</template>

17.3.5. 删除模板

删除虚拟机模板需要 DELETE 请求。

例 17.6. 删除虚拟机模板

DELETE /ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

17.4. Actions

17.4.1. 导出模板操作

注意
导出存储域已弃用。存储数据域可以从数据中心取消附加,并导入到同一环境中或不同环境中的其他数据中心。然后,可以将虚拟机、浮动虚拟磁盘镜像和模板从导入的存储域上传到附加的数据中心。有关 导入存储域 的信息,请参阅 Red Hat Virtualization 管理指南中的 导入现有存储域部分。
templates 集合包含一个 导出 操作。
export 操作会将模板导出到 导出存储域。目标存储域通过 storage_domain 引用来指定。
如果目标域中存在相同名称的虚拟机模板,则 export 操作会报告失败的操作。将 exclusive 参数设置为 true 以更改此行为并覆盖任何现有的虚拟机模板。

例 17.7. 将模板导出到导出存储域的操作

POST /ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000/export HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain id="00000000-0000-0000-0000-000000000000"/>
    <exclusive>true<exclusive/>
</action>

第 18 章 虚拟机池

18.1. 虚拟机池元素

vmpools 集合提供有关 Red Hat Virtualization 环境中的虚拟机池的信息。API 用户通过从入口点 URI 获取的 rel="vmpools" 链接访问此信息。
下表显示了虚拟机池资源表示法中包含的特定元素。
表 18.1. 虚拟机池元素
元素 类型 Description Properties
name 字符串 用户提供的、人类可读的名称。名称 在所有池资源中是唯一的。
description 字符串 用户提供的、人类可读的、对虚拟机池的描述。 
link rel="permissions" 关系 到虚拟机池 权限权限 子集合的链接。 
size 整数 池中的虚拟机数量。
cluster id= GUID 对此池中的虚拟机运行的集群资源的引用。
template id= GUID 对此池中的虚拟机所基于的模板资源的引用。
prestarted_vms 整数 虚拟机池中预先启动的虚拟机数量。 
max_user_vms 整数 一个用户可从虚拟机池中获取的最大虚拟机数量。 
重要的
如本章所述的 API 是实验性的,可能随时更改。它不包含在向后兼容声明中。

18.2. 虚拟机池的 XML 表

例 18.1. 虚拟机池的 XML 表示

<vmpool href="/ovirt-engine/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e">
  id="2d2d5e26-1b6e-11e1-8cda-001320f76e8e"
    <actions>
    	<link href="/ovirt-engine/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm"
    	  rel="allocatevm"/>
    </actions>
    <name>VMPool1</name>
    <description>Virtual Machine Pool 1</description>
    <size>2</size>
    <cluster href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
      id="99408929-82cf-4dc7-a532-9d998063fa95"
    <template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"/>
      id="00000000-0000-0000-0000-000000000000"
    <prestarted_vms>0</prestarted_vms>
    <max_user_vms>1</max_user_vms>
</vmpool>

18.3. Methods

18.3.1. 创建新虚拟机池

新池需要 名称clustertemplate 元素。使用 id 属性或 name 元素识别 集群和 模板

例 18.2. 创建虚拟机池

POST /ovirt-engine/api/vmpools HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vmpool>
    <name>VM_Pool_A</name>
    <cluster href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
      id="99408929-82cf-4dc7-a532-9d998063fa95"
    <template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"/>
      id="00000000-0000-0000-0000-000000000000"
</vmpool>

18.3.2. 更新虚拟机池

在创建虚拟机后,可以更新 名称描述sizeprestarted_vmsmax_user_vms

例 18.3. 更新虚拟机池

PUT /ovirt-engine/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vmpool>
    <name>VM_Pool_B</name>
    <description>Virtual Machine Pool B</description>
    <size>3</size>
    <prestarted_vms>1</size>
    <max_user_vms>2</size>
</vmpool>

18.3.3. 删除虚拟机池

删除虚拟机池需要 DELETE 请求。

例 18.4. 删除虚拟机

DELETE /ovirt-engine/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1

HTTP/1.1 204 No Content

18.4. Actions

18.4.1. 分配虚拟机操作

分配虚拟机操作在虚拟机池中分配虚拟机。

例 18.5. 从虚拟机池分配虚拟机的操作

POST /ovirt-engine/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

第 19 章 Domains

19.1. 域元素

API 提供了使用 集合从组织的目录服务访问用户和组信息的功能。使用 rel="domains" 链接引用域信息。
表 19.1. 域元素
元素 类型 描述
name 字符串 域名。
link rel="users" 关系 与这个域关联的用户的子集合的链接。
link rel="groups" 关系 到与此域关联的组的子集合的链接。
用户和组 子集合的链接也接受搜索查询。
注意
domains 集合及其子集合是只读的。

19.2. XML 代表一个域资源

例 19.1. 域资源的 XML 表示

<domain id="77696e32-6b38-7268-6576-2e656e676c61"
  href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61">
    <name>domain.example.com</name>
    <link rel="users"
      href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users"/>
    <link rel="groups"
      href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups"/>
    <link rel="users/search"
      href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
      users?search={query}"/>
    <link rel="groups/search"
      href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
      groups?search={query}"/>
</domain>

19.3. sub-Collections

19.3.1. 域用户 Sub-Collection

users 子集合包含目录服务中的所有用户。这些信息用于在 Red Hat Virtualization 环境中添加新用户。
表 19.2. 域用户元素
元素 类型 描述
name 字符串 用户名称。
last_name 字符串 用户的姓氏。
user_name 字符串 来自目录服务的用户名。
域 ID GUID 包含目录服务域。
groups complex 此用户的目录服务组群列表。

例 19.2. 用户子集合中的用户的 XML 表示

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users/
  d3b4e7be-5f57-4dac-b937-21e1771a501f">
    <name>RHEV-M Admin</name>
    <user_name>rhevmadmin@domain.example.com</user_name>
    <domain id="77696e32-6b38-7268-6576-2e656e676c61"
      href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
    <groups>
        <group>
            <name>domain.example.com/Users/Enterprise Admins</name>
        </group>
        <group>
            <name>domain.example.com/Users/Domain Admins</name>
        </group>
        ...
    </groups>
</user>

19.3.2. 域组 Sub-Collection

groups 子集合包含目录服务中的所有组。域 组资源 包含一组元素。
表 19.3. 域组元素
元素 类型 描述
name 字符串 组名称。
域 ID GUID 包含目录服务域。

例 19.3. 组子集合中的组的 XML 表示

<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
  href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups/
  85bf8d97-273c-4a5c-b801-b17d58330dab">
    <name>example.com/Users/Enterprise Admins</name>
    <domain id="77696e32-6b38-7268-6576-2e656e676c61"
      href="/ovirt-engine/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
</group>

第 20 章 组

20.1. 导入的组元素

groups 集合包含从目录服务导入的组。group 资源包含一组元素。
表 20.1. 导入的组元素
元素 类型 Description
link rel="tags" 关系 到附加到此组的标签的标签的 tags 子集合的链接。
link rel="permissions" 关系 附加到该 组的权限 子集合的链接。
link rel="roles" 关系 附加到此组的角色的 roles 子集合的链接。

20.2. 一个组群资源的 XML 代表

例 20.1. 组资源的 XML 表示

<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
  href="/ovirt-engine/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab">
    <name>Everyone</name>
    <link rel="tags"
      href="/ovirt-engine/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/tags"/>
    <link rel="permissions"
      href="/ovirt-engine/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/permissions"/>
    <link rel="roles"
      href="/ovirt-engine/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/roles"/>
    <domain_entry_id>
          65656530303030302D303030302D303030302D303030
    </domain_entry_id>
    <namespace>*</namespace>
</group>

20.3. 从目录服务添加组

API 使用 POST 请求到组集合,将现有目录服务组添加到 Red Hat Virtualization Manager 数据库中。

例 20.2. 从目录服务添加组

POST /ovirt-engine/api/group HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<group>
    <name>www.example.com/accounts/groups/mygroup</name>
    <domain> 
     <name>example.com</name>
    </domain> 
</group>

第 21 章 角色

21.1. 角色元素

从入口点 URI 获取的 rel="roles" 链接提供对静态系统角色集的访问权限。每个单独的 role 元素都包含以下内容:
表 21.1. 角色元素
元素 类型 Description Properties
link="permits" 关系 角色允许 子集合的链接。
可变 布尔值: true 或 false 定义更新或删除角色的能力。mutable 设置为 false 的角色是 Red Hat Virtualization 环境中构建的角色。
administrative 布尔值: true 或 false 角色仅定义为仅限管理。

21.2. 角色集合的 XML 表

例 21.1. 角色集合的 XML 表示

<roles>
    <role id="00000000-0000-0000-0000-000000000001"
      href="/ovirt-engine/api/roles/00000000-0000-0000-0000-000000000001">
        <name>SuperUser</name>
        <description>Roles management administrator</description>
        <link rel="permits"
          href="/ovirt-engine/api/roles/00000000-0000-0000-0000-000000000001/permits"/>
        <mutable>false</mutable>
        <administrative>true</administrative>
    </role>
    <role id="00000000-0000-0000-0001-000000000001"
      href="/ovirt-engine/api/roles/00000000-0000-0000-0001-000000000001">
        <name>RHEVMUser</name>
        <description>RHEVM user</description>
        <link rel="permits"
          href="/ovirt-engine/api/roles/00000000-0000-0000-0001-000000000001/permits"/>
        <mutable>false</mutable>
        <administrative>false</administrative>
    </role>
    <role id="00000000-0000-0000-0001-000000000002"
       href="/ovirt-engine/api/roles/00000000-0000-0000-0001-000000000002">
        <name>RHEVMPowerUser</name>
        <description>RHEVM power user</description>
        <link rel="permits"
          href="/ovirt-engine/api/roles/00000000-0000-0000-0001-000000000002/permits"/>
        <mutable>false</mutable>
        <administrative>false</administrative>
    </role>
</roles>

21.3. Methods

21.3.1. 创建角色

创建角色需要 名称 的值、管理 以及初始列表 允许

例 21.2. 创建角色

POST /ovirt-engine/api/roles HTTP/1.1
Accept: application/xml
Content-type: application/xml

<role>
    <name>Finance Role</name>
    <administrative>true</administrative>
    <permits>
        <permit id="1"/>
    </permits>
</role>

21.3.2. 更新角色

名称描述 和管理 元素是创建后的 updatable。

例 21.3. 更新角色

PUT /ovirt-engine/api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<role>
    <name>Engineering Role</name>
    <description>Standard users in the Engineering Role</description>
    <administrative>false</administrative>
</role>

21.3.3. 删除角色

删除角色需要 DELETE 请求。

例 21.4. 删除角色

DELETE /ovirt-engine/api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1

HTTP/1.1 204 No Content

21.4. 角色 Permits Sub-Collection

21.4.1. 角色 Permits Sub-Collection

每个角色都包含一组允许的操作,或允许,API 列表在 功能 中。
角色的 允许 列为子集合:

例 21.5. 列出角色的允许

GET /ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml

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

<permits>
    <permit id="1"
      href="/ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>create_vm</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
    ...
</permits>

21.4.2. 为角色分配一个 Permit

permit 分配给带有 POST 请求到 允许 子集合的角色。使用 id 属性或 name 元素来指定要分配的 允许

例 21.6. 为角色分配 permit

POST /ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<permit id="1"/>

HTTP/1.1 201 Created
Content-Type: application/xml

<permits>
    <permit id="1"
      href="/ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>create_vm</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
</permits>

21.4.3. 从角色中删除 Permit

从具有 DELETE 请求到 permit 资源的角色中删除 permit

例 21.7. 从角色中删除允许

DELETE /ovirt-engine/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1 HTTP/1.1

HTTP/1.1 204 No Content

第 22 章 用户

22.1. 用户元素

用户在顶级集合中公开,并使用 rel="users" 链接来引用。每个用户 元素包括:
表 22.1. 用户元素
元素 类型 Description Properties
user_name 字符串 用户主体名称(UPN)。UPN 在添加新用户时用作更方便的标识符。
link rel="tags" 关系 到 user 资源的 tags 子集合的链接。 
link rel="roles" 关系 到 user 资源的 roles 子集合的链接。 
name 字符串 用户的自由文本名称。
domain 字符串 包含目录服务域。
groups complex 此用户的目录服务组群列表。

22.2. 用户资源的 XML 表示

例 22.1. 用户资源的 XML 表示

GET /ovirt-engine/api/users HTTP/1.1
Accept: application/xml

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/ovirt-engine/api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
    <name>RHEV-M Admin</name>
    <actions/>
    <link rel="roles"
      href="/ovirt-engine/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
    <link rel="tags"
      href="/ovirt-engine/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/tags"/>
    <domain>domain.example.com</domain>
    <logged_in>false</logged_in>
    <user_name>rhevmadmin@domain.example.com</user_name>
    <groups>
        <group>Group Policy Creator Owners@domain.example.com/Users</group>
        <group>Domain Admins@domain.example.com/Users</group>
        <group>Enterprise Admins@domain.example.com/Users</group>
        <group>Schema Admins@domain.example.com/Users</group>
        <group>Administrators@domain.example.com/Builtin</group>
    </groups>
</user>

22.3. Methods

22.3.1. 添加用户

API 通过 向用户 集合的 POST 请求向 Red Hat Virtualization Manager 数据库添加一个现有目录服务用户。客户端提供的新用户表示中包括至少一个可分配给用户的初始 角色的 嵌入式 角色列表。例如,以下请求将两个初始 角色分配给用户 joe@domain.example.com:

例 22.2. 从目录服务添加用户并分配两个角色

POST /ovirt-engine/api/users HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<user>
    <user_name>joe@domain.example.com</user_name>
    <roles>
        <role>
            <name>RHEVMPowerUser</name>
        </role>
        <role id="00000000-0000-0000-0001-000000000003"/>
    </roles>
</user>
新用户可通过 Red Hat Virtualization Manager 用户 ID 或通过目录服务用户主体名称(UPN)标识。从目录服务域报告的用户 ID 格式可能与预期的 Red Hat Virtualization Manager 格式不同,比如在 LDIF 中 [5] ,ID 具有相反的字节顺序,采用 base-64 编码。因此,通过 UPN 引用新用户通常更为方便。
注意
在将用户添加到 Red Hat Virtualization Manager 数据库之前,该用户存在于目录服务域中。API 用户有选项,可以在创建用户 之前通过域 集合查询这个域。
角色按名称或 ID 标识。上面的例子显示了这两种方法。

22.3.2. 向用户添加角色

通过 POSTDELETE 请求将进一步角色附加或分离到单个用户的角色子集合。以下示例说明了 API 如何将 RHEVMVDIUser 角色添加到特定用户的角色分配中。
注意
user 元素的嵌入式用户角色列表仅用于初始创建。所有创建后与用户角色分配的交互都通过 角色 子集合。

例 22.3. 向用户添加角色

POST /ovirt-engine/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<role>
    <name>RHEVMVDIUser</name>
</role>


[5] RFC 2849 中描述了 LDAP 数据交换格式。

第 23 章 MAC 地址池

23.1. MAC 地址池元素

macpools 集合提供有关 Red Hat Virtualization 环境中 MAC 地址池的信息。API 用户通过从入口点 URI 获取的 rel="macpools" 链接访问此信息。下表显示了 MAC 地址池资源表示法中包含的特定元素。
表 23.1. MAC 地址池元素
元素 类型 Description Properties
name 字符串 MAC 地址池的纯文本可读名称。
description 字符串 MAC 地址池的纯文本、人类可读的描述。
allow_duplicates 布尔值: true 或 false 定义池中是否允许重复的 MAC 地址。如果没有指定,则 allow_duplicates 默认为 false。
default_pool 布尔值: true 或 false 定义是否是默认池。如果没有指定,default_pool 默认为 false。
范围 complex 定义池的 MAC 地址范围。可以在 ranges 元素中定义多个 范围

23.2. MAC 地址池集合的 XML 代表

例 23.1. MAC 地址池集合的 XML 表示

<mac_pools>
    <mac_pool href="/ovirt-engine/api/macpools/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
        <name>Default</name>
        <description>Default MAC pool</description>
        <allow_duplicates>false</allow_duplicates>
        <default_pool>true</default_pool>
        <ranges>
            <range>
                <from>00:1A:4A:16:01:51</from>
                <to>00:1A:4A:16:01:e6</to>
            </range>
        </ranges>
    </mac_pool>
</mac_pools>

23.3. Methods

23.3.1. 创建 MAC 地址池

创建 MAC 地址池需要 nameranges 的值。

例 23.2. 创建 MAC 地址池

POST /ovirt-engine/api/macpools HTTP/1.1
Accept: application/xml
Content-type: application/xml

<mac_pool>
    <name>MACPool</name>
    <description>A MAC address pool</description>
    <allow_duplicates>true</allow_duplicates>
    <default_pool>false</default_pool>
    <ranges>
        <range>
            <from>00:1A:4A:16:01:51</from>
            <to>00:1A:4A:16:01:e6</to>
        </range>
    </ranges>
</mac_pool>

23.3.2. 更新 MAC 地址池

名称描述allow_duplicatesranges 元素在创建后是 updatable。

例 23.3. 更新 MAC 地址池

PUT /ovirt-engine/api/macpools/ab39bbc1-1d64-4737-9b20-ce081f99b0e1 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<mac_pool>
    <name>UpdatedMACPool</name>
    <description>An updated MAC address pool</description>
    <allow_duplicates>false</allow_duplicates>
    <ranges>
        <range>
            <from>00:1A:4A:16:01:51</from>
            <to>00:1A:4A:16:01:e6</to>
        </range>
        <range>
            <from>02:1A:4A:01:00:00</from>
            <to>02:1A:4A:FF:FF:FF</to>
        </range>
    </ranges>
</mac_pool>

23.3.3. 删除 MAC 地址池

删除 MAC 地址池需要 DELETE 请求。

例 23.4. 删除 MAC 地址池

DELETE /ovirt-engine/api/macpools/ab39bbc1-1d64-4737-9b20-ce081f99b0e1 HTTP/1.1

HTTP/1.1 204 No Content

第 24 章 Tags

24.1. 标签元素

tags 集合提供有关 Red Hat Virtualization 环境中标签的信息。API 用户通过从入口点 URI 获取的 rel="tags" 链接访问此信息。
下表显示了标签资源表示法中包含的特定元素。
表 24.1. 标签元素
元素 类型 Description Properties
主机 GUID 对附加标签的主机的引用。
user GUID 对附加标签的用户的引用。
vm GUID 对附加标签的虚拟机的引用。
parent complex 对附加标签的虚拟机的引用。 

24.2. XML 代表标签资源

例 24.1. 标签资源的 XML 表示

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/ovirt-engine/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <parent>
        <tag id="-1" href="/ovirt-engine/api/tags/-1"/>
    </parent>
</tag>

24.3. 关联标签

24.3.1. 将标签与主机、用户或虚拟机关联

通过 主机 中的 链接 rel="tags" 引用的集合,用户或 vms 代表与实体关联的一组标签。
这些标签表示法也包含 主机 ID、用户 IDvm id 引用问题中的实体。
通过 POST标签引用(通过其 idname)与集合来实现,即可实现标签与实体。

例 24.2. 将标签与虚拟机关联

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <name>Finance</name>
</tag>

HTTP/1.1 201 Created
Content-Type: application/xml

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
  f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>

24.3.2. 删除标签

通过到集合中适当元素的 DELETE 请求实现删除关联。

例 24.3. 从虚拟机中删除标签

DELETE /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1

HTTP/1.1 204 No Content

24.3.3. 查询一组标记的资源

要查询与给定标签关联的实体集合,应使用相应 集合的集合/搜索 URI 模板来搜索与 tag=MyTag 匹配的实体。

例 24.4. 查询已标记资源的集合

GET /ovirt-engine/api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml

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

<vms>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
        ...
    </vm>
    ...
</vms>

24.4. 父标签

24.4.1. 父标签

API 用户为标签分配一个 元素,以创建指向父标签的分层链接。标签以扁平集合的形式显示,该集合来自 root 标签,带有标签表示,包含链接元素到父标签
备注
如果未指定父标签,则 root 标签是一个特殊的伪标签,假定为默认的父标签。root 标签不能被删除或分配父标签。
此标签层次结构采用以下方法表示:

例 24.5. Tag Hierarchy

<tags>
    <tag id="-1" href="/ovirt-engine/api/tags/-1">
        <name>root</name>
        <description>root</description>
        <parent>
            <tag id="-1" href="/ovirt-engine/api/tags/-1"/>
        </parent>
    </tag>
    <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
      href="/ovirt-engine/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
        <name>Finance</name>
        <description>Resources for the Finance department</description>
        <parent>
            <tag id="-1" href="/ovirt-engine/api/tags/-1"/>
        </parent>
    </tag>
    <tag id="ac18dabf-23e5-12be-a383-a38b165ca7bd"
      href="/ovirt-engine/api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd">
        <name>Billing</name>
        <description>Billing Resources</description>
        <parent>
            <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
              href="/ovirt-engine/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
        </parent>
    </tag>
</tags>
在这个 XML 表示法中,标签遵循以下层次结构:
root              (id: -1)
  - Finance       (id: f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e)
      - Billing   (id: ac18dabf-23e5-12be-a383-a38b165ca7bd)

24.4.2. 设置父标签

POST使用 元素的新标签创建与父标签关联,使用 id 属性或 name 元素来引用父标签

例 24.6. 设置与 id 属性的父标签的关联

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

<tag>
    <name>Billing</name>
    <description>Billing Resources</description>
    <parent>
        <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
    </parent>
</tag>

例 24.7. 设置与父标签与 name 元素的关联

POST /ovirt-engine/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

<tag>
    <name>Billing</name>
    <description>Billing Resources</description>
    <parent>
        <tag>
            <name>Finance</name>
        </tag>
    </parent>
</tag>

24.4.3. 更改父标签

标签使用 PUT 请求更改父项:

例 24.8. 更改父标签

PUT /ovirt-engine/api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <parent>
        <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
    </parent>
</tag>

第 25 章 事件

25.1. 事件元素

从入口点 URI 获取的 rel="events" 链接可以访问 事件 集合,并列出 Red Hat Virtualization Manager 中的系统事件。
表 25.1. 事件元素
元素 类型 描述
description 字符串 系统事件的描述
code 整数 整数事件代码。
严重性 正常warningerroralert之一 事件的严重性等级。
time xsd:dateTime 格式: YYYY-MM-DDTh:mm:ss 事件发生的时间戳。
correlation_id 字符串 在 Red Hat Virtualization 层间分布的操作识别字符串。
user id= GUID 触发该事件的用户的识别代码。
origin 字符串 事件源。oVirt 报告标准事件.
custom_id 整数 自定义事件标识号。标准事件的 custom_id-1
flood_rate 整数 在事件列表中,同一事件无法重新调用的时间(以秒为单位)。默认值为 30
external_status complex 主机的外部健康状态。包含 state 元素,可以是 ok 之一、infoerrorwarningfailure

25.2. 事件集合的 XML 表

例 25.1. 事件集合的 XML 表示

<events>
    <event id="537" href="/ovirt-engine/api/events/537">
        <description>User vdcadmin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-01-12T10:48:27.827+02:00</time>
        <user id="9b9002d1-ec33-4083-8a7b-31f6b8931648"
          href="/ovirt-engine/api/users/9b9002d1-ec33-4083-8a7b-31f6b8931648"/>
    </event>
    ...
</events>

25.3. XML 代表虚拟机创建事件

除了 用户 外,事件 表示法还包含一组与事件相关的资源的 XML 元素关系。

例 25.2. 虚拟机创建事件的 XML 表示

<event id="635" href="/ovirt-engine/api/events/635">
    <description>VM bar was created by rhevadmin.</description>
    <code>34</code>
    <severity>normal</severity>
    <time>2011-07-11T16:32:03.172+02:00</time>
    <user id="4621b611-43eb-4d2b-ae5f-1180850268c4"
      href="/ovirt-engine/api/users/4621b611-43eb-4d2b-ae5f-1180850268c4"/>
    <vm id="9b22d423-e16b-4dd8-9c06-c8e9358fbc66"
      href="/ovirt-engine/api/vms/9b22d423-e16b-4dd8-9c06-c8e9358fbc66"/>
    <storage_domain id="a8a0e93d-c570-45ab-9cd6-3c68ab31221f"
      href="/ovirt-engine/api/storagedomains/a8a0e93d-c570-45ab-9cd6-3c68ab31221f"/>
</event>
这个示例表示提供与虚拟机资源和存储域资源相关的 XML 元素。

25.4. Methods

25.4.1. 搜索事件

events 集合提供与其他资源集合类似的搜索查询。搜索事件集合时的附加功能是能够从特定事件搜索。这会查询指定事件之后的所有事件。
从事件查询需要额外添加 from 参数,然后再搜索查询。这一 from 参数引用事件 ID 代码。

例 25.3. 从事件搜索

GET /ovirt-engine/api/events;from=1012?search=type%3D30 HTTP/1.1
Accept: application/xml
这将显示所有事件,其 type 设为 30,因为 id="1012"
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="1018" href="/ovirt-engine/api/events/1018">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:22.485+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1016" href="/ovirt-engine/api/events/1016">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:07.236+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1014" href="/ovirt-engine/api/events/1014">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:02:16.009+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/ovirt-engine/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
</events>

例 25.4. 使用特定事件严重性搜索

GET /ovirt-engine/api/events?search=severity>normal HTTP/1.1
Accept: application/xml
这将显示严重性高于 normal 的所有事件。严重级别包括 常规warningerroralert
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="2823" href="/ovirt-engine/api/events/2823">
        <description>Host Host-05 has time-drift of 36002 seconds while maximum configured value is 300 seconds.</description>
        <code>604</code>
        <severity>warning</severity>
        <time>2015-07-11T14:03:22.485+10:00</time>
        <host href= "/ovirt-engine/api/hosts/44e52bb2-27d6-4d35-8038-0c4b4db89789" id="44e52bb2-27d6-4d35-8038-0c4b4db89789"/>
        <cluster href= "/ovirt-engine/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
        <origin>oVirt</origin>
        <custom_id>-1</custom_id>
        <flood_rate>30</flood_rate>
    </event>
...
</events>

25.4.2. 分页事件

虚拟化环境会在一段时间内生成大量事件。但是,API 仅显示一个搜索查询的默认事件数。要显示多于默认值,API 在搜索查询中用 page 命令分隔到 页面
以下搜索查询告知 API 使用 page 值与 sortby 子句的组合来分页结果:
按时间排序页 1
sortby 子句定义用于订购结果的基本元素,以及结果是升序还是降序。对于 事件 的搜索查询,请将基础元素设置为 time,以及升序(asc)的顺序,以便 API 显示从创建虚拟化环境中的所有事件。
页面 条件定义页面号。一个页面等于要列出的默认事件数。分页从第 1 页 开始。要查看更多页面,请增加 页面 值:
按时间排序第 2 页
按时间排序第 3 页
按时间排序 4 页

例 25.5. 分页事件

这个示例分页 事件 资源。URL 编码的请求为:
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1
Accept: application/xml
增加 page 值以查看结果的下一页。
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1
Accept: application/xml
使用参数中 的其他参数 设置起始 ID
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202&from=30 HTTP/1.1
Accept: application/xml

25.4.3. 添加事件

API 可以通过 POST 请求将自定义事件添加到 事件 集合中。新事件需要 描述严重性origincustom_id 元素。自定义事件还可以包括 flood_rate用户 ID 以及与事件相关的任何资源的 id 代码。hoststorage_domain 元素可以包含 external_status 元素来设置外部健康状态。

例 25.6. 将自定义事件添加到事件列表中

POST /ovirt-engine/api/events HTTP/1.1
Accept: application/xml
Content-type: application/xml

<event>
  <description>The heat of the host is above 30 Oc</description>
  <severity>warning</severity>
  <origin>HP Openview</origin>
  <custom_id>1</custom_id>
  <flood_rate>30</flood_rate>
  <host id="f59a29cd-587d-48a3-b72a-db537eb21957" >
    <external_status>
       <state>warning</state>
    </external_status>
  </host>
</event>

25.4.4. 删除事件

从事件列表中删除事件需要 DELETE 请求。

例 25.7. 删除事件

DELETE /ovirt-engine/api/events/1705 HTTP/1.1

HTTP/1.1 204 No Content

附录 A. 使用 cURL 的 API 使用情况

A.1. 使用 cURL 的 API 使用情况

本附录提供了调整 REST 请求以用于 cURL 的说明。curl 是一个命令行工具,用于跨各种协议传输数据,包括 HTTP,并支持多个平台,如 Linux、Windows、Mac 和 Solaris。大多数 Linux 发行版包括 cURL 作为软件包。

A.2. 安装 cURL

Red Hat Enterprise Linux 用户使用以下终端命令安装 cURL
yum install curl
有关其他平台,请参阅 cURL 网站(http://curl.haxx.se/)的安装说明。

A.3. 使用 cURL

curl 使用命令行界面将请求发送到 HTTP 服务器。集成请求需要以下命令语法:
Usage: curl [options] uri
uri 指的是发送请求的目标 HTTP 地址。这是 API 入口点路径(/ovirt-engine/api)中的 Red Hat Virtualization Manager 主机上的位置。

curl 选项

-X COMMAND, --request COMMAND
要使用的请求命令。在 REST API 的上下文中,使用 GETPOSTPUTDELETE
示例: -X GET
-H , --header LINE
与请求包含的 HTTP 标头。如果需要多个标头,请使用多个标头选项。
示例: -H "Accept: application/xml" -H "Content-Type: application/xml"
-u USERNAME:PASSWORD, --user USERNAME:PASSWORD
Red Hat Virtualization 用户的用户名和密码。此属性充当 Authorization: 标头的便捷替换。