Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

REST API 指南

Red Hat Virtualization 4.4

使用红帽虚拟化 REST 应用程序编程接口

摘要

本指南描述了 Red Hat Virtualization Manager 表述性状态转移应用程序编程接口。
本指南从 ovirt-engine-api-model代码中的文档注释生成，目前已完成。随着新内容可用，此文档的更新版本将会发布。

第 1 章 简介
复制链接

Red Hat Virtualization Manager 提供表述性状态转移(REST)API。API 为软件开发人员和系统管理员提供控制标准 Web 界面之外的红帽虚拟化环境。API 有助于开发人员和管理员将红帽虚拟化环境的功能与通过标准 Hypertext 传输协议(HTTP)访问 API 的自定义脚本或外部应用程序集成。

API 的优点是：

  • 广泛的客户端支持 - 任何支持 HTTP 协议的编程语言、框架或系统都可以使用 API。
  • 自描述性 - 客户端应用程序需要最少了解虚拟化基础架构，因为运行时会发现许多细节。
  • 基于资源的模式 - 基于资源的 REST 模式提供了管理虚拟化平台的自然方法。

这使开发人员和管理员能够：

  • 与企业 IT 系统集成.
  • 与第三方虚拟化软件集成.
  • 执行自动维护或错误检查任务。
  • 使用脚本在红帽虚拟化环境中自动执行重复任务。

本文档可用作 Red Hat Virtualization API 的参考。它旨在为开发人员和管理员提供相关说明和示例，以帮助通过 API（直接或使用提供的 SDK）利用其红帽虚拟化环境的功能。

1.1. 表述状态传输
复制链接

表述性状态转移(REST) 是一种设计架构，侧重于特定服务及其表示法的资源。资源表示是对应于服务器上一个特定受管元素的重要信息抽象。客户端向位于统一资源标识符(URI)的服务器元素发送请求，并使用标准 HTTP 方法（如 GET、POST、PUT 和 DELETE ）执行操作。这在客户端和服务器之间提供无状态通信，每个请求都独立于任何其他请求，并且包含完成请求所需的所有信息。

1.2. API 先决条件
复制链接

使用 Red Hat Virtualization API 的先决条件：

第 2 章 身份验证和安全
复制链接

2.1. TLS/SSL 认证
复制链接

红帽虚拟化 API 需要 Hypertext 传输协议安全(HTTPS) [1] 用于与客户端软件（如 SDK 和 CLI 组件）进行安全交互。这包括获取服务器使用的 CA 证书，并将其导入到客户端的证书存储中。

2.1.1. 获取 CA 证书
复制链接

您可以从 Red Hat Virtualization Manager 获取 CA 证书，并使用以下方法之一将其传送到客户端机器：

方法 1

获取 CA 证书的首选方法是使用 openssl s_client 命令行工具与服务器执行真正的 TLS 握手，然后提取它所提供的证书。运行类似如下的命令： 

$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null

这个命令将连接到服务器并显示类似如下的输出： 

CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
 0 s:/C=US/O=Example Inc./CN=myengine.example.com
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 之间的文本显示服务器提供的证书。第一个是服务器本身的证书，最后一个是 CA 的证书。将 CA 证书（包括标记）复制到 ca.crt 文件中。结果应如下所示： 

-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
重要

这是获取服务器使用的 CA 证书的最可靠方法。此处描述的其余方法将在大多数情形中可用，但是如果被服务器管理员手动替换，它们将无法获得正确的 CA 证书。

方法 2

如果无法使用上述 的openssl s_client 方法，您可以使用命令行工具从 Red Hat Virtualization Manager 下载 CA 证书。

命令行工具示例包括 curl 和 wget，它们都可在多个平台上使用。

如果使用 curl ： 

$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

如果使用 wget: 

$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
方法 3

使用 Web 浏览器导航到位于以下位置的证书： 

https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

根据所选的浏览器，证书下载或导入浏览器的密钥存储。

  1. 如果浏览器下载证书 ：将文件保存为 ca.crt。
  2. 如果浏览器导入证书 ：从浏览器的认证选项导出它，并将其保存为 ca.crt。
方法 4

登录 Red Hat Virtualization Manager，从信任存储导出证书，并将其复制到您的客户端计算机。

  1. 以 root 用户身份登录 Red Hat Virtualization Manager 机器 。

  2. 使用 Java 密钥工具管理 实用程序从信任存储导出证书： 

    # keytool \
-keystore /etc/pki/ovirt-engine/.truststore \
-storepass mypass \
-exportcert \
-alias cacert \
-rfc \
-file ca.crt

    这会创建一个名为 ca.crt 的证书文件。

  3. 使用 scp 命令将证书复制到客户端机器： 

    $ scp ca.crt myuser@myclient.example.com:/home/myuser/.

每个方法都会在您的客户端机器上产生名为 ca.crt 的证书文件。然后，您必须将此文件导入到客户端的证书存储中。

2.1.2. 将证书导入到客户端
复制链接

将证书导入到客户端取决于客户端如何存储和解释证书。有关导入证书的更多信息，请参阅您的客户端文档。

2.2. Authentication
复制链接

具有 Red Hat Virtualization Manager 帐户的任何用户都可以访问该 API。所有请求都必须使用 OAuth 或基本身份验证进行身份验证，如下所述。

2.2.1. OAuth 身份验证
复制链接

自 Red Hat Virtualization 版本 4.0 起，首选身份验证机制为 OAuth 2.0，如 RFC 6749 所述。

OAuth 是一种复杂的协议，具有多种获取授权和访问令牌的机制。与 Red Hat Virtualization API 一起使用，唯一支持的是 Resource Owner Password Credentials Grant，如 RFC 6749 的 4.3 节所述。

您必须首先获取令牌，将用户名和密码发送到 Red Hat Virtualization Manager 单点登录服务： 

POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

请求正文必须包含 grant_type、scope、username 和 password 参数：

Expand
表 2.1. OAuth 令牌请求参数
名称值

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

这些参数必须经过 URL 编码。例如，用户名中的 @ 字符需要编码为 %40。生成的请求正文将类似如下： 

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
重要

在 OAuth RFC 中，scope 参数被描述为可选，但在将它与 Red Hat Virtualization API 搭配使用时，它的值必须是 ovirt-app-api。

如果用户名和密码有效，Red Hat Virtualization Manager 单点登录服务将使用类似本文档的 JSON 文档进行响应： 

{
  "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
  "token_type": "bearer",
  "scope": "...",
  ...
}

出于 API 身份验证目的，唯一相关的名称/值对是 access_token。不要以任何方式操作；使用它与 SSO 服务提供的完全相同。

获取令牌后，它可用于通过在 HTTP 授权 标头中包含和使用 Bearer 方案来对 API 执行请求。例如，要获取虚拟机列表，请发送如下请求： 

GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

该令牌可以多次用于多个请求，但它最终会过期。当它过期时，服务器将使用 401 HTTP 响应代码拒绝请求： 

HTTP/1.1 401 Unauthorized

当发生这种情况时，需要一个新的令牌，因为 Red Hat Virtualization Manager 单点登录服务目前不支持刷新令牌。可以使用上述相同方法请求新的令牌。

2.2.2. 基本身份验证
复制链接

重要

基本身份验证只支持向后兼容，自 Red Hat Virtualization 版本 4.0 起已弃用，并将在以后的中删除。

每个请求使用 HTTP 基本身份验证 [2] 对凭据进行编码：如果请求没有包含适当的 授权 标头，服务器会发送 401 Authorization Required 响应： 

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com

HTTP/1.1 401 Authorization Required

请求通过指定域 的授权 标头发出。使用 username@domain:password 约定在提供的凭证中对适当的 Red Hat Virtualization Manager 域和用户进行编码。

下表显示了 Base64 中编码凭据的流程。

Expand
表 2.2. 编码凭证用于 API 访问
项值

用户名

admin

域

internal

密码

mypassword

未编码凭证

admin@internal:mypassword

Base64 编码的凭证

YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

提供 Base64 编码的凭证，如下所示： 

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK
重要

基本身份验证涉及潜在的敏感信息，如密码，以纯文本形式发送。API 需要 Hypertext 传输协议安全(HTTPS)进行纯文本请求的传输级别的加密。

重要

有些 Base64 库将结果分为多行，并使用换行字符终止每行。这会破坏标头，并导致出现错误的请求。Authorization 标头需要在标头内一行上编码的凭据。

2.2.3. 身份验证会话
复制链接

API 也提供身份验证会话支持。使用身份验证详细信息发送初始请求，然后使用会话 Cookie 发送所有后续请求进行身份验证。

2.2.3.1. 请求经过身份验证的会话
复制链接

  1. 使用 Authorization 和 Prefer: persistent-auth 标头发送请求： 

    HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
Prefer: persistent-auth

HTTP/1.1 200 OK
...

    这会返回一个带有以下标头的响应： 

    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure

    记录 JSESSIONID= 值。在本例中，值为 5dQja5ubr4yvI2MM2z+LZxrK。

  2. 使用 JSESSIONID= 值的 Prefer: persistent-auth 和 Cookie 标头发送随后的所有请求。使用经过身份验证的会话时，不再需要 Authorization 标头。 

    HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Prefer: persistent-auth
Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK

HTTP/1.1 200 OK
...

  3. 当不再需要会话时，请在没有 Prefer: persistent-auth 标头的情况下对服务器执行请求。 

    HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK
...


第 3 章 常见概念
复制链接

3.1. 类型
复制链接

API 使用类型概念来描述接受和返回的不同对象类型。

有三种相关的类型：

原语类型
描述简单对象种类，如字符串或 整数。
枚举类型
描述有效值列表，如 VmStatus 或 DiskFormat。
结构化类型
描述结构化对象，具有多个属性和链接，如 Vm 或 Disk。

3.2. 识别的类型
复制链接

API 使用的许多类型都代表有标识的对象，它们具有唯一标识符并且独立于其他对象。用于描述这些对象的类型扩展了 Identified 类型，其中包含以下常用属性集合：

Expand
属性类型描述

id

字符串

虚拟化基础架构中的每个对象包含一个 id，它充当唯一标识符。

href

字符串

对象的规范位置作为绝对路径。

name

字符串

用户提供的对象的人类可读名称。名称 在同一类型的所有对象中都是唯一的。

description

字符串

免费的用户提供对象的人类可读描述。

重要

目前，对于大多数类型的对象，id 属性实际上是一个随机生成的 UUID，但这是一个实施细节，用户不应依赖它，因为它将来可能会有所变化。相反，用户应该假定这些标识符只是字符串。

3.3. 对象（object）
复制链接

对象是 API 支持的类型的单独实例。例如，标识符为 123 的虚拟机 是 Vm 类型的对象。

3.4. 集合
复制链接

集合是一组同类型的对象。

3.5. 表示
复制链接

在客户端和服务器之间传输对象时，需要表示对象的状态。该 API 支持 XML 和 JSON 作为对象状态的一种表示，包括用于输入和输出的对象。

3.5.1. XML 表述
复制链接

对象的 XML 表示法包含与对象类型对应的 XML 元素、id 和 href 属性的 XML 属性，以及其余属性的嵌套 XML 元素。例如，虚拟机的 XML 表述如下： 

<vm id="123" href="/ovirt-engine/api/vms/123">
  <name>myvm</name>
  <description>My VM</description>
  <memory>1073741824</memory>
  ...
</vm>

对象集合的 XML 表示由 XML 元素组成，以对象类型命名，以复数表示。这包含集合对象的表示。例如，虚拟机集合的 XML 表述如下： 

<vms>
  <vm id="123" href="/ovirt-engine/api/vms/123">
    <name>yourvm</name>
    <description>Your VM</description>
    <memory>1073741824</memory>
    ...
  </vm>
  <vm id="456" href="/ovirt-engine/api/vms/456">
    <name>myname</name>
    <description>My description</description>
    <memory>2147483648</memory>
    ...
  </vm>
  ...
</vms>
重要

在对象 XML 表示中，id 和 href 属性是唯一以 XML 属性表示的属性，其余则表示为嵌套的 XML 元素。

3.5.2. JSON 表示
复制链接

对象的 JSON 表示形式包含含有各个属性（包括 id 和 href）的名称/值对的 JSON 文档。例如，虚拟机的 JSON 表示形式如下： 

{
  "id": "123",
  "href": "/ovirt-engine/api/vms/123",
  "name": "myvm",
  "description": "My VM",
  "memory": 1073741824,
  ...
}

对象集合的 JSON 表示形式包含一个 JSON 文档，包含一个名称/值对（以单数形式命名对象类型），后者包含一个数组，其中包含集合对象的表示形式。例如，虚拟机集合的 JSON 代表形式如下： 

{
  "vm": [
    {
      "id": "123",
      "href": "/ovirt-engine/api/vms/123",
      "name": "myvm",
      "description": "My VM",
      "memory": 1073741824,
      ...
    },
    {
      "id": "456",
      "href": "/ovirt-engine/api/vms/456",
      "name": "yourvm",
      "description": "Your VM",
      "memory": 2147483648,
      ...
    },
  ]
}

3.6. 服务
复制链接

服务是负责检索、添加更新、删除和执行 API 支持的对象操作的服务器的一部分。

有两种相关的服务：

管理一组对象的服务
这些服务可用于列出现有对象和添加新对象。例如，Vms 服务负责管理系统中可用的虚拟机的集合。
管理特定对象的服务
这些服务负责在特定对象中检索、更新、删除和执行操作。例如，Vm 服务负责管理特定的虚拟机。

每一服务都可通过服务器中的特定路径访问。例如，可以通过路径 /vms 在 中管理系统中可用的虚拟机集合的服务，以及管理虚拟机 123 的服务可通过路径 /vms/123 获取。

所有类型的服务都具有一组方法，表示它们可以执行的操作。管理对象集合的服务通常具有 列表 和 添加 方法。管理特定对象的服务通常具有 get、update和 remove 方法。此外，服务也可能具有代表较少常见操作的操作方法。例如，Vm 服务具有一个用于启动虚拟机的 start 方法。

对于更常用的方法，方法名称和 HTTP 方法名称之间存在直接映射：

Expand
方法名称HTTP 方法

add

POST

get

GET

list

GET

update

PUT

remove

删除

HTTP 请求中使用的路径是服务的路径，其前缀为 /ovirt-engine/api。

例如，列出 虚拟机的请求应如下所示，使用 HTTP GET 方法和路径 /vms: 

GET /ovirt-engine/api/vms

对于操作方法，HTTP 方法始终为 POST，方法的名称作为后缀添加到路径中。例如，启动虚拟机 123 的请求 应 如下所示，使用 HTTP POST 方法和路径 /vms/123/start ： 

POST /ovirt-engine/api/vms/123/start

每种方法具有一组参数。

参数分为两类：

main 参数
main 参数对应检索、添加或更新的对象或集合。这只适用于 add、get、列表 和更新 方法，每个方法正好有一个这样的主参数。
辅助参数
其余的参数.

例如，添加虚拟机的操作（请参阅 此处）具有三个参数：vm 、 克隆和 clone _permissions。主要参数是 vm，因为它描述了要添加的对象。clone 和 clone_permissions 参数是辅助参数。

用于输入的主要参数必须包含在 HTTP 请求的正文中。例如，在添加虚拟机时，类型为 Vm 的 vm 参数必须包含在请求正文中。因此，添加虚拟机的完整请求（包括所有 HTTP 详情）必须如下所示： 

POST /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
</vm>

当用于输出时，主要参数包含在响应正文中。例如，添加虚拟机时，vm 参数将包含在响应正文中。因此，完整的响应正文如下所示： 

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

<vm href="/ovirt-engine/api/vms/123" id="123">
  <name>myvm</name>
  <description>My VM</description>
  ...
</vm>

辅助参数仅允许进行输入（操作方法除外，稍后介绍），且必须作为查询参数包含。例如，当添加将 clone 参数设置为 true 的虚拟机时，完整的请求必须如下所示： 

POST /ovirt-engine/api/vms?clone=true HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
</vm>

操作方法仅具有次要参数。它们可用于输入和输出，并且它们应包含在请求正文中，并用 action 元素打包。例如，用于启动虚拟机的操作方法（请参阅 此处）有一个 vm 参数，用于描述应当如何启动虚拟机，以及用于指定是否应使用 cloud-init 参数来配置客户机操作系统 的 use_cloud_ init 参数。因此，在使用 XML 时，使用 cloud-init 启动虚拟机 123 的完整请求将如下所示： 

POST /ovirt-engine/api/vms/123/start HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<action>
  <use_cloud_init>true</use_cloud_init>
  <vm>
    <initialization>
      <nic_configurations>
        <nic_configuration>
          <name>eth0</name>
          <on_boot>true</on_boot>
          <boot_protocol>static</boot_protocol>
          <ip>
            <address>192.168.0.100</address>
            <netmask>255.255.255.0</netmask>
            <gateway>192.168.0.1</netmask>
          </ip>
        </nic_configuration>
      </nic_configurations>
      <dns_servers>192.168.0.1</dns_servers>
    </initialization>
  </vm>
</action>

3.7. 搜索
复制链接

某些服务的列表 方法有一个 搜索 参数，可用于指定搜索条件。使用时，服务器将仅返回满足这些条件的集合中的对象。例如，以下请求将仅返回名为 myvm 的虚拟机： 

GET /ovirt-engine/api/vms?search=name%3Dmyvm

3.7.1. 最大结果参数
复制链接

使用 max 参数限制返回的对象数量。例如，无论系统中有多少可用的虚拟机，以下请求将仅返回一个虚拟机： 

GET /ovirt-engine/api/vms?max=1

没有 max 参数的搜索请求将返回所有对象。建议指定 max 参数，以减少请求对系统整体性能的影响。

3.7.2. 问题单敏感度
复制链接

默认情况下，查询不区分大小写。例如，以下请求将返回名为 myvm、MyVM 和 MYVM 的虚拟机： 

GET /ovirt-engine/api/vms?search=name%3Dmyvm

可选的 区分大小写 的布尔值参数可用于更改此冲突。例如，要完全获取名为 myhost 的虚拟机，而不是 MyHost 或 MYHOST，请发送如下请求： 

GET /ovirt-engine/api/vms?search=name%3D=myvm&case_sensitive=true

3.7.3. 搜索语法
复制链接

搜索 参数使用与 Red Hat Virtualization 查询语言相同的语法： 

(criteria) [sortby (element) asc|desc]

sortby 子 句是可选的，仅当对结果进行排序时才需要。

搜索查询示例：

Expand
集合(Collection)标准结果

主机

vms.status=up

返回正在运行虚拟机的所有主机的列表 。

vms

domain=example.com

返回在指定域上运行的所有虚拟机的列表。

vms

users.name=mary

返回属于用户名为 name mary 的所有虚拟机的列表。

事件

severity > 正常排序

返回所有严重级别高于 正常 并按照 time 属性值排序的事件的列表。

事件

severity > normal sortby time desc

返回所有严重级别高于 正常 的事件列表，并按其 time 属性值降序排列。

搜索 参数的值必须经过 URL 编码，才能翻译保留的字符，如 operators 和空格。例如，等号应编码为 %3D: 

GET /ovirt-engine/api/vms?search=name%3Dmyvm

3.7.4. 通配符
复制链接

星号可用作值的一部分，以指示任何字符串匹配，包括 emtpy 字符串。例如，以下请求将返回名称以 myvm 开头的所有虚拟机，如 myvm、myvm 2、myvm a 或 myvm-webserver ： 

GET /ovirt-engine/api/vms?search=name%3Dmyvm*

3.7.5. 分页
复制链接

有些 Red Hat Virtualization 环境包含大量对象。通过一个请求检索所有这些请求并不实际，会损害性能。为了允许通过页面检索它们，搜索 参数支持可选 page 子 句。这与 max 参数相结合，是分页的基础。例如，要获得虚拟机的第一页，页面大小为 10 个虚拟机，请按如下所示发送请求： 

GET /ovirt-engine/api/vms?search=page%201&max=10
注意

搜索参数是 URL 编码的，搜索 参数的实际值在编码前是第 1 页，因此这实际上正在请求第一页。

增加 页面 值以检索下一页： 

GET /ovirt-engine/api/vms?search=page%202&max=10

page 子句可以和 search 参数内的其他子句搭配使用。例如，以下请求将返回虚拟机的第二页，但按名称排序： 

GET /ovirt-engine/api/vms?search=sortby%20name%20page%202&max=10
重要

API 是无状态的；不能在不同请求之间保留状态，因为所有请求都是相互独立的。因此，如果您的请求之间发生状态更改，则页面结果可能会不一致。

例如，如果您从虚拟机列表中请求特定页面，并且在请求下一页之前创建或删除虚拟机，您的结果可能缺失，或者包含重复项。

3.8. 以下链接
复制链接

API 返回对相关对象的引用作为链接。例如，当检索虚拟机时，它包含到其磁盘附加和网络接口卡的链接： 

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <link rel="diskattachments" href="/ovirt-engine/api/vms/123/diskattachments"/>
  <link rel="nics" href="/ovirt-engine/api/vms/123/nics"/>
  ...
</vm>

这些链接对象的完整描述可通过发送单独的请求来检索 ： 

GET /ovirt-engine/api/vms/123/diskattachments
GET /ovirt-engine/api/vms/123/nics

但在某些情况下，使用 API 检索同一请求中链接的信息更为方便。例如，当额外的网络往返会带来不便的开销时，或者当多个请求以不接受的方式使应用代码变得复杂时，这很有用。对于这些用例，API 提供了一个 以下参数，它允许应用仅使用一个请求来检索链接的信息。

以下 参数的值 是由逗号分隔的字符串列表。这些字符串各自是链接的对象的路径。例如，要检索磁盘附件和上例中的 NIC，请求应类似如下： 

GET /ovirt-engine/api/vms/123?follow=disk_attachments,nics

这将返回类似如下的响应： 

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789"/>
    </disk_attachment>
    ...
  </disk_attacments>
  <nics>
    <nic id="234" href="/ovirt-engine/api/vms/123/nics/234">
      <name>eth0</name>
      <interface>virtio</interface>
      <linked>true</linked>
      <mac>
        <address>00:1a:4a:16:01:00</address>
      </mac>
      <plugged>true</plugged>
    </nic>
    ...
  </nics>
  ...
</vm>

链接对象的路径可以是单个词语，如上例中所示，也可以是一系列词语（用点分隔）来请求嵌套数据。例如，上例使用 disk_attachments 来检索磁盘附加的完整描述，但每个磁盘附加包含一个指向磁盘的链接，而这并未 遵循。要追踪到磁盘的链接，可以使用以下请求： 

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk

这将产生以下响应： 

<vm id="123" href="/ovirt-engine/api/vms/123">
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789">
        <name>mydisk</name>
        <description>My disk</description>
        <actual_size>0</actual_size>
        <format>raw</format>
        <sparse>true</sparse>
        <status>ok</status>
        <storage_type>image</storage_type>
        <total_size>0</total_size>
        ...
      </disk>
    </disk_attachment>
    ...
  </disk_attachments>
  ...
</vm>

路径可根据需要深层进行。例如，也要获取磁盘统计信息： 

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics

可以组合多个路径元素和多个路径。例如，要获取磁盘附件和网络接口卡，以及它们的统计信息： 

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics,nics.statistics
重要

几乎所有检索对象的操作都支持 以下参数，但确保明确检查参考文档，因为某些操作可能不支持它，或者可能会提供有关如何使用它来获取最佳性能的建议。

重要

使用以下 参数，将开销从客户端移到服务器端。当您请求其他数据时，服务器必须获取并将其与基本数据合并。这在服务器端消耗 CPU 和内存，并且大部分情况下需要额外的数据库查询。这可能会对服务器的性能造成负面影响，特别是在大规模环境中。确保在真实的环境中测试您的应用程序，并且仅 在合理时才使用以下参数。

3.9. 权限
复制链接

管理单个对象的许多服务都提供对 权限 服务的引用，该服务管理分配给该对象的权限。每个权限包含指向用户或组、角色和对象的链接。例如，可以检索分配给特定虚拟机的权限来发送如下请求： 

GET /ovirt-engine/api/vms/123/permissions

响应正文如下所示： 

<permissions>
  <permission id="456" href="/ovirt-engien/api/vms/123/permissions/456">
    <user id="789" href="/ovirt-engine/api/users/789"/>
    <role id="abc" href="/ovirt-engine/api/roles/abc"/>
    <vm id="123" href="/ovirt-engine/api/vms/123"/>
  </permission>
  ...
</permissions>

向发送 POST 请求的对象添加权限，并将权限表示给此服务。每个新权限都需要一个角色和用户。

3.10. 处理错误
复制链接

某些错误需要在标准 HTTP 状态代码之外做进一步的说明。例如，API 报告 响应 正文中失败的对象状态更新或操作失败。此错误包含 原因和 详细信息 属性。例如，当服务器收到在没有强制 name 属性的情况下创建虚拟机的请求时，它将使用以下 HTTP 响应行响应： 

HTTP/1.1 400 Bad Request

和以下响应正文： 

<fault>
  <reason>Incomplete parameters</reason>
  <detail>Vm [name] required for add</detail>
</fault>

第 4 章 快速入门示例
复制链接

本节中的示例演示了如何使用 REST API 设置基本红帽虚拟化环境并创建虚拟机。除了标准先决条件外，这些示例还需要以下内容：

  • 联网和配置红帽虚拟化安装。
  • 包含您要安装的虚拟机操作系统的 ISO 文件。本章使用 CentOS 7 作为安装 ISO 示例。

API 示例使用 curl 来演示客户端应用的 API 请求。您可以使用任何发送 HTTP 请求的应用。

重要

本例中的 HTTP 请求标头省略 Host 和 Authorization 标头。但是，这些字段是必需的，需要特定于 Red Hat Virtualization 安装的数据。

curl 示例使用 admin@internal 作为用户名，my password 作为密码，/etc/pki/ovirt-engine/ca.pem 用作证书位置，myengine.example.com 作为主机名。您必须将它们替换为您的环境的正确值。

Red Hat Virtualization 会为每个资源生成唯一标识符，用于 id 属性。本例中的标识符代码将与 Red Hat Virtualization 环境中的标识符代码不同。

在许多示例中，为了简洁起见，API 返回的结果的一些属性已被省略。例如，请参阅集群引用来获取属性的完整列表。

4.1. 访问 API 入口点
复制链接

以下请求检索 API 版本 4 的主要入口点表示： 

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

同一请求，但使用 /v4 URL 前缀而不是 Version 标头： 

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

同一个请求，使用 curl 命令： 

curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api

结果是一个类型为 Api 的对象： 

<api>
  <link href="/ovirt-engine/api/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters" rel="datacenters"/>
  ...
  <product_info>
    <name>oVirt Engine</name>
    <vendor>ovirt.org</vendor>
    <version>
      <build>0</build>
      <full_version>4.0.0-0.0.el7</full_version>
      <major>4</major>
      <minor>0</minor>
      <revision>0</revision>
    </version>
  </product_info>
  <special_objects>
    <blank_template href="..." id="..."/>
    <root_tag href="..." id="..."/>
  </special_objects>
  <summary>
    <hosts>
      <active>23</active>
      <total>30</total>
    </hosts>
    <storage_domains>
      <active>5</active>
      <total>6</total>
    </storage_domains>
    <users>
      <active>12</active>
      <total>102</total>
    </users>
    <vms>
      <active>253</active>
      <total>545</total>
    </vms>
  </summary>
  <time>2016-10-06T15:38:18.548+02:00</time>
</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

更改此参数会影响未明确指定版本的 API 的所有用户。

入口点为用户提供虚拟环境中集合的链接。每个集合链接的 Therel 属性 都会为每个链接提供一个参考点。本例中的下一步将检查数据中心集合，该集合可通过 datacenters 链接使用。

入口点还包含其他数据，如 product_info、special_objects 和 summary。本例之外的章节将对此数据进行阐述。

4.2. 列出数据中心
复制链接

Red Hat Virtualization 在安装时创建一个默认 数据中心。本例使用 Default 数据中心作为虚拟环境的基础。

以下请求检索数据中心的表示法： 

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

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/datacenters

结果将是 DataCenter 类型的对象列表： 

<data_centers>
  <data_center href="/ovirt-engine/api/datacenters/001" id="001">
    <name>Default</name>
    <description>The default Data Center</description>
    <link href="/ovirt-engine/api/datacenters/001/clusters" rel="clusters"/>
    <link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/>
    ...
    <local>false</local>
    <quota_mode>disabled</quota_mode>
    <status>up</status>
    <supported_versions>
      <version>
        <major>4</major>
        <minor>0</minor>
      </version>
    </supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
    </version>
  </data_center>
  ...
</data_centers>

请注意您的 Default 数据中心的 ID。它相对于虚拟环境的其他资源标识此数据中心。

数据中心还包含指向管理附加到数据中心的存储域的服务的链接 ： 

<link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/>

该服务用于从主 storagedomains 集合中附加存储域，本例稍后将对此进行阐述。

4.3. 列出主机集群
复制链接

Red Hat Virtualization 在安装时创建一个默认 主机集群。本例使用 Default 集群对 Red Hat Virtualization 环境中的资源进行分组。

以下请求检索集群集合的表示形式： 

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

同一个请求，使用 curl 命令： 

curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/clusters

结果将是类型为 Cluster 的对象列表： 

<clusters>
  <cluster href="/ovirt-engine/api/clusters/002" id="002">
    <name>Default</name>
    <description>The default server cluster</description>
    <link href="/ovirt-engine/api/clusters/002/networks" rel="networks"/>
    <link href="/ovirt-engine/api/clusters/002" rel="permissions"/>
    ...
    <cpu>
      <architecture>x86_64</architecture>
      <type>Intel Nehalem Family</type>
    </cpu>
    <version>
      <major>4</major>
      <minor>0</minor>
    </version>
    <data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
  </cluster>
  ...
</clusters>

请注意 默认 主机集群的 id。它根据虚拟环境的其他资源标识此主机集群。

Default 集群通过使用 data_center 链接的 id 和 href 属性的关系，与 Default 数据中心 关联： 

<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>

网络 链接是对管理与此集群关联的网络的 服务的 引用。下一节将更详细地阐述网络集合。

4.4. 列出逻辑网络
复制链接

Red Hat Virtualization 在安装时创建一个默认的 ovirtmgmt 网络。此网络充当红帽虚拟化管理器访问主机的管理网络。

此网络与 Default 集群关联，是 Default 数据中心的成员。本例使用 ovirtmgmt 网络来连接虚拟机。

以下请求检索逻辑网络列表： 

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

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/networks

结果将是网络类型的对象列表 ： 

<networks>
  <network href="/ovirt-engine/api/networks/003" id="003">
    <name>ovirtmgmt</name>
    <description>Management Network</description>
    <link href="/ovirt-engine/api/networks/003/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/networks/003/vnicprofiles" rel="vnicprofiles"/>
    <link href="/ovirt-engine/api/networks/003/networklabels" rel="networklabels"/>
    <mtu>0</mtu>
    <stp>false</stp>
    <usages>
      <usage>vm</usage>
    </usages>
    <data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
  </network>
  ...
</networks>

ovirtmgmt 网络通过利用数据中心的 ID 的关系附加到 Default 数据中心。

ovirtmgmt 网络还通过集群网络子集合中的关系附加到 Default 集群。

4.5. 列出主机
复制链接

本示例检索主机列表，并显示在虚拟环境中注册的名为 myhost 的主机： 

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

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/hosts

结果将是主机类型的对象列表 ： 

<hosts>
  <host href="/ovirt-engine/api/hosts/004" id="004">
    <name>myhost</name>
    <link href="/ovirt-engine/api/hosts/004/nics" rel="nics"/>
    ...
    <address>node40.example.com</address>
    <cpu>
      <name>Intel Core Processor (Haswell, no TSX)</name>
      <speed>3600</speed>
      <topology>
        <cores>1</cores>
        <sockets>2</sockets>
        <threads>1</threads>
      </topology>
    </cpu>
    <memory>8371830784</memory>
    <os>
      <type>RHEL</type>
      <version>
        <full_version>7 - 2.1511.el7.centos.2.10</full_version>
        <major>7</major>
      </version>
    </os>
    <port>54321</port>
    <status>up</status>
    <cluster href="/ovirt-engine/api/clusters/002" id="002"/>
  </host>
  ...
</hosts>

请注意主机的 id。它根据虚拟环境的其他资源标识此主机。

此主机是 Default 集群的成员，访问 nics 子集合显示此主机已连接到 ovirtmgmt 网络。

4.6. 创建 NFS 数据存储
复制链接

NFS 数据存储域是连接到数据中心的 NFS 共享，为虚拟 guest 映像提供存储。创建新存储域需要 POST 请求，其中包含存储域表示法，并发送到存储域集合的 URL。

在存储域上，您可以默认启用 wipe 后删除选项。要配置此功能，请在 POST 请求中指定 wipe_after_delete。可以在创建域后编辑此选项，但是这样做不会在删除已存在的磁盘属性后更改擦除。

请求应类似如下： 

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

请求正文应类似如下： 

<storage_domain>
  <name>mydata</name>
  <type>data</type>
  <description>My data</description>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>mydata</name>
  <description>My data</description>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

服务器使用主机 myhost 创建名为 my data 的 NFS 数据存储域，其导出路径为 mynfs.example.com:/exports/mydata。该 API 还返回以下表示新创建的存储域资源（类型为 StorageDomain）： 

<storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">
  <name>mydata</name>
  <description>My data</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
    <type>nfs</type>
  </storage>
  <storage_format>v3</storage_format>
  <type>data</type>
  <used>9663676416</used>
</storage_domain>

4.7. 创建 NFS ISO 存储
复制链接

NFS ISO 存储域是连接到数据中心的已挂载 NFS 共享，为 DVD/CD-ROM ISO 和虚拟软盘(VFD)镜像文件提供存储。创建新存储域需要 POST 请求，其中包含存储域表示法，并将其发送到存储域集合的 URL：

请求应类似如下： 

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

请求正文应类似如下： 

<storage_domain>
  <name>myisos</name>
  <description>My ISOs</description>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>myisos</name>
  <description>My ISOs</description>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

服务器使用主机 myhost 创建名为 myisos 的 NFS ISO 存储域，其导出路径为 mynfs.example.com:/exports/myisos。该 API 还返回以下表示新创建的存储域资源（类型为 StorageDomain）： 

<storage_domain href="/ovirt-engine/api/storagedomains/006" id="006">
  <name>myiso</name>
  <description>My ISOs</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
    <type>nfs</type>
  </storage>
  <storage_format>v1</storage_format>
  <type>iso</type>
  <used>9663676416</used>
</storage_domain>

4.8. 将存储域附加到数据中心
复制链接

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

要附加 mydata 存储域，请发送类似如下的请求： 

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

这样的请求正文： 

<storage_domain>
  <name>mydata</name>
</storage_domain>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>mydata</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains

要附加 myisos 存储域，请发送类似如下的请求： 

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

这样的请求正文： 

<storage_domain>
  <name>myisos</name>
</storage_domain>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>myisos</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains

4.9. 创建虚拟机
复制链接

以下示例使用虚拟环境的空白模板为基础，在 Default 集群上创建一个名为 myvm 的虚拟机。该请求还将虚拟机的内存定义为 512 MiB，并将启动设备设置为虚拟硬盘。

请求应包含类型为 Vm 的对象，用于描述要创建的虚拟机： 

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

请求正文应类似如下： 

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
</vm>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
</vm>
' \
https://myengine.example.com/ovirt-engine/api/vms

响应正文将是 Vm 类型的对象： 

<vm href="/ovirt-engine/api/vms/007" id="007">
  <name>myvm</name>
  <link href="/ovirt-engine/api/vms/007/diskattachments" rel="diskattachments"/>
  <link href="/ovirt-engine/api/vms/007/nics" rel="nics"/>
  ...
  <cpu>
    <architecture>x86_64</architecture>
    <topology>
      <cores>1</cores>
      <sockets>1</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
  <memory>1073741824</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
    <type>other</type>
  </os>
  <type>desktop</type>
  <cluster href="/ovirt-engine/api/clusters/002" id="002"/>
  <status>down</status>
  <original_template href="/ovirt-engine/api/templates/000" id="00"/>
  <template href="/ovirt-engine/api/templates/000" id="000"/>
</vm>

4.10. 创建虚拟机 NIC
复制链接

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

请求应类似如下： 

POST /ovirt-engine/api/vms/007/nics HTTP/1.1
Content-Type: application/xml
Accept: application/xml

请求正文应包含类型 Nic 描述要创建的 NIC 的对象： 

<nic>
  <name>mynic</name>
  <description>My network interface card</description>
</nic>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<nic>
  <name>mynic</name>
  <description>My network interface card</description>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics

4.11. 创建虚拟机磁盘
复制链接

以下示例为示例虚拟机创建一个 8 GiB 写时复制磁盘。

请求应类似如下： 

POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1
Content-Type: application/xml
Accept: application/xml

请求正文应该是类型为 DiskAttachment 的对象，描述磁盘以及如何将其附加到虚拟机： 

<disk_attachment>
  <bootable>false</bootable>
  <interface>virtio</interface>
  <active>true</active>
  <disk>
    <description>My disk</description>
    <format>cow</format>
    <name>mydisk</name>
    <provisioned_size>8589934592</provisioned_size>
    <storage_domains>
      <storage_domain>
        <name>mydata</name>
      </storage_domain>
    </storage_domains>
  </disk>
</disk_attachment>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<disk_attachment>
  <bootable>false</bootable>
  <interface>virtio</interface>
  <active>true</active>
  <disk>
    <description>My disk</description>
    <format>cow</format>
    <name>mydisk</name>
    <provisioned_size>8589934592</provisioned_size>
    <storage_domains>
      <storage_domain>
        <name>mydata</name>
      </storage_domain>
    </storage_domains>
  </disk>
</disk_attachment>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/diskattachments

storage_domains 属性告知 API 将磁盘存储在 mydata 存储域中。

4.12. 将 ISO 镜像附加到虚拟机
复制链接

下面的虚拟机的引导介质需要一个 CD-ROM 或者 DVD ISO 镜像进行操作系统安装。这个示例使用 CentOS 7 镜像。

ISO 映像必须在 myisos ISO 域中提供，供虚拟机使用。您可以使用 第 6.124 节 “ImageTransfers” 创建镜像传输，使用 第 6.123 节 “ImageTransfer” 上传 ISO 镜像。

上传 ISO 镜像后，API 可用于从 ISO 存储域请求文件列表： 

GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1
Accept: application/xml

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
https://myengine.example.com/ovirt-engine/api/storagedomains/006/files

服务器返回以下 File 类型的对象列表，每个可用 ISO（或软盘）镜像一个对象： 

<files>
  <file href="..." id="CentOS-7-x86_64-Minimal.iso">
    <name>CentOS-7-x86_64-Minimal.iso</name>
  </file>
  ...
</files>

API 用户将 CentOS-7-x86_64-Minimal.iso 附加到示例虚拟机。连接 ISO 映像等同于在管理或用户门户应用程序中使用 Change CD 按钮。

请求应类似如下： 

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

请求正文应该是类型为 Cdrom 的对象，它包含一个内 文件 属性，以指示 ISO（或软盘）镜像的标识符： 

<cdrom>
  <file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request PUT \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<cdrom>
  <file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000

如需了解更多详细信息，请参阅管理虚拟机 CD-ROMS 的服务文档。

4.13. 启动虚拟机
复制链接

虚拟环境已经完成，虚拟机包含运行所需的所有组件。本例使用 start 方法启动虚拟机。

请求应类似如下： 

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

请求正文应类似如下： 

<action>
  <vm>
    <os>
      <boot>
        <devices>
          <device>cdrom</device>
        </devices>
      </boot>
    </os>
  </vm>
</action>

同一个请求，使用 curl 命令： 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<action>
  <vm>
    <os>
      <boot>
        <devices>
          <device>cdrom</device>
        </devices>
      </boot>
    </os>
  </vm>
</action>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/start

额外请求正文将虚拟机的引导设备设置为 CD-ROM 仅用于此启动。这可让虚拟机从附加的 ISO 镜像安装操作系统。引导设备恢复为磁盘以进行以后的所有引导。

第 5 章 Requests
复制链接

本节枚举 API 中提供的所有请求。

第 6 章 服务
复制链接

本节枚举 API 中提供的所有服务。

6.1. AffinityGroup
复制链接

此服务管理单个关联性组。

Expand
表 6.1. 方法概述
名称概述

get

检索关联性组详细信息。

remove

移除 affinity 组。

update

更新 affinity 组。

6.1.1. 获取 GET
复制链接

检索关联性组详细信息。 

<affinity_group id="00000000-0000-0000-0000-000000000000">
  <name>AF_GROUP_001</name>
  <cluster id="00000000-0000-0000-0000-000000000000"/>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
Expand
表 6.2. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

group

AffinityGroup

out

关联性组。

6.1.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.1.2. 删除 DELETE
复制链接

移除 affinity 组。 

DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
Expand
表 6.3. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.1.3. 更新 PUT
复制链接

更新 affinity 组。

Expand
表 6.4. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

group

AffinityGroup

in/Out

关联性组。

6.2. AffinityGroupHost
复制链接

此服务管理单个主机与关联性组分配。

Expand
表 6.5. 方法概述
名称概述

remove

从 affinity 组移除主机。

6.2.1. 删除 DELETE
复制链接

从 affinity 组移除主机。

Expand
表 6.6. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.3. AffinityGroupHostLabel
复制链接

此服务管理分配至关联性组的单一主机标签。

Expand
表 6.7. 方法概述
名称概述

remove

从 affinity 组移除此标签。

6.3.1. 删除 DELETE
复制链接

从 affinity 组移除此标签。

Expand
表 6.8. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.4. AffinityGroupHostLabels
复制链接

此服务管理分配到关联性组的所有主机标签的集合。

Expand
表 6.9. 方法概述
名称概述

add

将主机标签添加到 affinity 组。

list

列出分配到此关联性组的所有主机标签。

6.4.1. 添加 POST
复制链接

将主机标签添加到 affinity 组。

例如，要将 label 789 添加到集群 123 的关联性组 456 中，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/123/affinitygroups/456/hostlabels

使用以下机构： 

<affinity_label id="789"/>
Expand
表 6.10. 参数摘要
名称类型方向概述

label

AffinityLabel

in/Out

要添加到关联性组中的 AffinityLabel 对象。

6.4.2. 列出 GET
复制链接

列出分配到此关联性组的所有主机标签。

返回标签的顺序不受保证。

Expand
表 6.11. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

labels

AffinityLabel[]

out

分配给 affinity 组的主机标签。

max

整数

in

设置要返回的最大主机标签数。

6.4.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.4.2.2. Max
复制链接

设置要返回的最大主机标签数。如果没有指定，则返回所有标签。

6.5. AffinityGroupHosts
复制链接

此服务管理分配到关联性组的所有主机的集合。

Expand
表 6.12. 方法概述
名称概述

add

将主机添加到关联性组。

list

列出分配到此关联性组的所有主机。

6.5.1. 添加 POST
复制链接

将主机添加到关联性组。

例如，要将 host 789 添加到集群 123 的关联性组 456 中，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/123/affinitygroups/456/hosts

使用以下机构： 

<host id="789"/>
Expand
表 6.13. 参数摘要
名称类型方向概述

host

主机

in/Out

要添加到关联性组中的主机。

6.5.2. 列出 GET
复制链接

列出分配到此关联性组的所有主机。

返回的主机的顺序不受保证。

Expand
表 6.14. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

主机

Host[]

out

分配给此关联性组的主机列表。

max

整数

in

设置要返回的最大主机数。

6.5.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.5.2.2. Max
复制链接

设置要返回的最大主机数。如果未指定，则返回所有主机。

6.6. AffinityGroupVm
复制链接

此服务管理单个虚拟机与组分配关联。

Expand
表 6.15. 方法概述
名称概述

remove

从关联性组中移除此虚拟机。

6.6.1. 删除 DELETE
复制链接

从关联性组中移除此虚拟机。

Expand
表 6.16. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.7. AffinityGroupVmLabel
复制链接

此服务管理分配至关联性组的单一虚拟机标签。

Expand
表 6.17. 方法概述
名称概述

remove

从 affinity 组移除此标签。

6.7.1. 删除 DELETE
复制链接

从 affinity 组移除此标签。

Expand
表 6.18. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.8. AffinityGroupVmLabels
复制链接

此服务管理分配到关联性组的所有虚拟机标签的集合。

Expand
表 6.19. 方法概述
名称概述

add

向关联性组添加虚拟机标签。

list

列出分配到此关联性组的所有虚拟机标签。

6.8.1. 添加 POST
复制链接

向关联性组添加虚拟机标签。

例如，要将 label 789 添加到集群 123 的关联性组 456 中，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/123/affinitygroups/456/vmlabels

使用以下机构： 

<affinity_label id="789"/>
Expand
表 6.20. 参数摘要
名称类型方向概述

label

AffinityLabel

in/Out

要添加到关联性组中的 AffinityLabel 对象。

6.8.2. 列出 GET
复制链接

列出分配到此关联性组的所有虚拟机标签。

返回标签的顺序不受保证。

Expand
表 6.21. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

labels

AffinityLabel[]

out

分配给关联性组的虚拟机标签。

max

整数

in

设置要返回的最大虚拟机标签数。

6.8.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.8.2.2. Max
复制链接

设置要返回的最大虚拟机标签数。如果没有指定，则返回所有标签。

6.9. AffinityGroupVms
复制链接

此服务管理分配到关联性组的所有虚拟机的集合。

Expand
表 6.22. 方法概述
名称概述

add

将虚拟机添加到关联性组。

list

列出分配到此关联性组的所有虚拟机。

6.9.1. 添加 POST
复制链接

将虚拟机添加到关联性组。

例如，要将虚拟机 789 添加到集群 123 的关联性组 456 中，请发送如下请求： 

POST /ovirt-engine/api/clusters/123/affinitygroups/456/vms

使用以下机构： 

<vm id="789"/>
Expand
表 6.23. 参数摘要
名称类型方向概述

vm

VM

in/Out

 

6.9.2. 列出 GET
复制链接

列出分配到此关联性组的所有虚拟机。

返回的虚拟机的顺序无法保证。

Expand
表 6.24. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大虚拟机数量。

vms

Vm[]

out

 
6.9.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.9.2.2. Max
复制链接

设置要返回的最大虚拟机数量。如果未指定，则返回所有虚拟机。

6.10. AffinityGroups
复制链接

关联性组服务管理虚拟机关系和依赖项。

Expand
表 6.25. 方法概述
名称概述

add

创建新的关联性组。

list

列出现有的关联性组。

6.10.1. 添加 POST
复制链接

创建新的关联性组。

在下例中发布一个请求以创建新关联性组： 

POST /ovirt-engine/api/clusters/000-000/affinitygroups

并在正文中使用以下示例： 

<affinity_group>
  <name>AF_GROUP_001</name>
  <hosts_rule>
    <enforcing>true</enforcing>
    <positive>true</positive>
  </hosts_rule>
  <vms_rule>
    <enabled>false</enabled>
  </vms_rule>
</affinity_group>
Expand
表 6.26. 参数摘要
名称类型方向概述

group

AffinityGroup

in/Out

要创建的关联性组对象。

6.10.2. 列出 GET
复制链接

列出现有的关联性组。

关联组结果的顺序不受保证。

Expand
表 6.27. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

groups

AffinityGroup[]

out

现有关联性组的列表。

max

整数

in

设置要返回的关联性组的最大数量。

6.10.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.10.2.2. Max
复制链接

设置要返回的关联性组的最大数量。如果未指定，则返回所有关联性组。

6.11. AffinityLabel
复制链接

单个关联性标签的详细信息。

Expand
表 6.28. 方法概述
名称概述

get

检索标签的详细信息。

remove

从系统中删除标签并清除已删除标签的所有分配。

update

更新标签。

6.11.1. 获取 GET
复制链接

检索标签的详细信息。

Expand
表 6.29. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

label

AffinityLabel

out

 
6.11.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.11.2. 删除 DELETE
复制链接

从系统中删除标签并清除已删除标签的所有分配。

6.11.3. 更新 PUT
复制链接

更新标签。此调用将更新所有元数据，如名称或描述。

Expand
表 6.30. 参数摘要
名称类型方向概述

label

AffinityLabel

in/Out

 

6.12. AffinityLabelHost
复制链接

此服务表示在通过 affinitylabels/hosts 子集合访问时具有特定标签的主机。

Expand
表 6.31. 方法概述
名称概述

get

检索分配了此标签的主机的详细信息。

remove

从主机中删除标签。

6.12.1. 获取 GET
复制链接

检索分配了此标签的主机的详细信息。

Expand
表 6.32. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

host

主机

out

 
6.12.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.12.2. 删除 DELETE
复制链接

从主机中删除标签。

6.13. AffinityLabelHosts
复制链接

此服务代表通过 affinitylabels/hosts 子集合访问时具有特定标签的主机列表。

Expand
表 6.33. 方法概述
名称概述

add

向主机添加标签。

list

列出具有 标签的所有主机。

6.13.1. 添加 POST
复制链接

向主机添加标签。

Expand
表 6.34. 参数摘要
名称类型方向概述

host

主机

in/Out

 

6.13.2. 列出 GET
复制链接

列出具有 标签的所有主机。

返回的主机的顺序不受保证。

Expand
表 6.35. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

主机

Host[]

out

 
6.13.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.14. AffinityLabelVm
复制链接

此服务代表 vm，它在通过 affinitylabels/vms 子集合访问时具有特定标签。

Expand
表 6.36. 方法概述
名称概述

get

检索分配了此标签的 vm 的详细信息。

remove

从 vm 中删除标签。

6.14.1. 获取 GET
复制链接

检索分配了此标签的 vm 的详细信息。

Expand
表 6.37. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

vm

VM

out

 
6.14.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.14.2. 删除 DELETE
复制链接

从 vm 中删除标签。

6.15. AffinityLabelVms
复制链接

此服务代表通过 affinitylabels/vms 子集合访问时具有特定标签的 vms 列表。

Expand
表 6.38. 方法概述
名称概述

add

向 vm 添加标签。

list

列出所有具有 标签的虚拟机。

6.15.1. 添加 POST
复制链接

向 vm 添加标签。

Expand
表 6.39. 参数摘要
名称类型方向概述

vm

VM

in/Out

 

6.15.2. 列出 GET
复制链接

列出所有具有 标签的虚拟机。

返回的虚拟机的顺序无法保证。

Expand
表 6.40. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

vms

Vm[]

out

 
6.15.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.16. AffinityLabels
复制链接

管理系统中可用的关联性标签。

Expand
表 6.41. 方法概述
名称概述

add

创建新标签。

list

列出系统中存在的所有标签。

6.16.1. 添加 POST
复制链接

创建新标签。标签自动附加到 vms 或 hosts 列表中提及的所有实体。

Expand
表 6.42. 参数摘要
名称类型方向概述

label

AffinityLabel

in/Out

 

6.16.2. 列出 GET
复制链接

列出系统中存在的所有标签。

返回标签的顺序不受保证。

Expand
表 6.43. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

labels

AffinityLabel[]

out

 

max

整数

in

设置要返回的最大标签数。

6.16.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.16.2.2. Max
复制链接

设置要返回的最大标签数。如果没有指定，则返回所有标签。

6.17. 区域
复制链接

此注释旨在指定与以下内容相关的带注释概念的 oVirt 区域：目前，以下领域正在使用中，它们与 oVirt 团队紧密相关，但不一定是相同的：

  • 基础架构
  • Network
  • SLA
  • 存储
  • 虚拟化

概念可以与多个区域相关联，或者与任何区域相关联。

此注解的值仅用于报告，它不会影响生成的所有代码或模型的有效性

6.18. AssignedAffinityLabel
复制链接

此服务表示在使用实体/关联性标签子集合访问时，实体分配的一个标签。

Expand
表 6.44. 方法概述
名称概述

get

检索所附加标签的详细信息。

remove

从实体中删除该标签。

6.18.1. 获取 GET
复制链接

检索所附加标签的详细信息。

Expand
表 6.45. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

label

AffinityLabel

out

 
6.18.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.18.2. 删除 DELETE
复制链接

从实体中删除该标签。请勿接触标签本身。

6.19. AssignedAffinityLabels
复制链接

此服务用于列出和操作在使用实体/关联性标签访问时分配给支持的实体的关联性标签。

Expand
表 6.46. 方法概述
名称概述

add

将标签附加到实体。

list

列出附加到实体的所有标签。

6.19.1. 添加 POST
复制链接

将标签附加到实体。

Expand
表 6.47. 参数摘要
名称类型方向概述

label

AffinityLabel

in/Out

 

6.19.2. 列出 GET
复制链接

列出附加到实体的所有标签。

返回实体的顺序不受保证。

Expand
表 6.48. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

label

AffinityLabel[]

out

 
6.19.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.20. AssignedCpuProfile
复制链接

Expand
表 6.49. 方法概述
名称概述

get

 

remove

 

6.20.1. 获取 GET
复制链接

Expand
表 6.50. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

profile

CpuProfile

out

 
6.20.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.20.2. 删除 DELETE
复制链接

Expand
表 6.51. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.21. AssignedCpuProfiles
复制链接

Expand
表 6.52. 方法概述
名称概述

add

为集群添加新 cpu 配置集。

list

列出分配给集群的 CPU 配置集。

6.21.1. 添加 POST
复制链接

为集群添加新 cpu 配置集。

Expand
表 6.53. 参数摘要
名称类型方向概述

profile

CpuProfile

in/Out

 

6.21.2. 列出 GET
复制链接

列出分配给集群的 CPU 配置集。

返回的 CPU 配置文件的顺序不受保证。

Expand
表 6.54. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大配置集数。

profiles

CpuProfile[]

out

 
6.21.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.21.2.2. Max
复制链接

设置要返回的最大配置集数。如果没有指定，则返回所有配置集。

6.22. AssignedDiskProfile
复制链接

Expand
表 6.55. 方法概述
名称概述

get

 

remove

 

6.22.1. 获取 GET
复制链接

Expand
表 6.56. 参数摘要
名称类型方向概述

disk_profile

DiskProfile

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.22.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.22.2. 删除 DELETE
复制链接

Expand
表 6.57. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.23. AssignedDiskProfiles
复制链接

Expand
表 6.58. 方法概述
名称概述

add

为存储域添加新磁盘配置文件。

list

返回分配给存储域的磁盘配置文件列表。

6.23.1. 添加 POST
复制链接

为存储域添加新磁盘配置文件。

Expand
表 6.59. 参数摘要
名称类型方向概述

profile

DiskProfile

in/Out

 

6.23.2. 列出 GET
复制链接

返回分配给存储域的磁盘配置文件列表。

返回的磁盘配置文件的顺序无法保证。

Expand
表 6.60. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大配置集数。

profiles

DiskProfile[]

out

 
6.23.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.23.2.2. Max
复制链接

设置要返回的最大配置集数。如果没有指定，则返回所有配置集。

6.24. AssignedPermissions
复制链接

表示权限子集合，按用户、组或某些实体类型的范围。

Expand
表 6.61. 方法概述
名称概述

add

为特定实体为用户或组分配新权限。

list

列出特定实体的所有权限。

6.24.1. 添加 POST
复制链接

为特定实体为用户或组分配新权限。

例如，要为 ID 为 123 的虚拟机分配 UserVmManager 角色给 ID 为 456 的用户发送类似如下的请求： 

POST /ovirt-engine/api/vms/123/permissions

这样的请求正文： 

<permission>
  <role>
    <name>UserVmManager</name>
  </role>
  <user id="456"/>
</permission>

要将 SuperUser 角色分配给 ID 为 456 的用户，请发送如下请求： 

POST /ovirt-engine/api/permissions

这样的请求正文： 

<permission>
  <role>
    <name>SuperUser</name>
  </role>
  <user id="456"/>
</permission>

如果要为组而不是用户分配权限，请将 user 元素替换为 组 元素的适当 ID。例如，将 UserRole 角色分配给 ID 为 123 的集群，将 id 789 的组分配如下： 

POST /ovirt-engine/api/clusters/123/permissions

这样的请求正文： 

<permission>
  <role>
    <name>UserRole</name>
  </role>
  <group id="789"/>
</permission>
Expand
表 6.62. 参数摘要
名称类型方向概述

权限

权限

in/Out

权限。

6.24.2. 列出 GET
复制链接

列出特定实体的所有权限。

例如，列出 ID 为 123 的集群的所有权限 发送 如下请求： 

GET /ovirt-engine/api/clusters/123/permissions
 
<permissions>
  <permission id="456">
    <cluster id="123"/>
    <role id="789"/>
    <user id="451"/>
  </permission>
  <permission id="654">
    <cluster id="123"/>
    <role id="789"/>
    <group id="127"/>
  </permission>
</permissions>

返回的权限顺序不受保证。

Expand
表 6.63. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

权限

permission[]

out

权限列表。

6.24.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.25. AssignedRoles
复制链接

代表子集合的角色，如用户作用域。

Expand
表 6.64. 方法概述
名称概述

list

返回分配给权限的角色。

6.25.1. 列出 GET
复制链接

返回分配给权限的角色。

返回角色的顺序不受保证。

Expand
表 6.65. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的角色的最大数量。

角色

role[]

out

 
6.25.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.25.1.2. Max
复制链接

设置要返回的角色的最大数量。如果未指定，则返回所有角色。

6.26. AssignedTag
复制链接

种服务，用于管理为系统中特定实体分配特定标签的服务。

Expand
表 6.66. 方法概述
名称概述

get

获取关于分配标签的信息。

remove

从系统中的特定实体取消分配标签。

6.26.1. 获取 GET
复制链接

获取关于分配标签的信息。

例如，要检索 ID 为 456 的标签信息，该标签分配给 id 123 的虚拟机，发送如下请求： 

GET /ovirt-engine/api/vms/123/tags/456
 
<tag href="/ovirt-engine/api/tags/456" id="456">
  <name>root</name>
  <description>root</description>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>
Expand
表 6.67. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

tag

Tag

out

分配的标签。

6.26.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.26.2. 删除 DELETE
复制链接

从系统中的特定实体取消分配标签。

例如，要从 ID 123 的虚拟机中取消分配 ID 为 456 的标签，发送 类似如下的请求： 

DELETE /ovirt-engine/api/vms/123/tags/456
Expand
表 6.68. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.27. AssignedTags
复制链接

此服务用于管理向系统中特定实体分配标签的服务。

Expand
表 6.69. 方法概述
名称概述

add

为系统中的特定实体分配标签。

list

列出分配给特定实体的所有标签。

6.27.1. 添加 POST
复制链接

为系统中的特定实体分配标签。

例如，将标签 mytag 分配给 ID 为 123 的虚拟机发送如下请求： 

POST /ovirt-engine/api/vms/123/tags

这样的请求正文： 

<tag>
  <name>mytag</name>
</tag>
Expand
表 6.70. 参数摘要
名称类型方向概述

tag

Tag

in/Out

分配的标签。

6.27.2. 列出 GET
复制链接

列出分配给特定实体的所有标签。

例如，要列出 ID 为 123 的虚拟机的所有标签，发送 如下请求： 

GET /ovirt-engine/api/vms/123/tags
 
<tags>
  <tag href="/ovirt-engine/api/tags/222" id="222">
    <name>mytag</name>
    <description>mytag</description>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </tag>
</tags>

返回标签的顺序不受保证。

Expand
表 6.71. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大标签数。

tags

Tag[]

out

所分配标签的列表。

6.27.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.27.2.2. Max
复制链接

设置要返回的最大标签数。如果未指定，则返回所有标签。

6.28. AssignedVnicProfile
复制链接

Expand
表 6.72. 方法概述
名称概述

get

 

remove

 

6.28.1. 获取 GET
复制链接

Expand
表 6.73. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

profile

VnicProfile

out

 
6.28.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.28.2. 删除 DELETE
复制链接

Expand
表 6.74. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.29. AssignedVnicProfiles
复制链接

Expand
表 6.75. 方法概述
名称概述

add

为网络添加新的虚拟网络接口卡配置文件。

list

将 VNIC 配置集列表返回给网络。

6.29.1. 添加 POST
复制链接

为网络添加新的虚拟网络接口卡配置文件。

Expand
表 6.76. 参数摘要
名称类型方向概述

profile

VnicProfile

in/Out

 

6.29.2. 列出 GET
复制链接

将 VNIC 配置集列表返回给网络。

返回的 VNIC 配置集的顺序无法保证。

Expand
表 6.77. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大配置集数。

profiles

VnicProfile[]

out

 
6.29.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.29.2.2. Max
复制链接

设置要返回的最大配置集数。如果没有指定，则返回所有配置集。

6.30. AttachedStorageDomain
复制链接

Expand
表 6.78. 方法概述
名称概述

激活

此操作将激活已连接的存储域。

取消激活

此操作将停用已连接的存储域。

get

 

remove

 

6.30.1. 激活 POST
复制链接

此操作将激活已连接的存储域。激活存储域后，该存储域就已准备好用于数据中心。 

POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate

激活操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>
Expand
表 6.79. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行激活。

6.30.2. 取消激活 POST
复制链接

此操作将停用已连接的存储域。存储域被停用后，该存储域将不会与数据中心一起使用。例如，要停用存储域 456，请发送以下请求： 

POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate

这样的请求正文： 

<action/>

如果 force 参数为 true，则操作将成功，即使取消激活存储域失败前进行 OVF 更新也是如此。如果 force 参数为 false，OVF 更新失败，则存储域的停用也将失败。

Expand
表 6.80. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行取消激活。

force

布尔值

in

指明操作是否应该成功，并且存储域应移到停用的状态，即使存储域的 OVF 更新失败。

6.30.2.1. force
复制链接

指明操作是否应该成功，并且存储域应移到停用的状态，即使存储域的 OVF 更新失败。例如，要使用 force 标志停用存储域 456，请发送以下请求： 

POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate

这样的请求正文： 

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

此参数是可选的，默认值为 false。

6.30.3. 获取 GET
复制链接

Expand
表 6.81. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

storage_domain

StorageDomain

out

 
6.30.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.30.4. 删除 DELETE
复制链接

Expand
表 6.82. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.31. AttachedStorageDomainDisk
复制链接

管理附加到数据中心的存储域中的单个磁盘。

重要

由于引擎版本 4.2 旨在仅列出存储域中可用的磁盘，并注册未注册的磁盘。所有其他操作（如复制磁盘、移动磁盘等）已被弃用，并将在以后的中删除。要执行这些操作，请使用管理系统所有磁盘的服务 ，或者使用管理特定磁盘的服务。

Expand
表 6.83. 方法概述
名称概述

copy

将磁盘复制到指定的存储域.

export

将磁盘导出到导出存储域.

get

检索磁盘的描述。

Move

将磁盘移动到其他存储域.

Register

注册未注册的磁盘。

remove

删除磁盘.

sparsify

稀疏磁盘。

update

更新磁盘.

6.31.1. 复制 POST
复制链接

将磁盘复制到指定的存储域.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要复制磁盘，请使用管理该磁盘的服务的副本操作。

Expand
表 6.84. 参数摘要
名称类型方向概述

disk

Disk

in

生成磁盘的描述。

storage_domain

StorageDomain

in

创建新磁盘的存储域。

6.31.2. 导出 POST
复制链接

将磁盘导出到导出存储域.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。若要导出磁盘，可使用管理该磁盘的服务的导出操作。

Expand
表 6.85. 参数摘要
名称类型方向概述

storage_domain

StorageDomain

in

磁盘应导出到的导出存储域。

6.31.3. 获取 GET
复制链接

检索磁盘的描述。

Expand
表 6.86. 参数摘要
名称类型方向概述

disk

Disk

out

磁盘的描述。

follow

字符串

in

指明应遵循哪些内联链接。

6.31.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.31.4. 移动 POST
复制链接

将磁盘移动到其他存储域.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要移动磁盘，请使用管理该磁盘的服务的移动操作。

Expand
表 6.87. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移动。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

storage_domain

StorageDomain

in

磁盘将移动到的存储域。

6.31.5. 注册 POST
复制链接

注册未注册的磁盘。

6.31.6. 删除 DELETE
复制链接

删除磁盘.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要删除磁盘，请使用管理该磁盘的服务的 remove 操作。

6.31.7. 稀疏 POST
复制链接

稀疏磁盘。

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要删除磁盘，请使用管理该磁盘的服务的 remove 操作。

6.31.8. 更新 PUT
复制链接

更新磁盘.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。若要更新磁盘，可使用管理该磁盘的服务的更新操作。

Expand
表 6.88. 参数摘要
名称类型方向概述

disk

Disk

in/Out

应用到磁盘的更新。

6.32. AttachedStorageDomainDisks
复制链接

管理附加到数据中心的存储域中可用磁盘的集合。

Expand
表 6.89. 方法概述
名称概述

add

添加或注册磁盘。

list

检索存储域中可用的磁盘的列表。

6.32.1. 添加 POST
复制链接

添加或注册磁盘。

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要添加新磁盘，请使用管理系统磁盘的服务的 add 操作。要注册一个未注册的磁盘，请使用管理该磁盘的服务注册操作。

Expand
表 6.90. 参数摘要
名称类型方向概述

disk

Disk

in/Out

要添加或注册的磁盘。

unregistered

布尔值

in

指明是否应添加新磁盘，或者是否应注册现有的未注册磁盘。

6.32.1.1. unregistered
复制链接

指明是否应添加新磁盘，或者是否应注册现有的未注册磁盘。如果值为 true，则需要提供要注册的磁盘标识符。例如，使用 id 456 注册磁盘会发送如下请求： 

POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true

这样的请求正文： 

<disk id="456"/>

如果值为 false，则会在存储域中创建新磁盘。在这种情况下，provisioning _size、格式和 name 属性是必需的。例如：要在 1 GiB 的写入磁盘上创建新副本，请发送如下请求： 

POST /ovirt-engine/api/storagedomains/123/disks

这样的请求正文： 

<disk>
  <name>mydisk</name>
  <format>cow</format>
  <provisioned_size>1073741824</provisioned_size>
</disk>

默认值为 false。

6.32.2. 列出 GET
复制链接

检索存储域中可用的磁盘的列表。

Expand
表 6.91. 参数摘要
名称类型方向概述

磁盘

disk[]

out

检索的磁盘列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

6.32.2.1. 磁盘
复制链接

检索的磁盘列表。

返回的磁盘的顺序无法保证。

6.32.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.32.2.3. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.33. AttachedStorageDomains
复制链接

管理附加到数据中心的存储域。

Expand
表 6.92. 方法概述
名称概述

add

将现有存储域附加到数据中心.

list

返回附加到数据中心的存储域的列表。

6.33.1. 添加 POST
复制链接

将现有存储域附加到数据中心.

Expand
表 6.93. 参数摘要
名称类型方向概述

storage_domain

StorageDomain

in/Out

要连接到数据中心的存储域。

6.33.2. 列出 GET
复制链接

返回附加到数据中心的存储域的列表。

返回的存储域的顺序不受保证。

Expand
表 6.94. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的存储域的最大数量。

storage_domains

StorageDomain[]

out

附加到数据中心的存储域的列表。

6.33.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.33.2.2. Max
复制链接

设置要返回的存储域的最大数量。如果没有指定，则返回所有存储域。

6.34. balance
复制链接

Expand
表 6.95. 方法概述
名称概述

get

 

remove

 

6.34.1. 获取 GET
复制链接

Expand
表 6.96. 参数摘要
名称类型方向概述

balance

balance

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

6.34.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.34.2. 删除 DELETE
复制链接

Expand
表 6.97. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.35. 平衡
复制链接

Expand
表 6.98. 方法概述
名称概述

add

向指定的用户定义的调度策略中添加 balance 模块。

list

返回调度策略使用的平衡模块列表。

6.35.1. 添加 POST
复制链接

向指定的用户定义的调度策略中添加 balance 模块。

Expand
表 6.99. 参数摘要
名称类型方向概述

balance

balance

in/Out

 

6.35.2. 列出 GET
复制链接

返回调度策略使用的平衡模块列表。

返回的平衡模块的顺序无法保证。

Expand
表 6.100. 参数摘要
名称类型方向概述

平衡

balance[]

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置返回的最大平衡数。

6.35.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.35.2.2. Max
复制链接

设置返回的最大平衡数。如果未指定，将返回所有平衡。

6.36. 书签
复制链接

用于管理书签的服务。

Expand
表 6.101. 方法概述
名称概述

get

获取书签.

remove

删除书签.

update

更新书签.

6.36.1. 获取 GET
复制链接

获取书签.

获取书签的示例： 

GET /ovirt-engine/api/bookmarks/123
 
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
  <name>example_vm</name>
  <value>vm: name=example*</value>
</bookmark>
Expand
表 6.102. 参数摘要
名称类型方向概述

bookmark

书签

out

请求的书签。

follow

字符串

in

指明应遵循哪些内联链接。

6.36.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.36.2. 删除 DELETE
复制链接

删除书签.

删除书签的示例： 

DELETE /ovirt-engine/api/bookmarks/123
Expand
表 6.103. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.36.3. 更新 PUT
复制链接

更新书签.

更新书签的示例： 

PUT /ovirt-engine/api/bookmarks/123

使用请求正文： 

<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>
Expand
表 6.104. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

bookmark

书签

in/Out

更新的书签.

6.37. 书签
复制链接

用于管理书签的服务。

Expand
表 6.105. 方法概述
名称概述

add

添加新书签.

list

列出所有可用的书签。

6.37.1. 添加 POST
复制链接

添加新书签.

添加书签示例： 

POST /ovirt-engine/api/bookmarks
 
<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>
Expand
表 6.106. 参数摘要
名称类型方向概述

bookmark

书签

in/Out

添加的书签.

6.37.2. 列出 GET
复制链接

列出所有可用的书签。

列出书签示例： 

GET /ovirt-engine/api/bookmarks
 
<bookmarks>
  <bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
    <name>database</name>
    <value>vm: name=database*</value>
  </bookmark>
  <bookmark href="/ovirt-engine/api/bookmarks/456" id="456">
    <name>example</name>
    <value>vm: name=example*</value>
  </bookmark>
</bookmarks>

返回的书签的顺序无法保证。

Expand
表 6.107. 参数摘要
名称类型方向概述

bookmarks

书签[]

out

可用书签列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大书签数。

6.37.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.37.2.2. Max
复制链接

设置要返回的最大书签数。如果没有指定，则返回所有书签。

6.38. Cluster
复制链接

管理特定集群的服务。

Expand
表 6.108. 方法概述
名称概述

get

获取有关集群的信息。

refreshglusterhealstatus

刷新集群中所有卷的 Gluster 修复信息。

remove

从系统中删除集群。

resetemulatedmachine

 

syncallnetworks

同步集群中的所有网络。

update

更新有关集群的信息。

upgrade

根据操作值启动、更新或完成集群的升级过程。

6.38.1. 获取 GET
复制链接

获取有关集群的信息。

获取集群的示例： 

GET /ovirt-engine/api/clusters/123
 
<cluster href="/ovirt-engine/api/clusters/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/clusters/123/resetemulatedmachine" rel="resetemulatedmachine"/>
  </actions>
  <name>Default</name>
  <description>The default server cluster</description>
  <link href="/ovirt-engine/api/clusters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/clusters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/clusters/123/glustervolumes" rel="glustervolumes"/>
  <link href="/ovirt-engine/api/clusters/123/glusterhooks" rel="glusterhooks"/>
  <link href="/ovirt-engine/api/clusters/123/affinitygroups" rel="affinitygroups"/>
  <link href="/ovirt-engine/api/clusters/123/cpuprofiles" rel="cpuprofiles"/>
  <ballooning_enabled>false</ballooning_enabled>
  <cpu>
    <architecture>x86_64</architecture>
    <type>Intel Nehalem Family</type>
  </cpu>
  <error_handling>
    <on_error>migrate</on_error>
  </error_handling>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
  </fencing_policy>
  <gluster_service>false</gluster_service>
  <ha_reservation>false</ha_reservation>
  <ksm>
    <enabled>true</enabled>
    <merge_across_nodes>true</merge_across_nodes>
  </ksm>
  <memory_policy>
    <over_commit>
      <percent>100</percent>
    </over_commit>
    <transparent_hugepages>
      <enabled>true</enabled>
    </transparent_hugepages>
  </memory_policy>
  <migration>
    <auto_converge>inherit</auto_converge>
    <bandwidth>
      <assignment_method>auto</assignment_method>
    </bandwidth>
    <compressed>inherit</compressed>
  </migration>
  <required_rng_sources>
    <required_rng_source>random</required_rng_source>
  </required_rng_sources>
  <scheduling_policy href="/ovirt-engine/api/schedulingpolicies/456" id="456"/>
  <threads_as_cores>false</threads_as_cores>
  <trusted_service>false</trusted_service>
  <tunnel_migration>false</tunnel_migration>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <virt_service>true</virt_service>
  <data_center href="/ovirt-engine/api/datacenters/111" id="111"/>
</cluster>
Expand
表 6.109. 参数摘要
名称类型方向概述

cluster

Cluster

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

6.38.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.38.2. refreshglusterhealstatus POST
复制链接

刷新集群中所有卷的 Gluster 修复信息。

例如，Cluster 123，发送类似如下的请求： 

POST /ovirt-engine/api/clusters/123/refreshglusterhealstatus

6.38.3. 删除 DELETE
复制链接

从系统中删除集群。 

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Expand
表 6.110. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.38.4. resetemulatedmachine POST
复制链接

Expand
表 6.111. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重置。

6.38.5. syncallnetworks POST
复制链接

同步集群中的所有网络。 

POST /ovirt-engine/api/clusters/123/syncallnetworks

这样的请求正文： 

<action/>
Expand
表 6.112. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.38.6. 更新 PUT
复制链接

更新有关集群的信息。

只有指定的字段会被更新，其他字段保持不变。

例如，更新集群的 CPU： 

PUT /ovirt-engine/api/clusters/123

这样的请求正文： 

<cluster>
  <cpu>
    <type>Intel Haswell-noTSX Family</type>
  </cpu>
</cluster>
Expand
表 6.113. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

cluster

Cluster

in/Out

 

6.38.7. 升级 POST
复制链接

根据操作值启动、更新或完成集群的升级过程。此操作将集群标记为升级，更新进度，或者根据 启动 值、停止或 update_progress 的值来清除在集群中运行的升级标志。 

POST /ovirt-engine/api/clusters/123/upgrade

使用这个请求正文来标记集群进行升级： 

<action>
    <upgrade_action>
        start
    </upgrade_action>
</action>

在开始升级后，请使用请求正文将进度更新为 15%： 

<action>
    <upgrade_action>
        update_progress
    </upgrade_action>
    <upgrade_percent_complete>
        15
    </upgrade_percent_complete>
</action>
Expand
表 6.114. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

correlation_id

字符串

in

明确设置升级相关性标识符。

upgrade_action

ClusterUpgradeAction

in

要执行的操作。

upgrade_percent_complete

整数

in

将升级的过程作为总过程的百分比更新。

6.38.7.1. correlation_id
复制链接

明确设置升级相关性标识符。使用 将详细说明集群升级的事件与升级本身相关联。如果不指定，则使用来自 Correlation-Id http 标头的关联 ID。

6.39. ClusterEnabledFeature
复制链接

代表为集群启用的功能。

Expand
表 6.115. 方法概述
名称概述

get

提供有关启用集群功能的信息。

remove

禁用集群功能。

6.39.1. 获取 GET
复制链接

提供有关启用集群功能的信息。

例如，要查找集群 123 启用的功能 456 的详细信息，请发送如下请求： 

GET /ovirt-engine/api/clusters/123/enabledfeatures/456

这将返回包含名称的 ClusterFeature 对象： 

<cluster_feature id="456">
  <name>libgfapi_supported</name>
</cluster_feature>
Expand
表 6.116. 参数摘要
名称类型方向概述

功能

ClusterFeature

out

检索启用的集群功能。

follow

字符串

in

指明应遵循哪些内联链接。

6.39.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.39.2. 删除 DELETE
复制链接

禁用集群功能。

例如，要禁用集群 123 的功能 456，发送如下请求： 

DELETE /ovirt-engine/api/clusters/123/enabledfeatures/456

6.40. ClusterEnabledFeatures
复制链接

提供有关为此集群启用的其他功能的信息。启用的功能是集群级别的可用功能

Expand
表 6.117. 方法概述
名称概述

add

为集群启用额外功能。

list

列出为集群启用的其他功能。

6.40.1. 添加 POST
复制链接

为集群启用额外功能。

例如，要在集群 123 上启用功能 456，请发送如下请求： 

POST /ovirt-engine/api/clusters/123/enabledfeatures

请求正文应类似如下： 

<cluster_feature id="456"/>
Expand
表 6.118. 参数摘要
名称类型方向概述

功能

ClusterFeature

in/Out

 

6.40.2. 列出 GET
复制链接

列出为集群启用的其他功能。

例如，要为集群 123 启用功能，请发送类似如下的请求： 

GET /ovirt-engine/api/clusters/123/enabledfeatures

这将返回一个功能列表： 

<enabled_features>
  <cluster_feature id="123">
     <name>test_feature</name>
  </cluster_feature>
  ...
</enabled_features>
Expand
表 6.119. 参数摘要
名称类型方向概述

功能

ClusterFeature[]

out

检索的功能.

follow

字符串

in

指明应遵循哪些内联链接。

6.40.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.41. ClusterExternalProviders
复制链接

此服务列出了外部提供程序。

Expand
表 6.120. 方法概述
名称概述

list

返回外部提供程序列表。

6.41.1. 列出 GET
复制链接

返回外部提供程序列表。

无法保证返回的供应商列表的顺序。

Expand
表 6.121. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

供应商

ExternalProvider[]

out

 
6.41.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.42. ClusterFeature
复制链接

代表为集群级别启用的功能

Expand
表 6.122. 方法概述
名称概述

get

提供有关集群级别支持的集群功能的信息。

6.42.1. 获取 GET
复制链接

提供有关集群级别支持的集群功能的信息。

例如，要查找集群级别 4.1 的集群功能 456 的详情，请发送类似如下的请求： 

GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures/456

这将返回包含名称的 ClusterFeature 对象： 

<cluster_feature id="456">
  <name>libgfapi_supported</name>
</cluster_feature>
Expand
表 6.123. 参数摘要
名称类型方向概述

功能

ClusterFeature

out

检索的集群功能。

follow

字符串

in

指明应遵循哪些内联链接。

6.42.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.43. ClusterFeatures
复制链接

提供有关集群级别支持的集群功能的信息。

Expand
表 6.124. 方法概述
名称概述

list

列出集群级别支持的集群功能。

6.43.1. 列出 GET
复制链接

列出集群级别支持的集群功能。 

GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures

这将返回集群级别支持的集群功能列表： 

<cluster_features>
  <cluster_feature id="123">
     <name>test_feature</name>
  </cluster_feature>
  ...
</cluster_features>
Expand
表 6.125. 参数摘要
名称类型方向概述

功能

ClusterFeature[]

out

检索的功能.

follow

字符串

in

指明应遵循哪些内联链接。

6.43.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.44. ClusterLevel
复制链接

提供有关特定集群级别的信息。如需更多信息，请参阅 ClusterLevels 服务。

Expand
表 6.126. 方法概述
名称概述

get

提供有关此服务管理的特定集群级别功能的信息。

6.44.1. 获取 GET
复制链接

提供有关此服务管理的特定集群级别功能的信息。

例如，要查找级别 3.6 支持哪些 CPU 类型，您可以发送类似如下的请求： 

GET /ovirt-engine/api/clusterlevels/3.6

这将返回一个包含支持的 CPU 类型的 ClusterLevel 对象，以及描述集群级别的其他信息： 

<cluster_level id="3.6">
  <cpu_types>
    <cpu_type>
      <name>Intel Nehalem Family</name>
      <level>3</level>
      <architecture>x86_64</architecture>
    </cpu_type>
    ...
  </cpu_types>
  <permits>
    <permit id="1">
      <name>create_vm</name>
      <administrative>false</administrative>
    </permit>
    ...
  </permits>
</cluster_level>
Expand
表 6.127. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

level

ClusterLevel

out

Retreived 集群级别.

6.44.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.45. ClusterLevels
复制链接

提供有关引擎支持的不同集群级别功能的信息。引擎的版本 4.0 支持级别 4.0 和 3.6。每个级别都支持不同的 CPU 类型集，例如：此服务提供该信息。

Expand
表 6.128. 方法概述
名称概述

list

列出系统支持的集群级别。

6.45.1. 列出 GET
复制链接

列出系统支持的集群级别。 

GET /ovirt-engine/api/clusterlevels

这将返回可用集群级别的列表。 

<cluster_levels>
  <cluster_level id="4.0">
     ...
  </cluster_level>
  ...
</cluster_levels>

返回的集群级别的顺序不受保证。

Expand
表 6.129. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

level

ClusterLevel[]

out

检索的集群级别。

6.45.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.46. ClusterNetwork
复制链接

管理特定集群网络的服务。

Expand
表 6.130. 方法概述
名称概述

get

检索集群网络详情。

remove

从集群中取消分配网络。

update

更新集群中的网络。

6.46.1. 获取 GET
复制链接

检索集群网络详情。

Expand
表 6.131. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network

Network

out

集群网络。

6.46.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.46.2. 删除 DELETE
复制链接

从集群中取消分配网络。

6.46.3. 更新 PUT
复制链接

更新集群中的网络。

Expand
表 6.132. 参数摘要
名称类型方向概述

network

Network

in/Out

集群网络。

6.47. ClusterNetworks
复制链接

用于管理集群网络的服务。

Expand
表 6.133. 方法概述
名称概述

add

将网络分配给集群。

list

列出分配到集群的网络。

6.47.1. 添加 POST
复制链接

将网络分配给集群。

在以下示例中发布一个将网络分配给集群的请求： 

POST /ovirt-engine/api/clusters/123/networks

在正文中使用以下示例： 

<network id="123" />
Expand
表 6.134. 参数摘要
名称类型方向概述

network

Network

in/Out

要分配给集群的网络对象。

6.47.2. 列出 GET
复制链接

列出分配到集群的网络。

返回的集群的顺序不受保证。

Expand
表 6.135. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

网络

network[]

out

分配给集群的网络列表。

6.47.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.47.2.2. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.48. 集群
复制链接

用于管理集群的服务。

Expand
表 6.136. 方法概述
名称概述

add

创建新群集.

list

返回系统群集列表。

6.48.1. 添加 POST
复制链接

创建新群集.

这需要 name、cpu.type 和 data_center 属性。使用 id 或 name 属性识别数据中心。 

POST /ovirt-engine/api/clusters

这样的请求正文： 

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Nehalem Family</type>
  </cpu>
  <data_center id="123"/>
</cluster>

要创建具有外部网络供应商的集群，请在添加到集群中的每个主机上部署，请发送如下请求： 

POST /ovirt-engine/api/clusters

使用一个请求正文，其中包含对所需供应商的引用： 

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Nehalem Family</type>
  </cpu>
  <data_center id="123"/>
  <external_network_providers>
    <external_provider name="ovirt-provider-ovn"/>
  </external_network_providers>
</cluster>
Expand
表 6.137. 参数摘要
名称类型方向概述

cluster

Cluster

in/Out

 

6.48.2. 列出 GET
复制链接

返回系统群集列表。

只有 search 参数中包含 sortby 子句时，才会保证返回的集群的顺序。

Expand
表 6.138. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下执行搜索。

clusters

cluster[]

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大集群数量。

search

字符串

in

用于限制返回的集群的查询字符串。

6.48.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下执行搜索。默认值为 true，这意味着会考虑这个情况。要搜索忽略大小写，将其设置为 false。

6.48.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.48.2.3. Max
复制链接

设置要返回的最大集群数量。如果没有指定，则会返回所有集群。

6.49. Copyable
复制链接

Expand
表 6.139. 方法概述
名称概述

copy

 

6.49.1. 复制 POST
复制链接

Expand
表 6.140. 参数摘要
名称类型方向概述

async

布尔值

in

指明复制应异步执行。

6.50. CpuProfile
复制链接

Expand
表 6.141. 方法概述
名称概述

get

 

remove

 

update

更新系统中指定的 cpu 配置集。

6.50.1. 获取 GET
复制链接

Expand
表 6.142. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

profile

CpuProfile

out

 
6.50.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.50.2. 删除 DELETE
复制链接

Expand
表 6.143. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.50.3. 更新 PUT
复制链接

更新系统中指定的 cpu 配置集。

Expand
表 6.144. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

profile

CpuProfile

in/Out

 

6.51. CpuProfiles
复制链接

Expand
表 6.145. 方法概述
名称概述

add

向系统添加新 cpu 配置集。

list

返回系统的 CPU 配置文件列表。

6.51.1. 添加 POST
复制链接

向系统添加新 cpu 配置集。

Expand
表 6.146. 参数摘要
名称类型方向概述

profile

CpuProfile

in/Out

 

6.51.2. 列出 GET
复制链接

返回系统的 CPU 配置文件列表。

CPU 配置文件返回列表的顺序是随机的。

Expand
表 6.147. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大配置集数。

profile

CpuProfile[]

out

 
6.51.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.51.2.2. Max
复制链接

设置要返回的最大配置集数。如果没有指定，则会返回所有配置集。

6.52. DataCenter
复制链接

用于管理数据中心的服务。

Expand
表 6.148. 方法概述
名称概述

cleanfinishedtasks

目前，如果 SPM 不参与任务，存储池管理器(SPM)无法切换到其他主机。

get

获取数据中心.

remove

移除数据中心.

setmaster

用于将数据中心中的存储域手动设置为主域。

update

更新数据中心.

6.52.1. 清理finishedtasks POST
复制链接

目前，如果 SPM 不参与任务，存储池管理器(SPM)无法切换到其他主机。清除所有已完成的任务可启用 SPM 切换。

例如，要清理 ID 为 123 的数据中心中的所有已完成任务，请 发送 类似如下的请求： 

POST /ovirt-engine/api/datacenters/123/cleanfinishedtasks

这样的请求正文： 

<action/>
Expand
表 6.149. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.52.2. 获取 GET
复制链接

获取数据中心.

获取数据中心的示例： 

GET /ovirt-engine/api/datacenters/123
 
<data_center href="/ovirt-engine/api/datacenters/123" id="123">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
  <link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
  <link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
  <link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
  <local>false</local>
  <quota_mode>disabled</quota_mode>
  <status>up</status>
  <storage_format>v3</storage_format>
  <supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
   </version>
  </supported_versions>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <mac_pool href="/ovirt-engine/api/macpools/456" id="456"/>
</data_center>
Expand
表 6.150. 参数摘要
名称类型方向概述

data_center

DataCenter

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

6.52.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.52.3. 删除 DELETE
复制链接

移除数据中心. 

DELETE /ovirt-engine/api/datacenters/123

如果不使用任何特殊参数，附加到数据中心的存储域将被分离，然后从存储中删除。如果执行此操作时出现问题，例如没有主机可用于从存储中删除存储域，则完整的操作将失败。

如果 force 参数为 true，则操作将始终成功，即使某些操作在删除一个存储域时也会失败，例如：故障只是被忽略，数据中心仍然从数据库中删除。

Expand
表 6.151. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

force

布尔值

in

指明操作是否应该成功，并且存储域从数据库中删除，即使操作期间出现问题。

6.52.3.1. force
复制链接

指明操作是否应该成功，并且存储域从数据库中删除，即使操作期间出现问题。

此参数是可选的，默认值为 false。

6.52.4. setmaster POST
复制链接

用于将数据中心中的存储域手动设置为主域。例如，若要在 ID 为 '123' 的数据中心上将 ID 为"456"的存储域设置为 master，请发送类似如下的请求： 

POST /ovirt-engine/api/datacenters/123/setmaster

这样的请求正文： 

<action>
  <storage_domain id="456"/>
</action>

也可以通过其名称来指定新的主存储域。

Expand
表 6.152. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

storage_domain

StorageDomain

in

数据中心的新主存储域.

6.52.5. 更新 PUT
复制链接

更新数据中心.

name、description、storage _type、version、storage_format 和 mac_pool 元素是 updatable 后创建。例如，要更改数据中心 123 的名称和描述，请发送如下请求： 

PUT /ovirt-engine/api/datacenters/123

这样的请求正文： 

<data_center>
  <name>myupdatedname</name>
  <description>An updated description for the data center</description>
</data_center>
Expand
表 6.153. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

data_center

DataCenter

in/Out

正在更新的数据中心。

6.53. DataCenterNetwork
复制链接

用于管理特定数据中心网络的服务。

Expand
表 6.154. 方法概述
名称概述

get

检索数据中心网络详细信息。

remove

移除网络。

update

更新数据中心中的网络。

6.53.1. 获取 GET
复制链接

检索数据中心网络详细信息。

Expand
表 6.155. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network

Network

out

数据中心网络.

6.53.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.53.2. 删除 DELETE
复制链接

移除网络。

6.53.3. 更新 PUT
复制链接

更新数据中心中的网络。

Expand
表 6.156. 参数摘要
名称类型方向概述

network

Network

in/Out

数据中心网络.

6.54. DataCenterNetworks
复制链接

用于管理数据中心网络的服务。

Expand
表 6.157. 方法概述
名称概述

add

在数据中心中创建新网络。

list

列出数据中心中的网络.

6.54.1. 添加 POST
复制链接

在数据中心中创建新网络。

在下例中发出一个请求，以在 ID 为 123 的数据中心中创建一个新网络 。 

POST /ovirt-engine/api/datacenters/123/networks

在正文中使用以下示例： 

<network>
  <name>mynetwork</name>
</network>
Expand
表 6.158. 参数摘要
名称类型方向概述

network

Network

in/Out

要在数据中心中创建的网络对象。

6.54.2. 列出 GET
复制链接

列出数据中心中的网络.

网络返回列表的顺序无法保证。

Expand
表 6.159. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

网络

network[]

out

数据中心中的网络列表。

6.54.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.54.2.2. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.55. DataCenters
复制链接

用于管理数据中心的服务。

Expand
表 6.160. 方法概述
名称概述

add

创建新的数据中心.

list

列出数据中心.

6.55.1. 添加 POST
复制链接

创建新的数据中心.

创建新数据中心需要 名称和 本地 元素。例如，要创建名为 mydc 的数据中心，它使用共享存储（NFS、iSCSI 或光纤通道）发送如下的请求： 

POST /ovirt-engine/api/datacenters

这样的请求正文： 

<data_center>
  <name>mydc</name>
  <local>false</local>
</data_center>
Expand
表 6.161. 参数摘要
名称类型方向概述

data_center

DataCenter

in/Out

正在添加的数据中心。

6.55.2. 列出 GET
复制链接

列出数据中心.

以下请求检索数据中心的表示法： 

GET /ovirt-engine/api/datacenters

以上请求通过 curl 执行： 

curl \
--request GET \
--cacert /etc/pki/ovirt-engine/ca.pem \
--header "Version: 4" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
https://myengine.example.com/ovirt-engine/api/datacenters

以下是响应示例： 

<data_center href="/ovirt-engine/api/datacenters/123" id="123">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
  <link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
  <link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
  <link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
  <local>false</local>
  <quota_mode>disabled</quota_mode>
  <status>up</status>
  <supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
    </version>
  </supported_versions>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
</data_center>

注意您的 Default 数据中心的 id 代码。此代码相对于虚拟环境的其他资源标识此数据中心。

数据中心还包含指向存储域集合的链接。数据中心使用此集合从存储域主集合中附加存储域。

只有 search 参数中包含 sortby 子句时，才会保证返回的数据中心列表的顺序。

Expand
表 6.162. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

data_centers

DataCenter[]

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的数据中心的最大数量。

search

字符串

in

用于限制返回的数据中心的查询字符串。

6.55.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.55.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.55.2.3. Max
复制链接

设置要返回的数据中心的最大数量。如果没有指定，则会返回所有数据中心。

6.56. Disk
复制链接

管理单个磁盘.

Expand
表 6.163. 方法概述
名称概述

convert

转换磁盘格式和/或预分配模式。

copy

此操作将磁盘复制到指定的存储域。

export

将磁盘导出到导出存储域.

get

检索磁盘的描述。

Move

将磁盘移动到其他存储域.

减少

减少磁盘镜像的大小。

refreshlun

使用存储中的最新信息刷新直接 LUN 磁盘。

remove

删除磁盘.

sparsify

稀疏磁盘。

update

更新指定磁盘的参数。

6.56.1. 转换 POST
复制链接

转换磁盘格式和/或预分配模式。

例如，要将磁盘格式从预分配转换为稀疏镜像，请发送如下请求： 

POST /ovirt-engine/api/disks/123/convert

使用以下请求正文： 

 <action>
   <disk>
     <sparse>true</sparse>
     <format>raw</format>
   </disk>
 </action>
Expand
表 6.164. 参数摘要
名称类型方向概述

disk

Disk

in

磁盘的描述。

follow

字符串

in

指明应遵循哪些内联链接。

6.56.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.56.2. 复制 POST
复制链接

此操作将磁盘复制到指定的存储域。

例如，可使用以下请求复制磁盘： 

POST /ovirt-engine/api/disks/123/copy

这样的请求正文： 

<action>
  <storage_domain id="456"/>
  <disk>
    <name>mydisk</name>
  </disk>
</action>

如果没有为新存储域定义磁盘配置文件或磁盘当前使用的配额，则可以明确指定它们。如果没有指定它们，则使用第一个可用磁盘配置文件和默认配额。

例如，要指定磁盘配置集 987 和配额 753，请发送如下请求正文： 

<action>
  <storage_domain id="456"/>
  <disk_profile id="987"/>
  <quota id="753"/>
</action>
Expand
表 6.165. 参数摘要
名称类型方向概述

async

布尔值

in

指明复制应异步执行。

disk

Disk

in

 

disk_profile

DiskProfile

in

新存储域中磁盘的磁盘配置文件。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

quota

Quota

in

新存储域中的磁盘配额。

storage_domain

StorageDomain

in

创建新磁盘的存储域。

6.56.2.1. disk_profile
复制链接

新存储域中磁盘的磁盘配置文件。

为存储域定义磁盘配置文件，因此旧磁盘配置文件不会存在于新存储域中。如果未使用此参数，则将向磁盘分配用户具有权限的新存储域中的第一个磁盘配置文件。

6.56.2.2. quota
复制链接

新存储域中的磁盘配额。

此可选参数可用于指定磁盘的新配额，因为可能不会为新存储域定义当前的配额。如果未为新存储域定义此参数，并且未为新存储域定义旧配额，则将向磁盘分配默认（无限）配额。

6.56.2.3. storage_domain
复制链接

创建新磁盘的存储域。这可以使用 id 或 name 属性指定。例如，要将磁盘复制到名为 mydata 的存储域，请发送类似如下的请求： 

POST /ovirt-engine/api/storagedomains/123/disks/789

这样的请求正文： 

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
</action>

6.56.3. 导出 POST
复制链接

将磁盘导出到导出存储域.

Expand
表 6.166. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导出。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

storage_domain

StorageDomain

in

磁盘要导出到的导出存储域。

6.56.4. 获取 GET
复制链接

检索磁盘的描述。

Expand
表 6.167. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将磁盘的所有属性包含在响应中。

disk

Disk

out

磁盘的描述。

follow

字符串

in

指明应遵循哪些内联链接。

6.56.4.1. all_content
复制链接

指明是否应将磁盘的所有属性包含在响应中。

默认情况下，排除以下磁盘属性：

  • vms

例如，要检索磁盘 '123' 的完整表示法： 

GET /ovirt-engine/api/disks/123?all_content=true
6.56.4.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.56.5. 移动 POST
复制链接

将磁盘移动到其他存储域.

例如，要将标识符为 123 的磁盘移动到标识符 456 的存储域中，发送以下请求： 

POST /ovirt-engine/api/disks/123/move

使用以下请求正文： 

<action>
  <storage_domain id="456"/>
</action>

如果没有为新存储域定义磁盘配置文件或当前磁盘使用的配额，则可以明确指定它们。如果没有，则使用第一个可用磁盘配置文件和默认配额。

例如，要显式使用磁盘 profile 987，配额 753 会发送如下请求正文： 

<action>
  <storage_domain id="456"/>
  <disk_profile id="987"/>
  <quota id="753"/>
</action>
Expand
表 6.168. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移动。

disk_profile

DiskProfile

in

新存储域中磁盘的磁盘配置文件。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

quota

Quota

in

新存储域中的磁盘配额。

storage_domain

StorageDomain

in

磁盘将移动到的存储域。

6.56.5.1. disk_profile
复制链接

新存储域中磁盘的磁盘配置文件。

为存储域定义磁盘配置文件，因此旧磁盘配置文件不会存在于新存储域中。如果未使用此参数，则将向磁盘分配用户具有权限的新存储域中的第一个磁盘配置文件。

6.56.5.2. quota
复制链接

新存储域中的磁盘配额。

此可选参数可用于指定磁盘的新配额，因为可能不会为新存储域定义当前的配额。如果未为新存储域定义此参数，并且未为新存储域定义旧配额，则将向磁盘分配默认（无限）配额。

6.56.6. 减少 POST
复制链接

减少磁盘镜像的大小。

在逻辑卷中调用 less（即，这仅适用于块存储域）。这适用于附加到未运行虚拟机的浮动磁盘和磁盘。无需指定大小，因为会自动计算最佳大小。

Expand
表 6.169. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.56.7. refreshlun POST
复制链接

使用存储中的最新信息刷新直接 LUN 磁盘。

在以下情况下刷新直接 LUN 磁盘非常有用：

  • LUN 在没有 host 参数的情况下使用 API 添加，因此不包含存储中的任何信息（请参阅 DisksService::add）。
  • 有关 LUN 的新信息可在存储中获取，您希望使用它更新 LUN。

要使用主机 456 刷新直接 LUN 磁盘 123，请发送以下请求： 

POST /ovirt-engine/api/disks/123/refreshlun

使用以下请求正文： 

<action>
  <host id='456'/>
</action>
Expand
表 6.170. 参数摘要
名称类型方向概述

host

主机

in

用于刷新直接 LUN 磁盘的主机。

6.56.8. 删除 DELETE
复制链接

删除磁盘.

Expand
表 6.171. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.56.9. 稀疏 POST
复制链接

稀疏磁盘。

解析可在其文件系统不使用的磁盘映像中释放空间。因此，镜像会在存储中占用较少的空间。

目前稀疏仅适用于没有快照的磁盘。也不允许有派生磁盘的磁盘。

6.56.10. 更新 PUT
复制链接

更新指定磁盘的参数。

此操作允许更新以下浮动磁盘属性：

  • 对于映像磁盘： provisioned_size、alias、description、wipe_after_delete、可共享、备份 和 disk_profile。
  • LUN 磁盘： 别名、说明 和可共享.
  • Cinder 集成已被 Managed Block Storage 替代。
  • 对于 Managed Block 磁盘： provisioned_size、别名 和描述。
  • 对于虚拟机附加的磁盘，也可更新 qcow_version。

例如，可以使用以下请求完成磁盘的更新： 

PUT /ovirt-engine/api/disks/123

这样的请求正文： 

<disk>
  <qcow_version>qcow2_v3</qcow_version>
  <alias>new-alias</alias>
  <description>new-desc</description>
</disk>

由于后端操作是异步的，返回给用户的磁盘元素可能无法与更改的属性同步。

Expand
表 6.172. 参数摘要
名称类型方向概述

disk

Disk

in/Out

应用到磁盘的更新。

6.57. DiskAttachment
复制链接

此服务管理磁盘附加到虚拟机。

Expand
表 6.173. 方法概述
名称概述

get

返回附加的详细信息，包括可引导标志和磁盘链接。

remove

删除磁盘附加。

update

更新磁盘附加及其中的磁盘属性。

6.57.1. 获取 GET
复制链接

返回附加的详细信息，包括可引导标志和磁盘链接。

获取磁盘附加的示例： 

GET /ovirt-engine/api/vms/123/diskattachments/456
 
<disk_attachment href="/ovirt-engine/api/vms/123/diskattachments/456" id="456">
  <active>true</active>
  <bootable>true</bootable>
  <interface>virtio</interface>
  <disk href="/ovirt-engine/api/disks/456" id="456"/>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</disk_attachment>
Expand
表 6.174. 参数摘要
名称类型方向概述

Attach

DiskAttachment

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.57.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.57.2. 删除 DELETE
复制链接

删除磁盘附加。

这只会将磁盘从虚拟机分离，但不会将其从系统中删除，除非 detach_only 参数为 false。

删除磁盘附加的示例： 

DELETE /ovirt-engine/api/vms/123/diskattachments/456?detach_only=true
Expand
表 6.175. 参数摘要
名称类型方向概述

detach_only

布尔值

in

指明磁盘是否应该从虚拟机分离，但不应从系统中删除。

6.57.2.1. detach_only
复制链接

指明磁盘是否应该从虚拟机分离，但不应从系统中删除。默认值为 true，这不会从系统中删除磁盘。

6.57.3. 更新 PUT
复制链接

更新磁盘附加及其中的磁盘属性。 

PUT /vms/{vm:id}/disksattachments/{attachment:id}
<disk_attachment>
  <bootable>true</bootable>
  <interface>ide</interface>
  <active>true</active>
  <disk>
    <name>mydisk</name>
    <provisioned_size>1024</provisioned_size>
    ...
  </disk>
</disk_attachment>
Expand
表 6.176. 参数摘要
名称类型方向概述

disk_attachment

DiskAttachment

in/Out

 

6.58. DiskAttachments
复制链接

此服务管理附加到虚拟机的磁盘集合。每个附加的磁盘都由 DiskAttachment 表示，其中包含可引导标志、磁盘接口和磁盘引用。

Expand
表 6.177. 方法概述
名称概述

add

将新磁盘附加添加到虚拟机。

list

列出附加到虚拟机的磁盘。

6.58.1. 添加 POST
复制链接

将新磁盘附加添加到虚拟机。如果磁盘已存在，附加 参数可以只包含一个引用： 

<disk_attachment>
  <bootable>true</bootable>
  <pass_discard>true</pass_discard>
  <interface>ide</interface>
  <active>true</active>
  <disk id="123"/>
</disk_attachment>

或者，如果磁盘还不存在，它可以包含磁盘的完整表示法： 

<disk_attachment>
  <bootable>true</bootable>
  <pass_discard>true</pass_discard>
  <interface>ide</interface>
  <active>true</active>
  <disk>
    <name>mydisk</name>
    <provisioned_size>1024</provisioned_size>
    ...
  </disk>
</disk_attachment>

在这种情况下，将创建磁盘并附加到虚拟机。

在这两种情况下，为 ID 为 345 的虚拟机使用以下 URL： 

POST /ovirt-engine/api/vms/345/diskattachments
重要

服务器接受不包含 active 属性但效果未定义的请求。在某些情况下，磁盘将被自动激活，在其他情况下则不会激活。为避免出现问题，强烈建议始终使用所需值包含 active 属性。

Expand
表 6.178. 参数摘要
名称类型方向概述

Attach

DiskAttachment

in/Out

要添加到虚拟机的磁盘附件。

6.58.2. 列出 GET
复制链接

列出附加到虚拟机的磁盘。

无法保证返回的磁盘附件列表的顺序。

Expand
表 6.179. 参数摘要
名称类型方向概述

附件

DiskAttachment[]

out

附加到虚拟机的磁盘附件列表。

follow

字符串

in

指明应遵循哪些内联链接。

6.58.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.59. DiskProfile
复制链接

Expand
表 6.180. 方法概述
名称概述

get

 

remove

 

update

更新系统中指定的磁盘配置文件。

6.59.1. 获取 GET
复制链接

Expand
表 6.181. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

profile

DiskProfile

out

 
6.59.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.59.2. 删除 DELETE
复制链接

Expand
表 6.182. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.59.3. 更新 PUT
复制链接

更新系统中指定的磁盘配置文件。

Expand
表 6.183. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

profile

DiskProfile

in/Out

 

6.60. DiskProfiles
复制链接

Expand
表 6.184. 方法概述
名称概述

add

向系统添加新磁盘配置文件。

list

返回系统的磁盘配置文件列表。

6.60.1. 添加 POST
复制链接

向系统添加新磁盘配置文件。

Expand
表 6.185. 参数摘要
名称类型方向概述

profile

DiskProfile

in/Out

 

6.60.2. 列出 GET
复制链接

返回系统的磁盘配置文件列表。

无法保证返回的磁盘配置文件列表的顺序。

Expand
表 6.186. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大配置集数。

profile

DiskProfile[]

out

 
6.60.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.60.2.2. Max
复制链接

设置要返回的最大配置集数。如果没有指定，则返回所有配置集。

6.61. DiskSnapshot
复制链接

Expand
表 6.187. 方法概述
名称概述

get

 

remove

 

6.61.1. 获取 GET
复制链接

Expand
表 6.188. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

snapshot

DiskSnapshot

out

 
6.61.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.61.2. 删除 DELETE
复制链接

Expand
表 6.189. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.62. DiskSnapshots
复制链接

管理存储域中可用的磁盘快照的集合。

Expand
表 6.190. 方法概述
名称概述

list

返回存储域的磁盘快照列表。

6.62.1. 列出 GET
复制链接

返回存储域的磁盘快照列表。

无法保证磁盘快照返回列表的顺序。

Expand
表 6.191. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

include_active

布尔值

in

如果 true 也返回活动快照。

include_template

布尔值

in

如果 true 也返回模板快照。

max

整数

in

设置要返回的快照的最大数量。

snapshots

DiskSnapshot[]

out

 
6.62.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.62.1.2. include_active
复制链接

如果 true 也返回活动快照。如果未指定活动快照，则不返回。

6.62.1.3. include_template
复制链接

如果 true 也返回模板快照。如果没有返回指定的模板快照。

6.62.1.4. Max
复制链接

设置要返回的快照的最大数量。如果没有指定，则返回所有快照。

6.63. 磁盘
复制链接

管理系统中可用的磁盘集合。

Expand
表 6.192. 方法概述
名称概述

add

添加新浮动磁盘。

list

获取磁盘列表.

6.63.1. 添加 POST
复制链接

添加新浮动磁盘。

可以添加三种类型的磁盘 - 磁盘镜像、直接 LUN 和 Managed Block 磁盘。Cinder 集成已被 Managed Block Storage 替代。

添加新镜像磁盘：

在创建新的浮动映像 磁盘 时，API 需要 storage_domain、provision_size 和 format 属性。

请注意，块存储域（例如 iSCSI 或 FCP 存储类型的 存储域）不支持将原始 格式 与 稀疏=true 的组合，因此必须明确说明 sparse=false。

要使用指定的 provisioned_size 创建一个新的浮动镜像磁盘，在存储域上格式化和 名称 （id 123 并启用了增量备份），请发送如下请求： 

POST /ovirt-engine/api/disks

请求正文如下： 

<disk>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <name>mydisk</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
  <backup>incremental</backup>
</disk>

添加新直接 LUN 磁盘：

在通过 API 添加新浮动直接 LUN 时，可以使用两种类别：

  1. 对于 主机 元素 - 在这种情况下，主机用于完整性检查（例如，LUN 是可见的）并检索有关 LUN 的基本信息（如大小和串行）。
  2. 如果没有 主机 元素 - 在这种情况下，操作仅为数据库，并且不会访问存储。

要使用 ID 为 123、指定 别名、类型和 logical_unit 的主机 元素创建一个新的浮动直接 LUN 磁盘 （ 具有属性 地址、端口 和目标），请发送请求，如下所示： 

POST /ovirt-engine/api/disks

请求正文如下： 

<disk>
  <alias>mylun</alias>
  <lun_storage>
    <host id="123"/>
    <type>iscsi</type>
    <logical_units>
      <logical_unit id="456">
        <address>10.35.10.20</address>
        <port>3260</port>
        <target>iqn.2017-01.com.myhost:444</target>
      </logical_unit>
    </logical_units>
  </lun_storage>
</disk>

若要创建新的浮动直接 LUN 磁盘，而不使用主机，请删除 主机 元素。

添加新 Cinder 磁盘：

Cinder 集成已被 Managed Block Storage 替代。

添加浮动磁盘以上传磁盘快照：

由于引擎的版本 4.2，可以使用快照上传磁盘。此请求应当用于创建映像链的基础镜像（镜像），在创建快照时使用 disk-attachments 元素创建。

磁盘必须使用与上传镜像相同的磁盘标识符和映像标识符创建。i. 标识符应保存为备份过程的一部分。也可以使用 qemu-img info 命令来获取映像标识符。例如，如果磁盘映像存储在名为 b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img 的文件中： 

$ qemu-img info b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img
image: b548366b-fb51-4b41-97be-733c887fe305
file format: qcow2
virtual size: 1.0G (1073741824 bytes)
disk size: 196K
cluster_size: 65536
backing file: ad58716a-1fe9-481f-815e-664de1df04eb
backing file format: raw

要使用上面显示的 qemu-img info 命令获取的磁盘标识符和映像标识符创建磁盘，请发送类似如下的请求： 

POST /ovirt-engine/api/disks

请求正文如下： 

<disk id="b7a4c6c5-443b-47c5-967f-6abc79675e8b">
  <image_id>b548366b-fb51-4b41-97be-733c887fe305</image_id>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <name>mydisk</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
</disk>
Expand
表 6.193. 参数摘要
名称类型方向概述

disk

Disk

in/Out

磁盘.

6.63.2. 列出 GET
复制链接

获取磁盘列表. 

GET /ovirt-engine/api/disks

您将获得类似如下的 XML 响应： 

<disks>
  <disk id="123">
    <actions>...</actions>
    <name>MyDisk</name>
    <description>MyDisk description</description>
    <link href="/ovirt-engine/api/disks/123/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/disks/123/statistics" rel="statistics"/>
    <actual_size>5345845248</actual_size>
    <alias>MyDisk alias</alias>
    ...
    <status>ok</status>
    <storage_type>image</storage_type>
    <wipe_after_delete>false</wipe_after_delete>
    <disk_profile id="123"/>
    <quota id="123"/>
    <storage_domains>...</storage_domains>
  </disk>
  ...
</disks>

只有 search 参数中包含 sortby 子句时，才会保证返回的磁盘列表的顺序。

Expand
表 6.194. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

磁盘

disk[]

out

检索的磁盘列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

search

字符串

in

用于限制返回的磁盘的查询字符串。

6.63.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.63.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.63.2.3. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.64. 域
复制链接

此服务可用于查看系统中身份验证域的详细信息。

Expand
表 6.195. 方法概述
名称概述

get

获取身份验证域信息.

6.64.1. 获取 GET
复制链接

获取身份验证域信息.

使用方法： 

GET /ovirt-engine/api/domains/5678

将返回域信息： 

<domain href="/ovirt-engine/api/domains/5678" id="5678">
  <name>internal-authz</name>
  <link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
  <link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
  <link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/>
  <link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/>
</domain>
Expand
表 6.196. 参数摘要
名称类型方向概述

domain

域

out

身份验证域.

follow

字符串

in

指明应遵循哪些内联链接。

6.64.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.65. DomainGroup
复制链接

Expand
表 6.197. 方法概述
名称概述

get

 

6.65.1. 获取 GET
复制链接

Expand
表 6.198. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

get

组

out

 
6.65.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.66. DomainGroups
复制链接

Expand
表 6.199. 方法概述
名称概述

list

返回组列表。

6.66.1. 列出 GET
复制链接

返回组列表。

无法保证返回的组列表的顺序。

Expand
表 6.200. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

groups

group[]

out

 

max

整数

in

设置要返回的最大组数。

search

字符串

in

用于限制返回的组的查询字符串。

6.66.1.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.66.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.66.1.3. Max
复制链接

设置要返回的最大组数。如果没有指定，则返回所有组。

6.67. DomainUser
复制链接

用于查看系统中域用户的服务。

Expand
表 6.201. 方法概述
名称概述

get

获取域用户信息.

6.67.1. 获取 GET
复制链接

获取域用户信息.

使用方法： 

GET /ovirt-engine/api/domains/5678/users/1234

将返回域用户信息： 

<user href="/ovirt-engine/api/users/1234" id="1234">
  <name>admin</name>
  <namespace>*</namespace>
  <principal>admin</principal>
  <user_name>admin@internal-authz</user_name>
  <domain href="/ovirt-engine/api/domains/5678" id="5678">
    <name>internal-authz</name>
  </domain>
  <groups/>
</user>
Expand
表 6.202. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

user

用户

out

域用户.

6.67.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.68. DomainUserGroups
复制链接

在 AAA 扩展中显示用户的组成员资格的服务。

Expand
表 6.203. 方法概述
名称概述

list

返回用户所属组的列表：

6.68.1. 列出 GET
复制链接

返回用户所属组的列表：

Expand
表 6.204. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

groups

group[]

out

用户所属组的列表。

6.68.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.69. DomainUsers
复制链接

用于列出系统中的所有域用户的服务。

Expand
表 6.205. 方法概述
名称概述

list

列出 域中的所有用户。

6.69.1. 列出 GET
复制链接

列出 域中的所有用户。

使用方法： 

GET /ovirt-engine/api/domains/5678/users

将返回域中的用户列表： 

<users>
  <user href="/ovirt-engine/api/domains/5678/users/1234" id="1234">
    <name>admin</name>
    <namespace>*</namespace>
    <principal>admin</principal>
    <user_name>admin@internal-authz</user_name>
    <domain href="/ovirt-engine/api/domains/5678" id="5678">
      <name>internal-authz</name>
    </domain>
    <groups/>
  </user>
</users>

无法保证返回的用户列表的顺序。

Expand
表 6.206. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大用户数。

search

字符串

in

用于限制返回的用户的查询字符串。

用户

user[]

out

域中的用户列表。

6.69.1.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.69.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.69.1.3. Max
复制链接

设置要返回的最大用户数。如果未指定，则返回所有用户。

6.70. 域
复制链接

用于列出系统中的所有身份验证域的服务。

Expand
表 6.207. 方法概述
名称概述

list

列出系统中的所有身份验证域。

6.70.1. 列出 GET
复制链接

列出系统中的所有身份验证域。

使用方法： 

GET /ovirt-engine/api/domains

将返回域列表： 

<domains>
  <domain href="/ovirt-engine/api/domains/5678" id="5678">
    <name>internal-authz</name>
    <link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
    <link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
    <link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/>
    <link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/>
  </domain>
</domains>

无法保证返回的域列表的顺序。

Expand
表 6.208. 参数摘要
名称类型方向概述

domains

Domain[]

out

域列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大域数。

6.70.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.70.1.2. Max
复制链接

设置要返回的最大域数。如果未指定，则返回所有域。

6.71. EngineKatelloErrata
复制链接

此服务用于管理分配给引擎的 Katello 勘误表。该信息是从 Katello 检索而来。

Expand
表 6.209. 方法概述
名称概述

list

检索 Katello 勘误表的表示形式。

6.71.1. 列出 GET
复制链接

检索 Katello 勘误表的表示形式。 

GET /ovirt-engine/api/katelloerrata

您将在 XML 中收到类似以下的响应： 

<katello_errata>
  <katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
    <name>RHBA-2013:XYZ</name>
    <description>The description of the erratum</description>
    <title>some bug fix update</title>
    <type>bugfix</type>
    <issued>2013-11-20T02:00:00.000+02:00</issued>
    <solution>Few guidelines regarding the solution</solution>
    <summary>Updated packages that fix one bug are now available for XYZ</summary>
    <packages>
      <package>
        <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
      </package>
      ...
    </packages>
  </katello_erratum>
  ...
</katello_errata>

返回的勘误列表的顺序无法保证。

Expand
表 6.210. 参数摘要
名称类型方向概述

勘误

KatelloErratum[]

out

Katello 勘误表的表示。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的勘误表的最大数量。

6.71.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.71.1.2. Max
复制链接

设置要返回的勘误表的最大数量。如果没有指定，则会返回所有勘误。

6.72. event
复制链接

用于管理系统中事件的服务。

Expand
表 6.211. 方法概述
名称概述

get

获取事件.

remove

从内部审计日志中移除事件。

6.72.1. 获取 GET
复制链接

获取事件.

获取事件的示例： 

GET /ovirt-engine/api/events/123
 
<event href="/ovirt-engine/api/events/123" id="123">
  <description>Host example.com was added by admin@internal-authz.</description>
  <code>42</code>
  <correlation_id>135</correlation_id>
  <custom_id>-1</custom_id>
  <flood_rate>30</flood_rate>
  <origin>oVirt</origin>
  <severity>normal</severity>
  <time>2016-12-11T11:13:44.654+02:00</time>
  <cluster href="/ovirt-engine/api/clusters/456" id="456"/>
  <host href="/ovirt-engine/api/hosts/789" id="789"/>
  <user href="/ovirt-engine/api/users/987" id="987"/>
</event>

请注意，字段数量根据事件中驻留的信息而变化。例如，对于与存储域相关的事件，您将获得存储域参考以及该存储域所在数据中心的引用。

Expand
表 6.212. 参数摘要
名称类型方向概述

event

event

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.72.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.72.2. 删除 DELETE
复制链接

从内部审计日志中移除事件。

通过发送以下请求可以删除事件 

DELETE /ovirt-engine/api/events/123
Expand
表 6.213. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.73. EventSubscription
复制链接

在系统中管理特定事件订阅的服务。

Expand
表 6.214. 方法概述
名称概述

get

获取与 event-subscription 相关的信息。

remove

从系统中删除 event-subscription。

6.73.1. 获取 GET
复制链接

获取与 event-subscription 相关的信息。

例如，要将用户 '123' 订阅到事件 'vm_console_detected' 的信息检索到事件 'vm_console_detected'： 

GET /ovirt-engine/api/users/123/vm_console_detected
 
<event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_console_detected">
  <event>vm_console_detected</event>
  <notification_method>smtp</notification_method>
  <user href="/ovirt-engine/api/users/123" id="123"/>
  <address>a@b.com</address>
</event-subscription>
Expand
表 6.215. 参数摘要
名称类型方向概述

event_subscription

EventSubscription

out

event-subscription。

6.73.2. 删除 DELETE
复制链接

从系统中删除 event-subscription。

例如，要删除用户 123 的订阅到 vm_console_detected 事件： 

DELETE /ovirt-engine/api/users/123/vm_console_detected
Expand
表 6.216. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.74. EventSubscriptions
复制链接

代表用于管理用户事件订阅集合的服务。

Expand
表 6.217. 方法概述
名称概述

add

向系统添加新的 event-subscription。

list

列出提供的用户的 event-subscriptions。

6.74.1. 添加 POST
复制链接

向系统添加新的 event-subscription。

event-subscription 始终在用户的上下文中添加。例如，要为用户 123 为 host_high_cpu_use 添加新的 event-subscription，并将通知发送到电子邮件地址：a@b.com ， 发送如下请求： 

POST /ovirt-engine/api/users/123/eventsubscriptions

这样的请求正文： 

<event_subscription>
    <event>host_high_cpu_use</event>
    <address>a@b.com</address>
</event_subscription>

该事件名称将成为新 event-subscription 实体的 ID： GET …​/api/users/123/eventsubscriptions/host_high_cpu_use

请注意，请求正文中不提供用户 ID。这是因为，API 已经从上下文中了解 user-id（本例中为 123）。另请注意，event-subscription 实体包含 notification-method 字段，但它也不会在请求正文中提供。这是因为当前总是设置为 SMTP，因为 API 层仍不支持 SNMP 通知。

Expand
表 6.218. 参数摘要
名称类型方向概述

event_subscription

EventSubscription

in/Out

添加的 event-subscription。

6.74.2. 列出 GET
复制链接

列出提供的用户的 event-subscriptions。

例如，列出用户 123 的 event-subscriptions： 

GET /ovirt-engine/api/users/123/event-subscriptions
 
<event-subscriptions>
  <event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/host_install_failed">
    <event>host_install_failed</event>
    <notification_method>smtp</notification_method>
    <user href="/ovirt-engine/api/users/123" id="123"/>
    <address>a@b.com</address>
  </event-subscription>
  <event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_paused">
    <event>vm_paused</event>
    <notification_method>smtp</notification_method>
    <user href="/ovirt-engine/api/users/123" id="123"/>
    <address>a@b.com</address>
  </event-subscription>
</event-subscriptions>
Expand
表 6.219. 参数摘要
名称类型方向概述

event_subscriptions

EventSubscription[]

out

指定用户的 event-subscriptions 列表

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 event-subscriptions 数。

6.74.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.74.2.2. Max
复制链接

设置要返回的最大 event-subscriptions 数。如果没有指定所有 event-subscriptions，则会返回。

6.75. 事件
复制链接

用于管理系统中事件的服务。

Expand
表 6.220. 方法概述
名称概述

add

将外部事件添加到内部审计日志中。

list

获取事件列表.

undelete

 

6.75.1. 添加 POST
复制链接

将外部事件添加到内部审计日志中。

这可用于与检测或生成与系统管理员相关的事件的外部系统集成。例如，外部监控工具可以检测文件系统是否完全在虚拟机的客户机操作系统内。此事件可添加到内部审计日志中，如下所示发送请求： 

POST /ovirt-engine/api/events
<event>
  <description>File system /home is full</description>
  <severity>alert</severity>
  <origin>mymonitor</origin>
  <custom_id>1467879754</custom_id>
</event>

事件也可以链接到特定的对象。例如，以上事件可使用 vm 链接到发生该事件的特定虚拟机： 

POST /ovirt-engine/api/events
<event>
  <description>File system /home is full</description>
  <severity>alert</severity>
  <origin>mymonitor</origin>
  <custom_id>1467879754</custom_id>
  <vm id="aae98225-5b73-490d-a252-899209af17e9"/>
</event>
注意

使用链接时，如上例中的 vm，仅接受 id 属性。name 属性（如果提供）被简单地忽略。

Expand
表 6.221. 参数摘要
名称类型方向概述

event

event

in/Out

 

6.75.2. 列出 GET
复制链接

获取事件列表. 

GET /ovirt-engine/api/events

对上述请求，我们得到以下响应： 

<events>
  <event href="/ovirt-engine/api/events/2" id="2">
    <description>User admin@internal-authz logged out.</description>
    <code>31</code>
    <correlation_id>1e892ea9</correlation_id>
    <custom_id>-1</custom_id>
    <flood_rate>30</flood_rate>
    <origin>oVirt</origin>
    <severity>normal</severity>
    <time>2016-09-14T12:14:34.541+02:00</time>
    <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
  </event>
  <event href="/ovirt-engine/api/events/1" id="1">
    <description>User admin logged in.</description>
    <code>30</code>
    <correlation_id>1fbd81f4</correlation_id>
    <custom_id>-1</custom_id>
    <flood_rate>30</flood_rate>
    <origin>oVirt</origin>
    <severity>normal</severity>
    <time>2016-09-14T11:54:35.229+02:00</time>
    <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
  </event>
</events>

发生以下事件：

  • ID="1" - admin 用户帐户中的 API 日志。
  • ID="2" - API 注销 admin 用户帐户。

返回的事件列表的顺序始终是巨大的。如果 search 参数中包含 sortby 子句，则事件将根据该子句排序。如果没有包括 sortby 子句，则事件将按 id 属性的数字值排序，从最高值开始。这与 max 参数相结合，简化了获取最新事件的过程： 

GET /ovirt-engine/api/events?max=1
Expand
表 6.222. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

事件

Event[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

来自

整数

in

指定应返回的事件索引。

max

整数

in

设置要返回的最大事件数。

search

字符串

in

events 服务提供类似于其他资源服务的搜索查询。

6.75.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.75.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.75.2.3. 来自
复制链接

指定应返回的事件索引。事件索引严格增加，因此当仅返回具有更大索引的事件时，才会返回此参数。例如，以下请求将仅返回索引大于 123 的事件： 

GET /ovirt-engine/api/events?from=123

这个参数是可选的，如果没有指定，则返回的第一个事件将最近生成。

6.75.2.4. Max
复制链接

设置要返回的最大事件数。如果没有指定，则返回所有事件。

6.75.3. 取消删除 POST
复制链接

Expand
表 6.223. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行取消删除。

6.76. ExternalComputeResource
复制链接

管理单个外部计算资源。

计算资源是一个主机外部提供程序术语。外部提供程序还需要知道调配的主机需要注册的位置。引擎的登录详情保存为外部提供程序端的计算资源。

Expand
表 6.224. 方法概述
名称概述

get

检索外部计算资源详细信息.

6.76.1. 获取 GET
复制链接

检索外部计算资源详细信息.

例如，要获取 供应商 123 的计算资源详情，请发送类似如下的请求： 

GET /ovirt-engine/api/externalhostproviders/123/computeresources/234

它将返回类似如下的响应： 

<external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234">
  <name>hostname</name>
  <provider>oVirt</provider>
  <url>https://hostname/api</url>
  <user>admin@internal</user>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_compute_resource>
Expand
表 6.225. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

resource

ExternalComputeResource

out

外部计算资源信息

6.76.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.77. ExternalComputeResources
复制链接

管理一系列外部计算资源。

计算资源是一个主机外部提供程序术语。外部提供程序还需要知道调配的主机需要注册的位置。引擎的登录详情保存为外部提供程序端的计算资源。

Expand
表 6.226. 方法概述
名称概述

list

检索外部计算资源的列表。

6.77.1. 列出 GET
复制链接

检索外部计算资源的列表。

例如，要检索外部主机供应商 123 的计算资源，请发送如下请求： 

GET /ovirt-engine/api/externalhostproviders/123/computeresources

它将返回类似如下的响应： 

<external_compute_resources>
  <external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234">
    <name>hostname</name>
    <provider>oVirt</provider>
    <url>https://address/api</url>
    <user>admin@internal</user>
    <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
   </external_compute_resource>
   ...
</external_compute_resources>

无法保证返回的计算资源列表的顺序。

Expand
表 6.227. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的资源的最大数量。

资源

ExternalComputeResource[]

out

外部计算机资源列表。

6.77.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.77.1.2. Max
复制链接

设置要返回的资源的最大数量。如果没有指定，则返回所有资源。

6.78. ExternalDiscoveredHost
复制链接

此服务管理单个发现的主机。

Expand
表 6.228. 方法概述
名称概述

get

获取发现的主机信息.

6.78.1. 获取 GET
复制链接

获取发现的主机信息.

检索有关在外部提供程序管理系统中管理的主机的信息，如 Foreman。该信息包括主机名、地址、子网、基础镜像等。

例如，要从供应商 123 获取主机 234 的详细信息，请发送类似如下的请求： 

GET /ovirt-engine/api/externalhostproviders/123/discoveredhosts/234

结果如下： 

<external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/234" id="234">
 <name>mac001a4ad04040</name>
 <ip>10.34.67.43</ip>
 <last_report>2017-04-24 11:05:41 UTC</last_report>
 <mac>00:1a:4a:d0:40:40</mac>
 <subnet_name>sat0</subnet_name>
 <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_discovered_host>
Expand
表 6.229. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

host

ExternalDiscoveredHost

out

主机的硬件和配置信息.

6.78.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.79. ExternalDiscoveredHosts
复制链接

此服务管理外部发现的主机。

Expand
表 6.230. 方法概述
名称概述

list

获取发现的主机信息列表。

6.79.1. 列出 GET
复制链接

获取发现的主机信息列表。

从 Foreman 等第三方提供程序获取发现的主机。

要列出供应商 123 的所有发现的主机，请执行以下操作： 

GET /ovirt-engine/api/externalhostproviders/123/discoveredhost
 
<external_discovered_hosts>
 <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/456" id="456">
  <name>mac001a4ad04031</name>
  <ip>10.34.67.42</ip>
  <last_report>2017-04-24 11:05:41 UTC</last_report>
  <mac>00:1a:4a:d0:40:31</mac>
  <subnet_name>sat0</subnet_name>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
 </external_discovered_host>
 <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/789" id="789">
  <name>mac001a4ad04040</name>
  <ip>10.34.67.43</ip>
  <last_report>2017-04-24 11:05:41 UTC</last_report>
  <mac>00:1a:4a:d0:40:40</mac>
  <subnet_name>sat0</subnet_name>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
 </external_discovered_host>
 ...
</external_discovered_hosts>

无法保证返回的主机列表的顺序。

Expand
表 6.231. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

主机

ExternalDiscoveredHost[]

out

发现的主机列表

max

整数

in

设置要返回的最大主机数。

6.79.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.79.1.2. Max
复制链接

设置要返回的最大主机数。如果未指定，则返回所有主机。

6.80. ExternalHost
复制链接

Expand
表 6.232. 方法概述
名称概述

get

 

6.80.1. 获取 GET
复制链接

Expand
表 6.233. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

host

ExternalHost

out

 
6.80.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.81. ExternalHostGroup
复制链接

此服务管理单个主机组信息。

主机组是主机提供程序的术语，主机组中包含应用于新发现主机的调配详细信息。子网、操作系统、域等信息.

Expand
表 6.234. 方法概述
名称概述

get

获取主机组信息.

6.81.1. 获取 GET
复制链接

获取主机组信息.

例如，要获取供应商 123 的 hostgroup 234 的详细信息，请发送类似如下的请求： 

GET /ovirt-engine/api/externalhostproviders/123/hostgroups/234

它将返回类似如下的响应： 

<external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234">
  <name>rhel7</name>
  <architecture_name>x86_64</architecture_name>
  <domain_name>s.com</domain_name>
  <operating_system_name>RedHat 7.3</operating_system_name>
  <subnet_name>sat0</subnet_name>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_host_group>
Expand
表 6.235. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

group

ExternalHostGroup

out

主机组信息.

6.81.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.82. ExternalHostGroups
复制链接

此服务管理主机组。

Expand
表 6.236. 方法概述
名称概述

list

从外部主机提供程序获取主机组列表。

6.82.1. 列出 GET
复制链接

从外部主机提供程序获取主机组列表。

主机组是主机提供程序的一个术语 - 主机组中包含调配详细信息。此 API 返回外部提供程序公开的所有可能的主机组。

例如，要获取供应商 123 的所有主机组的详情，请发送如下请求： 

GET /ovirt-engine/api/externalhostproviders/123/hostgroups

回答如下： 

<external_host_groups>
  <external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234">
    <name>rhel7</name>
    <architecture_name>x86_64</architecture_name>
    <domain_name>example.com</domain_name>
    <operating_system_name>RedHat 7.3</operating_system_name>
    <subnet_name>sat0</subnet_name>
    <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
  </external_host_group>
  ...
</external_host_groups>

主机组返回列表的顺序不保证。

Expand
表 6.237. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

groups

ExternalHostGroup[]

out

可用于外部主机提供程序的所有主机组的列表

max

整数

in

设置要返回的最大组数。

6.82.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.82.1.2. Max
复制链接

设置要返回的最大组数。如果没有指定，则返回所有组。

6.83. ExternalHostProvider
复制链接

代表外部主机提供程序，如 Foreman 或卫星。

有关 Foreman 的更多详细信息，请参见 https://www.theforeman.org/。有关 Red Hat Satellite 的详情，请查看 https://access.redhat.com/products/red-hat-satellite。

Expand
表 6.238. 方法概述
名称概述

get

获取外部主机提供程序信息

主机提供程序 Foreman 或卫星可以在 ovirt 中设置为外部提供程序。

importcertificates

导入外部主机提供程序的 SSL 证书。

remove

 

testconnectivity

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。

update

更新系统中指定的外部主机供应商。

6.83.1. 获取 GET
复制链接

获取外部主机提供程序信息

主机提供程序 Foreman 或卫星可以在 ovirt 中设置为外部提供程序。要查看附加到 ovirt 的特定主机提供程序的详细信息，请使用这个 API。

例如，要获取主机供应商 123 的详细信息，请发送类似如下的请求： 

GET /ovirt-engine/api/externalhostproviders/123

回答如下： 

<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123">
  <name>mysatellite</name>
  <requires_authentication>true</requires_authentication>
  <url>https://mysatellite.example.com</url>
  <username>admin</username>
</external_host_provider>
Expand
表 6.239. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

provider

ExternalHostProvider

out

 
6.83.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.83.2. importcertificates POST
复制链接

导入外部主机提供程序的 SSL 证书。

Expand
表 6.240. 参数摘要
名称类型方向概述

证书

certificate[]

in

 

6.83.3. 删除 DELETE
复制链接

Expand
表 6.241. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.83.4. 测试连接 POST
复制链接

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。 

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Expand
表 6.242. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行测试。

6.83.5. 更新 PUT
复制链接

更新系统中指定的外部主机供应商。

Expand
表 6.243. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

provider

ExternalHostProvider

in/Out

 

6.84. ExternalHostProviders
复制链接

Expand
表 6.244. 方法概述
名称概述

add

向系统添加新的外部主机提供程序。

list

返回外部主机提供程序列表。

6.84.1. 添加 POST
复制链接

向系统添加新的外部主机提供程序。

Expand
表 6.245. 参数摘要
名称类型方向概述

provider

ExternalHostProvider

in/Out

 

6.84.2. 列出 GET
复制链接

返回外部主机提供程序列表。

主机提供程序返回列表的顺序不受保证。

Expand
表 6.246. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大供应商数量。

供应商

ExternalHostProvider[]

out

 

search

字符串

in

用于限制返回的外部主机供应商的查询字符串。

6.84.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.84.2.2. Max
复制链接

设置要返回的最大供应商数量。如果没有指定，则返回所有供应商。

6.85. ExternalHosts
复制链接

Expand
表 6.247. 方法概述
名称概述

list

返回外部主机列表。

6.85.1. 列出 GET
复制链接

返回外部主机列表。

无法保证返回的主机列表的顺序。

Expand
表 6.248. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

主机

ExternalHost[]

out

 

max

整数

in

设置要返回的最大主机数。

6.85.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.85.1.2. Max
复制链接

设置要返回的最大主机数。如果未指定，则返回所有主机。

6.86. ExternalNetworkProviderConfiguration
复制链接

描述主机上系统如何调配外部网络提供程序。

Expand
表 6.249. 方法概述
名称概述

get

返回主机上外部网络提供程序的信息。

6.86.1. 获取 GET
复制链接

返回主机上外部网络提供程序的信息。

Expand
表 6.250. 参数摘要
名称类型方向概述

配置

ExternalNetworkProviderConfiguration

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.86.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.87. ExternalNetworkProviderConfigurations
复制链接

此服务用于列出系统在主机上调配的所有外部网络提供程序。

Expand
表 6.251. 方法概述
名称概述

list

返回主机上所有外部网络提供程序的列表。

6.87.1. 列出 GET
复制链接

返回主机上所有外部网络提供程序的列表。

无法保证返回的网络列表的顺序。

Expand
表 6.252. 参数摘要
名称类型方向概述

配置

ExternalNetworkProviderConfiguration[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.87.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.88. ExternalProvider
复制链接

提供管理外部提供程序的功能。

Expand
表 6.253. 方法概述
名称概述

importcertificates

导入外部主机提供程序的 SSL 证书。

testconnectivity

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。

6.88.1. importcertificates POST
复制链接

导入外部主机提供程序的 SSL 证书。

Expand
表 6.254. 参数摘要
名称类型方向概述

证书

certificate[]

in

 

6.88.2. 测试连接 POST
复制链接

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。 

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Expand
表 6.255. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行测试。

6.89. ExternalProviderCertificate
复制链接

用于查看外部提供程序特定证书的服务。

Expand
表 6.256. 方法概述
名称概述

get

获取特定证书.

6.89.1. 获取 GET
复制链接

获取特定证书. 

GET /ovirt-engine/api/externalhostproviders/123/certificate/0

以下是响应示例： 

<certificate id="0">
  <organization>provider.example.com</organization>
  <subject>CN=provider.example.com</subject>
  <content>...</content>
</certificate>
Expand
表 6.257. 参数摘要
名称类型方向概述

certificate

证书

out

证书的详细信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.89.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.90. ExternalProviderCertificates
复制链接

用于查看外部供应商证书的服务。

Expand
表 6.258. 方法概述
名称概述

list

返回外部供应商提供的证书链。

6.90.1. 列出 GET
复制链接

返回外部供应商提供的证书链。 

GET /ovirt-engine/api/externalhostproviders/123/certificates

以下是响应示例： 

<certificates>
  <certificate id="789">...</certificate>
  ...
</certificates>

返回的证书的顺序始终被保证为符号顺序：第一个是服务器本身的证书，第二个是签署第一个证书的 CA 的证书，以此类推。

Expand
表 6.259. 参数摘要
名称类型方向概述

证书

certificate[]

out

包含证书详细信息的列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大证书数。

6.90.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.90.1.2. Max
复制链接

设置要返回的最大证书数。如果没有指定，则返回所有证书。

6.91. ExternalTemplateImports
复制链接

提供导入外部模板的功能。目前仅支持 OVA。

Expand
表 6.260. 方法概述
名称概述

add

此操作用于从外部虚拟机监控程序导入模板。

6.91.1. 添加 POST
复制链接

此操作用于从外部虚拟机监控程序导入模板。

例如，可以使用以下请求来简化模板 OVA 的导入： 

POST /externaltemplateimports

使用 ExternalTemplateImport 类型的请求正文，例如： 

<external_template_import>
  <template>
    <name>my_template</name>
  </template>
  <cluster id="2b18aca2-4469-11eb-9449-482ae35a5f83" />
  <storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
  <url>ova:///mnt/ova/ova_template.ova</url>
  <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
</external_template_import>
Expand
表 6.261. 参数摘要
名称类型方向概述

import

ExternalTemplateImport

in/Out

 

6.92. ExternalVmImports
复制链接

提供导入外部虚拟机的功能。

Expand
表 6.262. 方法概述
名称概述

add

此操作用于从外部管理程序（如 KVM、XEN 或 VMware）导入虚拟机。

6.92.1. 添加 POST
复制链接

此操作用于从外部管理程序（如 KVM、XEN 或 VMware）导入虚拟机。

例如，可以使用以下请求来简化从 VMware 导入虚拟机： 

POST /externalvmimports

使用 ExternalVmImport 类型的请求正文，例如： 

<external_vm_import>
  <vm>
    <name>my_vm</name>
  </vm>
  <cluster id="360014051136c20574f743bdbd28177fd" />
  <storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
  <name>vm_name_as_is_in_vmware</name>
  <sparse>true</sparse>
  <username>vmware_user</username>
  <password>123456</password>
  <provider>VMWARE</provider>
  <url>vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1</url>
  <drivers_iso id="virtio-win-1.6.7.iso" />
</external_vm_import>
Expand
表 6.263. 参数摘要
名称类型方向概述

import

ExternalVmImport

in/Out

 

6.93. FenceAgent
复制链接

用于管理特定主机的隔离代理的服务。

Expand
表 6.264. 方法概述
名称概述

get

获取该隔离代理的详情。

remove

删除特定主机的隔离代理。

update

更新 fence-agent。

6.93.1. 获取 GET
复制链接

获取该隔离代理的详情。 

GET /ovirt-engine/api/hosts/123/fenceagents/0

以下是响应示例： 

<agent id="0">
  <type>apc</type>
  <order>1</order>
  <ip>192.168.1.101</ip>
  <user>user</user>
  <password>xxx</password>
  <port>9</port>
  <options>name1=value1, name2=value2</options>
</agent>
Expand
表 6.265. 参数摘要
名称类型方向概述

agent

agent

out

隔离代理详细信息.

follow

字符串

in

指明应遵循哪些内联链接。

6.93.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.93.2. 删除 DELETE
复制链接

删除特定主机的隔离代理。 

DELETE /ovirt-engine/api/hosts/123/fenceagents/0
Expand
表 6.266. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.93.3. 更新 PUT
复制链接

更新 fence-agent。

Expand
表 6.267. 参数摘要
名称类型方向概述

agent

agent

in/Out

隔离代理详细信息.

async

布尔值

in

指明是否应异步执行更新。

6.94. FenceAgents
复制链接

用于管理特定主机的隔离代理的服务。

Expand
表 6.268. 方法概述
名称概述

add

向主机添加新的 fence-agent。

list

返回为主机配置的隔离代理列表。

6.94.1. 添加 POST
复制链接

向主机添加新的 fence-agent。 

POST /ovirt-engine/api/hosts/123/fenceagents

You should consult the /usr/sbin/fence_<agent_name> manual page for
the legal parameters to [name1=value1, name2=value2,...] in the options field.
If any parameter in options appears by name that means that it is mandatory.
For example in <options>slot=7[,name1=value1, name2=value2,...]</options>
slot is mandatory.

APC, bladecenter, wti 隔离代理/s 示例请求： 

  <agent>
    <type>apc</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>slot=7[,name1=value1, name2=value2,...]</options>
  </agent>

apc_snmp, hpblade, ilo, ilo2, ilo_ssh, redfish, rsa 隔离代理/s 示例请求： 

  <agent>
    <type>apc_snmp</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>[name1=value1, name2=value2,...]</options>
  </agent>

cisco_ucs, drac5, eps 隔离代理/s 示例请求： 

  <agent>
    <type>cisco_ucs</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <options>slot=7[,name1=value1, name2=value2,...]</options>
  </agent>

drac7、ilo3、ilo4、ipmilan、rsb 隔离代理/s 示例请求： 

  <agent>
    <type>drac7</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <options>[name1=value1, name2=value2,...]</options>
  </agent>
Expand
表 6.269. 参数摘要
名称类型方向概述

agent

agent

in/Out

 

6.94.2. 列出 GET
复制链接

返回为主机配置的隔离代理列表。 

GET /ovirt-engine/api/hosts/123/fenceagents

以下是响应示例： 

<agents>
  <agent id="0">
    <type>apc</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>name1=value1, name2=value2</options>
  </agent>
</agents>

无法保证返回的隔离代理列表的顺序。

Expand
表 6.270. 参数摘要
名称类型方向概述

代理

agent[]

out

隔离代理详情列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的代理的最大数量。

6.94.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.94.2.2. Max
复制链接

设置要返回的代理的最大数量。如果没有指定，则返回所有代理。

6.95. File
复制链接

Expand
表 6.271. 方法概述
名称概述

get

 

6.95.1. 获取 GET
复制链接

Expand
表 6.272. 参数摘要
名称类型方向概述

file

File

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.95.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.96. 文件
复制链接

提供了一种方式，供客户端列出可用的文件。

此服务专用于 ISO 存储域，后者包含管理员上传的 ISO 映像和虚拟软盘(VFD)。

向虚拟机中添加 CD-ROM 设备需要来自 ISO 存储域文件的 ISO 映像。

Expand
表 6.273. 方法概述
名称概述

list

返回存储域中可用的 ISO 映像和虚拟软盘的列表。

6.96.1. 列出 GET
复制链接

返回存储域中可用的 ISO 映像和虚拟软盘的列表。无法保证返回列表的顺序。

如果 刷新 参数为 false，则返回的列表可能无法反映对存储域的最新更改；例如，它可能不包含最近添加的新 ISO 文件。这是因为服务器缓存文件列表以提高性能。要获得最新结果，请将 refresh 参数设置为 true。

refresh 参数的默认值为 true，但可使用配置值 force RefreshDomainFilesByDefault 更改： 

# engine-config -s ForceRefreshDomainFilesByDefault=false
重要

将 refresh 参数的值设置为 true 会影响服务器的性能。必要时才使用。

Expand
表 6.274. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否使用 search 参数进行的搜索应考虑大小写。

file

file[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大文件数。

refresh

布尔值

in

指明是否应从存储域刷新文件列表，而不显示以特定间隔更新的缓存结果。

search

字符串

in

用于限制返回文件的查询字符串。

6.96.1.1. case_sensitive
复制链接

指明是否使用 search 参数进行的搜索应考虑大小写。默认值为 true。

6.96.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.96.1.3. Max
复制链接

设置要返回的最大文件数。如果未指定，则返回所有文件。

6.97. filter
复制链接

Expand
表 6.275. 方法概述
名称概述

get

 

remove

 

6.97.1. 获取 GET
复制链接

Expand
表 6.276. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

结果

filter

out

 
6.97.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.97.2. 删除 DELETE
复制链接

Expand
表 6.277. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.98. 过滤器
复制链接

管理调度策略使用的过滤器。

Expand
表 6.278. 方法概述
名称概述

add

向指定用户定义的调度策略添加过滤器。

list

返回调度策略使用的过滤器列表。

6.98.1. 添加 POST
复制链接

向指定用户定义的调度策略添加过滤器。

Expand
表 6.279. 参数摘要
名称类型方向概述

filter

filter

in/Out

 

6.98.2. 列出 GET
复制链接

返回调度策略使用的过滤器列表。

返回的过滤器列表的顺序无法保证。

Expand
表 6.280. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

过滤器

filter[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大过滤器数。

6.98.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.98.2.2. Max
复制链接

设置要返回的最大过滤器数。如果没有指定，则会返回所有过滤器。

6.99. 关注
复制链接

6.100. GlusterBrick
复制链接

此服务管理单个 gluster brick。

Expand
表 6.281. 方法概述
名称概述

get

获取 brick 的详细信息。

remove

删除 brick。

replace

将此 brick 替换为新的 brick。

6.100.1. 获取 GET
复制链接

获取 brick 的详细信息。

从底层 gluster 卷检索 brick 的状态详细信息，并标头 All-Content 设为 true。这等同于运行 gluster 卷状态 <volumename> <brickname> 详情。

例如，若要获取 gluster 卷 123 的 brick 234 的详细信息，请发送类似如下的请求： 

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234

这会返回类似如下的响应正文： 

<brick id="234">
  <name>host1:/rhgs/data/brick1</name>
  <brick_dir>/rhgs/data/brick1</brick_dir>
  <server_id>111</server_id>
  <status>up</status>
  <device>/dev/mapper/RHGS_vg1-lv_vmaddldisks</device>
  <fs_name>xfs</fs_name>
  <gluster_clients>
    <gluster_client>
      <bytes_read>2818417648</bytes_read>
      <bytes_written>1384694844</bytes_written>
      <client_port>1011</client_port>
      <host_name>client2</host_name>
    </gluster_client>
  </gluster_clients>
  <memory_pools>
    <memory_pool>
      <name>data-server:fd_t</name>
      <alloc_count>1626348</alloc_count>
      <cold_count>1020</cold_count>
      <hot_count>4</hot_count>
      <max_alloc>23</max_alloc>
      <max_stdalloc>0</max_stdalloc>
      <padded_size>140</padded_size>
      <pool_misses>0</pool_misses>
    </memory_pool>
  </memory_pools>
  <mnt_options>rw,seclabel,noatime,nodiratime,attr2,inode64,sunit=512,swidth=2048,noquota</mnt_options>
  <pid>25589</pid>
  <port>49155</port>
</brick>
Expand
表 6.282. 参数摘要
名称类型方向概述

brick

GlusterBrick

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.100.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.100.2. 删除 DELETE
复制链接

删除 brick。

从底层 gluster 卷移除 brick，并从数据库中删除条目。这只能在没有数据迁移的情况下删除单个 brick 时使用。若要删除多个 brick 和 数据迁移，请改为使用 migrate。

例如，要从 gluster 卷 123 中删除 brick 234，请发送如下所示的请求： 

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
Expand
表 6.283. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.100.3. 替换 POST
复制链接

将此 brick 替换为新的 brick。

重要

自引擎版本 3.5 起，此操作已弃用，并将在以后的中删除。改为使用 add brick， 再迁移 brick。

Expand
表 6.284. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行替换。

force

布尔值

in

 

6.101. GlusterBricks
复制链接

此服务管理 gluster 卷中的 gluster brick

Expand
表 6.285. 方法概述
名称概述

激活

在删除 brick 操作的数据迁移后激活 brick。

add

添加 brick 列表到 gluster 卷。

list

列出 gluster 卷的 brick。

migrate

在删除 brick 之前开始迁移数据。

remove

从 gluster 卷移除 brick。

stopmigrate

停止从 brick 操作迁移 brick 数据。

6.101.1. 激活 POST
复制链接

在删除 brick 操作的数据迁移后激活 brick。

用于在 brick 的数据迁移完成后激活 brick，但用户不想再删除 brick。之前标记为移除的 brick 现在用作普通 brick。

例如，若要保留迁移数据的 glustervolume 123 上的 brick，请发送如下请求： 

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate

这样的请求正文： 

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>
Expand
表 6.286. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行激活。

brick

GlusterBrick[]

in

需要重新激活的 brick 列表。

6.101.2. 添加 POST
复制链接

添加 brick 列表到 gluster 卷。

用于通过添加 brick 来扩展 gluster 卷。对于复制卷类型，需要传递参数 replica_count。如果副本数增加，则 brick 的数量需要等于副本集的数量。

例如，要将 brick 添加到 gluster 卷 123，请发送如下所示的请求： 

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

这样的请求正文： 

<bricks>
  <brick>
    <server_id>111</server_id>
    <brick_dir>/export/data/brick3</brick_dir>
  </brick>
</bricks>
Expand
表 6.287. 参数摘要
名称类型方向概述

brick

GlusterBrick[]

in/Out

要添加到卷中的 brick 列表

replica_count

整数

in

添加后操作的副本数。

stripe_count

整数

in

添加后操作的条带计数.

6.101.3. 列出 GET
复制链接

列出 gluster 卷的 brick。

例如，要列出 gluster 卷 123 的 brick，请发送如下所示的请求： 

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

提供如下输出： 

<bricks>
  <brick id="234">
    <name>host1:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>111</server_id>
    <status>up</status>
  </brick>
  <brick id="233">
    <name>host2:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>222</server_id>
    <status>up</status>
  </brick>
</bricks>

返回列表的顺序基于在创建 gluster 卷时提供的 brick 顺序。

Expand
表 6.288. 参数摘要
名称类型方向概述

brick

GlusterBrick[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 brick 数。

6.101.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.101.3.2. Max
复制链接

设置要返回的最大 brick 数。如果未指定，则返回所有 brick。

6.101.4. 迁移 POST
复制链接

在删除 brick 之前开始迁移数据。

删除 brick 的过程包含两步，其中要移除 brick 上的数据首先迁移到剩余的 brick。迁移完成后，通过 API 删除确认 brick 删除。如果随时需要取消该操作，则必须调用该操作。

例如，要从 ID 为 123 的 gluster 卷中删除 brick ， 请发送请求： 

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate

这样的请求正文： 

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>

可以使用作业和作业中的步骤从 API 返回的作业 id 中跟踪迁移过程。

Expand
表 6.289. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行迁移。

brick

GlusterBrick[]

in

需要为其启动数据迁移的 brick 的列表。

6.101.5. 删除 DELETE
复制链接

从 gluster 卷移除 brick。

在不丢失数据的情况下删除 brick 的建议方法是首先使用 stopmigrate 来迁移数据，然后删除它们。如果删除之前未在 brick 上调用迁移，则 brick 将被删除，而无需数据迁移，这可能会导致数据丢失。

例如，要从 gluster 卷 123 中删除 brick，请发送如下所示的请求： 

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

这样的请求正文： 

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>
Expand
表 6.290. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

brick

GlusterBrick[]

in

要删除的 brick 的列表

replica_count

整数

in

添加后操作的副本数。

6.101.6. stopmigrate POST
复制链接

停止从 brick 操作迁移 brick 数据。

若要取消在 2 步中启动的数据迁移，如果用户希望继续使用 brick，则删除 brick 进程。标记为移除的 brick 在执行此操作后将作为普通 brick 发挥作用。

例如，若要停止从 gluster 卷 123 的 brick 迁移数据，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate

这样的请求正文： 

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>
Expand
表 6.291. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

brick

GlusterBrick[]

in

需要停止数据迁移的 brick 列表。

6.101.6.1. brick
复制链接

需要停止数据迁移的 brick 列表。此列表应与传递给迁移的参数匹配。

6.102. GlusterHook
复制链接

Expand
表 6.292. 方法概述
名称概述

disable

通过禁用集群中的所有服务器中的 Gluster hook，解决集群中服务器之间的 hook 状态冲突。

启用

通过禁用集群中的所有服务器中的 Gluster hook，解决集群中服务器之间的 hook 状态冲突。

get

 

remove

从集群中的所有服务器移除此 Gluster hook，并将它从数据库中删除。

resolve

根据解析类型解决缺少的 hook 冲突。

6.102.1. 禁用 POST
复制链接

通过禁用集群中的所有服务器中的 Gluster hook，解决集群中服务器之间的 hook 状态冲突。这会将 hook 状态更新为 数据库中的 DISABLED。

Expand
表 6.293. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.102.2. 启用 POST
复制链接

通过禁用集群中的所有服务器中的 Gluster hook，解决集群中服务器之间的 hook 状态冲突。这会将 hook 状态更新为 数据库中的 DISABLED。

Expand
表 6.294. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.102.3. 获取 GET
复制链接

Expand
表 6.295. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

hook

GlusterHook

out

 
6.102.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.102.4. 删除 DELETE
复制链接

从集群中的所有服务器移除此 Gluster hook，并将它从数据库中删除。

Expand
表 6.296. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.102.5. 解析 POST
复制链接

根据解析类型解决缺少的 hook 冲突。

对于 ADD，通过将存储在引擎数据库中的 hook 复制到缺少 hook 的所有服务器上来解决：引擎维护缺少 hook 的所有服务器的列表。

对于 COPY，通过将存储在引擎数据库中的 hook 复制到缺少 hook 的所有服务器来解决 hook 内容冲突。引擎维护内容有冲突的所有服务器的列表。如果主机 ID 作为参数传递，则服务器的 hook 内容将用作主服务器以复制到集群中的其他服务器。

Expand
表 6.297. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

host

主机

in

 

resolution_type

字符串

in

 

6.103. GlusterHooks
复制链接

Expand
表 6.298. 方法概述
名称概述

list

返回 hook 列表。

6.103.1. 列出 GET
复制链接

返回 hook 列表。

返回的 hook 列表的顺序不受保证。

Expand
表 6.299. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

Hook

GlusterHook[]

out

 

max

整数

in

设置要返回的最大 hook 数。

6.103.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.103.1.2. Max
复制链接

设置要返回的最大 hook 数。如果没有指定，则返回所有 hook。

6.104. GlusterVolume
复制链接

此服务管理单个 gluster 卷。

Expand
表 6.300. 方法概述
名称概述

get

获取 gluster 卷详细信息。

getprofilestatistics

获取 gluster 卷配置文件统计信息。

rebalance

重新平衡 gluster 卷。

remove

删除 gluster 卷。

resetalloptions

重置 gluster 卷中设置的所有选项。

resetoption

重置 gluster 卷中的特定选项。

setoption

在 gluster 卷中设置特定选项。

start

启动 gluster 卷。

startprofile

启动 gluster 卷性能分析.

stop

停止 gluster 卷。

stopprofile

停止分析 gluster 卷。

stoprebalance

停止重新平衡 gluster 卷。

6.104.1. 获取 GET
复制链接

获取 gluster 卷详细信息。

例如，若要获取群集 456 中标识符为 123 的 gluster 卷详情，请发送类似如下的请求： 

GET /ovirt-engine/api/clusters/456/glustervolumes/123

此 GET 请求将返回以下输出： 

<gluster_volume id="123">
 <name>data</name>
 <link href="/ovirt-engine/api/clusters/456/glustervolumes/123/glusterbricks" rel="glusterbricks"/>
 <disperse_count>0</disperse_count>
 <options>
   <option>
     <name>storage.owner-gid</name>
     <value>36</value>
   </option>
   <option>
     <name>performance.io-cache</name>
     <value>off</value>
   </option>
   <option>
     <name>cluster.data-self-heal-algorithm</name>
     <value>full</value>
   </option>
 </options>
 <redundancy_count>0</redundancy_count>
 <replica_count>3</replica_count>
 <status>up</status>
 <stripe_count>0</stripe_count>
 <transport_types>
   <transport_type>tcp</transport_type>
 </transport_types>
 <volume_type>replicate</volume_type>
 </gluster_volume>
Expand
表 6.301. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

卷

GlusterVolume

out

gluster 卷的表示形式.

6.104.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.104.2. getprofilestatistics POST
复制链接

获取 gluster 卷配置文件统计信息。

例如，若要获取群集 456 中标识符为 123 的 gluster 卷的配置集统计信息，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/getprofilestatistics
Expand
表 6.302. 参数摘要
名称类型方向概述

详情

GlusterVolumeProfileDetails

out

Gluster 卷性能分析从操作返回的信息.

6.104.3. 重新平衡 POST
复制链接

重新平衡 gluster 卷。

重新平衡 gluster 卷有助于在所有 brick 之间均匀分布数据。在扩展或缩小 gluster 卷（无需迁移数据）后，我们需要在 brick 之间重新平衡数据。在非复制卷中，所有 brick 都应在线，以执行重新平衡操作。在复制卷中，副本中应至少有一个 brick 在线。

例如，若要在集群 456 中使用标识符 123 重新平衡 gluster 卷，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/rebalance
Expand
表 6.303. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重新平衡。

fix_layout

布尔值

in

如果设为 true，则重新平衡将仅修复布局，以便添加到卷的新数据在所有主机上分布。

force

布尔值

in

指明是否应强制启动重新平衡。

6.104.3.1. fix_layout
复制链接

如果设为 true，则重新平衡将仅修复布局，以便添加到卷的新数据在所有主机上分布。但它不会迁移/重新平衡现有数据。默认为 false。

6.104.3.2. force
复制链接

指明是否应强制启动重新平衡。重新平衡命令可以使用 force 选项执行，即使旧的客户端连接到集群时也是如此。但是，这会导致数据丢失的情况。默认为 false。

6.104.4. 删除 DELETE
复制链接

删除 gluster 卷。

例如，要删除在集群 456 中带有 123 的卷，请发送类似如下的请求： 

DELETE /ovirt-engine/api/clusters/456/glustervolumes/123
Expand
表 6.304. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.104.5. resetalloptions POST
复制链接

重置 gluster 卷中设置的所有选项。

例如，若要重置群集 456 中标识符为 123 的 gluster 卷中的所有选项，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetalloptions
Expand
表 6.305. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重置。

6.104.6. resetoption POST
复制链接

重置 gluster 卷中的特定选项。

例如，若要在群集 456 中使用标识符 123 重置 gluster 卷中的特定 选项 option1，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetoption

使用以下请求正文： 

<action>
 <option name="option1"/>
</action>
Expand
表 6.306. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重置。

force

布尔值

in

 

选项

选项

in

重置选项.

6.104.7. setoption POST
复制链接

在 gluster 卷中设置特定选项。

例如，要在群集 456 中为 gluster 卷设置 值为 value1 的 option1，请在群集 456 中使用标识符 123 设置 option1，发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/setoption

使用以下请求正文： 

<action>
 <option name="option1" value="value1"/>
</action>
Expand
表 6.307. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

选项

选项

in

要设置的选项.

6.104.8. 启动 POST
复制链接

启动 gluster 卷。

应当启动 Gluster 卷以读/写数据。例如，要在集群 456 中启动一个带有标识符 123 的 gluster 卷，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/start
Expand
表 6.308. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

force

布尔值

in

指明是否应强制启动该卷。

6.104.8.1. force
复制链接

指明是否应强制启动该卷。如果 gluster 卷已启动，但很少/所有 brick 已停机，则可以使用 force start 来启动所有 brick。默认为 false。

6.104.9. startprofile POST
复制链接

启动 gluster 卷性能分析.

例如，要在群集 456 中使用标识符 123 开始分析 gluster 卷，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/startprofile
Expand
表 6.309. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.104.10. 停止 POST
复制链接

停止 gluster 卷。

停止卷将使其数据无法访问。

例如，若要在集群 456 中停止带有标识符 123 的 gluster 卷，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stop
Expand
表 6.310. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

force

布尔值

in

 

6.104.11. stopprofile POST
复制链接

停止分析 gluster 卷。

例如，要在集群 456 中停止使用标识符 123 分析 gluster 卷，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stopprofile
Expand
表 6.311. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.104.12. 停止平衡 POST
复制链接

停止重新平衡 gluster 卷。

例如，若要停止在集群 456 中使用标识符 123 重新平衡 gluster 卷，请发送类似如下的请求： 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stoprebalance
Expand
表 6.312. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.105. GlusterVolumes
复制链接

此服务管理集群中可用的 gluster 卷的集合。

Expand
表 6.313. 方法概述
名称概述

add

创建新的 gluster 卷。

list

列出集群中的所有 gluster 卷。

6.105.1. 添加 POST
复制链接

创建新的 gluster 卷。

卷基于 volume 参数的属性创建。需要属性 名称 、volume_type 和 brick。

例如，要将名为 myvolume 的卷添加到集群 123 中，请发送以下请求： 

POST /ovirt-engine/api/clusters/123/glustervolumes

使用以下请求正文： 

<gluster_volume>
  <name>myvolume</name>
  <volume_type>replicate</volume_type>
  <replica_count>3</replica_count>
  <bricks>
    <brick>
      <server_id>server1</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server2</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server3</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
  <bricks>
</gluster_volume>
Expand
表 6.314. 参数摘要
名称类型方向概述

卷

GlusterVolume

in/Out

要创建卷的 gluster 卷定义作为输入传递，并且新创建的卷返回。

6.105.2. 列出 GET
复制链接

列出集群中的所有 gluster 卷。

例如，若要列出群集 456 中的所有 Gluster 卷，请发送如下所示的请求： 

GET /ovirt-engine/api/clusters/456/glustervolumes

无法保证返回的卷列表的顺序。

Expand
表 6.315. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大卷数。

search

字符串

in

用于限制返回的卷的查询字符串。

卷

GlusterVolume[]

out

 
6.105.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.105.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.105.2.3. Max
复制链接

设置要返回的最大卷数。如果没有指定，则返回所有卷。

6.106. 组
复制链接

管理一组用户。使用此服务获取组详细信息或删除组。要添加新组，请使用管理组集合的服务。

Expand
表 6.316. 方法概述
名称概述

get

获取系统组信息.

remove

删除系统组。

6.106.1. 获取 GET
复制链接

获取系统组信息.

使用方法： 

GET /ovirt-engine/api/groups/123

将返回组信息： 

<group href="/ovirt-engine/api/groups/123" id="123">
  <name>mygroup</name>
  <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/>
  <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/>
  <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id>
  <namespace>DC=example,DC=com</namespace>
  <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF">
    <name>myextension-authz</name>
  </domain>
</group>
Expand
表 6.317. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

get

组

out

系统组.

6.106.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.106.2. 删除 DELETE
复制链接

删除系统组。

使用方法： 

DELETE /ovirt-engine/api/groups/123
Expand
表 6.318. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.107. 组
复制链接

管理用户组的集合。

Expand
表 6.319. 方法概述
名称概述

add

从目录服务添加组.

list

列出系统中的所有组。

6.107.1. 添加 POST
复制链接

从目录服务添加组.请注意，域名是授权供应商的名称。

例如，从 internal-authz 授权供应商添加 Developers 组，发送类似如下的请求： 

POST /ovirt-engine/api/groups

这样的请求正文： 

<group>
  <name>Developers</name>
  <domain>
    <name>internal-authz</name>
  </domain>
</group>
Expand
表 6.320. 参数摘要
名称类型方向概述

group

组

in/Out

要添加的组。

6.107.2. 列出 GET
复制链接

列出系统中的所有组。

使用方法： 

GET /ovirt-engine/api/groups

将返回组列表： 

<groups>
  <group href="/ovirt-engine/api/groups/123" id="123">
    <name>mygroup</name>
    <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/>
    <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/>
    <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id>
    <namespace>DC=example,DC=com</namespace>
    <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF">
      <name>myextension-authz</name>
    </domain>
  </group>
  ...
</groups>

无法保证返回的组列表的顺序。

Expand
表 6.321. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

groups

group[]

out

组列表。

max

整数

in

设置要返回的最大组数。

search

字符串

in

用于限制返回的组的查询字符串。

6.107.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.107.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.107.2.3. Max
复制链接

设置要返回的最大组数。如果没有指定，则返回所有组。

6.108. 主机
复制链接

用于管理主机的服务。

Expand
表 6.322. 方法概述
名称概述

激活

激活要使用的主机，例如用于运行虚拟机的主机。

批准

批准预安装的系统管理程序主机，以便在虚拟化环境中使用。

commitnetconfig

将网络配置标记为良好的，并在主机中持久保留。

copyhostnetworks

将指定主机的网络配置复制到当前主机。

取消激活

停用主机以执行维护任务。

discoveriscsi

使用启动器详细信息，在主机上发现 iSCSI 目标。

注册证书

注册主机的证书。

fence

控制主机的电源管理设备。

forceselectspm

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

get

获取主机详细信息。

install

在主机上安装最新版本的 VDSM 和相关软件。

iscsidiscover

这个方法自 Engine 版本 4 起已弃用。

iscsilogin

使用目标详细信息登录到主机上的 iSCSI 目标。

refresh

刷新主机设备和功能。

remove

从系统中删除主机。

setupnetworks

此方法用于更改主机网络接口的配置。

syncallnetworks

要同步主机上的所有网络，请发送如下请求：

[source] ---- POST /ovirt-engine/api/hosts/123/syncallnetworks ----

这样的请求正文：

[source,xml] ---- <action/> ----

unregisteredstoragedomainsdiscover

发现要导入到设置的块存储域。

update

更新主机属性。

upgrade

升级主机上的 VDSM 和选定的软件.

upgradecheck

检查是否有适用于主机的升级。

6.108.1. 激活 POST
复制链接

激活要使用的主机，例如用于运行虚拟机的主机。

Expand
表 6.323. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行激活。

6.108.2. 批准 POST
复制链接

批准预安装的系统管理程序主机，以便在虚拟化环境中使用。

此操作还接受用于定义此主机的目标集群的可选集群元素。

Expand
表 6.324. 参数摘要
名称类型方向概述

激活

布尔值

in

当设置为"true"时，此主机将在其批准完成后激活。

async

布尔值

in

指明是否应当异步执行批准。

cluster

Cluster

in

在批准主机后将添加主机的群集。

host

主机

in

要批准的主机。

reboot

布尔值

in

指明是否应当在安装成功后重新启动该主机。

6.108.2.1. 激活
复制链接

当设置为"true"时，此主机将在其批准完成后激活。当设置为"false"时，主机在批准后将保持"维护"状态。缺少此参数将解释为 'true'，因为所需的默认行为是在批准后激活主机。

6.108.2.2. reboot
复制链接

指明是否应当在安装成功后重新启动该主机。默认值为 true。

6.108.3. commitnetconfig POST
复制链接

将网络配置标记为良好的，并在主机中持久保留。

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

重要

只有在引擎确定了主机连接不会因为配置更改而丢失后，才会提交网络配置。如果主机连接丢失，则主机需要重新引导，并且自动恢复到先前的网络配置。

例如，要提交 ID 为 123 的主机 的网络配置，发送如下请求： 

POST /ovirt-engine/api/hosts/123/commitnetconfig

这样的请求正文： 

<action/>
重要

由于 Red Hat Virtualization Manager 4.3，也可以在 setupnetworks 请求中指定 commit_on_success，在这种情况下，新配置会在完成设置并重新建立 {hypervisor-name} 和 Red Hat Virtualization Manager 之间的连接后自动保存在 {hypervisor-name} 和 Red Hat Virtualization Manager，且无需等待单独的 commitnetconfig 请求。

Expand
表 6.325. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.108.4. copyhostnetworks POST
复制链接

将指定主机的网络配置复制到当前主机。

重要

源主机上不存在的任何网络附加都会通过复制操作从目标主机上清除。

要从另一个主机复制网络，请发送如下请求： 

POST /ovirt-engine/api/hosts/123/copyhostnetworks

这样的请求正文： 

<action>
   <source_host id="456"/>
</action>
Expand
表 6.326. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

source_host

主机

in

要从中复制网络的主机。

6.108.5. 取消激活 POST
复制链接

停用主机以执行维护任务。

Expand
表 6.327. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行取消激活。

reason

字符串

in

 

stop_gluster_service

布尔值

in

指明是否应当在停用主机时停止 gluster 服务。

6.108.5.1. stop_gluster_service
复制链接

指明是否应当在停用主机时停止 gluster 服务。它可用于在 gluster 主机上执行维护操作。此变量的默认值为 false。

6.108.6. 发现iscsi POST
复制链接

使用启动器详细信息，在主机上发现 iSCSI 目标。返回包含已发现数据的 IscsiDetails 对象的列表。

例如，要从主机 123 发现 myiscsi.example.com 中可用的 iSCSI 目标，请发送如下请求： 

POST /ovirt-engine/api/hosts/123/discoveriscsi

这样的请求正文： 

<action>
  <iscsi>
    <address>myiscsi.example.com</address>
  </iscsi>
</action>

结果如下： 

<discovered_targets>
  <iscsi_details>
    <address>10.35.1.72</address>
    <port>3260</port>
    <portal>10.35.1.72:3260,1</portal>
    <target>iqn.2015-08.com.tgt:444</target>
  </iscsi_details>
</discovered_targets>
重要

当使用此方法发现 iscsi 目标时，您可以使用 FQDN 或 IP 地址，但必须使用发现的目标中的 iscsi 详情才能使用 iscsilogin 方法登录。

Expand
表 6.328. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行发现。

discovered_targets

IscsiDetails[]

out

发现的目标包括所有连接信息。

iscsi

IscsiDetails

in

目标 iSCSI 设备。

6.108.7. 注册certificate POST
复制链接

注册主机的证书。如果您收到即将过期或已过期的警告，则很有用。

Expand
表 6.329. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行注册。

6.108.8. 隔离 POST
复制链接

控制主机的电源管理设备。

例如，要启动主机：这可以通过以下方法完成： 

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
  <fence_type>start</fence_type>
</action>
' \
"${url}/hosts/123/fence"
Expand
表 6.330. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行隔离。

fence_type

字符串

in

 

maintenance_after_restart

布尔值

in

指明是否应在重新启动后将主机置于维护状态。

power_management

PowerManagement

out

 

6.108.9. forceelectspm POST
复制链接

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

POST /ovirt-engine/api/hosts/123/forceselectspm

这样的请求正文： 

<action/>
Expand
表 6.331. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.108.10. 获取 GET
复制链接

获取主机详细信息。 

GET /ovirt-engine/api/hosts/123
Expand
表 6.332. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将主机的所有属性包含在响应中。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

host

主机

out

查询的主机.

6.108.10.1. all_content
复制链接

指明是否应将主机的所有属性包含在响应中。

默认情况下排除以下属性：

  • hosted_engine

例如，要检索主机 '123' 的完整表示法： 

GET /ovirt-engine/api/hosts/123?all_content=true
注意

这些属性默认不包含在内，因为检索它们会影响性能。它们很少使用，需要对数据库进行其他查询。谨慎使用此参数，且仅在有特殊需要时才使用。

6.108.10.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.108.11. 安装 POST
复制链接

在主机上安装最新版本的 VDSM 和相关软件。

该操作还会在主机上执行在向引擎中添加主机时执行的每个配置步骤：kdump 配置、hosted-engine 部署、内核选项更改等。

主机类型定义操作的其他参数。

使用 curl 和 JSON 安装主机示例： 

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
  "root_password": "myrootpassword"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123"

使用带有托管引擎组件的 curl 和 JSON 安装主机示例： 

curl \
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
  "root_password": "myrootpassword"
"deploy_hosted_engine" : "true"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123"
重要

自引擎版本 4.1.2 起，在重新安装主机时，我们默认覆盖主机防火墙定义。

Expand
表 6.333. 参数摘要
名称类型方向概述

激活

布尔值

in

当设置为"true"时，此主机将在安装完成后激活。

async

布尔值

in

指明是否应异步执行安装。

deploy_hosted_engine

布尔值

in

如果设置为 true，此主机也会部署自托管引擎组件。

host

主机

in

override_iptables 属性用于指示防火墙配置是否应该替换为默认配置。

image

字符串

in

安装 {hypervisor-name} 时，需要一个 ISO 镜像文件。

reboot

布尔值

in

指明是否应当在安装成功后重新启动该主机。

root_password

字符串

in

用于通过 SSH 连接到主机的 root 用户的密码。

ssh

ssh

in

用于连接主机的 SSH 详细信息。

undeploy_hosted_engine

布尔值

in

如果设置为 true，此主机将取消部署自托管引擎组件，此主机将不充当高可用性群集的一部分。

6.108.11.1. 激活
复制链接

当设置为"true"时，此主机将在安装完成后激活。当设置为"false"时，主机在安装后将保持"维护"状态。缺少此参数将解释为"true"，因为所需的默认行为是在安装后激活主机。

6.108.11.2. deploy_hosted_engine
复制链接

如果设置为 true，此主机也会部署自托管引擎组件。缺少的值被视为 true，即 deploy。省略此参数表示 假，且不会在自托管引擎区域执行任何操作。

6.108.11.3. reboot
复制链接

指明是否应当在安装成功后重新启动该主机。默认值为 true。

6.108.11.4. undeploy_hosted_engine
复制链接

如果设置为 true，此主机将取消部署自托管引擎组件，此主机将不充当高可用性群集的一部分。缺少的值被视为 true，即 un-deploy。省略此参数表示 假，且不会在自托管引擎区域执行任何操作。

6.108.12. iscsidiscover POST
复制链接

这个方法自 Engine 版本 4.4.6 起已弃用。应改为使用 DiscoverIscsi。

使用启动器详细信息，在主机上发现 iSCSI 目标。返回包含发现数据的字符串数组。

例如，要从主机 123 发现 myiscsi.example.com 中可用的 iSCSI 目标，请发送如下请求： 

POST /ovirt-engine/api/hosts/123/iscsidiscover

这样的请求正文： 

<action>
  <iscsi>
    <address>myiscsi.example.com</address>
  </iscsi>
</action>
Expand
表 6.334. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行发现。

iscsi

IscsiDetails

in

目标 iSCSI 设备。

iscsi_targets

string[]

out

iSCSI 目标.

6.108.12.1. iscsi_targets
复制链接

iSCSI 目标。*

6.108.13. iscsilogin POST
复制链接

使用目标详细信息登录到主机上的 iSCSI 目标。

重要

使用此方法登录时，您必须使用发现的目标中的 iscsi 详情会导致 discoveriscsi 方法。

Expand
表 6.335. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行登录。

iscsi

IscsiDetails

in

目标 iSCSI 设备。

6.108.14. 刷新 POST
复制链接

刷新主机设备和功能。

Expand
表 6.336. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行刷新。

6.108.15. 删除 DELETE
复制链接

从系统中删除主机。 

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"
Expand
表 6.337. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

force

布尔值

in

表示该主机应被删除，即使它不响应，或者即使它属于 Gluster 存储群集并且有卷 brick。

6.108.16. setupnetworks POST
复制链接

此方法用于更改主机网络接口的配置。

例如，如果您有一个具有三个网络接口的主机 eth0、eth1 和 eth2，并且您想要使用 eth0 和 eth 1 配置一个新绑定，并在上面放置 VLAN。使用一个简单的 shell 脚本和 curl 命令行 HTTP 客户端，可以按如下方式完成： 

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
  <modified_bonds>
    <host_nic>
      <name>bond0</name>
      <bonding>
        <options>
          <option>
            <name>mode</name>
            <value>4</value>
          </option>
          <option>
            <name>miimon</name>
            <value>100</value>
          </option>
        </options>
        <slaves>
          <host_nic>
            <name>eth1</name>
          </host_nic>
          <host_nic>
            <name>eth2</name>
          </host_nic>
        </slaves>
      </bonding>
    </host_nic>
  </modified_bonds>
  <modified_network_attachments>
    <network_attachment>
      <network>
        <name>myvlan</name>
      </network>
      <host_nic>
        <name>bond0</name>
      </host_nic>
      <ip_address_assignments>
        <ip_address_assignment>
          <assignment_method>static</assignment_method>
          <ip>
            <address>192.168.122.10</address>
            <netmask>255.255.255.0</netmask>
          </ip>
        </ip_address_assignment>
      </ip_address_assignments>
      <dns_resolver_configuration>
        <name_servers>
          <name_server>1.1.1.1</name_server>
          <name_server>2.2.2.2</name_server>
        </name_servers>
      </dns_resolver_configuration>
    </network_attachment>
  </modified_network_attachments>
 </action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"
注意

这对 API 版本 4 有效。在以前的版本中，部分元素表示为 XML 属性而不是 XML 元素。特别是，选项和 ip 元素的表示如下： 

<options name="mode" value="4"/>
<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/>

同样的操作也可使用 Python SDK 及以下代码完成： 

# Find the service that manages the collection of hosts:
hosts_service = connection.system_service().hosts_service()

# Find the host:
host = hosts_service.list(search='name=myhost')[0]

# Find the service that manages the host:
host_service = hosts_service.host_service(host.id)

# Configure the network adding a bond with two slaves and attaching it to a
# network with an static IP address:
host_service.setup_networks(
    modified_bonds=[
        types.HostNic(
            name='bond0',
            bonding=types.Bonding(
                options=[
                    types.Option(
                        name='mode',
                        value='4',
                    ),
                    types.Option(
                        name='miimon',
                        value='100',
                    ),
                ],
                slaves=[
                    types.HostNic(
                        name='eth1',
                    ),
                    types.HostNic(
                        name='eth2',
                    ),
                ],
            ),
        ),
    ],
    modified_network_attachments=[
        types.NetworkAttachment(
            network=types.Network(
                name='myvlan',
            ),
            host_nic=types.HostNic(
                name='bond0',
            ),
            ip_address_assignments=[
                types.IpAddressAssignment(
                    assignment_method=types.BootProtocol.STATIC,
                    ip=types.Ip(
                        address='192.168.122.10',
                        netmask='255.255.255.0',
                    ),
                ),
            ],
            dns_resolver_configuration=types.DnsResolverConfiguration(
                name_servers=[
                    '1.1.1.1',
                    '2.2.2.2',
                ],
            ),
        ),
    ],
)

# After modifying the network configuration it is very important to make it
# persistent:
host_service.commit_net_config()
重要

为确保网络配置已保存到主机上，并且主机重启时会应用它，请记得调用 commitnetconfig。

重要

由于 Red Hat Virtualization Manager 4.3，也可以在 setupnetworks 请求中指定 commit_on_success，在这种情况下，新配置会在完成设置并重新建立 {hypervisor-name} 和 Red Hat Virtualization Manager 之间的连接后自动保存在 {hypervisor-name} 和 Red Hat Virtualization Manager，且无需等待单独的 commitnetconfig 请求。

Expand
表 6.338. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

check_connectivity

布尔值

in

 

commit_on_success

布尔值

in

指定在完成设置并重新建立 {hypervisor-name} 和 Red Hat Virtualization Manager 之间的连接后，是否会在 {hypervisor-name} 和 Red Hat Virtualization Manager 中自动保存配置，且不会等待单独的 commitnetconfig 请求。

connectivity_timeout

整数

in

 

modified_bonds

HostNic[]

in

 

modified_labels

NetworkLabel[]

in

 

modified_network_attachments

NetworkAttachment[]

in

 

removed_bonds

HostNic[]

in

 

removed_labels

NetworkLabel[]

in

 

removed_network_attachments

NetworkAttachment[]

in

 

synchronized_network_attachments

NetworkAttachment[]

in

将同步的网络附加列表。

6.108.16.1. commit_on_success
复制链接

指定在完成设置并重新建立 {hypervisor-name} 和 Red Hat Virtualization Manager 之间的连接后，是否会在 {hypervisor-name} 和 Red Hat Virtualization Manager 中自动保存配置，且不会等待单独的 commitnetconfig 请求。默认值为 false，这意味着配置不会自动保存。

6.108.17. syncallnetworks POST
复制链接

要同步主机上的所有网络，请发送如下请求： 

POST /ovirt-engine/api/hosts/123/syncallnetworks

这样的请求正文： 

<action/>
Expand
表 6.339. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.108.18. unregisteredstoragedomainsdiscover POST
复制链接

发现要导入到设置的块存储域。对于 FCP，不需要参数。

Expand
表 6.340. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行发现。

iscsi

IscsiDetails

in

 

storage_domains

StorageDomain[]

out

 

6.108.19. 更新 PUT
复制链接

更新主机属性。

例如，更新主机的内核命令行可发送如下请求： 

PUT /ovirt-engine/api/hosts/123

借助此类请求正文： 

<host>
  <os>
    <custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
  </os>
</host>
Expand
表 6.341. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

host

主机

in/Out

 

6.108.20. 升级 POST
复制链接

升级主机上的 VDSM 和选定的软件.

Expand
表 6.342. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行升级。

image

字符串

in

此属性不再相关，因为 Vintage 节点不再被支持，并且已弃用。

reboot

布尔值

in

指明是否应在升级后重新引导该主机。

timeout

整数

in

升级超时。

6.108.20.1. reboot
复制链接

指明是否应在升级后重新引导该主机。默认情况下，将重新引导主机。

注意

{hypervisor-name} 会忽略这个参数，它总是在升级后重启。

6.108.20.2. timeout
复制链接

升级超时。

等待升级完成的最长时间（以分钟为单位）。默认值由 ANSIBLE_PLAYBOOK_EXEC_DEFAULT_TIMEOUT 配置选项指定。

6.108.21. upgradecheck POST
复制链接

检查是否有适用于主机的升级。如果有可用的升级，管理门户中主机状态图标旁边将显示一个图标。也添加了审计日志消息，以指示升级的可用性。升级可以从 webadmin 或升级主机操作启动。

6.109. HostCpuUnits
复制链接

Expand
表 6.343. 方法概述
名称概述

list

返回所有主机的 CPU 列表，其中包含关于拓扑（套接字、核心）的详细信息，以及有关当前 CPU 固定的信息。

6.109.1. 列出 GET
复制链接

返回所有主机的 CPU 列表，其中包含关于拓扑（套接字、核心）的详细信息，以及有关当前 CPU 固定的信息。

Expand
表 6.344. 参数摘要
名称类型方向概述

cpu_units

HostCpuUnit[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.109.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.110. HostDevice
复制链接

用于访问主机特定设备的服务。

Expand
表 6.345. 方法概述
名称概述

get

检索特定主机设备的信息。

6.110.1. 获取 GET
复制链接

检索特定主机设备的信息。

获取主机设备的示例： 

GET /ovirt-engine/api/hosts/123/devices/456
 
<host_device href="/ovirt-engine/api/hosts/123/devices/456" id="456">
  <name>usb_1_9_1_1_0</name>
  <capability>usb</capability>
  <host href="/ovirt-engine/api/hosts/123" id="123"/>
  <parent_device href="/ovirt-engine/api/hosts/123/devices/789" id="789">
    <name>usb_1_9_1</name>
  </parent_device>
</host_device>
Expand
表 6.346. 参数摘要
名称类型方向概述

device

HostDevice

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.110.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.111. HostDevices
复制链接

用于访问主机设备的服务。

Expand
表 6.347. 方法概述
名称概述

list

列出主机的设备。

6.111.1. 列出 GET
复制链接

列出主机的设备。

无法保证返回的设备列表的顺序。

Expand
表 6.348. 参数摘要
名称类型方向概述

devices

HostDevice[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大设备数。

6.111.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.111.1.2. Max
复制链接

设置要返回的最大设备数。如果没有指定，则返回所有设备。

6.112. HostHook
复制链接

Expand
表 6.349. 方法概述
名称概述

get

 

6.112.1. 获取 GET
复制链接

Expand
表 6.350. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

hook

Hook

out

 
6.112.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.113. HostHooks
复制链接

Expand
表 6.351. 方法概述
名称概述

list

返回为主机配置的 hook 列表。

6.113.1. 列出 GET
复制链接

返回为主机配置的 hook 列表。

返回的 hook 列表的顺序是随机的。

Expand
表 6.352. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

Hook

Hook[]

out

 

max

整数

in

设置要返回的最大 hook 数。

6.113.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.113.1.2. Max
复制链接

设置要返回的最大 hook 数。如果没有指定，则会返回所有 hook。

6.114. HostNic
复制链接

用于管理主机的网络接口的服务。

Expand
表 6.353. 方法概述
名称概述

get

 

updatevirtualfunctionsconfiguration

如果当前资源代表启用了 SR-IOV 的 NIC，则该操作会更新虚拟功能配置。

6.114.1. 获取 GET
复制链接

Expand
表 6.354. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将主机网络接口的所有属性包含在响应中。

follow

字符串

in

指明应遵循哪些内联链接。

nic

HostNic

out

 
6.114.1.1. all_content
复制链接

指明是否应将主机网络接口的所有属性包含在响应中。

默认情况下排除以下属性：

  • virtual_functions_configuration

例如，要检索主机 '123' 的完整表示网络接口 '456'： 

GET /ovirt-engine/api/hosts/123/nics/456?all_content=true
注意

这些属性默认不包含在内，因为检索它们会影响性能。它们很少使用，需要对数据库进行其他查询。谨慎使用此参数，且仅在有特殊需要时才使用。

6.114.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.114.2. 更新虚拟功能配置 POST
复制链接

如果当前资源代表启用了 SR-IOV 的 NIC，则该操作会更新虚拟功能配置。输入应至少包含以下属性之一：

  • allNetworksAllowed
  • numberOfVirtualFunctions

请参阅 HostNicVirtualFunctionsConfiguration 类型以了解属性的含义。

Expand
表 6.355. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

in

 

6.115. HostNics
复制链接

用于管理主机的网络接口的服务。

Expand
表 6.356. 方法概述
名称概述

list

返回主机的网络接口列表。

6.115.1. 列出 GET
复制链接

返回主机的网络接口列表。

无法保证返回的网络接口列表的顺序。

Expand
表 6.357. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将主机网络接口的所有属性包含在响应中。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 NIC 数。

nics

HostNic[]

out

 
6.115.1.1. all_content
复制链接

指明是否应将主机网络接口的所有属性包含在响应中。

默认情况下排除以下属性：

  • virtual_functions_configuration

例如，要检索主机 '123' 的网络接口 '456' 的完整表示法： 

GET /ovirt-engine/api/hosts/123/nics?all_content=true
注意

这些属性默认不包含在内，因为检索它们会影响性能。它们很少使用，需要对数据库进行其他查询。谨慎使用此参数，且仅在有特殊需要时才使用。

6.115.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.115.1.3. Max
复制链接

设置要返回的最大 NIC 数。如果没有指定，则会返回所有 NIC。

6.116. HostNumaNode
复制链接

Expand
表 6.358. 方法概述
名称概述

get

 

6.116.1. 获取 GET
复制链接

Expand
表 6.359. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

node

NumaNode

out

 
6.116.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.117. HostNumaNodes
复制链接

Expand
表 6.360. 方法概述
名称概述

list

返回主机的 NUMA 节点列表。

6.117.1. 列出 GET
复制链接

返回主机的 NUMA 节点列表。

NUMA 节点返回列表的顺序不受保证。

Expand
表 6.361. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大节点数。

节点

NumaNode[]

out

 
6.117.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.117.1.2. Max
复制链接

设置要返回的最大节点数。如果没有指定，则返回所有节点。

6.118. HostStorage
复制链接

用于管理主机存储的服务。

Expand
表 6.362. 方法概述
名称概述

list

获取存储列表.

6.118.1. 列出 GET
复制链接

获取存储列表. 

GET /ovirt-engine/api/hosts/123/storage

您得到的 XML 响应如下： 

<host_storages>
  <host_storage id="123">
    ...
  </host_storage>
  ...
</host_storages>

无法保证返回的存储列表的顺序。

Expand
表 6.363. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

report_status

布尔值

in

指明是否应检查存储中的 LUN 状态。

Storages

HostStorage[]

out

检索的存储列表。

6.118.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.118.1.2. report_status
复制链接

指明是否应检查存储中的 LUN 状态。检查 LUN 状态是一种重量型操作，用户并不总是需要这个数据。此参数将提供选项，使其不执行 LUN 的状态检查。

默认为 向后 兼容。

这里有一个 LUN 状态为 的示例： 

<host_storage id="123">
  <logical_units>
    <logical_unit id="123">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>123</serial>
      <size>10737418240</size>
      <status>used</status>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>123</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="123"/>
</host_storage>

这里有一个没有 LUN 状态的示例： 

<host_storage id="123">
  <logical_units>
    <logical_unit id="123">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>123</serial>
      <size>10737418240</size>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>123</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="123"/>
</host_storage>

6.119. 主机
复制链接

管理主机的服务。

Expand
表 6.364. 方法概述
名称概述

add

创建新主机.

list

获取所有可用主机的列表。

6.119.1. 添加 POST
复制链接

创建新主机.

主机基于 host 参数的属性创建。name、address 和 root_password 属性是必需的。

例如，要添加主机，请发送以下请求： 

POST /ovirt-engine/api/hosts

使用以下请求正文： 

<host>
  <name>myhost</name>
  <address>myhost.example.com</address>
  <root_password>myrootpassword</root_password>
</host>
注意

root_password 元素仅包含在客户端提供的初始表示法中，不会在从后续请求返回的表示中公开。

重要

自引擎版本 4.1.2 起，当新添加主机时，主机防火墙定义将默认被覆盖。

要添加托管引擎主机，请使用可选的 deploy_hosted_engine 参数： 

POST /ovirt-engine/api/hosts?deploy_hosted_engine=true

如果集群有一个支持自动部署的默认外部网络供应商，则在添加主机时会部署外部网络供应商。只有 OVN 的外部网络提供程序支持自动部署。要部署集群中定义的外部网络供应商，请在添加主机时覆盖外部网络供应商，请发送以下请求： 

POST /ovirt-engine/api/hosts

使用一个请求正文，其中包含对 external_network_provider_configuration 中所需提供程序的引用： 

<host>
  <name>myhost</name>
  <address>myhost.example.com</address>
  <root_password>123456</root_password>
  <external_network_provider_configurations>
    <external_network_provider_configuration>
      <external_network_provider name="ovirt-provider-ovn"/>
    </external_network_provider_configuration>
  </external_network_provider_configurations>
</host>
Expand
表 6.365. 参数摘要
名称类型方向概述

激活

布尔值

in

当设置为 true 时，此主机将在安装完成后激活。

deploy_hosted_engine

布尔值

in

当设置为 true 时，此主机将部署托管引擎组件。

host

主机

in/Out

创建新主机的主机定义作为参数传递，而新创建的主机将返回。

reboot

布尔值

in

指明是否应当在安装成功后重新启动该主机。

undeploy_hosted_engine

布尔值

in

当设置为 true 时，此主机将取消部署托管引擎组件，且不会作为高可用性集群的一部分运行。

6.119.1.1. 激活
复制链接

当设置为 true 时，此主机将在安装完成后激活。当设置为 false 时，主机安装后将保持 维护 状态。如果没有此参数，将解释为 true，因为所需的默认行为是在安装后激活主机。

6.119.1.2. deploy_hosted_engine
复制链接

当设置为 true 时，此主机将部署托管引擎组件。缺少的值被视为 true，即部署托管引擎组件。省略此参数等于 false，主机不会在托管引擎区域执行任何操作。

6.119.1.3. reboot
复制链接

指明是否应当在安装成功后重新启动该主机。默认值为 true。

6.119.1.4. undeploy_hosted_engine
复制链接

当设置为 true 时，此主机将取消部署托管引擎组件，且不会作为高可用性集群的一部分运行。缺少的值被视为 true，即 un-deploy。省略此参数等于 false，主机不会在托管引擎区域执行任何操作。

6.119.2. 列出 GET
复制链接

获取所有可用主机的列表。

例如，列出发送以下请求的主机： 

GET /ovirt-engine/api/hosts

响应正文类似如下： 

<hosts>
  <host href="/ovirt-engine/api/hosts/123" id="123">
    ...
  </host>
  <host href="/ovirt-engine/api/hosts/456" id="456">
    ...
  </host>
  ...
</host>

只有 search 参数中包含 sortby 子句时，才会保证返回的主机列表的顺序。

Expand
表 6.366. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将主机的所有属性包含在响应中。

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

check_vms_in_affinity_closure

布尔值

in

此参数可与 migration_target_of 一起使用，为列出的虚拟机和所有其他与列出的虚拟机执行密切关系的虚拟机获取有效的迁移目标。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

主机

Host[]

out

 

max

整数

in

设置要返回的最大主机数。

migration_target_of

字符串

in

接受以逗号分隔的虚拟机 ID 列表，并返回可迁移到这些虚拟机的主机。

search

字符串

in

用于限制返回的主机的查询字符串。

6.119.2.1. all_content
复制链接

指明是否应将主机的所有属性包含在响应中。

默认情况下，排除以下主机属性：

  • hosted_engine

例如，要检索主机的完整表示法： 

GET /ovirt-engine/api/hosts?all_content=true
注意

这些属性默认不包含在内，因为检索它们会影响性能。它们很少使用，需要对数据库进行其他查询。谨慎使用此参数，且仅在有特殊需要时才使用。

6.119.2.2. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.119.2.3. check_vms_in_affinity_closure
复制链接

此参数可与 migration_target_of 一起使用，为列出的虚拟机和所有其他与列出的虚拟机执行密切关系的虚拟机获取有效的迁移目标。

这在虚拟机与正关联组中的其他虚拟机一起迁移时非常有用。

默认值为 false。 

GET /ovirt-engine/api/hosts?migration_target_of=123,456&check_vms_in_affinity_closure=true
6.119.2.4. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.119.2.5. Max
复制链接

设置要返回的最大主机数。如果未指定，则返回所有主机。

6.119.2.6. migration_target_of
复制链接

接受以逗号分隔的虚拟机 ID 列表，并返回可迁移到这些虚拟机的主机。

例如，要检索 ID 为 123 的虚拟机和 ID 为 456 的虚拟机可以迁移到的主机列表，请发送以下请求： 

GET /ovirt-engine/api/hosts?migration_target_of=123,456

6.120. icon
复制链接

用于管理图标的服务（只读）。

Expand
表 6.367. 方法概述
名称概述

get

获取图标.

6.120.1. 获取 GET
复制链接

获取图标. 

GET /ovirt-engine/api/icons/123

您将获得类似以下的 XML 响应： 

<icon id="123">
  <data>Some binary data here</data>
  <media_type>image/png</media_type>
</icon>
Expand
表 6.368. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

icon

icon

out

检索图标.

6.120.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.121. icons
复制链接

用于管理图标的服务。

Expand
表 6.369. 方法概述
名称概述

list

获取图标列表.

6.121.1. 列出 GET
复制链接

获取图标列表. 

GET /ovirt-engine/api/icons

您将获得类似以下的 XML 响应： 

<icons>
  <icon id="123">
    <data>...</data>
    <media_type>image/png</media_type>
  </icon>
  ...
</icons>

无法保证返回的图标列表的顺序。

Expand
表 6.370. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

icons

Icon[]

out

检索到的图标列表.

max

整数

in

设置要返回的最大图标数。

6.121.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.121.1.2. Max
复制链接

设置要返回的最大图标数。如果没有指定，则返回所有图标。

6.122. Image
复制链接

Expand
表 6.371. 方法概述
名称概述

get

 

import

导入映像.

6.122.1. 获取 GET
复制链接

Expand
表 6.372. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

image

Image

out

 
6.122.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.122.2. 导入 POST
复制链接

导入映像.

如果 import_as_template 参数为 true，则映像将作为模板导入，否则它将作为磁盘导入。

将模板导入为模板时，可以通过可选的 template.name 参数指定模板的名称。如果未指定该参数，则引擎将自动将该模板的名称指定为 GlanceTemplate-x （其中 x 是七个随机十六进制字符）。

作为磁盘导入时，可以通过可选的 disk.name 参数指定磁盘名称。如果未指定该参数，则引擎将自动将该磁盘名称指定为 GlanceDisk-x （其中 x 将是映像标识符的七个十六进制字符）。

建议始终明确指定模板或磁盘名称，以避免引擎生成的这些自动名称。

Expand
表 6.373. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导入。

cluster

Cluster

in

如果 import_as_template 参数设为 true，则镜像应导入到的集群。

disk

Disk

in

要导入的磁盘。

import_as_template

布尔值

in

指定是否应从导入磁盘创建模板。

storage_domain

StorageDomain

in

磁盘应导入到的存储域。

模板

Template

in

如果 import_as_template 参数设为 true，则所创建的模板的名称。

6.123. ImageTransfer
复制链接

此服务提供控制镜像传输的机制。客户端必须使用 第 6.124 节 “ImageTransfers” 服务添加来创建传输，指示要在其中传输数据的镜像。

执行此操作后，转让由此服务管理。

使用 oVirt 的 Python SDK:

上传 ID 123 的磁盘 （在数据中心的随机主机上）： 

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      disk=types.Disk(
         id='123'
      )
   )
)

在 主机 ID 456 上上传 ID 123 的磁盘 ： 

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      disk=types.Disk(
         id='123'
      ),
      host=types.Host(
         id='456'
     )
   )
)

如果用户想要下载磁盘而不是上传，则应将 下载 指定为传输 的方向 属性。这将授予镜像的读取权限，而不是写入权限。

例如： 

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      disk=types.Disk(
         id='123'
      ),
      direction=types.ImageTransferDirection.DOWNLOAD
   )
)

传输具有控制上传/下载流程的阶段。实施此类流程的客户端应轮询/检查转让的阶段，并相应地操作。所有可能的阶段都可以在 ImageTransferPhase 中找到。

添加新转移后，其阶段将初始化。在转让更改之前，客户端必须轮询传输阶段。当阶段开始转移后，会话就可以开始转移。

例如： 

transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
   time.sleep(3)
   transfer = transfer_service.get()

在该阶段，如果转让的阶段是 paused_system，则无法成功建立会话。这可能是因为 ovirt-imageio-daemon 没有在选择进行传输的主机中运行。可以通过调用管理它的服务恢复传输。

如果会话成功建立 - 返回的传输实体将包含 transfer_url 和 proxy_url 属性，客户端需要使用这些属性来传输所需的数据。客户端可以选择任何技术和工具来发送带有镜像数据的 HTTPS 请求。

  • transfer_url 是其中一个虚拟机监控程序上运行的 imageio 服务器的地址。
  • proxy_url 是 imageio 代理服务器的地址，如果您无法访问 transfer_url，则可以使用该地址。

若要传输映像，建议使用 imageio 客户端 python 库。 

from ovirt_imageio import client

# Upload qcow2 image to virtual disk:
client.upload("disk.qcow2", transfer.transfer_url)

# Download virtual disk to qcow2 image:
client.download(transfer.transfer_url, "disk.qcow2")

您还可以使用 imageio REST API 上传和下载。如需了解更多相关信息，请参阅 imageio API 文档： 

http://ovirt.github.io/ovirt-imageio/images.html

完成转让后，用户应致电完成。这将为完成转移过程做出最终调整和验证。

例如： 

transfer_service.finalize()

如果出现错误，传输阶段将更改为 finished_failure，磁盘的状态将更改为 Illegal。否则，它将更改为 completed_success，磁盘将可供使用。在这两种情况下，转让实体将在后面很快删除。

使用 HTTP 和 cURL 调用：

  • 对于上传，首先创建一个新磁盘：

    • 以字节为单位指定 'initial_size' 和 'provisioned_size'。
    • 'initial_size' 必须大于或与上传数据的大小相同。 
POST /ovirt-engine/api/disks

请求正文如下： 

<disk>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <alias>mydisk</alias>
  <initial_size>1073741824</initial_size>
  <provisioned_size>1073741824</provisioned_size>
  <format>raw</format>
</disk>
  • 创建用于下载/卸载 ID 为 456 的磁盘 的新镜像传输： 
POST /ovirt-engine/api/imagetransfers

请求正文如下： 

<image_transfer>
  <disk id="456"/>
  <direction>upload|download</direction>
</image_transfer>

将响应： 

<image_transfer id="123">
  <direction>download|upload</direction>
  <phase>initializing|transferring</phase>
  <proxy_url>https://proxy_fqdn:54323/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb</proxy_url>
  <transfer_url>https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb</transfer_url>
  ...
</image_transfer>

注意：如果阶段为"初始化"，请轮询 image_transfer，直到其阶段变为"传输"。

  • 使用 'transfer_url' 或 'proxy_url' 来调用 curl 命令：
  • 使用 'transfer_url' 直接从/到 ovirt-imageio-daemon 传输，或者使用 'proxy_url' 从/ ovirt-imageio-proxy 传输。注意：使用代理可以缓解没有直接连接到守护进程计算机的情况，例如 vdsm 机器位于与引擎不同的网络中。

 -usersdownload： 

$ curl --cacert /etc/pki/ovirt-engine/ca.pem https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb -o <output_file>

 - SASupload： 

$ curl --cacert /etc/pki/ovirt-engine/ca.pem --upload-file <file_to_upload> -X PUT https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb
  • 通过调用操作来结束镜像传输： 
POST /ovirt-engine/api/imagetransfers/123/finalize

请求正文如下： 

<action />
Expand
表 6.374. 方法概述
名称概述

取消

取消镜像传输会话。

extend

扩展映像传输会话。

Finish

在完成传输数据后，完成传输。

get

获取映像传输实体。

pause

暂停映像传输会话。

resume

恢复镜像传输会话。

6.123.1. 取消 POST
复制链接

取消镜像传输会话。这会终止传输操作并移除部分镜像。

6.123.2. 扩展 POST
复制链接

扩展映像传输会话。

6.123.3. 最终 POST
复制链接

在完成传输数据后，完成传输。

这样将确保传输的数据有效，并且适合传输中的目标映像实体。具体来说，将验证映像实体是否为 QCOW 磁盘，上传的数据实际上是 QCOW 文件，并且映像没有后备文件。

6.123.4. 获取 GET
复制链接

获取映像传输实体。

Expand
表 6.375. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

image_transfer

ImageTransfer

out

 
6.123.4.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.123.5. 暂停 POST
复制链接

暂停映像传输会话。

6.123.6. 恢复 POST
复制链接

恢复镜像传输会话。客户需要轮询传输阶段，直到这与 恢复不同。例如： 

transfer_service = transfers_service.image_transfer_service(transfer.id)
transfer_service.resume()
transfer = transfer_service.get()

while transfer.phase == types.ImageTransferPhase.RESUMING:
   time.sleep(1)
   transfer = transfer_service.get()

6.124. ImageTransfers
复制链接

此服务管理镜像传输，以用于在红帽虚拟化中执行镜像 I/O API。有关更多文档，请参阅图像传送。

Expand
表 6.376. 方法概述
名称概述

add

添加新映像传输。

list

检索当前正在执行的镜像传输的列表。

6.124.1. 添加 POST
复制链接

添加新映像传输。需要指定映像、磁盘或磁盘快照才能进行新的传输。

重要

image 属性已弃用，因为引擎的版本 4.2。改为使用 disk 或 snapshot 属性。

创建用于下载或上传 磁盘 的新镜像传输：

要创建镜像传输来下载或上传 ID 为 123 的磁盘，请发送以下请求： 

POST /ovirt-engine/api/imagetransfers

这样的请求正文： 

<image_transfer>
  <disk id="123"/>
  <direction>upload|download</direction>
</image_transfer>

创建用于下载或上传 disk_snapshot 的新映像传输：

要创建映像传输来下载或上传 ID 为 456 的 disk_snapshot，请发送以下请求： 

POST /ovirt-engine/api/imagetransfers

这样的请求正文： 

<image_transfer>
  <snapshot id="456"/>
  <direction>download|upload</direction>
</image_transfer>
Expand
表 6.377. 参数摘要
名称类型方向概述

image_transfer

ImageTransfer

in/Out

要添加的镜像传输。

6.124.2. 列出 GET
复制链接

检索当前正在执行的镜像传输的列表。

返回的镜像传输列表的顺序不受保证。

Expand
表 6.378. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

image_transfer

ImageTransfer[]

out

当前正在执行的镜像传输列表。

6.124.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.125. 镜像
复制链接

管理存储域或 OpenStack 映像提供程序中可用的镜像集合。

Expand
表 6.379. 方法概述
名称概述

list

返回存储域或提供程序中可用映像的列表。

6.125.1. 列出 GET
复制链接

返回存储域或提供程序中可用映像的列表。

无法保证返回的镜像列表的顺序。

Expand
表 6.380. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

images

image[]

out

 

max

整数

in

设置要返回的最大镜像数。

6.125.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.125.1.2. Max
复制链接

设置要返回的最大镜像数。如果没有指定，则返回所有镜像。

6.126. InstanceType
复制链接

Expand
表 6.381. 方法概述
名称概述

get

获取特定实例类型及其属性。

remove

从系统移除特定的实例类型。

update

更新特定的实例类型及其属性。

6.126.1. 获取 GET
复制链接

获取特定实例类型及其属性。 

GET /ovirt-engine/api/instancetypes/123
Expand
表 6.382. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

instance_type

InstanceType

out

 
6.126.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.126.2. 删除 DELETE
复制链接

从系统移除特定的实例类型。

如果在删除实例类型后使用实例类型 X 创建虚拟机，则虚拟机的实例类型将设置为 custom。 

DELETE /ovirt-engine/api/instancetypes/123
Expand
表 6.383. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.126.3. 更新 PUT
复制链接

更新特定的实例类型及其属性。

所有属性均可在创建后编辑。如果使用实例类型 X 创建虚拟机，并且更新了实例类型 X 中的一些配置，引擎将自动更新虚拟机的配置。 

PUT /ovirt-engine/api/instancetypes/123

例如，要将实例类型 123 的内存更新为 1 GiB，并将 cpu 拓扑设置为 2 个插槽和 1 个内核，请发送类似如下的请求： 

<instance_type>
  <memory>1073741824</memory>
  <cpu>
    <topology>
      <cores>1</cores>
      <sockets>2</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
</instance_type>
Expand
表 6.384. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

instance_type

InstanceType

in/Out

 

6.127. InstanceTypeGraphicsConsole
复制链接

Expand
表 6.385. 方法概述
名称概述

get

获取实例类型的图形控制台配置。

remove

从实例类型中删除图形控制台。

6.127.1. 获取 GET
复制链接

获取实例类型的图形控制台配置。

Expand
表 6.386. 参数摘要
名称类型方向概述

console

GraphicsConsole

out

关于实例类型的图形控制台的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.127.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.127.2. 删除 DELETE
复制链接

从实例类型中删除图形控制台。

Expand
表 6.387. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.128. InstanceTypeGraphicsConsoles
复制链接

Expand
表 6.388. 方法概述
名称概述

add

向实例类型添加新的图形控制台。

list

列出实例类型的所有配置的图形控制台。

6.128.1. 添加 POST
复制链接

向实例类型添加新的图形控制台。

Expand
表 6.389. 参数摘要
名称类型方向概述

console

GraphicsConsole

in/Out

 

6.128.2. 列出 GET
复制链接

列出实例类型的所有配置的图形控制台。

无法保证返回的图形控制台列表的顺序。

Expand
表 6.390. 参数摘要
名称类型方向概述

consoles

GraphicsConsole[]

out

实例类型的图形控制台列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大控制台数。

6.128.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.128.2.2. Max
复制链接

设置要返回的最大控制台数。如果没有指定，则返回所有控制台。

6.129. InstanceTypeNic
复制链接

Expand
表 6.391. 方法概述
名称概述

get

获取实例类型的网络接口配置。

remove

从实例类型中删除网络接口。

update

更新实例类型的网络接口配置。

6.129.1. 获取 GET
复制链接

获取实例类型的网络接口配置。

Expand
表 6.392. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

nic

NIC

out

 
6.129.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.129.2. 删除 DELETE
复制链接

从实例类型中删除网络接口。

Expand
表 6.393. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.129.3. 更新 PUT
复制链接

更新实例类型的网络接口配置。

Expand
表 6.394. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

nic

NIC

in/Out

 

6.130. InstanceTypeNics
复制链接

Expand
表 6.395. 方法概述
名称概述

add

向实例类型添加新网络接口。

list

列出实例类型的所有已配置网络接口。

6.130.1. 添加 POST
复制链接

向实例类型添加新网络接口。

Expand
表 6.396. 参数摘要
名称类型方向概述

nic

NIC

in/Out

 

6.130.2. 列出 GET
复制链接

列出实例类型的所有已配置网络接口。

无法保证返回的网络接口列表的顺序。

Expand
表 6.397. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 NIC 数。

nics

Nic[]

out

 

search

字符串

in

用于限制返回的模板的查询字符串。

6.130.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.130.2.2. Max
复制链接

设置要返回的最大 NIC 数。如果没有指定，则会返回所有 NIC。

6.131. InstanceTypeWatchdog
复制链接

Expand
表 6.398. 方法概述
名称概述

get

获取实例类型的 watchdog 配置。

remove

从实例类型中删除 watchdog。

update

更新实例类型的 watchdog 配置。

6.131.1. 获取 GET
复制链接

获取实例类型的 watchdog 配置。

Expand
表 6.399. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

watchdog

Watchdog

out

 
6.131.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.131.2. 删除 DELETE
复制链接

从实例类型中删除 watchdog。

Expand
表 6.400. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.131.3. 更新 PUT
复制链接

更新实例类型的 watchdog 配置。

Expand
表 6.401. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

watchdog

Watchdog

in/Out

 

6.132. InstanceTypeWatchdogs
复制链接

Expand
表 6.402. 方法概述
名称概述

add

向实例类型添加新的 watchdog。

list

列出实例类型的所有配置的 watchdog。

6.132.1. 添加 POST
复制链接

向实例类型添加新的 watchdog。

Expand
表 6.403. 参数摘要
名称类型方向概述

watchdog

Watchdog

in/Out

 

6.132.2. 列出 GET
复制链接

列出实例类型的所有配置的 watchdog。

返回的 watchdogs 列表的顺序不受保证。

Expand
表 6.404. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 watchdogs 数。

search

字符串

in

用于限制返回的模板的查询字符串。

watchdogs

Watchdog[]

out

 
6.132.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.132.2.2. Max
复制链接

设置要返回的最大 watchdogs 数。如果未指定，则返回所有 watchdogs。

6.133. InstanceTypes
复制链接

Expand
表 6.405. 方法概述
名称概述

add

创建新的实例类型。

list

列出系统中的所有现有实例类型。

6.133.1. 添加 POST
复制链接

创建新的实例类型。

这只需要 name 属性，并且可以包含虚拟机的所有硬件配置。 

POST /ovirt-engine/api/instancetypes

这样的请求正文： 

<instance_type>
  <name>myinstancetype</name>
</template>

使用请求正文创建包含所有硬件配置的实例类型，如下方所示： 

<instance_type>
  <name>myinstancetype</name>
  <console>
    <enabled>true</enabled>
  </console>
  <cpu>
    <topology>
      <cores>2</cores>
      <sockets>2</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
  <custom_cpu_model>AMD Opteron_G2</custom_cpu_model>
  <custom_emulated_machine>q35</custom_emulated_machine>
  <display>
    <monitors>1</monitors>
    <single_qxl_pci>true</single_qxl_pci>
    <smartcard_enabled>true</smartcard_enabled>
    <type>spice</type>
  </display>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <io>
    <threads>2</threads>
  </io>
  <memory>4294967296</memory>
  <memory_policy>
    <ballooning>true</ballooning>
    <guaranteed>268435456</guaranteed>
  </memory_policy>
  <migration>
    <auto_converge>inherit</auto_converge>
    <compressed>inherit</compressed>
    <policy id="00000000-0000-0000-0000-000000000000"/>
  </migration>
  <migration_downtime>2</migration_downtime>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
  <rng_device>
    <rate>
      <bytes>200</bytes>
      <period>2</period>
    </rate>
    <source>urandom</source>
  </rng_device>
  <soundcard_enabled>true</soundcard_enabled>
  <usb>
    <enabled>true</enabled>
    <type>native</type>
  </usb>
  <virtio_scsi>
    <enabled>true</enabled>
  </virtio_scsi>
</instance_type>
Expand
表 6.406. 参数摘要
名称类型方向概述

instance_type

InstanceType

in/Out

 

6.133.2. 列出 GET
复制链接

列出系统中的所有现有实例类型。

无法保证返回的实例类型列表的顺序。

Expand
表 6.407. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

instance_type

InstanceType[]

out

 

max

整数

in

设置要返回的实例类型的最大数量。

search

字符串

in

用于限制返回的模板的查询字符串。

6.133.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.133.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.133.2.3. Max
复制链接

设置要返回的实例类型的最大数量。如果没有指定，则返回所有实例类型。

6.134. IscsiBond
复制链接

Expand
表 6.408. 方法概述
名称概述

get

 

remove

删除现有 iSCSI 绑定.

update

更新 iSCSI 绑定.

6.134.1. 获取 GET
复制链接

Expand
表 6.409. 参数摘要
名称类型方向概述

bond

IscsiBond

out

iSCSI 绑定.

follow

字符串

in

指明应遵循哪些内联链接。

6.134.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.134.2. 删除 DELETE
复制链接

删除现有 iSCSI 绑定.

例如，要删除 iSCSI 绑定 456，发送类似如下的请求： 

DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456
Expand
表 6.410. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.134.3. 更新 PUT
复制链接

更新 iSCSI 绑定.

iSCSI 绑定的更新只能在 名称和 描述 属性上完成。例如，要更新数据中心 123 的 iSCSI bond 456，请发送如下请求： 

PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234

请求正文应类似如下： 

<iscsi_bond>
   <name>mybond</name>
   <description>My iSCSI bond</description>
</iscsi_bond>
Expand
表 6.411. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

bond

IscsiBond

in/Out

要更新的 iSCSI 绑定。

6.135. IscsiBonds
复制链接

Expand
表 6.412. 方法概述
名称概述

add

在数据中心上创建新的 iSCSI 绑定。

list

返回数据中心中配置的 iSCSI 绑定列表。

6.135.1. 添加 POST
复制链接

在数据中心上创建新的 iSCSI 绑定。

例如，要使用存储连接 456 和 789 在数据中心 123 上创建新的 iSCSI 绑定，请发送如下请求： 

POST /ovirt-engine/api/datacenters/123/iscsibonds

请求正文应类似如下： 

<iscsi_bond>
  <name>mybond</name>
  <storage_connections>
    <storage_connection id="456"/>
    <storage_connection id="789"/>
  </storage_connections>
  <networks>
    <network id="abc"/>
  </networks>
</iscsi_bond>
Expand
表 6.413. 参数摘要
名称类型方向概述

bond

IscsiBond

in/Out

 

6.135.2. 列出 GET
复制链接

返回数据中心中配置的 iSCSI 绑定列表。

无法保证返回的 iSCSI 绑定列表的顺序。

Expand
表 6.414. 参数摘要
名称类型方向概述

bonds

IscsiBond[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大绑定数。

6.135.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.135.2.2. Max
复制链接

设置要返回的最大绑定数。如果没有指定所有绑定，则会返回所有绑定。

6.136. Job
复制链接

用于管理作业的服务。

Expand
表 6.415. 方法概述
名称概述

clear

设置系统要清除的外部作业执行。

end

将外部作业执行标记为结束。

get

检索作业。

6.136.1. 清除 POST
复制链接

设置系统要清除的外部作业执行。

例如，要设置标识符为 123 的作业，发送 以下请求： 

POST /ovirt-engine/api/jobs/clear

使用以下请求正文： 

<action/>
Expand
表 6.416. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.136.2. 最终 POST
复制链接

将外部作业执行标记为结束。

例如，要终止标识符为 123 的作业，发送 以下请求： 

POST /ovirt-engine/api/jobs/end

使用以下请求正文： 

<action>
  <force>true</force>
  <status>finished</status>
</action>
Expand
表 6.417. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

force

布尔值

in

指明该作业是否应该被强制终止。

succeeded

布尔值

in

表示作业应标记为成功完成或失败。

6.136.2.1. succeeded
复制链接

表示作业应标记为成功完成或失败。

此参数是可选的，默认值为 true。

6.136.3. 获取 GET
复制链接

检索作业。 

GET /ovirt-engine/api/jobs/123

您将在 XML 中收到类似以下的响应： 

<job href="/ovirt-engine/api/jobs/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
    <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
  </actions>
  <description>Adding Disk</description>
  <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
  <auto_cleared>true</auto_cleared>
  <end_time>2016-12-12T23:07:29.758+02:00</end_time>
  <external>false</external>
  <last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
  <start_time>2016-12-12T23:07:26.593+02:00</start_time>
  <status>failed</status>
  <owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Expand
表 6.418. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

job

Job

out

检索作业的表示法。

6.136.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.137. Jobs
复制链接

用于管理作业的服务。

Expand
表 6.419. 方法概述
名称概述

add

添加外部作业。

list

检索作业的表示法。

6.137.1. 添加 POST
复制链接

添加外部作业。

例如，使用以下请求添加作业： 

POST /ovirt-engine/api/jobs

使用以下请求正文： 

<job>
  <description>Doing some work</description>
  <auto_cleared>true</auto_cleared>
</job>

响应应类似于： 

<job href="/ovirt-engine/api/jobs/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
    <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
  </actions>
  <description>Doing some work</description>
  <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
  <auto_cleared>true</auto_cleared>
  <external>true</external>
  <last_updated>2016-12-13T02:15:42.130+02:00</last_updated>
  <start_time>2016-12-13T02:15:42.130+02:00</start_time>
  <status>started</status>
  <owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Expand
表 6.420. 参数摘要
名称类型方向概述

job

Job

in/Out

将添加的作业。

6.137.2. 列出 GET
复制链接

检索作业的表示法。 

GET /ovirt-engine/api/jobs

您将在 XML 中收到类似以下的响应： 

<jobs>
  <job href="/ovirt-engine/api/jobs/123" id="123">
    <actions>
      <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
      <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
    </actions>
    <description>Adding Disk</description>
    <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
    <auto_cleared>true</auto_cleared>
    <end_time>2016-12-12T23:07:29.758+02:00</end_time>
    <external>false</external>
    <last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
    <start_time>2016-12-12T23:07:26.593+02:00</start_time>
    <status>failed</status>
    <owner href="/ovirt-engine/api/users/456" id="456"/>
  </job>
  ...
</jobs>

无法保证返回的作业列表的顺序。

Expand
表 6.421. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

任务

Job[]

out

作业表示。

max

整数

in

设置要返回的最大作业数。

search

字符串

in

用于限制返回的作业的查询字符串。

6.137.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.137.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.137.2.3. Max
复制链接

设置要返回的最大作业数。如果未指定，则返回所有作业。

6.138. KatelloErrata
复制链接

用于管理 Katello 勘误表的服务。该信息是从 Katello 检索而来。

Expand
表 6.422. 方法概述
名称概述

list

检索 Katello 勘误表的表示形式。

6.138.1. 列出 GET
复制链接

检索 Katello 勘误表的表示形式。 

GET /ovirt-engine/api/katelloerrata

您将在 XML 中收到类似以下的响应： 

<katello_errata>
  <katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
    <name>RHBA-2013:XYZ</name>
    <description>The description of the erratum</description>
    <title>some bug fix update</title>
    <type>bugfix</type>
    <issued>2013-11-20T02:00:00.000+02:00</issued>
    <solution>Few guidelines regarding the solution</solution>
    <summary>Updated packages that fix one bug are now available for XYZ</summary>
    <packages>
      <package>
        <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
      </package>
      ...
    </packages>
  </katello_erratum>
  ...
</katello_errata>

返回的勘误列表的顺序无法保证。

Expand
表 6.423. 参数摘要
名称类型方向概述

勘误

KatelloErratum[]

out

Katello 勘误表的表示。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的勘误表的最大数量。

6.138.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.138.1.2. Max
复制链接

设置要返回的勘误表的最大数量。如果没有指定，则会返回所有勘误。

6.139. KatelloErratum
复制链接

用于管理 Katello 勘误的服务。

Expand
表 6.424. 方法概述
名称概述

get

检索 Katello 勘误.

6.139.1. 获取 GET
复制链接

检索 Katello 勘误. 

GET /ovirt-engine/api/katelloerrata/123

您将在 XML 中收到类似以下的响应： 

<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
  <name>RHBA-2013:XYZ</name>
  <description>The description of the erratum</description>
  <title>some bug fix update</title>
  <type>bugfix</type>
  <issued>2013-11-20T02:00:00.000+02:00</issued>
  <solution>Few guidelines regarding the solution</solution>
  <summary>Updated packages that fix one bug are now available for XYZ</summary>
  <packages>
    <package>
      <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
    </package>
    ...
  </packages>
</katello_erratum>
Expand
表 6.425. 参数摘要
名称类型方向概述

erratum

KatelloErratum

out

检索 Katello 勘误的表示形式。

follow

字符串

in

指明应遵循哪些内联链接。

6.139.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.141. MacPool
复制链接

Expand
表 6.428. 方法概述
名称概述

get

 

remove

删除 MAC 地址池。

update

更新 MAC 地址池。

6.141.1. 获取 GET
复制链接

Expand
表 6.429. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

池

MacPool

out

 
6.141.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.141.2. 删除 DELETE
复制链接

删除 MAC 地址池。

例如，要删除 ID 123 的 MAC 地址池，发送 类似如下的请求： 

DELETE /ovirt-engine/api/macpools/123
Expand
表 6.430. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.141.3. 更新 PUT
复制链接

更新 MAC 地址池。

可以更新 name、description、allow_duplicates 和 ranges 属性。

例如，更新 id 123 的 MAC 地址池可发送如下请求： 

PUT /ovirt-engine/api/macpools/123

这样的请求正文： 

<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>
Expand
表 6.431. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

池

MacPool

in/Out

 

6.142. MacPools
复制链接

Expand
表 6.432. 方法概述
名称概述

add

创建新的 MAC 地址池。

list

返回系统的 MAC 地址池列表。

6.142.1. 添加 POST
复制链接

创建新的 MAC 地址池。

创建 MAC 地址池需要 名称和 范围属性值。

例如，要创建 MAC 地址池发送如下请求： 

POST /ovirt-engine/api/macpools

这样的请求正文： 

<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>
Expand
表 6.433. 参数摘要
名称类型方向概述

池

MacPool

in/Out

 

6.142.2. 列出 GET
复制链接

返回系统的 MAC 地址池列表。

MAC 地址池返回的列表不受保证。

Expand
表 6.434. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大池数。

pools

MacPool[]

out

 
6.142.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.142.2.2. Max
复制链接

设置要返回的最大池数。如果没有指定，则返回所有池。

6.143. 可测量
复制链接

6.144. 可移动
复制链接

Expand
表 6.435. 方法概述
名称概述

Move

 

6.144.1. 移动 POST
复制链接

Expand
表 6.436. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移动。

6.145. Network
复制链接

管理网络的服务

Expand
表 6.437. 方法概述
名称概述

get

获取逻辑网络.

remove

删除逻辑网络或逻辑网络与数据中心的关联。

update

更新逻辑网络.

6.145.1. 获取 GET
复制链接

获取逻辑网络.

例如： 

GET /ovirt-engine/api/networks/123

将响应： 

<network href="/ovirt-engine/api/networks/123" id="123">
  <name>ovirtmgmt</name>
  <description>Default Management Network</description>
  <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/>
  <mtu>0</mtu>
  <stp>false</stp>
  <usages>
    <usage>vm</usage>
  </usages>
  <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</network>
Expand
表 6.438. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network

Network

out

 
6.145.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.145.2. 删除 DELETE
复制链接

删除逻辑网络或逻辑网络与数据中心的关联。

例如，要删除逻辑网络 123，发送类似如下的请求： 

DELETE /ovirt-engine/api/networks/123

每个网络都完全绑定到一个数据中心。因此，如果我们将网络与数据中心解除关联，其结果就与我们只是删除该网络一样。但是，可能更具体地指出我们删除了数据中心 123 的网络 456。

例如，要删除网络 456 到数据中心 123 的关联，请发送类似如下的请求： 

DELETE /ovirt-engine/api/datacenters/123/networks/456
注意

要移除外部逻辑网络，必须通过 OpenStack 网络 API 将网络直接从其提供程序中删除。如果为提供商启用了 auto_sync，则代表红帽虚拟化内部外部网络的实体将自动删除，否则必须使用此方法移除该实体。

Expand
表 6.439. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.145.3. 更新 PUT
复制链接

更新逻辑网络.

可以更新 name 、 description、ip、vlan、stp 和 display 属性。

例如，要更新逻辑网络 123 的描述，可发送如下请求： 

PUT /ovirt-engine/api/networks/123

这样的请求正文： 

<network>
  <description>My updated description</description>
</network>

网络的最大传输单元使用 PUT 请求来设置，以指定 mtu 属性的整数值。

例如，要设置最大传输单元会发送如下请求： 

PUT /ovirt-engine/api/datacenters/123/networks/456

这样的请求正文： 

<network>
  <mtu>1500</mtu>
</network>
注意

更新外部网络不会传播到提供程序。

Expand
表 6.440. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

network

Network

in/Out

 

6.146. NetworkAttachment
复制链接

Expand
表 6.441. 方法概述
名称概述

get

 

remove

 

update

更新主机上指定的网络附加。

6.146.1. 获取 GET
复制链接

Expand
表 6.442. 参数摘要
名称类型方向概述

Attach

NetworkAttachment

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.146.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.146.2. 删除 DELETE
复制链接

Expand
表 6.443. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.146.3. 更新 PUT
复制链接

更新主机上指定的网络附加。

Expand
表 6.444. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

Attach

NetworkAttachment

in/Out

 

6.147. NetworkAttachments
复制链接

管理主机或主机 NIC 的网络附加集合。

Expand
表 6.445. 方法概述
名称概述

add

向网络接口添加新网络附加。

list

返回主机或主机 NIC 的网络附加列表。

6.147.1. 添加 POST
复制链接

向网络接口添加新网络附加。

Expand
表 6.446. 参数摘要
名称类型方向概述

Attach

NetworkAttachment

in/Out

 

6.147.2. 列出 GET
复制链接

返回主机或主机 NIC 的网络附加列表。

网络附加列表返回的顺序不受保证。

Expand
表 6.447. 参数摘要
名称类型方向概述

附件

NetworkAttachment[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置返回的最大附件数。

6.147.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.147.2.2. Max
复制链接

设置返回的最大附件数。如果没有指定，则返回所有附件。

6.148. NetworkFilter
复制链接

管理网络过滤器。 

<network_filter id="00000019-0019-0019-0019-00000000026b">
  <name>example-network-filter-b</name>
  <version>
    <major>4</major>
    <minor>0</minor>
    <build>-1</build>
    <revision>-1</revision>
  </version>
</network_filter>

请注意，版本指的是特定过滤器的最小支持版本。

Expand
表 6.448. 方法概述
名称概述

get

检索网络过滤器的表示法。

6.148.1. 获取 GET
复制链接

检索网络过滤器的表示法。

Expand
表 6.449. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network_filter

NetworkFilter

out

 
6.148.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.149. NetworkFilters
复制链接

表示只读网络过滤器子集合。

网络过滤器允许根据定义的规则过滤发送到/从虚拟机的 nic 发送的数据包。如需更多信息，请参阅 NetworkFilter 服务文档

从版本 3.0 开始，支持网络过滤器的不同版本。

为每个 vnic 配置集定义一个网络过滤器。

为特定网络定义 vnic 配置集。

网络可以分配给多个不同的集群。未来，将在集群级别上定义每个网络。

目前，每个网络都在数据中心级别上定义。每个网络的潜在网络过滤器由网络的数据中心兼容性版本 V 决定。V 必须是 >= 网络过滤器版本，以便为特定网络配置这个网络过滤器。请注意，如果将网络分配给带有支持网络过滤器的版本的集群，则该过滤器可能会因为数据中心版本较小而不可用，然后网络过滤器的版本便不可用。

列出特定集群的所有支持的网络过滤器示例： 

GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters

输出： 

<network_filters>
  <network_filter id="00000019-0019-0019-0019-00000000026c">
    <name>example-network-filter-a</name>
    <version>
      <major>4</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
  <network_filter id="00000019-0019-0019-0019-00000000026b">
    <name>example-network-filter-b</name>
    <version>
      <major>4</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
  <network_filter id="00000019-0019-0019-0019-00000000026a">
    <name>example-network-filter-a</name>
    <version>
      <major>3</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
</network_filters>
Expand
表 6.450. 方法概述
名称概述

list

检索网络过滤器的表示法。

6.149.1. 列出 GET
复制链接

检索网络过滤器的表示法。

网络过滤器返回列表的顺序不受保证。

Expand
表 6.451. 参数摘要
名称类型方向概述

过滤器

NetworkFilter[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.149.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.150. NetworkLabel
复制链接

Expand
表 6.452. 方法概述
名称概述

get

 

remove

从逻辑网络中删除标签.

6.150.1. 获取 GET
复制链接

Expand
表 6.453. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

label

NetworkLabel

out

 
6.150.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.150.2. 删除 DELETE
复制链接

从逻辑网络中删除标签.

例如，要从 ID 为 123 的逻辑网络中删除标签 示例，发送以下请求： 

DELETE /ovirt-engine/api/networks/123/networklabels/exemplary
Expand
表 6.454. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.151. NetworkLabels
复制链接

管理附加到网络或主机 NIC 的标签ser。

Expand
表 6.455. 方法概述
名称概述

add

将标签附加到逻辑网络.

list

返回附加到网络或主机 NIC 的标签列表。

6.151.1. 添加 POST
复制链接

将标签附加到逻辑网络.

您可以将标签附加到逻辑网络，从而将该逻辑网络与已附加相同标签的物理主机网络接口自动关联。

例如，要将标签 mylabel 附加到 ID 123 的逻辑网络上，可 发送 如下所示的请求： 

POST /ovirt-engine/api/networks/123/networklabels

这样的请求正文： 

<network_label id="mylabel"/>
Expand
表 6.456. 参数摘要
名称类型方向概述

label

NetworkLabel

in/Out

 

6.151.2. 列出 GET
复制链接

返回附加到网络或主机 NIC 的标签列表。

返回的标签列表的顺序不受保证。

Expand
表 6.457. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

labels

NetworkLabel[]

out

 

max

整数

in

设置要返回的最大标签数。

6.151.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.151.2.2. Max
复制链接

设置要返回的最大标签数。如果没有指定，则返回所有标签。

6.152. 网络
复制链接

管理逻辑网络.

引擎会在安装时创建一个默认的 ovirtmgmt 网络。此网络充当访问虚拟机监控程序主机的管理网络。此网络与 Default 集群关联，是 Default 数据中心的成员。

Expand
表 6.458. 方法概述
名称概述

add

创建新的逻辑网络，或者将现有网络与数据中心相关联。

list

列出逻辑网络.

6.152.1. 添加 POST
复制链接

创建新的逻辑网络，或者将现有网络与数据中心相关联。

创建新网络需要 name 和 data _center 元素。

例如，要为数据中心创建名为 mynetwork 的网络 123 可发送如下请求： 

POST /ovirt-engine/api/networks

这样的请求正文： 

<network>
  <name>mynetwork</name>
  <data_center id="123"/>
</network>

要将现有网络 456 与数据中心 123 关联，可发送如下所示的请求： 

POST /ovirt-engine/api/datacenters/123/networks

这样的请求正文： 

<network>
  <name>ovirtmgmt</name>
</network>

要在外部 OpenStack 网络提供商 456 上创建名为 exnetwork 的网络，请发送如下请求： 

POST /ovirt-engine/api/networks
 
<network>
  <name>exnetwork</name>
  <external_provider id="456"/>
  <data_center id="123"/>
</network>
Expand
表 6.459. 参数摘要
名称类型方向概述

network

Network

in/Out

 

6.152.2. 列出 GET
复制链接

列出逻辑网络.

例如： 

GET /ovirt-engine/api/networks

将响应： 

<networks>
  <network href="/ovirt-engine/api/networks/123" id="123">
    <name>ovirtmgmt</name>
    <description>Default Management Network</description>
    <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/>
    <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/>
    <mtu>0</mtu>
    <stp>false</stp>
    <usages>
      <usage>vm</usage>
    </usages>
    <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
  </network>
  ...
</networks>

只有 search 参数中包含 sortby 子句时，才能保证返回的网络列表的顺序。

Expand
表 6.460. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

网络

network[]

out

 

search

字符串

in

用于限制返回的网络的查询字符串。

6.152.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.152.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.152.2.3. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.153. NicNetworkFilterParameter
复制链接

此服务管理网络过滤器的参数。

Expand
表 6.461. 方法概述
名称概述

get

检索网络过滤器参数表示法。

remove

删除过滤器参数。

update

更新网络过滤器参数。

6.153.1. 获取 GET
复制链接

检索网络过滤器参数表示法。

Expand
表 6.462. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

参数

NetworkFilterParameter

out

网络过滤器参数的表示。

6.153.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.153.2. 删除 DELETE
复制链接

删除过滤器参数。

例如，要删除在虚拟机 789 的 NIC 456 上 ID 123 的 filter 参数，发送类似如下的请求： 

DELETE /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123

6.153.3. 更新 PUT
复制链接

更新网络过滤器参数。

例如，要更新在虚拟机 789 的 NIC 456 上带有 id 123 的网络过滤器参数发送如下请求： 

PUT /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123

这样的请求正文： 

<network_filter_parameter>
  <name>updatedName</name>
  <value>updatedValue</value>
</network_filter_parameter>
Expand
表 6.463. 参数摘要
名称类型方向概述

参数

NetworkFilterParameter

in/Out

正在更新的网络过滤器参数。

6.154. NicNetworkFilterParameters
复制链接

此服务管理网络过滤器的一组参数。

Expand
表 6.464. 方法概述
名称概述

add

添加网络过滤器参数。

list

检索网络过滤器参数的表示法。

6.154.1. 添加 POST
复制链接

添加网络过滤器参数。

例如，要在虚拟机 789 的 NIC 456 上为网络过滤器添加 参数，发送类似如下的请求： 

POST /ovirt-engine/api/vms/789/nics/456/networkfilterparameters

这样的请求正文： 

<network_filter_parameter>
  <name>IP</name>
  <value>10.0.1.2</value>
</network_filter_parameter>
Expand
表 6.465. 参数摘要
名称类型方向概述

参数

NetworkFilterParameter

in/Out

正在添加的网络过滤器参数。

6.154.2. 列出 GET
复制链接

检索网络过滤器参数的表示法。

网络过滤器返回列表的顺序不受保证。

Expand
表 6.466. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

parameters

NetworkFilterParameter[]

out

网络过滤器参数列表。

6.154.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.155. OpenstackImage
复制链接

Expand
表 6.467. 方法概述
名称概述

get

 

import

从 Glance 映像存储域导入虚拟机。

6.155.1. 获取 GET
复制链接

Expand
表 6.468. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

image

OpenStackImage

out

 
6.155.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.155.2. 导入 POST
复制链接

从 Glance 映像存储域导入虚拟机。

例如，要从存储域导入标识符为 456 的镜像，标识符为 123，发送类似如下的请求： 

POST /ovirt-engine/api/openstackimageproviders/123/images/456/import

这样的请求正文： 

<action>
  <storage_domain>
    <name>images0</name>
  </storage_domain>
  <cluster>
    <name>images0</name>
  </cluster>
</action>
Expand
表 6.469. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导入。

cluster

Cluster

in

如果使用 import_as_template，则此参数是必需的，并指明哪个集群应用于导入 glance 镜像作为模板。

disk

Disk

in

 

import_as_template

布尔值

in

指明是否应当将映像导入为模板。

storage_domain

StorageDomain

in

 

模板

Template

in

 

6.156. OpenstackImageProvider
复制链接

Expand
表 6.470. 方法概述
名称概述

get

 

importcertificates

导入外部主机提供程序的 SSL 证书。

remove

 

testconnectivity

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。

update

更新系统中指定的 OpenStack 镜像提供程序。

6.156.1. 获取 GET
复制链接

Expand
表 6.471. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

provider

OpenStackImageProvider

out

 
6.156.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.156.2. importcertificates POST
复制链接

导入外部主机提供程序的 SSL 证书。

Expand
表 6.472. 参数摘要
名称类型方向概述

证书

certificate[]

in

 

6.156.3. 删除 DELETE
复制链接

Expand
表 6.473. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.156.4. 测试连接 POST
复制链接

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。 

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Expand
表 6.474. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行测试。

6.156.5. 更新 PUT
复制链接

更新系统中指定的 OpenStack 镜像提供程序。

Expand
表 6.475. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

provider

OpenStackImageProvider

in/Out

 

6.157. OpenstackImageProviders
复制链接

Expand
表 6.476. 方法概述
名称概述

add

向系统添加新的 OpenStack 映像提供程序。

list

返回提供程序列表。

6.157.1. 添加 POST
复制链接

向系统添加新的 OpenStack 映像提供程序。

Expand
表 6.477. 参数摘要
名称类型方向概述

provider

OpenStackImageProvider

in/Out

 

6.157.2. 列出 GET
复制链接

返回提供程序列表。

返回的供应商列表的顺序不受保证。

Expand
表 6.478. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大供应商数量。

供应商

OpenStackImageProvider[]

out

 

search

字符串

in

用于限制返回的 OpenStack 镜像提供程序的查询字符串。

6.157.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.157.2.2. Max
复制链接

设置要返回的最大供应商数量。如果没有指定，则返回所有供应商。

6.158. OpenstackImages
复制链接

Expand
表 6.479. 方法概述
名称概述

list

列出 Glance 映像存储域的映像。

6.158.1. 列出 GET
复制链接

列出 Glance 映像存储域的映像。

无法保证返回的镜像列表的顺序。

Expand
表 6.480. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

images

OpenStackImage[]

out

 

max

整数

in

设置要返回的最大镜像数。

6.158.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.158.1.2. Max
复制链接

设置要返回的最大镜像数。如果没有指定，则返回所有镜像。

6.159. OpenstackNetwork
复制链接

Expand
表 6.481. 方法概述
名称概述

get

 

import

此操作将外部网络导入到红帽虚拟化中。

6.159.1. 获取 GET
复制链接

Expand
表 6.482. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network

OpenStackNetwork

out

 
6.159.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.159.2. 导入 POST
复制链接

此操作将外部网络导入到红帽虚拟化中。网络将添加到指定的数据中心。

Expand
表 6.483. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导入。

data_center

DataCenter

in

网络要导入到的数据中心。

6.159.2.1. data_center
复制链接

网络要导入到的数据中心。数据中心是必需的，可使用 id 或 name 属性指定。将忽略其余属性。

注意

如果为供应商启用了 auto_sync，则网络可能会自动导入。要防止这种情况，可以通过将 auto_sync 设置为 false 来禁用自动导入，并在导入网络后再次启用它。

6.160. OpenstackNetworkProvider
复制链接

此服务管理 OpenStack 网络提供程序。

Expand
表 6.484. 方法概述
名称概述

get

返回此服务管理的对象表示法。

importcertificates

导入外部主机提供程序的 SSL 证书。

remove

删除供应商。

testconnectivity

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。

update

更新提供程序。

6.160.1. 获取 GET
复制链接

返回此服务管理的对象表示法。

例如，要获取标识符为 1234 的 OpenStack 网络提供程序，请发送如下请求： 

GET /ovirt-engine/api/openstacknetworkproviders/1234
Expand
表 6.485. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

provider

OpenStackNetworkProvider

out

 
6.160.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.160.2. importcertificates POST
复制链接

导入外部主机提供程序的 SSL 证书。

Expand
表 6.486. 参数摘要
名称类型方向概述

证书

certificate[]

in

 

6.160.3. 删除 DELETE
复制链接

删除供应商。

例如，要删除带有标识符 1234 的 OpenStack 网络提供程序，请发送类似如下的请求： 

DELETE /ovirt-engine/api/openstacknetworkproviders/1234
Expand
表 6.487. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.160.4. 测试连接 POST
复制链接

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。 

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Expand
表 6.488. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行测试。

6.160.5. 更新 PUT
复制链接

更新提供程序。

例如，要更新 provider_name、Requires_authentication、url、tenant_name 和 type 属性，请向带有标识符 1234 的 OpenStack 网络供应商发送如下请求： 

PUT /ovirt-engine/api/openstacknetworkproviders/1234

这样的请求正文： 

<openstack_network_provider>
  <name>ovn-network-provider</name>
  <requires_authentication>false</requires_authentication>
  <url>http://some_server_url.domain.com:9696</url>
  <tenant_name>oVirt</tenant_name>
  <type>external</type>
</openstack_network_provider>
Expand
表 6.489. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

provider

OpenStackNetworkProvider

in/Out

要更新的供应商。

6.161. OpenstackNetworkProviders
复制链接

此服务管理 OpenStack 网络提供程序。

Expand
表 6.490. 方法概述
名称概述

add

该操作向系统添加新的网络提供程序。

list

返回提供程序列表。

6.161.1. 添加 POST
复制链接

该操作向系统添加新的网络提供程序。如果 类型 属性不存在，将使用默认值 NEUTRON。

Expand
表 6.491. 参数摘要
名称类型方向概述

provider

OpenStackNetworkProvider

in/Out

 

6.161.2. 列出 GET
复制链接

返回提供程序列表。

返回的供应商列表的顺序不受保证。

Expand
表 6.492. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大供应商数量。

供应商

OpenStackNetworkProvider[]

out

 

search

字符串

in

用于限制返回的 OpenStack 网络提供程序的查询字符串。

6.161.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.161.2.2. Max
复制链接

设置要返回的最大供应商数量。如果没有指定，则返回所有供应商。

6.162. OpenstackNetworks
复制链接

Expand
表 6.493. 方法概述
名称概述

list

返回网络列表。

6.162.1. 列出 GET
复制链接

返回网络列表。

网络返回列表的顺序无法保证。

Expand
表 6.494. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

网络

OpenStackNetwork[]

out

 
6.162.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.162.1.2. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.163. OpenstackSubnet
复制链接

Expand
表 6.495. 方法概述
名称概述

get

 

remove

 

6.163.1. 获取 GET
复制链接

Expand
表 6.496. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

subnet

OpenStackSubnet

out

 
6.163.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.163.2. 删除 DELETE
复制链接

Expand
表 6.497. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.164. OpenstackSubnets
复制链接

Expand
表 6.498. 方法概述
名称概述

add

 

list

返回子网列表。

6.164.1. 添加 POST
复制链接

Expand
表 6.499. 参数摘要
名称类型方向概述

subnet

OpenStackSubnet

in/Out

 

6.164.2. 列出 GET
复制链接

返回子网列表。

返回的子网列表的顺序不受保证。

Expand
表 6.500. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大子网数。

子网

OpenStackSubnet[]

out

 
6.164.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.164.2.2. Max
复制链接

设置要返回的最大子网数。如果没有指定，则返回所有子网。

6.165. OpenstackVolumeAuthenticationKey
复制链接

OpenStack 卷(Cinder)集成已被 Managed Block Storage 替代。

Expand
表 6.501. 方法概述
名称概述

get

 

remove

 

update

更新指定的身份验证密钥。

6.165.1. 获取 GET
复制链接

Expand
表 6.502. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

key

OpenstackVolumeAuthenticationKey

out

 
6.165.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.165.2. 删除 DELETE
复制链接

Expand
表 6.503. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.165.3. 更新 PUT
复制链接

更新指定的身份验证密钥。

Expand
表 6.504. 参数摘要
名称类型方向概述

key

OpenstackVolumeAuthenticationKey

in/Out

 

6.166. OpenstackVolumeAuthenticationKeys
复制链接

OpenStack 卷(Cinder)集成已被 Managed Block Storage 替代。

Expand
表 6.505. 方法概述
名称概述

add

添加新的身份验证密钥到 OpenStack 卷提供程序。

list

返回身份验证密钥列表。

6.166.1. 添加 POST
复制链接

添加新的身份验证密钥到 OpenStack 卷提供程序。

Expand
表 6.506. 参数摘要
名称类型方向概述

key

OpenstackVolumeAuthenticationKey

in/Out

 

6.166.2. 列出 GET
复制链接

返回身份验证密钥列表。

身份验证密钥返回列表的顺序不保证。

Expand
表 6.507. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

Keys

OpenstackVolumeAuthenticationKey[]

out

 

max

整数

in

设置要返回的最大密钥数。

6.166.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.166.2.2. Max
复制链接

设置要返回的最大密钥数。如果没有指定，则返回所有键。

6.167. OpenstackVolumeProvider
复制链接

OpenStack 卷(Cinder)集成已被 Managed Block Storage 替代。

Expand
表 6.508. 方法概述
名称概述

get

 

importcertificates

导入外部主机提供程序的 SSL 证书。

remove

 

testconnectivity

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。

update

更新系统中指定的 OpenStack 卷提供程序。

6.167.1. 获取 GET
复制链接

Expand
表 6.509. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

provider

OpenStackVolumeProvider

out

 
6.167.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.167.2. importcertificates POST
复制链接

导入外部主机提供程序的 SSL 证书。

Expand
表 6.510. 参数摘要
名称类型方向概述

证书

certificate[]

in

 

6.167.3. 删除 DELETE
复制链接

Expand
表 6.511. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

force

布尔值

in

指明操作是否应该成功，并且供应商从数据库中删除，即使操作期间出现问题。

6.167.3.1. force
复制链接

指明操作是否应该成功，并且供应商从数据库中删除，即使操作期间出现问题。

此参数是可选的，默认值为 false。

6.167.4. 测试连接 POST
复制链接

为了测试外部提供程序的连接性，我们需要运行以下请求，其中 123 是提供程序的 ID。 

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Expand
表 6.512. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行测试。

6.167.5. 更新 PUT
复制链接

更新系统中指定的 OpenStack 卷提供程序。

Expand
表 6.513. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

provider

OpenStackVolumeProvider

in/Out

 

6.168. OpenstackVolumeProviders
复制链接

OpenStack 卷(Cinder)集成已被 Managed Block Storage 替代。

Expand
表 6.514. 方法概述
名称概述

add

添加新卷提供程序。

list

检索卷提供程序的列表。

6.168.1. 添加 POST
复制链接

添加新卷提供程序。

例如： 

POST /ovirt-engine/api/openstackvolumeproviders

这样的请求正文： 

<openstack_volume_provider>
  <name>mycinder</name>
  <url>https://mycinder.example.com:8776</url>
  <data_center>
    <name>mydc</name>
  </data_center>
  <requires_authentication>true</requires_authentication>
  <username>admin</username>
  <password>mypassword</password>
  <tenant_name>mytenant</tenant_name>
</openstack_volume_provider>
Expand
表 6.515. 参数摘要
名称类型方向概述

provider

OpenStackVolumeProvider

in/Out

 

6.168.2. 列出 GET
复制链接

检索卷提供程序的列表。

无法保证返回的卷提供程序列表的顺序。

Expand
表 6.516. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大供应商数量。

供应商

OpenStackVolumeProvider[]

out

 

search

字符串

in

用于限制返回的卷提供程序的查询字符串。

6.168.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.168.2.2. Max
复制链接

设置要返回的最大供应商数量。如果没有指定，则返回所有供应商。

6.169. OpenstackVolumeType
复制链接

OpenStack 卷(Cinder)集成已被 Managed Block Storage 替代。

Expand
表 6.517. 方法概述
名称概述

get

 

6.169.1. 获取 GET
复制链接

Expand
表 6.518. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

type

OpenStackVolumeType

out

 
6.169.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.170. OpenstackVolumeTypes
复制链接

OpenStack 卷(Cinder)集成已被 Managed Block Storage 替代。

Expand
表 6.519. 方法概述
名称概述

list

返回卷类型列表。

6.170.1. 列出 GET
复制链接

返回卷类型列表。

无法保证返回的卷类型列表的顺序。

Expand
表 6.520. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大卷类型数。

类型

OpenStackVolumeType[]

out

 
6.170.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.170.1.2. Max
复制链接

设置要返回的最大卷类型数。如果没有指定，则返回所有卷类型。

6.171. OperatingSystem
复制链接

Expand
表 6.521. 方法概述
名称概述

get

 

6.171.1. 获取 GET
复制链接

Expand
表 6.522. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

operating_system

OperatingSystemInfo

out

 
6.171.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.172. OperatingSystems
复制链接

管理系统中可用的操作系统集合。

Expand
表 6.523. 方法概述
名称概述

list

返回系统中可用操作系统类型的列表。

6.172.1. 列出 GET
复制链接

返回系统中可用操作系统类型的列表。

无法保证返回的操作系统列表的顺序。

Expand
表 6.524. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

operating_system

OperatingSystemInfo[]

out

 
6.172.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.172.1.2. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.173. 权限
复制链接

Expand
表 6.525. 方法概述
名称概述

get

 

remove

 

6.173.1. 获取 GET
复制链接

Expand
表 6.526. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

权限

权限

out

 
6.173.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.173.2. 删除 DELETE
复制链接

Expand
表 6.527. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.174. Allow
复制链接

用于管理该角色特定权限的服务。

Expand
表 6.528. 方法概述
名称概述

get

获取有关角色允许的信息。

remove

从角色中删除允许。

6.174.1. 获取 GET
复制链接

获取有关角色允许的信息。

例如，要检索有关角色 ID 为 456 的允许信息，id 123 会发送如下请求： 

GET /ovirt-engine/api/roles/123/permits/456
 
<permit href="/ovirt-engine/api/roles/123/permits/456" id="456">
  <name>change_vm_cd</name>
  <administrative>false</administrative>
  <role href="/ovirt-engine/api/roles/123" id="123"/>
</permit>
Expand
表 6.529. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

permit

Allow

out

角色的允许。

6.174.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.174.2. 删除 DELETE
复制链接

从角色中删除允许。

例如，要从 id 123 角色中删除 id 456 的允许，可发送类似如下的请求： 

DELETE /ovirt-engine/api/roles/123/permits/456
Expand
表 6.530. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.175. Allow
复制链接

表示允许特定角色的子集合。

Expand
表 6.531. 方法概述
名称概述

add

向角色添加允许。

list

列出角色允许。

6.175.1. 添加 POST
复制链接

向角色添加允许。允许名称可以从 第 6.45 节 “ClusterLevels” 服务检索。

例如，要将允许 create_vm 分配给具有 id 123 的角色，可发送如下所示的请求： 

POST /ovirt-engine/api/roles/123/permits

这样的请求正文： 

<permit>
  <name>create_vm</name>
</permit>
Expand
表 6.532. 参数摘要
名称类型方向概述

permit

Allow

in/Out

要添加的允许.

6.175.2. 列出 GET
复制链接

列出角色允许。

例如，使用 id 123 列出角色允许，发送类似如下的请求： 

GET /ovirt-engine/api/roles/123/permits
 
<permits>
  <permit href="/ovirt-engine/api/roles/123/permits/5" id="5">
    <name>change_vm_cd</name>
    <administrative>false</administrative>
    <role href="/ovirt-engine/api/roles/123" id="123"/>
  </permit>
  <permit href="/ovirt-engine/api/roles/123/permits/7" id="7">
    <name>connect_to_vm</name>
    <administrative>false</administrative>
    <role href="/ovirt-engine/api/roles/123" id="123"/>
  </permit>
</permits>

无法保证返回的许可列表的顺序。

Expand
表 6.533. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置返回的最大允许数。

Allow

Permit[]

out

允许列表.

6.175.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.175.2.2. Max
复制链接

设置返回的最大允许数。如果没有指定，则返回所有允许。

6.176. QoS
复制链接

Expand
表 6.534. 方法概述
名称概述

get

在数据中心中获取指定的 QoS。

remove

从数据中心移除指定的 QoS。

update

更新 dataCenter 中指定的 QoS。

6.176.1. 获取 GET
复制链接

在数据中心中获取指定的 QoS。 

GET /ovirt-engine/api/datacenters/123/qoss/123

您将获得如下响应： 

<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123">
  <name>123</name>
  <description>123</description>
  <max_iops>1</max_iops>
  <max_throughput>1</max_throughput>
  <type>storage</type>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
</qos>
Expand
表 6.535. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

qos

QoS

out

查询的 QoS 对象。

6.176.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.176.2. 删除 DELETE
复制链接

从数据中心移除指定的 QoS。 

DELETE /ovirt-engine/api/datacenters/123/qoss/123
Expand
表 6.536. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.176.3. 更新 PUT
复制链接

更新 dataCenter 中指定的 QoS。 

PUT /ovirt-engine/api/datacenters/123/qoss/123

例如，使用 curl： 

curl -u admin@internal:123456 -X PUT -H "content-type: application/xml" -d \
"<qos><name>321</name><description>321</description><max_iops>10</max_iops></qos>" \
https://engine/ovirt-engine/api/datacenters/123/qoss/123

您将收到如下响应： 

<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123">
  <name>321</name>
  <description>321</description>
  <max_iops>10</max_iops>
  <max_throughput>1</max_throughput>
  <type>storage</type>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
</qos>
Expand
表 6.537. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

qos

QoS

in/Out

更新了 QoS 对象。

6.177. Qoss
复制链接

管理数据中心中可用的一组服务质量配置。

Expand
表 6.538. 方法概述
名称概述

add

向 dataCenter 添加新 QoS。

list

返回数据中心中可用的服务质量配置列表。

6.177.1. 添加 POST
复制链接

向 dataCenter 添加新 QoS。 

POST /ovirt-engine/api/datacenters/123/qoss

回复方式如下： 

<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123">
  <name>123</name>
  <description>123</description>
  <max_iops>10</max_iops>
  <type>storage</type>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
</qos>
Expand
表 6.539. 参数摘要
名称类型方向概述

qos

QoS

in/Out

添加了 QoS 对象。

6.177.2. 列出 GET
复制链接

返回数据中心中可用的服务质量配置列表。 

GET /ovirt-engine/api/datacenter/123/qoss

您将获得类似如下的响应： 

<qoss>
  <qos href="/ovirt-engine/api/datacenters/123/qoss/1" id="1">...</qos>
  <qos href="/ovirt-engine/api/datacenters/123/qoss/2" id="2">...</qos>
  <qos href="/ovirt-engine/api/datacenters/123/qoss/3" id="3">...</qos>
</qoss>

返回的服务质量配置列表无法保证。

Expand
表 6.540. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 QoS 描述符数。

qoss

Qos[]

out

查询的 QoS 对象列表。

6.177.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.177.2.2. Max
复制链接

设置要返回的最大 QoS 描述符数。如果没有指定，则会返回所有描述符。

6.178. Quota
复制链接

Expand
表 6.541. 方法概述
名称概述

get

检索配额.

remove

删除配额.

update

更新配额.

6.178.1. 获取 GET
复制链接

检索配额.

获取配额的示例： 

GET /ovirt-engine/api/datacenters/123/quotas/456
 
<quota id="456">
  <name>myquota</name>
  <description>My new quota for virtual machines</description>
  <cluster_hard_limit_pct>20</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>80</cluster_soft_limit_pct>
  <storage_hard_limit_pct>20</storage_hard_limit_pct>
  <storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>
Expand
表 6.542. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

quota

Quota

out

 
6.178.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.178.2. 删除 DELETE
复制链接

删除配额.

删除配额的示例： 

DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321
-0472718ab224 HTTP/1.1
Accept: application/xml
Content-type: application/xml
Expand
表 6.543. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.178.3. 更新 PUT
复制链接

更新配额.

更新配额的示例： 

PUT /ovirt-engine/api/datacenters/123/quotas/456
 
<quota>
  <cluster_hard_limit_pct>30</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>70</cluster_soft_limit_pct>
  <storage_hard_limit_pct>20</storage_hard_limit_pct>
  <storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>
Expand
表 6.544. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

quota

Quota

in/Out

 

6.179. QuotaClusterLimit
复制链接

Expand
表 6.545. 方法概述
名称概述

get

 

remove

 

6.179.1. 获取 GET
复制链接

Expand
表 6.546. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

limit

QuotaClusterLimit

out

 
6.179.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.179.2. 删除 DELETE
复制链接

Expand
表 6.547. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.180. QuotaClusterLimits
复制链接

管理为集群配置的配额限值集合。

Expand
表 6.548. 方法概述
名称概述

add

将集群限制添加到指定的配额。

list

返回为集群配置的配额限值集合。

6.180.1. 添加 POST
复制链接

将集群限制添加到指定的配额。

Expand
表 6.549. 参数摘要
名称类型方向概述

limit

QuotaClusterLimit

in/Out

 

6.180.2. 列出 GET
复制链接

返回为集群配置的配额限值集合。

返回的配额限制列表不受保证。

Expand
表 6.550. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

limits

QuotaClusterLimit[]

out

 

max

整数

in

设置返回的最大限值数。

6.180.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.180.2.2. Max
复制链接

设置返回的最大限值数。如果没有指定，则会返回所有限制。

6.181. QuotaStorageLimit
复制链接

Expand
表 6.551. 方法概述
名称概述

get

 

remove

 

6.181.1. 获取 GET
复制链接

Expand
表 6.552. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

limit

QuotaStorageLimit

out

 
6.181.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.181.2. 删除 DELETE
复制链接

Expand
表 6.553. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

6.182. QuotaStorageLimits
复制链接

管理为配额配置的存储限值集合。

Expand
表 6.554. 方法概述
名称概述

add

为指定的配额添加存储限制。

list

返回为配额配置的存储限值列表。

6.182.1. 添加 POST
复制链接

为指定的配额添加存储限制。

要为数据中心中的所有存储域创建 100GiB 存储限值，请发送如下请求： 

POST /ovirt-engine/api/datacenters/123/quotas/456/quotastoragelimits

这样的请求正文： 

<quota_storage_limit>
  <limit>100</limit>
</quota_storage_limit>

要为 ID 为 000 的存储域创建 50GiB 存储限值，请发送如下请求： 

POST /ovirt-engine/api/datacenters/123/quotas/456/quotastoragelimits

这样的请求正文： 

<quota_storage_limit>
  <limit>50</limit>
  <storage_domain id="000"/>
</quota_storage_limit>
Expand
表 6.555. 参数摘要
名称类型方向概述

limit

QuotaStorageLimit

in/Out

 

6.182.2. 列出 GET
复制链接

返回为配额配置的存储限值列表。

无法保证返回的存储限值列表的顺序。

Expand
表 6.556. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

limits

QuotaStorageLimit[]

out

 

max

整数

in

设置返回的最大限值数。

6.182.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.182.2.2. Max
复制链接

设置返回的最大限值数。如果没有指定，则会返回所有限制。

6.183. 配额
复制链接

管理为数据中心配置的一组配额。

Expand
表 6.557. 方法概述
名称概述

add

创建新配额.

list

列出数据中心的配额.

6.183.1. 添加 POST
复制链接

创建新配额.

创建新配额的示例： 

POST /ovirt-engine/api/datacenters/123/quotas
 
<quota>
  <name>myquota</name>
  <description>My new quota for virtual machines</description>
</quota>
Expand
表 6.558. 参数摘要
名称类型方向概述

quota

Quota

in/Out

 

6.183.2. 列出 GET
复制链接

列出数据中心的配额.

无法保证返回的配额列表的顺序。

Expand
表 6.559. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大配额描述符数。

quotas

Quota[]

out

 
6.183.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.183.2.2. Max
复制链接

设置要返回的最大配额描述符数。如果没有指定，则会返回所有描述符。

6.184. 角色
复制链接

Expand
表 6.560. 方法概述
名称概述

get

获取角色.

remove

删除角色。

update

更新角色.

6.184.1. 获取 GET
复制链接

获取角色. 

GET /ovirt-engine/api/roles/123

您将收到类似以下的 XML 响应： 

<role id="123">
  <name>MyRole</name>
  <description>MyRole description</description>
  <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
  <administrative>true</administrative>
  <mutable>false</mutable>
</role>
Expand
表 6.561. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

role

角色

out

检索的角色.

6.184.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.184.2. 删除 DELETE
复制链接

删除角色。

要删除需要知道其 ID 的角色，然后发送类似如下的请求： 

DELETE /ovirt-engine/api/roles/{role_id}
Expand
表 6.562. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.184.3. 更新 PUT
复制链接

更新角色.您可以在角色创建后更新 名称 、 描述 和管理属性。在此端点中，您不能添加或删除角色，因此您需要使用管理角色允许的服务。

例如，要更新角色 的名称，描述 和管理 属性 会发送类似如下的请求： 

PUT /ovirt-engine/api/roles/123

这样的请求正文： 

<role>
  <name>MyNewRoleName</name>
  <description>My new description of the role</description>
  <administrative>true</administrative>
</group>
Expand
表 6.563. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

role

角色

in/Out

更新的角色.

6.185. 角色
复制链接

提供对全局角色集的只读访问权限

Expand
表 6.564. 方法概述
名称概述

add

创建新角色。

list

列出角色.

6.185.1. 添加 POST
复制链接

创建新角色。该角色可以是管理或非管理员角色，可以具有不同的许可。

例如，要将 MyRole 非管理员角色添加到 允许登录并创建虚拟机发送类似此请求（请注意，您必须传递允许 ID）： 

POST /ovirt-engine/api/roles

这样的请求正文： 

<role>
  <name>MyRole</name>
  <description>My custom role to create virtual machines</description>
  <administrative>false</administrative>
  <permits>
    <permit id="1"/>
    <permit id="1300"/>
  </permits>
</group>
Expand
表 6.565. 参数摘要
名称类型方向概述

role

角色

in/Out

将添加的角色.

6.185.2. 列出 GET
复制链接

列出角色. 

GET /ovirt-engine/api/roles

您将在 XML 中收到类似以下的响应： 

<roles>
  <role id="123">
     <name>SuperUser</name>
     <description>Roles management administrator</description>
     <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
     <administrative>true</administrative>
     <mutable>false</mutable>
  </role>
  ...
</roles>

无法保证返回的角色列表的顺序。

Expand
表 6.566. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的角色的最大数量。

角色

role[]

out

检索的角色列表.

6.185.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.185.2.2. Max
复制链接

设置要返回的角色的最大数量。如果未指定，则返回所有角色。

6.186. SchedulingPolicies
复制链接

管理系统中可用的一组调度策略。

Expand
表 6.567. 方法概述
名称概述

add

向系统添加新调度策略。

list

返回系统中可用的调度策略列表。

6.186.1. 添加 POST
复制链接

向系统添加新调度策略。

Expand
表 6.568. 参数摘要
名称类型方向概述

policy

SchedulingPolicy

in/Out

 

6.186.2. 列出 GET
复制链接

返回系统中可用的调度策略列表。

无法保证返回的调度策略列表的顺序。

Expand
表 6.569. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的策略的最大数量。

policies

SchedulingPolicy[]

out

 
6.186.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.186.2.2. Max
复制链接

设置要返回的策略的最大数量。如果没有指定，则返回所有策略。

6.187. SchedulingPolicy
复制链接

Expand
表 6.570. 方法概述
名称概述

get

 

remove

 

update

更新系统中指定的用户定义的调度策略。

6.187.1. 获取 GET
复制链接

Expand
表 6.571. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

policy

SchedulingPolicy

out

 
6.187.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.187.2. 删除 DELETE
复制链接

Expand
表 6.572. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.187.3. 更新 PUT
复制链接

更新系统中指定的用户定义的调度策略。

Expand
表 6.573. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

policy

SchedulingPolicy

in/Out

 

6.188. SchedulingPolicyUnit
复制链接

Expand
表 6.574. 方法概述
名称概述

get

 

remove

 

6.188.1. 获取 GET
复制链接

Expand
表 6.575. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

unit

SchedulingPolicyUnit

out

 
6.188.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.188.2. 删除 DELETE
复制链接

Expand
表 6.576. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.189. SchedulingPolicyUnits
复制链接

管理系统中可用的一组调度策略单元。

Expand
表 6.577. 方法概述
名称概述

list

返回系统中可用的调度策略单元列表。

6.189.1. 列出 GET
复制链接

返回系统中可用的调度策略单元列表。

无法保证返回的调度策略单元列表的顺序。

Expand
表 6.578. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大策略单元数。

unit

SchedulingPolicyUnit[]

out

 
6.189.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.189.1.2. Max
复制链接

设置要返回的最大策略单元数。如果没有指定，则返回所有策略单元。

6.190. snapshot
复制链接

Expand
表 6.579. 方法概述
名称概述

get

 

remove

 

restore

恢复虚拟机快照.

6.190.1. 获取 GET
复制链接

Expand
表 6.580. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

snapshot

snapshot

out

 
6.190.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.190.2. 删除 DELETE
复制链接

Expand
表 6.581. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将虚拟机快照的所有属性包含在响应中。

async

布尔值

in

指明是否应异步执行移除。

6.190.2.1. all_content
复制链接

指明是否应将虚拟机快照的所有属性包含在响应中。

默认情况下，排除属性 initialization.configuration.data。

例如，要检索 ID 为 456 且 ID 为 123 的虚拟机的快照的完整表示形式，发送如下请求： 

GET /ovirt-engine/api/vms/123/snapshots/456?all_content=true

6.190.3. 恢复 POST
复制链接

恢复虚拟机快照.

例如，要恢复带有标识符 456 的虚拟机的快照，并使用标识符 123 发送类似如下的请求： 

POST /ovirt-engine/api/vms/123/snapshots/456/restore

在正文中有一个空 操作 ： 

<action/>
注意

确认提交操作已完成，并且虚拟机已停机，然后运行虚拟机。

Expand
表 6.582. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行恢复。

磁盘

disk[]

in

指定快照恢复中包含的磁盘。

restore_memory

布尔值

in

 
6.190.3.1. 磁盘
复制链接

指定快照恢复中包含的磁盘。

对于每个磁盘参数，还需要指定其 image_id。

例如，要恢复具有标识符 123 （包括标识符为 111 ）和 image_id 为 222 的虚拟机的标识符 456 的快照 ， 请发送如下请求： 

POST /ovirt-engine/api/vms/123/snapshots/456/restore

请求正文： 

<action>
  <disks>
    <disk id="111">
      <image_id>222</image_id>
    </disk>
  </disks>
</action>

6.191. SnapshotCdrom
复制链接

Expand
表 6.583. 方法概述
名称概述

get

 

6.191.1. 获取 GET
复制链接

Expand
表 6.584. 参数摘要
名称类型方向概述

cdrom

cdrom

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.191.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.192. SnapshotCdroms
复制链接

管理虚拟机快照的 CD-ROM 设备集合。

Expand
表 6.585. 方法概述
名称概述

list

返回快照的 CD-ROM 设备列表。

6.192.1. 列出 GET
复制链接

返回快照的 CD-ROM 设备列表。

CD-ROM 设备返回列表的顺序不受保证。

Expand
表 6.586. 参数摘要
名称类型方向概述

cdroms

Cdrom[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 CDROMS 数。

6.192.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.192.1.2. Max
复制链接

设置要返回的最大 CDROMS 数。如果没有指定所有 CDROMS，则会返回。

6.193. SnapshotDisk
复制链接

Expand
表 6.587. 方法概述
名称概述

get

 

6.193.1. 获取 GET
复制链接

Expand
表 6.588. 参数摘要
名称类型方向概述

disk

Disk

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.193.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.194. SnapshotDisks
复制链接

管理快照的磁盘集合。

Expand
表 6.589. 方法概述
名称概述

list

返回快照的磁盘列表。

6.194.1. 列出 GET
复制链接

返回快照的磁盘列表。

无法保证返回的磁盘列表的顺序。

Expand
表 6.590. 参数摘要
名称类型方向概述

磁盘

disk[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

6.194.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.194.1.2. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.195. SnapshotNic
复制链接

Expand
表 6.591. 方法概述
名称概述

get

 

6.195.1. 获取 GET
复制链接

Expand
表 6.592. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

nic

NIC

out

 
6.195.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.196. SnapshotNics
复制链接

管理快照的一组 NIC。

Expand
表 6.593. 方法概述
名称概述

list

返回快照的 NIC 列表。

6.196.1. 列出 GET
复制链接

返回快照的 NIC 列表。

NIC 返回列表的顺序不受保证。

Expand
表 6.594. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 NIC 数。

nics

Nic[]

out

 
6.196.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.196.1.2. Max
复制链接

设置要返回的最大 NIC 数。如果没有指定，则会返回所有 NIC。

6.197. 快照
复制链接

管理存储域或虚拟机的一组快照。

Expand
表 6.595. 方法概述
名称概述

add

创建虚拟机快照.

list

返回存储域或虚拟机的快照列表。

6.197.1. 添加 POST
复制链接

创建虚拟机快照.

例如，要为虚拟机创建新快照 123 发送如下请求： 

POST /ovirt-engine/api/vms/123/snapshots

这样的请求正文： 

<snapshot>
  <description>My snapshot</description>
</snapshot>

对于仅将一组磁盘包含在快照中，请将 disk_attachments 元素添加到请求正文。请注意，在 disk_attachments 元素中未指定的磁盘将不属于快照的一部分。如果传递了空的 disk_attachments 元素，快照将仅包含虚拟机配置。如果没有传递 disk_attachments 元素，则所有磁盘都将包含在快照中。

对于每个磁盘，可以指定 image_id 元素来设置新的活动镜像 ID。这是为了从备份中恢复镜像链。i. 在恢复具有快照的磁盘时，应当为每个快照指定相关的 image_id （因此磁盘快照的标识符与备份相同）。 

<snapshot>
  <description>My snapshot</description>
  <disk_attachments>
    <disk_attachment>
      <disk id="123">
        <image_id>456</image_id>
      </disk>
    </disk_attachment>
  </disk_attachments>
</snapshot>
重要

创建快照时，persistent _memorystate 属性的默认值为 true。这意味着虚拟机的内存内容将包含在快照中，这也意味着虚拟机将暂停更长时间。这可能会对对计时非常敏感的应用程序（例如，NTP 服务器）造成负面影响。在这些情况下，请确保将属性设置为 false ： 

<snapshot>
  <description>My snapshot</description>
  <persist_memorystate>false</persist_memorystate>
</snapshot>
Expand
表 6.596. 参数摘要
名称类型方向概述

snapshot

snapshot

in/Out

 

6.197.2. 列出 GET
复制链接

返回存储域或虚拟机的快照列表。

快照返回列表的顺序无法保证。

Expand
表 6.597. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将虚拟机快照的所有属性包含在响应中。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的快照的最大数量。

snapshots

Snapshot[]

out

 
6.197.2.1. all_content
复制链接

指明是否应将虚拟机快照的所有属性包含在响应中。

默认情况下，排除属性 initialization.configuration.data。

例如，要检索 ID 123 快照的虚拟机的完整表示法，发送如下请求： 

GET /ovirt-engine/api/vms/123/snapshots?all_content=true
6.197.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.197.2.3. Max
复制链接

设置要返回的快照的最大数量。如果没有指定，则返回所有快照。

6.198. SshPublicKey
复制链接

Expand
表 6.598. 方法概述
名称概述

get

 

remove

 

update

使用新资源替换密钥。

6.198.1. 获取 GET
复制链接

Expand
表 6.599. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

key

SshPublicKey

out

 
6.198.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.198.2. 删除 DELETE
复制链接

Expand
表 6.600. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.198.3. 更新 PUT
复制链接

使用新资源替换密钥。

重要

因为引擎的 4.4.8 版本已弃用，并只保留向后兼容。以后会将其移除。请使用 DELETE 后跟 添加操作。

Expand
表 6.601. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

key

SshPublicKey

in/Out

 

6.199. SshPublicKeys
复制链接

Expand
表 6.602. 方法概述
名称概述

add

 

list

返回用户的 SSH 公钥列表。

6.199.1. 添加 POST
复制链接

Expand
表 6.603. 参数摘要
名称类型方向概述

key

SshPublicKey

in/Out

 

6.199.2. 列出 GET
复制链接

返回用户的 SSH 公钥列表。

例如，要检索标识符为 123 的 SSH 密钥列表，发送类似如下的请求： 

GET /ovirt-engine/api/users/123/sshpublickeys

其结果将是以下 XML 文档： 

<ssh_public_keys>
  <ssh_public_key href="/ovirt-engine/api/users/123/sshpublickeys/456" id="456">
    <content>ssh-rsa ...</content>
    <user href="/ovirt-engine/api/users/123" id="123"/>
  </ssh_public_key>
</ssh_public_keys>

或以下 JSON 对象 

{
  "ssh_public_key": [
    {
      "content": "ssh-rsa ...",
      "user": {
        "href": "/ovirt-engine/api/users/123",
        "id": "123"
      },
      "href": "/ovirt-engine/api/users/123/sshpublickeys/456",
      "id": "456"
    }
  ]
}

无法保证返回的密钥列表的顺序。

Expand
表 6.604. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

Keys

SshPublicKey[]

out

 

max

整数

in

设置要返回的最大密钥数。

6.199.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.199.2.2. Max
复制链接

设置要返回的最大密钥数。如果没有指定，则返回所有键。

6.200. 统计
复制链接

Expand
表 6.605. 方法概述
名称概述

get

 

6.200.1. 获取 GET
复制链接

Expand
表 6.606. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

statistic

统计

out

 
6.200.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.201. statistics
复制链接

Expand
表 6.607. 方法概述
名称概述

list

检索统计数据列表。

6.201.1. 列出 GET
复制链接

检索统计数据列表。

例如，要检索虚拟机 123 的统计信息，发送如下请求： 

GET /ovirt-engine/api/vms/123/statistics

结果如下： 

<statistics>
  <statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">
    <name>memory.installed</name>
    <description>Total memory configured</description>
    <kind>gauge</kind>
    <type>integer</type>
    <unit>bytes</unit>
    <values>
      <value>
        <datum>1073741824</datum>
      </value>
    </values>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </statistic>
  ...
</statistics>

可以通过在 URI 末尾指定其 ID 来检索统计的单个部分。这意味着： 

GET /ovirt-engine/api/vms/123/statistics/456

outputs: 

<statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">
  <name>memory.installed</name>
  <description>Total memory configured</description>
  <kind>gauge</kind>
  <type>integer</type>
  <unit>bytes</unit>
  <values>
    <value>
      <datum>1073741824</datum>
    </value>
  </values>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</statistic>

返回的统计数据列表的顺序无法保证。

Expand
表 6.608. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大统计数据数。

statistics

Statistic[]

out

 
6.201.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.201.1.2. Max
复制链接

设置要返回的最大统计数据数。如果没有指定，则返回所有统计信息。

6.202. 步骤
复制链接

用于管理步骤的服务。

Expand
表 6.609. 方法概述
名称概述

end

将外部步骤执行标记为结束。

get

检索步骤.

6.202.1. 最终 POST
复制链接

将外部步骤执行标记为结束。

例如，要终止标识符 456 的步骤，该步骤属于标识符为 123 的作业，发送 以下请求： 

POST /ovirt-engine/api/jobs/123/steps/456/end

使用以下请求正文： 

<action>
  <force>true</force>
  <succeeded>true</succeeded>
</action>
Expand
表 6.610. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

force

布尔值

in

指明是否应该强制终止该步骤。

succeeded

布尔值

in

表示该步骤应标记为成功完成还是失败。

6.202.1.1. succeeded
复制链接

表示该步骤应标记为成功完成还是失败。

此参数是可选的，默认值为 true。

6.202.2. 获取 GET
复制链接

检索步骤. 

GET /ovirt-engine/api/jobs/123/steps/456

您将在 XML 中收到类似以下的响应： 

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
  </actions>
  <description>Validating</description>
  <end_time>2016-12-12T23:07:26.627+02:00</end_time>
  <external>false</external>
  <number>0</number>
  <start_time>2016-12-12T23:07:26.605+02:00</start_time>
  <status>finished</status>
  <type>validating</type>
  <job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
Expand
表 6.611. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

步骤

步骤

out

检索步骤表示法。

6.202.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.203. 步骤
复制链接

用于管理步骤的服务。

Expand
表 6.612. 方法概述
名称概述

add

向现有作业或现有步骤中添加外部步骤。

list

检索步骤的表示法。

6.203.1. 添加 POST
复制链接

向现有作业或现有步骤中添加外部步骤。

例如，要为带有标识符 123 的作业 添加步骤，发送以下请求： 

POST /ovirt-engine/api/jobs/123/steps

使用以下请求正文： 

<step>
  <description>Validating</description>
  <start_time>2016-12-12T23:07:26.605+02:00</start_time>
  <status>started</status>
  <type>validating</type>
</step>

响应应类似于： 

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
  </actions>
  <description>Validating</description>
  <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/>
  <external>true</external>
  <number>2</number>
  <start_time>2016-12-13T01:06:15.380+02:00</start_time>
  <status>started</status>
  <type>validating</type>
  <job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
Expand
表 6.613. 参数摘要
名称类型方向概述

步骤

步骤

in/Out

将要添加的步骤.

6.203.2. 列出 GET
复制链接

检索步骤的表示法。 

GET /ovirt-engine/api/job/123/steps

您将在 XML 中收到类似以下的响应： 

<steps>
  <step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
    <actions>
      <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
    </actions>
    <description>Validating</description>
    <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/>
    <external>true</external>
    <number>2</number>
    <start_time>2016-12-13T01:06:15.380+02:00</start_time>
    <status>started</status>
    <type>validating</type>
    <job href="/ovirt-engine/api/jobs/123" id="123"/>
  </step>
  ...
</steps>

返回的步骤列表的顺序无法保证。

Expand
表 6.614. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置返回的最大步骤数。

步骤

第[] 步

out

步骤的表示。

6.203.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.203.2.2. Max
复制链接

设置返回的最大步骤数。如果没有指定，则返回所有步骤。

6.204. 存储
复制链接

Expand
表 6.615. 方法概述
名称概述

get

 

6.204.1. 获取 GET
复制链接

Expand
表 6.616. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

report_status

布尔值

in

指明是否应检查存储中的 LUN 状态。

storage

HostStorage

out

 
6.204.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.204.1.2. report_status
复制链接

指明是否应检查存储中的 LUN 状态。检查 LUN 状态是一种重量型操作，用户并不总是需要这个数据。此参数将提供选项，使其不执行 LUN 的状态检查。

默认为 向后 兼容。

这里有一个 LUN 状态为 的示例： 

<host_storage id="360014051136c20574f743bdbd28177fd">
  <logical_units>
    <logical_unit id="360014051136c20574f743bdbd28177fd">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial>
      <size>10737418240</size>
      <status>used</status>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/>
</host_storage>

这里有一个没有 LUN 状态的示例： 

<host_storage id="360014051136c20574f743bdbd28177fd">
  <logical_units>
    <logical_unit id="360014051136c20574f743bdbd28177fd">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial>
      <size>10737418240</size>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/>
</host_storage>

6.205. StorageDomain
复制链接

Expand
表 6.617. 方法概述
名称概述

get

检索存储域的描述。

isattached

用于查询存储域是否已通过 is_attached 布尔值字段连接到数据中心，该字段是存储服务器的一部分。

reduceluns

此操作可减少存储域中的逻辑单元。

refreshluns

此操作会刷新 LUN 大小。

remove

删除存储域.

update

更新存储域.

updateovfstore

此操作会强制更新此存储域的 OVF_STORE。

6.205.1. 获取 GET
复制链接

检索存储域的描述。

Expand
表 6.618. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

storage_domain

StorageDomain

out

存储域的描述。

6.205.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.205.2. 附加 POST
复制链接

用于查询存储域是否已通过 is_attached 布尔值字段连接到数据中心，该字段是存储服务器的一部分。重要信息：执行此 API 将会导致主机断开与存储域的连接。

Expand
表 6.619. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

host

主机

in

表示数据中心的主机。

is_attached

布尔值

out

指明存储域是否已附加到数据中心。

6.205.3. 减少luns POST
复制链接

此操作可减少存储域中的逻辑单元。

为此，存储在提供的逻辑单元上的数据将移到存储域的其他逻辑单元中，然后才会从存储域中减少。

例如，要从存储域减少两个逻辑单元，发送如下请求： 

POST /ovirt-engine/api/storageDomains/123/reduceluns

这样的请求正文： 

 <action>
   <logical_units>
     <logical_unit id="1IET_00010001"/>
     <logical_unit id="1IET_00010002"/>
   </logical_units>
 </action>
 
Note that this operation is only applicable to block storage domains (i.e., storage domains with the
<<types/storage_type, storage type> of iSCSI or FCP).
Expand
表 6.620. 参数摘要
名称类型方向概述

logical_units

LogicalUnit[]

in

需要从存储域中减少的逻辑单元。

6.205.4. refreshluns POST
复制链接

此操作会刷新 LUN 大小。

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

例如，要刷新两个 LUN 的大小，可发送如下请求： 

POST /ovirt-engine/api/storageDomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns

这样的请求正文： 

 <action>
   <logical_units>
     <logical_unit id="1IET_00010001"/>
     <logical_unit id="1IET_00010002"/>
   </logical_units>
 </action>
Expand
表 6.621. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行刷新。

logical_units

LogicalUnit[]

in

需要刷新的 LUN。

6.205.5. 删除 DELETE
复制链接

删除存储域.

若无任何特殊参数，存储域将从系统分离并从数据库中删除。然后，存储域可以导入到同一或不同的设置中，其中含有所有数据。如果无法访问存储，则操作会失败。

如果 destroy 参数为 true，那么操作将始终成功，即使存储无法访问，其故障只是被忽略，存储域也会从数据库中删除。

如果 format 参数为 true，则将格式化实际存储，并将元数据从 LUN 或目录中移除，因此无法再导入到同一设置或另一设置中。

Expand
表 6.622. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

destroy

布尔值

in

指明操作是否应该成功，并且存储域已从数据库中删除，即使该存储无法访问。

format

布尔值

in

指明是否应格式化实际存储，从底层 LUN 或目录中删除所有元数据：

[source] ---- DELETE /ovirt-engine/api/storageDomains/123?format=true ----

此参数是可选的，默认值为 false。

host

字符串

in

指明应使用哪个主机来删除存储域。

6.205.5.1. destroy
复制链接

指明操作是否应该成功，并且存储域已从数据库中删除，即使该存储无法访问。 

DELETE /ovirt-engine/api/storageDomains/123?destroy=true

此参数是可选的，默认值为 false。当 destroy 值为 true 时，host 参数将被忽略。

6.205.5.2. 主机
复制链接

指明应使用哪个主机来删除存储域。

此参数是必需的，除非包含 destroy 参数且其值为 true，这时将忽略 主机 参数。

该值应包含主机的名称或标识符。例如，使用名为 myhost 的主机删除带有标识符 123 的存储域，发送类似如下的请求： 

DELETE /ovirt-engine/api/storageDomains/123?host=myhost

6.205.6. 更新 PUT
复制链接

更新存储域.

并非所有 StorageDomain 的属性在创建后都是 updatable。可以更新的有 名称、描述、注释、warning_low_space_indicator、critical_space_action_blocker 和 wipe_after_delete。（请注意，更改 wipe_after_delete 属性不会在删除已存在的磁盘属性后更改擦除。）

要更新带有标识符 123 的存储域 的名称和 wipe_after_delete 属性，请发送请求，如下所示： 

PUT /ovirt-engine/api/storageDomains/123

请求正文如下： 

<storage_domain>
  <name>data2</name>
  <wipe_after_delete>true</wipe_after_delete>
</storage_domain>
Expand
表 6.623. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

storage_domain

StorageDomain

in/Out

更新的存储域.

6.205.7. updateovfstore POST
复制链接

此操作会强制更新此存储域的 OVF_STORE。

OVF_STORE 是一个磁盘映像，包含驻留在存储域中的虚拟机和磁盘的元数据。如果域是从其他数据中心或其他数据中心导入或导出的，则使用此元数据。

默认情况下，会定期更新 OVF_STORE （默认设置为 60 分钟），但用户可能需要在重要更改后或认为 OVF_STORE 损坏时强制更新更新。

当用户启动时，无论是否需要更新，都将执行 OVF_STORE 更新。

Expand
表 6.624. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行 OVF_STORE 更新。

6.206. StorageDomainContentDisk
复制链接

Expand
表 6.625. 方法概述
名称概述

get

 

6.206.1. 获取 GET
复制链接

Expand
表 6.626. 参数摘要
名称类型方向概述

disk

Disk

out

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

6.206.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.207. StorageDomainContentDisks
复制链接

管理存储域中可用的磁盘集合。

Expand
表 6.627. 方法概述
名称概述

list

返回存储域中可用磁盘的列表。

6.207.1. 列出 GET
复制链接

返回存储域中可用磁盘的列表。

只有 search 参数中包含 sortby 子句时，才会保证返回的磁盘列表的顺序。

Expand
表 6.628. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

磁盘

disk[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

search

字符串

in

用于限制返回的磁盘的查询字符串。

6.207.1.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.207.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.207.1.3. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.208. StorageDomainDisk
复制链接

管理存储域中可用的单个磁盘。

重要

由于引擎版本 4.2 旨在仅列出存储域中可用的磁盘，并注册未注册的磁盘。所有其他操作（如复制磁盘、移动磁盘等）已被弃用，并将在以后的中删除。要执行这些操作，请使用管理系统所有磁盘的服务 ，或者使用管理特定磁盘的服务。

Expand
表 6.629. 方法概述
名称概述

copy

将磁盘复制到指定的存储域.

export

将磁盘导出到导出存储域.

get

检索磁盘的描述。

Move

将磁盘移动到其他存储域.

减少

减少磁盘镜像的大小。

remove

删除磁盘.

sparsify

稀疏磁盘。

update

更新磁盘.

6.208.1. 复制 POST
复制链接

将磁盘复制到指定的存储域.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要复制磁盘，请使用管理该磁盘的服务的副本操作。

Expand
表 6.630. 参数摘要
名称类型方向概述

disk

Disk

in

生成磁盘的描述。

storage_domain

StorageDomain

in

创建新磁盘的存储域。

6.208.2. 导出 POST
复制链接

将磁盘导出到导出存储域.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。若要导出磁盘，可使用管理该磁盘的服务的导出操作。

Expand
表 6.631. 参数摘要
名称类型方向概述

storage_domain

StorageDomain

in

磁盘应导出到的导出存储域。

6.208.3. 获取 GET
复制链接

检索磁盘的描述。

Expand
表 6.632. 参数摘要
名称类型方向概述

disk

Disk

out

磁盘的描述。

follow

字符串

in

指明应遵循哪些内联链接。

6.208.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.208.4. 移动 POST
复制链接

将磁盘移动到其他存储域.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要移动磁盘，请使用管理该磁盘的服务的移动操作。

Expand
表 6.633. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移动。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

storage_domain

StorageDomain

in

磁盘将移动到的存储域。

6.208.5. 减少 POST
复制链接

减少磁盘镜像的大小。

在逻辑卷中调用 less（即，这仅适用于块存储域）。这适用于附加到未运行虚拟机的浮动磁盘和磁盘。无需指定大小，因为会自动计算最佳大小。

Expand
表 6.634. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.208.6. 删除 DELETE
复制链接

删除磁盘.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要删除磁盘，请使用管理该磁盘的服务的 remove 操作。

6.208.7. 稀疏 POST
复制链接

稀疏磁盘。

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。要删除磁盘，请使用管理该磁盘的服务的 remove 操作。

6.208.8. 更新 PUT
复制链接

更新磁盘.

重要

由于引擎版本 4.2 已被弃用，并只保留此版本以向后兼容性。以后会将其移除。若要更新磁盘，可使用管理该磁盘的服务的更新操作。

Expand
表 6.635. 参数摘要
名称类型方向概述

disk

Disk

in/Out

应用到磁盘的更新。

6.209. StorageDomainDisks
复制链接

管理特定存储域中可用的磁盘集合。

Expand
表 6.636. 方法概述
名称概述

add

添加或注册磁盘。

list

检索存储域中可用的磁盘的列表。

6.209.1. 添加 POST
复制链接

添加或注册磁盘。

重要

自 Red Hat Virtualization Manager 版本 4.2 起，此操作已弃用，仅用于向后兼容。以后会将其移除。要添加新磁盘，请使用管理系统磁盘的服务的 add 操作。要注册一个未注册的磁盘，请使用管理该磁盘的服务注册操作。

Expand
表 6.637. 参数摘要
名称类型方向概述

disk

Disk

in/Out

要添加或注册的磁盘。

unregistered

布尔值

in

指明是否应添加新磁盘，或者是否应注册现有的未注册磁盘。

6.209.1.1. unregistered
复制链接

指明是否应添加新磁盘，或者是否应注册现有的未注册磁盘。如果值为 true，则需要提供要注册的磁盘标识符。例如，要使用 ID 456 注册磁盘，请发送类似如下的请求： 

POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true

这样的请求正文： 

<disk id="456"/>

如果值为 false，则会在存储域中创建新磁盘。在这种情况下，provisioning _size、格式和 name 属性是必需的。例如：要在 1 GiB 的写入磁盘上创建新副本，请发送如下请求： 

POST /ovirt-engine/api/storagedomains/123/disks

这样的请求正文： 

<disk>
  <name>mydisk</name>
  <format>cow</format>
  <provisioned_size>1073741824</provisioned_size>
</disk>

默认值为 false。

从 Red Hat Virtualization Manager 的版本 4.2 开始，这个参数已弃用。

6.209.2. 列出 GET
复制链接

检索存储域中可用的磁盘的列表。

无法保证返回的磁盘列表的顺序。

Expand
表 6.638. 参数摘要
名称类型方向概述

磁盘

disk[]

out

检索的磁盘列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

unregistered

布尔值

in

指明是否检索存储域中已注册或未注册磁盘的列表。

6.209.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.209.2.2. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.209.2.3. unregistered
复制链接

指明是否检索存储域中已注册或未注册磁盘的列表。要获得存储域中未注册磁盘的列表，调用应指示未注册的标志。例如，要获得未注册磁盘的列表，REST API 调用应如下所示： 

GET /ovirt-engine/api/storagedomains/123/disks?unregistered=true

unregistered 标志的默认值为 false。请求仅适用于附加的存储域。

6.210. StorageDomainServerConnection
复制链接

Expand
表 6.639. 方法概述
名称概述

get

 

remove

将存储连接从存储分离。

6.210.1. 获取 GET
复制链接

Expand
表 6.640. 参数摘要
名称类型方向概述

连接

StorageConnection

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.210.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.210.2. 删除 DELETE
复制链接

将存储连接从存储分离。

Expand
表 6.641. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.211. StorageDomainServerConnections
复制链接

管理与存储域中存在的存储服务器的连接集合。

Expand
表 6.642. 方法概述
名称概述

add

 

list

将连接列表返回到存储域中存在的存储服务器。

6.211.1. 添加 POST
复制链接

Expand
表 6.643. 参数摘要
名称类型方向概述

连接

StorageConnection

in/Out

 

6.211.2. 列出 GET
复制链接

将连接列表返回到存储域中存在的存储服务器。

无法保证返回的连接列表的顺序。

Expand
表 6.644. 参数摘要
名称类型方向概述

连接

StorageConnection[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大连接数。

6.211.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.211.2.2. Max
复制链接

设置要返回的最大连接数。如果未指定，则返回所有连接。

6.212. StorageDomainTemplate
复制链接

Expand
表 6.645. 方法概述
名称概述

get

 

import

从导出存储域导入模板的操作。

Register

注册模板意味着要通过将模板和磁盘的配置插入到数据库中而无需复制过程来从数据域导入模板。

remove

 

6.212.1. 获取 GET
复制链接

Expand
表 6.646. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

模板

Template

out

 
6.212.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.212.2. 导入 POST
复制链接

从导出存储域导入模板的操作。

例如，要从存储域 123 导入模板 456，发送以下请求： 

POST /ovirt-engine/api/storagedomains/123/templates/456/import

使用以下请求正文： 

<action>
  <storage_domain>
    <name>myexport</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
</action>

如果您在没有指定集群 ID 或名称的情况下注册实体，将使用来自实体 OVF 的集群名称（除非注册请求也包含集群映射）。

Expand
表 6.647. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导入。

clone

布尔值

in

使用可选的 clone 参数为导入模板及其实体生成新 UUID。

cluster

Cluster

in

 

专用

布尔值

in

 

storage_domain

StorageDomain

in

 

模板

Template

in

 

vm

VM

in

 
6.212.2.1. clone
复制链接

使用可选的 clone 参数为导入模板及其实体生成新 UUID。

从导出域导入模板时，您可以使用不同 Red Hat Virtualization 环境导出的模板导入 克隆 参数设置为 false。

6.212.3. 注册 POST
复制链接

注册模板意味着要通过将模板和磁盘的配置插入到数据库中而无需复制过程来从数据域导入模板。

Expand
表 6.648. 参数摘要
名称类型方向概述

allow_partial_import

布尔值

in

指明是否只允许使用其中一些磁盘注册模板。

async

布尔值

in

指明是否应异步执行注册。

clone

布尔值

in

 

cluster

Cluster

in

 

专用

布尔值

in

 

registration_configuration

RegistrationConfiguration

in

此参数描述了模板的注册方式。

模板

Template

in

 

vnic_profile_mappings

VnicProfileMapping[]

in

弃用了将在导入\register 过程中应用的虚拟 NIC 配置集的映射规则的属性。

6.212.3.1. allow_partial_import
复制链接

指明是否只允许使用其中一些磁盘注册模板。

如果此标志为 true，则系统在未找到映像时不会在验证过程中失败，而是允许在不缺少磁盘的情况下注册模板。这主要用于注册模板时，当某些存储域不可用时。默认值为 false。

6.212.3.2. registration_configuration
复制链接

此参数描述了模板的注册方式。

这个参数是可选的。如果未指定 参数，则模板将使用在创建它的原始环境中具有的相同配置进行注册。

6.212.3.3. vnic_profile_mappings
复制链接

弃用了将在导入\register 过程中应用的虚拟 NIC 配置集的映射规则的属性。

警告

请注意，此属性自引擎版本 4.2.1 起已弃用，仅用于向后兼容。以后会将其移除。要指定 vnic_profile_mappings，请使用 RegistrationConfiguration 类型内的 vnic_profile_mappings 属性。

6.212.4. 删除 DELETE
复制链接

Expand
表 6.649. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.213. StorageDomainTemplates
复制链接

管理存储域中可用的一组模板。

Expand
表 6.650. 方法概述
名称概述

list

返回存储域中可用模板的列表。

6.213.1. 列出 GET
复制链接

返回存储域中可用模板的列表。

返回的模板列表的顺序无法保证。

Expand
表 6.651. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的模板的最大数量。

templates

template[]

out

 

unregistered

布尔值

in

指明要检索已注册或未注册的模板列表，这些模板是否包含存储域中的磁盘。

6.213.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.213.1.2. Max
复制链接

设置要返回的模板的最大数量。如果没有指定，则会返回所有模板。

6.213.1.3. unregistered
复制链接

指明要检索已注册或未注册的模板列表，这些模板是否包含存储域中的磁盘。要获得未注册模板的列表，调用应指示未注册的标志。例如，要获得未注册模板的列表，REST API 调用应如下所示： 

GET /ovirt-engine/api/storagedomains/123/templates?unregistered=true

unregisterd 标志的默认值为 false。请求仅适用于附加的存储域。

6.214. StorageDomainVm
复制链接

Expand
表 6.652. 方法概述
名称概述

get

 

import

从导出存储域导入虚拟机.

Register

 

remove

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

6.214.1. 获取 GET
复制链接

Expand
表 6.653. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

vm

VM

out

 
6.214.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.214.2. 导入 POST
复制链接

从导出存储域导入虚拟机.

例如，发送如下请求： 

POST /ovirt-engine/api/storagedomains/123/vms/456/import

这样的请求正文： 

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
</action>

要将虚拟机导入为新实体，请添加 clone 参数： 

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
  <clone>true</clone>
  <vm>
    <name>myvm</name>
  </vm>
</action>

包含可选的 disk 参数，以选择要导入的磁盘。例如，要导入具有标识符 123 和 456 的模板磁盘，发送以下请求正文： 

<action>
  <cluster>
    <name>mycluster</name>
  </cluster>
  <vm>
    <name>myvm</name>
  </vm>
  <disks>
    <disk id="123"/>
    <disk id="456"/>
  </disks>
</action>

如果您在没有指定集群 ID 或名称的情况下注册实体，将使用来自实体 OVF 的集群名称（除非注册请求也包含集群映射）。

Expand
表 6.654. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导入。

clone

布尔值

in

指明是否应重新生成导入虚拟机的标识符。

cluster

Cluster

in

 

collapse_snapshots

布尔值

in

表示导入的虚拟机的快照应折叠，以便结果为没有快照的虚拟机。

专用

布尔值

in

 

storage_domain

StorageDomain

in

 

vm

VM

in

 
6.214.2.1. clone
复制链接

指明是否应重新生成导入虚拟机的标识符。

默认情况下，导入虚拟机时会保留标识符。这意味着同一虚拟机不能多次导入，因为该标识符需要是唯一的。要允许导入同一台机器多次将此参数设置为 true，因为默认值为 false。

6.214.2.2. collapse_snapshots
复制链接

表示导入的虚拟机的快照应折叠，以便结果为没有快照的虚拟机。

这个参数是可选的，如果没有显式指定，则默认值为 false。

6.214.3. 注册 POST
复制链接

Expand
表 6.655. 参数摘要
名称类型方向概述

allow_partial_import

布尔值

in

指明是否只允许虚拟机注册到其中一些磁盘。

async

布尔值

in

指明是否应异步执行注册。

clone

布尔值

in

 

cluster

Cluster

in

 

reassign_bad_macs

布尔值

in

指明引擎是否应当在导入过程中重新分配有问题的 MAC 地址。

registration_configuration

RegistrationConfiguration

in

此参数描述了虚拟机应如何注册。

vm

VM

in

 

vnic_profile_mappings

VnicProfileMapping[]

in

弃用了将在导入\register 过程中应用的虚拟 NIC 配置集的映射规则的属性。

6.214.3.1. allow_partial_import
复制链接

指明是否只允许虚拟机注册到其中一些磁盘。

如果此标志为 true，则如果未找到映像，引擎不会在验证过程中失败，而是允许在不缺少磁盘的情况下注册虚拟机。这主要用于注册虚拟机，当某些存储域不可用时。默认值为 false。

6.214.3.2. reassign_bad_macs
复制链接

指明引擎是否应当在导入过程中重新分配有问题的 MAC 地址。

如果以下地址为 true，则 MAC 地址将被视为有问题的地址：

  • 它与已在目标环境中分配给虚拟机的 MAC 地址冲突。
  • 它不在目标 MAC 地址池的范围。
6.214.3.3. registration_configuration
复制链接

此参数描述了虚拟机应如何注册。

这个参数是可选的。如果未指定 参数，虚拟机将使用创建它的原始环境中相同的配置进行注册。

6.214.3.4. vnic_profile_mappings
复制链接

弃用了将在导入\register 过程中应用的虚拟 NIC 配置集的映射规则的属性。

警告

请注意，此属性自引擎版本 4.2.1 起已弃用，仅用于向后兼容。以后会将其移除。要指定 vnic_profile_mappings，请使用 RegistrationConfiguration 类型内的 vnic_profile_mappings 属性。

6.214.4. 删除 DELETE
复制链接

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

例如，要从存储域 123 中删除虚拟机 456，请发送类似如下的请求： 

DELETE /ovirt-engine/api/storagedomains/123/vms/456
Expand
表 6.656. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.215. StorageDomainVmDiskAttachment
复制链接

返回附加到导出域中虚拟机的虚拟机的磁盘详情。

Expand
表 6.657. 方法概述
名称概述

get

返回附件的详细信息及其所有属性以及磁盘的链接。

6.215.1. 获取 GET
复制链接

返回附件的详细信息及其所有属性以及磁盘的链接。

Expand
表 6.658. 参数摘要
名称类型方向概述

Attach

DiskAttachment

out

磁盘附加。

follow

字符串

in

指明应遵循哪些内联链接。

6.215.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.216. StorageDomainVmDiskAttachments
复制链接

返回附加到导出域中虚拟机的磁盘的详细信息。

Expand
表 6.659. 方法概述
名称概述

list

列出附加到虚拟机的磁盘。

6.216.1. 列出 GET
复制链接

列出附加到虚拟机的磁盘。

无法保证返回的磁盘附件列表的顺序。

Expand
表 6.660. 参数摘要
名称类型方向概述

附件

DiskAttachment[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.216.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.217. StorageDomainVms
复制链接

列出导出存储域的虚拟机.

例如，要检索存储域中可用且标识符为 123 的虚拟机，发送以下请求： 

GET /ovirt-engine/api/storagedomains/123/vms

这将返回以下响应正文： 

<vms>
  <vm id="456" href="/api/storagedomains/123/vms/456">
    <name>vm1</name>
    ...
    <storage_domain id="123" href="/api/storagedomains/123"/>
    <actions>
      <link rel="import" href="/api/storagedomains/123/vms/456/import"/>
    </actions>
  </vm>
</vms>

这些集合中的虚拟机和模板与顶级 Vm 和模板集合中的对应方表示相似，但它们还包含 StorageDomain 参考和 导入操作。

Expand
表 6.661. 方法概述
名称概述

list

返回导出存储域的虚拟机列表。

6.217.1. 列出 GET
复制链接

返回导出存储域的虚拟机列表。

虚拟机返回列表的顺序无法保证。

Expand
表 6.662. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大虚拟机数量。

unregistered

布尔值

in

指明要检索包含存储域中磁盘的已注册或未注册虚拟机的列表。

vm

Vm[]

out

 
6.217.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.217.1.2. Max
复制链接

设置要返回的最大虚拟机数量。如果未指定，则返回所有虚拟机。

6.217.1.3. unregistered
复制链接

指明要检索包含存储域中磁盘的已注册或未注册虚拟机的列表。要获得未注册的虚拟机列表，调用应指示未注册的标志。例如，要获得未注册虚拟机的列表，REST API 调用应如下所示： 

GET /ovirt-engine/api/storagedomains/123/vms?unregistered=true

unregisterd 标志的默认值为 false。请求仅适用于附加的存储域。

6.218. StorageDomains
复制链接

管理系统中的一组存储域。

Expand
表 6.663. 方法概述
名称概述

add

添加新存储域.

list

返回系统中存储域的列表。

6.218.1. 添加 POST
复制链接

添加新存储域.

创建新 StorageDomain 需要 名称、类型、主机和 存储 属性。使用 id 或 name 属性识别 主机 属性。在 Red Hat Virtualization 3.6 及更高版本中，您可以在存储域中默认启用 wipe 后删除选项。要配置此功能，请在 POST 请求中指定 wipe_after_delete。可以在创建域后编辑此选项，但是这样做不会在删除已存在的磁盘属性后更改擦除。

要添加具有指定 名称、类型、storage .type、storage.address 和 storage.path 的新存储域，并使用 ID 123 的主机发送类似如下的请求： 

POST /ovirt-engine/api/storageDomains

这样的请求正文： 

<storage_domain>
  <name>mydata</name>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

要创建新的 NFS ISO 存储域，请发送如下请求： 

<storage_domain>
  <name>myisos</name>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/export/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

要创建新 iSCSI 存储域，请发送如下请求： 

<storage_domain>
  <name>myiscsi</name>
  <type>data</type>
  <storage>
    <type>iscsi</type>
    <logical_units>
      <logical_unit id="3600144f09dbd050000004eedbd340001"/>
      <logical_unit id="3600144f09dbd050000004eedbd340002"/>
    </logical_units>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
Expand
表 6.664. 参数摘要
名称类型方向概述

storage_domain

StorageDomain

in/Out

要添加的存储域.

6.218.2. 列出 GET
复制链接

返回系统中存储域的列表。

只有 search 参数中包含 sortby 子句时，才会保证返回的存储域列表的顺序。

Expand
表 6.665. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下执行搜索。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的存储域的最大数量。

search

字符串

in

用于限制返回的存储域的查询字符串。

storage_domains

StorageDomain[]

out

系统中存储域的列表。

6.218.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写，将其设置为 false。

6.218.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.218.2.3. Max
复制链接

设置要返回的存储域的最大数量。如果未指定，则返回所有存储域。

6.219. StorageServerConnection
复制链接

Expand
表 6.666. 方法概述
名称概述

get

 

remove

删除存储连接。

update

更新存储连接。

6.219.1. 获取 GET
复制链接

Expand
表 6.667. 参数摘要
名称类型方向概述

conection

StorageConnection

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.219.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.219.2. 删除 DELETE
复制链接

删除存储连接。

只有在存储域和 LUN 磁盘均未引用存储连接时，才能删除存储连接。主机名或 id 是可选的；提供它断开与该主机的连接（解除挂载）。

Expand
表 6.668. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

host

字符串

in

从中卸载连接的主机的名称或标识符（断开连接）。

6.219.2.1. 主机
复制链接

从中卸载连接的主机的名称或标识符（断开连接）。如果未提供，则不会断开任何主机。

例如，要使用标识符 456 的主机删除带标识符 123 的存储连接，发送类似如下的请求： 

DELETE /ovirt-engine/api/storageconnections/123?host=456

6.219.3. 更新 PUT
复制链接

更新存储连接。

例如：要更改 NFS 存储服务器的地址，请发送类似如下的请求： 

PUT /ovirt-engine/api/storageconnections/123

这样的请求正文： 

<storage_connection>
  <address>mynewnfs.example.com</address>
</storage_connection>

要更改 iSCSI 存储服务器的连接，请发送类似如下的请求： 

PUT /ovirt-engine/api/storageconnections/123

这样的请求正文： 

<storage_connection>
  <port>3260</port>
  <target>iqn.2017-01.com.myhost:444</target>
</storage_connection>
Expand
表 6.669. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

连接

StorageConnection

in/Out

 

force

布尔值

in

指明无论相关存储域的状态如何（i.

6.219.3.1. force
复制链接

指明无论相关存储域的状态如何，操作都应成功（例如，当存储域的状态不是维护时，更新也适用）。

此参数是可选的，默认值为 false。

6.220. StorageServerConnectionExtension
复制链接

Expand
表 6.670. 方法概述
名称概述

get

 

remove

 

update

更新给定主机的存储服务器连接扩展。

6.220.1. 获取 GET
复制链接

Expand
表 6.671. 参数摘要
名称类型方向概述

扩展

StorageConnectionExtension

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.220.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.220.2. 删除 DELETE
复制链接

Expand
表 6.672. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.220.3. 更新 PUT
复制链接

更新给定主机的存储服务器连接扩展。

要更新主机 123 的存储连接 456，发送如下请求： 

PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456

这样的请求正文： 

<storage_connection_extension>
  <target>iqn.2016-01.com.example:mytarget</target>
  <username>myuser</username>
  <password>mypassword</password>
</storage_connection_extension>
Expand
表 6.673. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

扩展

StorageConnectionExtension

in/Out

 

6.221. StorageServerConnectionExtensions
复制链接

Expand
表 6.674. 方法概述
名称概述

add

为给定主机创建新的存储服务器连接扩展名。

list

返回列表 os 存储连接扩展。

6.221.1. 添加 POST
复制链接

为给定主机创建新的存储服务器连接扩展名。

扩展允许用户为特定主机的 iSCSI 目标定义凭据。例如，在从主机 123 连接到 iSCSI 目标时，使用 myuser 和 mypassword 作为凭证发送如下请求： 

POST /ovirt-engine/api/hosts/123/storageconnectionextensions

这样的请求正文： 

<storage_connection_extension>
  <target>iqn.2016-01.com.example:mytarget</target>
  <username>myuser</username>
  <password>mypassword</password>
</storage_connection_extension>
Expand
表 6.675. 参数摘要
名称类型方向概述

扩展

StorageConnectionExtension

in/Out

 

6.221.2. 列出 GET
复制链接

返回列表 os 存储连接扩展。

存储连接返回列表的顺序不受保证。

Expand
表 6.676. 参数摘要
名称类型方向概述

扩展

StorageConnectionExtension[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大扩展数。

6.221.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.221.2.2. Max
复制链接

设置要返回的最大扩展数。如果没有指定，则会返回所有扩展。

6.222. StorageServerConnections
复制链接

Expand
表 6.677. 方法概述
名称概述

add

创建新的存储连接。

list

返回存储连接列表。

6.222.1. 添加 POST
复制链接

创建新的存储连接。

例如，要为 NFS 服务器 mynfs.example.com 和 NFS 共享 /export/mydata 创建新存储连接，请发送如下请求： 

POST /ovirt-engine/api/storageconnections

这样的请求正文： 

<storage_connection>
  <type>nfs</type>
  <address>mynfs.example.com</address>
  <path>/export/mydata</path>
  <host>
    <name>myhost</name>
  </host>
</storage_connection>
Expand
表 6.678. 参数摘要
名称类型方向概述

连接

StorageConnection

in/Out

 

6.222.2. 列出 GET
复制链接

返回存储连接列表。

无法保证返回的连接列表的顺序。

Expand
表 6.679. 参数摘要
名称类型方向概述

连接

StorageConnection[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大连接数。

6.222.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.222.2.2. Max
复制链接

设置要返回的最大连接数。如果未指定，则返回所有连接。

6.223. 系统
复制链接

Expand
表 6.680. 方法概述
名称概述

get

返回描述 API 的基本信息，如产品名称、版本号和相关对象数量的摘要。

重新载入配置

 

6.223.1. 获取 GET
复制链接

返回描述 API 的基本信息，如产品名称、版本号和相关对象数量的摘要。 

GET /ovirt-engine/api

我们得到以下响应： 

<api>
  <link rel="capabilities" href="/api/capabilities"/>
  <link rel="clusters" href="/api/clusters"/>
  <link rel="clusters/search" href="/api/clusters?search={query}"/>
  <link rel="datacenters" href="/api/datacenters"/>
  <link rel="datacenters/search" href="/api/datacenters?search={query}"/>
  <link rel="events" href="/api/events"/>
  <link rel="events/search" href="/api/events?search={query}"/>
  <link rel="hosts" href="/api/hosts"/>
  <link rel="hosts/search" href="/api/hosts?search={query}"/>
  <link rel="networks" href="/api/networks"/>
  <link rel="roles" href="/api/roles"/>
  <link rel="storagedomains" href="/api/storagedomains"/>
  <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
  <link rel="tags" href="/api/tags"/>
  <link rel="templates" href="/api/templates"/>
  <link rel="templates/search" href="/api/templates?search={query}"/>
  <link rel="users" href="/api/users"/>
  <link rel="groups" href="/api/groups"/>
  <link rel="domains" href="/api/domains"/>
  <link rel="vmpools" href="/api/vmpools"/>
  <link rel="vmpools/search" href="/api/vmpools?search={query}"/>
  <link rel="vms" href="/api/vms"/>
  <link rel="vms/search" href="/api/vms?search={query}"/>
  <product_info>
    <name>oVirt Engine</name>
    <vendor>ovirt.org</vendor>
    <version>
      <build>4</build>
      <full_version>4.0.4</full_version>
      <major>4</major>
      <minor>0</minor>
      <revision>0</revision>
    </version>
  </product_info>
  <special_objects>
    <blank_template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <root_tag href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
  </special_objects>
  <summary>
    <hosts>
      <active>0</active>
      <total>0</total>
    </hosts>
    <storage_domains>
      <active>0</active>
      <total>1</total>
    </storage_domains>
    <users>
      <active>1</active>
      <total>1</total>
    </users>
    <vms>
      <active>0</active>
      <total>0</total>
    </vms>
  </summary>
  <time>2016-09-14T12:00:48.132+02:00</time>
</api>

入口点为用户提供虚拟环境中集合的链接。每个集合链接的 Therel 属性 都会为每个链接提供一个参考点。

入口点还包含其他数据，如 product_info、special_objects 和 summary。

Expand
表 6.681. 参数摘要
名称类型方向概述

api

api

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.223.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.223.2. 重新载入配置 POST
复制链接

Expand
表 6.682. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重新加载。

6.224. SystemOption
复制链接

此服务提供系统特定配置选项的值。

Expand
表 6.683. 方法概述
名称概述

get

获取特定配置选项的值。

6.224.1. 获取 GET
复制链接

获取特定配置选项的值。

例如，要检索配置选项 MigrationPoliciesSupported 的值，发送类似如下的请求： 

GET /ovirt-engine/api/options/MigrationPoliciesSupported

对这个请求的响应如下： 

<system_option href="/ovirt-engine/api/options/MigrationPoliciesSupported" id="MigrationPoliciesSupported">
  <name>MigrationPoliciesSupported</name>
  <values>
    <system_option_value>
      <value>true</value>
      <version>4.0</version>
    </system_option_value>
    <system_option_value>
      <value>true</value>
      <version>4.1</version>
    </system_option_value>
    <system_option_value>
      <value>true</value>
      <version>4.2</version>
    </system_option_value>
    <system_option_value>
      <value>false</value>
      <version>3.6</version>
    </system_option_value>
  </values>
</system_option>
注意

查询配置选项需要适当的权限。某些选项仅可由具备管理员权限的用户查询。

重要

没有向后兼容，无法保证选项的名称或值。可以删除选项，也可以随时更改其含义。

我们强烈建议将此服务用于与引擎同时发布的应用程序之外的应用程序。不支持其他应用程序的使用。因此，不会有文档列出可访问的配置选项。

Expand
表 6.684. 参数摘要
名称类型方向概述

选项

SystemOption

out

系统返回的配置选项。

version

字符串

in

指定仅应返回特定版本的配置选项的可选 version 参数。

6.224.1.1. version
复制链接

指定仅应返回特定版本的配置选项的可选 version 参数。如果未使用这个参数，则会返回所有版本。

例如，要获取 MigrationPoliciesSupported 选项的值，但只有版本 4.2 发送如下请求： 

GET /ovirt-engine/api/options/MigrationPoliciesSupported?version=4.2

对这个请求的响应如下： 

<system_option href="/ovirt-engine/api/options/MigrationPoliciesSupported" id="MigrationPoliciesSupported">
  <name>MigrationPoliciesSupported</name>
  <values>
    <system_option_value>
      <value>true</value>
      <version>4.2</version>
    </system_option_value>
  </values>
</system_option>

6.225. SystemOptions
复制链接

提供系统配置选项值的服务。

6.226. SystemPermissions
复制链接

此服务不添加新方法，只是注解的占位符，用于指定管理分配给系统对象的权限的资源的路径。

Expand
表 6.685. 方法概述
名称概述

add

为特定实体为用户或组分配新权限。

list

列出特定实体的所有权限。

6.226.1. 添加 POST
复制链接

为特定实体为用户或组分配新权限。

例如，要为 ID 为 123 的虚拟机分配 UserVmManager 角色给 ID 为 456 的用户发送类似如下的请求： 

POST /ovirt-engine/api/vms/123/permissions

这样的请求正文： 

<permission>
  <role>
    <name>UserVmManager</name>
  </role>
  <user id="456"/>
</permission>

要将 SuperUser 角色分配给 ID 为 456 的用户，请发送如下请求： 

POST /ovirt-engine/api/permissions

这样的请求正文： 

<permission>
  <role>
    <name>SuperUser</name>
  </role>
  <user id="456"/>
</permission>

如果要为组而不是用户分配权限，请将 user 元素替换为 组 元素的适当 ID。例如，将 UserRole 角色分配给 ID 为 123 的集群，将 id 789 的组分配如下： 

POST /ovirt-engine/api/clusters/123/permissions

这样的请求正文： 

<permission>
  <role>
    <name>UserRole</name>
  </role>
  <group id="789"/>
</permission>
Expand
表 6.686. 参数摘要
名称类型方向概述

权限

权限

in/Out

权限。

6.226.2. 列出 GET
复制链接

列出特定实体的所有权限。

例如，列出 ID 为 123 的集群的所有权限 发送 如下请求： 

GET /ovirt-engine/api/clusters/123/permissions
 
<permissions>
  <permission id="456">
    <cluster id="123"/>
    <role id="789"/>
    <user id="451"/>
  </permission>
  <permission id="654">
    <cluster id="123"/>
    <role id="789"/>
    <group id="127"/>
  </permission>
</permissions>

返回的权限顺序不受保证。

Expand
表 6.687. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

权限

permission[]

out

权限列表。

6.226.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.227. Tag
复制链接

在系统中管理特定标签的服务。

Expand
表 6.688. 方法概述
名称概述

get

获取有关标签的信息。

remove

从系统中删除该标签。

update

更新标签实体。

6.227.1. 获取 GET
复制链接

获取有关标签的信息。

例如，要检索 ID 123 的标签信息，发送 如下请求： 

GET /ovirt-engine/api/tags/123
 
<tag href="/ovirt-engine/api/tags/123" id="123">
  <name>root</name>
  <description>root</description>
</tag>
Expand
表 6.689. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

tag

Tag

out

标签。

6.227.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.227.2. 删除 DELETE
复制链接

从系统中删除该标签。

例如，要删除 ID 123 的标签，发送 类似如下的请求： 

DELETE /ovirt-engine/api/tags/123
Expand
表 6.690. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.227.3. 更新 PUT
复制链接

更新标签实体。

例如，将父标签更新为带有 id 123 的标签 ID 为 456 时，发送 类似如下的请求： 

PUT /ovirt-engine/api/tags/123

借助请求正文，例如： 

<tag>
  <parent id="456"/>
</tag>

您还可以指定标签名称而不是 id。例如，将父标签更新为带有 id 123 的标签名称为 mytag 时，发送类似如下的请求： 

<tag>
  <parent>
    <name>mytag</name>
  </parent>
</tag>
Expand
表 6.691. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

tag

Tag

in/Out

更新的标签。

6.228. Tags
复制链接

代表用于管理系统中标签集合的服务。

Expand
表 6.692. 方法概述
名称概述

add

向系统添加新标签。

list

列出系统中的标签。

6.228.1. 添加 POST
复制链接

向系统添加新标签。

例如，要向系统添加名称为 mytag 的新标签，发送类似如下的请求： 

POST /ovirt-engine/api/tags

这样的请求正文： 

<tag>
  <name>mytag</name>
</tag>
注意

如果未指定父标签，root 标签是一个特殊的 pseudo-tag，它假定为默认的父标签。root 标签不能被删除，也不能分配父标签。

使用特定父标签创建新标签会发送请求正文，如下所示： 

<tag>
  <name>mytag</name>
  <parent>
    <name>myparenttag</name>
  </parent>
</tag>
Expand
表 6.693. 参数摘要
名称类型方向概述

tag

Tag

in/Out

添加的标签。

6.228.2. 列出 GET
复制链接

列出系统中的标签。

例如，列出系统中标签的完整层次结构会发送如下请求： 

GET /ovirt-engine/api/tags
 
<tags>
  <tag href="/ovirt-engine/api/tags/222" id="222">
    <name>root2</name>
    <description>root2</description>
    <parent href="/ovirt-engine/api/tags/111" id="111"/>
  </tag>
  <tag href="/ovirt-engine/api/tags/333" id="333">
    <name>root3</name>
    <description>root3</description>
    <parent href="/ovirt-engine/api/tags/222" id="222"/>
  </tag>
  <tag href="/ovirt-engine/api/tags/111" id="111">
    <name>root</name>
    <description>root</description>
  </tag>
</tags>

在前面的 XML 输出中，您可以看到标签的以下层次结构： 

root:        (id: 111)
  - root2    (id: 222)
    - root3  (id: 333)

标签返回列表的顺序不受保证。

Expand
表 6.694. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大标签数。

tags

Tag[]

out

系统中的所有标签列表。

6.228.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.228.2.2. Max
复制链接

设置要返回的最大标签数。如果未指定，则返回所有标签。

6.229. Template
复制链接

管理虚拟机模板和模板版本。

Expand
表 6.695. 方法概述
名称概述

export

将模板导出到数据中心导出域。

get

返回有关此模板或模板版本的信息。

remove

删除虚拟机模板.

update

更新模板。

6.229.1. 导出 POST
复制链接

将模板导出到数据中心导出域。

例如，发送以下请求： 

POST /ovirt-engine/api/templates/123/export

这样的请求正文： 

<action>
  <storage_domain id="456"/>
  <exclusive>true<exclusive/>
</action>
Expand
表 6.696. 参数摘要
名称类型方向概述

专用

布尔值

in

指明是否应该覆盖具有相同名称的现有模板。

storage_domain

StorageDomain

in

指定目标导出存储域。

6.229.1.1. 专用
复制链接

指明是否应该覆盖具有相同名称的现有模板。

如果目标域中存在相同名称的模板，则导出操作会报告失败的操作。将此参数设置为 true 以更改此行为并覆盖任何现有的模板。

6.229.2. 获取 GET
复制链接

返回有关此模板或模板版本的信息。

Expand
表 6.697. 参数摘要
名称类型方向概述

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

模板

Template

out

有关模板或模板版本的信息。

6.229.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.229.3. 删除 DELETE
复制链接

删除虚拟机模板. 

DELETE /ovirt-engine/api/templates/123
Expand
表 6.698. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.229.4. 更新 PUT
复制链接

更新模板。

name、description、 type、memory、cpu,topology ,os , high_availability,display 、无状态、usb 和 timezone 元素可以在创建模板后更新。

例如，要更新模板，使其具有 1 GiB 内存发送请求，如下所示： 

PUT /ovirt-engine/api/templates/123

使用以下请求正文： 

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

version_name name 属性是唯一可在用于模板 版本的 version 属性中更新的属性： 

<template>
  <version>
    <version_name>mytemplate_2</version_name>
  </version>
</template>
Expand
表 6.699. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

模板

Template

in/Out

 

6.230. TemplateCdrom
复制链接

管理模板上 CD-ROM 设备的服务。

Expand
表 6.700. 方法概述
名称概述

get

返回有关此 CD-ROM 设备的信息。

6.230.1. 获取 GET
复制链接

返回有关此 CD-ROM 设备的信息。

例如，要获取有关模板 123 的 CD-ROM 设备的信息，请发送如下请求： 

GET /ovirt-engine/api/templates/123/cdroms/
Expand
表 6.701. 参数摘要
名称类型方向概述

cdrom

cdrom

out

有关 CD-ROM 设备的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.230.1.1. cdrom
复制链接

有关 CD-ROM 设备的信息。

该信息由 cdrom 属性组成，其中包含对 CD-ROM 设备、模板和插入磁盘的引用。

如果插入了磁盘，则 file 属性将包含对 ISO 镜像的引用： 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
  <file id="mycd.iso"/>
</cdrom>

如果没有插入磁盘，则不会报告 file 属性： 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
</cdrom>
6.230.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.231. TemplateCdroms
复制链接

列出模板的 CD-ROM 设备。

Expand
表 6.702. 方法概述
名称概述

list

返回模板的 CD-ROM 设备列表。

6.231.1. 列出 GET
复制链接

返回模板的 CD-ROM 设备列表。

CD-ROM 设备返回列表的顺序不受保证。

Expand
表 6.703. 参数摘要
名称类型方向概述

cdroms

Cdrom[]

out

模板的 CD-ROM 设备列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 CD-ROM 数。

6.231.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.231.1.2. Max
复制链接

设置要返回的最大 CD-ROM 数。如果没有指定，则返回所有 CD-ROM。

6.232. TemplateDisk
复制链接

Expand
表 6.704. 方法概述
名称概述

copy

将附加到模板的指定磁盘复制到特定的存储域。

export

 

get

 

remove

 

6.232.1. 复制 POST
复制链接

将附加到模板的指定磁盘复制到特定的存储域。

Expand
表 6.705. 参数摘要
名称类型方向概述

async

布尔值

in

指明复制应异步执行。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

storage_domain

StorageDomain

in

 

6.232.2. 导出 POST
复制链接

Expand
表 6.706. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导出。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

storage_domain

StorageDomain

in

 

6.232.3. 获取 GET
复制链接

Expand
表 6.707. 参数摘要
名称类型方向概述

disk

Disk

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.232.3.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.232.4. 删除 DELETE
复制链接

Expand
表 6.708. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.233. TemplateDiskAttachment
复制链接

此服务管理磁盘附加到模板。

Expand
表 6.709. 方法概述
名称概述

get

返回附件的详细信息。

remove

从模板中删除磁盘。

6.233.1. 获取 GET
复制链接

返回附件的详细信息。

Expand
表 6.710. 参数摘要
名称类型方向概述

Attach

DiskAttachment

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.233.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.233.2. 删除 DELETE
复制链接

从模板中删除磁盘。只有在其他存储域中存在磁盘的其他现有副本时，才会删除磁盘。

必须指定存储域来确定应删除哪些副本（模板磁盘可以在多个存储域上具有副本）。 

DELETE /ovirt-engine/api/templates/{template:id}/diskattachments/{attachment:id}?storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74
Expand
表 6.711. 参数摘要
名称类型方向概述

force

布尔值

in

 

storage_domain

字符串

in

指定要删除的镜像所在的存储域的标识符。

6.234. TemplateDiskAttachments
复制链接

此服务管理附加到模板的一组磁盘。每个附加的磁盘都由 DiskAttachment 表示。

Expand
表 6.712. 方法概述
名称概述

list

列出附加到模板的磁盘。

6.234.1. 列出 GET
复制链接

列出附加到模板的磁盘。

返回附件列表的顺序无法保证。

Expand
表 6.713. 参数摘要
名称类型方向概述

附件

DiskAttachment[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.234.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.235. TemplateDisks
复制链接

Expand
表 6.714. 方法概述
名称概述

list

返回模板的磁盘列表。

6.235.1. 列出 GET
复制链接

返回模板的磁盘列表。

无法保证返回的磁盘列表的顺序。

Expand
表 6.715. 参数摘要
名称类型方向概述

磁盘

disk[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

6.235.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.235.1.2. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.236. TemplateGraphicsConsole
复制链接

Expand
表 6.716. 方法概述
名称概述

get

获取模板的图形控制台配置。

remove

从模板中删除 graphics 控制台。

6.236.1. 获取 GET
复制链接

获取模板的图形控制台配置。

Expand
表 6.717. 参数摘要
名称类型方向概述

console

GraphicsConsole

out

模板图形控制台的相关信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.236.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.236.2. 删除 DELETE
复制链接

从模板中删除 graphics 控制台。

Expand
表 6.718. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.237. TemplateGraphicsConsoles
复制链接

Expand
表 6.719. 方法概述
名称概述

add

向模板添加新的图形控制台。

list

列出模板的所有配置的图形控制台。

6.237.1. 添加 POST
复制链接

向模板添加新的图形控制台。

Expand
表 6.720. 参数摘要
名称类型方向概述

console

GraphicsConsole

in/Out

 

6.237.2. 列出 GET
复制链接

列出模板的所有配置的图形控制台。

无法保证返回的图形控制台列表的顺序。

Expand
表 6.721. 参数摘要
名称类型方向概述

consoles

GraphicsConsole[]

out

模板的图形控制台列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大控制台数。

6.237.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.237.2.2. Max
复制链接

设置要返回的最大控制台数。如果没有指定，则返回所有控制台。

6.238. TemplateMediatedDevice
复制链接

Expand
表 6.722. 方法概述
名称概述

get

获取模板的介质设备配置。

remove

从模板创建介质设备。

update

更新有关介质设备的信息。

6.238.1. 获取 GET
复制链接

获取模板的介质设备配置。

Expand
表 6.723. 参数摘要
名称类型方向概述

device

VmMediatedDevice

out

有关模板的介质设备的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.238.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.238.2. 删除 DELETE
复制链接

从模板创建介质设备。

Expand
表 6.724. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.238.3. 更新 PUT
复制链接

更新有关介质设备的信息。

您可以使用 specParams 元素更新信息。

例如，要更新介质设备，请发送如下请求： 

PUT /ovirt-engine/api/templates/123/mediateddevices/00000000-0000-0000-0000-000000000000
<vm_mediated_device>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>

使用响应正文： 

<vm_mediated_device href="/ovirt-engine/api/templates/123/mediateddevices/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>
Expand
表 6.725. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

devices

VmMediatedDevice

in/Out

有关介质设备的信息。

6.238.3.1. devices
复制链接

有关介质设备的信息。

请求数据必须包含 specParams 属性。响应数据包含有关更新的介质设备的完整信息。

6.239. TemplateMediatedDevices
复制链接

管理模板的介质设备的服务。

Expand
表 6.726. 方法概述
名称概述

add

向模板添加新的介质设备。

list

列出模板的所有配置的介质设备。

6.239.1. 添加 POST
复制链接

向模板添加新的介质设备。

Expand
表 6.727. 参数摘要
名称类型方向概述

device

VmMediatedDevice

in/Out

 

6.239.2. 列出 GET
复制链接

列出模板的所有配置的介质设备。

返回的介质设备列表的顺序不能保证。

Expand
表 6.728. 参数摘要
名称类型方向概述

devices

VmMediatedDevice[]

out

模板的介质设备列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大介质设备数。

6.239.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.239.2.2. Max
复制链接

设置要返回的最大介质设备数。如果没有指定所有介质设备，则会返回。

6.240. TemplateNic
复制链接

Expand
表 6.729. 方法概述
名称概述

get

 

remove

 

update

更新附加到模板的指定网络接口卡。

6.240.1. 获取 GET
复制链接

Expand
表 6.730. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

nic

NIC

out

 
6.240.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.240.2. 删除 DELETE
复制链接

Expand
表 6.731. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.240.3. 更新 PUT
复制链接

更新附加到模板的指定网络接口卡。

Expand
表 6.732. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

nic

NIC

in/Out

 

6.241. TemplateNics
复制链接

Expand
表 6.733. 方法概述
名称概述

add

向模板添加新的网络接口卡。

list

返回模板的 NIC 列表。

6.241.1. 添加 POST
复制链接

向模板添加新的网络接口卡。

Expand
表 6.734. 参数摘要
名称类型方向概述

nic

NIC

in/Out

 

6.241.2. 列出 GET
复制链接

返回模板的 NIC 列表。

NIC 返回列表的顺序不受保证。

Expand
表 6.735. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 NIC 数。

nics

Nic[]

out

 
6.241.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.241.2.2. Max
复制链接

设置要返回的最大 NIC 数。如果没有指定，则会返回所有 NIC。

6.242. TemplateWatchdog
复制链接

Expand
表 6.736. 方法概述
名称概述

get

 

remove

 

update

为给定 ID 标识的模板更新 watchdog。

6.242.1. 获取 GET
复制链接

Expand
表 6.737. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

watchdog

Watchdog

out

 
6.242.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.242.2. 删除 DELETE
复制链接

Expand
表 6.738. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.242.3. 更新 PUT
复制链接

为给定 ID 标识的模板更新 watchdog。

Expand
表 6.739. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

watchdog

Watchdog

in/Out

 

6.243. TemplateWatchdogs
复制链接

Expand
表 6.740. 方法概述
名称概述

add

将 watchdog 添加到由给定 ID 标识的模板中。

list

返回 watchdogs 列表。

6.243.1. 添加 POST
复制链接

将 watchdog 添加到由给定 ID 标识的模板中。

Expand
表 6.741. 参数摘要
名称类型方向概述

watchdog

Watchdog

in/Out

 

6.243.2. 列出 GET
复制链接

返回 watchdogs 列表。

返回的 watchdogs 列表的顺序不受保证。

Expand
表 6.742. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 watchdogs 数。

watchdogs

Watchdog[]

out

 
6.243.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.243.2.2. Max
复制链接

设置要返回的最大 watchdogs 数。如果未指定，则返回所有 watchdogs。

6.244. 模板
复制链接

此服务管理系统中可用的虚拟机模板。

Expand
表 6.743. 方法概述
名称概述

add

创建新模板.

list

返回虚拟机模板列表。

6.244.1. 添加 POST
复制链接

创建新模板.

这需要 name 和 vm 元素。若要识别虚拟机，可使用 vm.id 或 vm.name 属性。例如，要使用标识符 123 从虚拟机创建模板，请发送类似如下的请求： 

POST /ovirt-engine/api/templates

这样的请求正文： 

<template>
  <name>mytemplate</name>
  <vm id="123"/>
</template>

从版本 4.3 开始，为了从快照创建虚拟机模板，发送如下请求正文： 

<template>
  <name>mytemplate</name>
  <vm id="123">
    <snapshots>
      <snapshot id="456"/>
    </snapshots>
  </vm>
</template>

可以自定义模板的磁盘，使其部分特征与原始虚拟机的磁盘不同。为此，可使用 vm.disk_attachments 属性，指定原始虚拟机的磁盘标识符和您要更改的特征。例如，如果原始虚拟机有一个标识符 456 的磁盘，并且对该磁盘要将格式更改为 mydisk，将其格式改为 Copy On Write 并将其 稀疏，发送一个请求正文，如下所示： 

<template>
  <name>mytemplate</name>
  <vm id="123">
    <disk_attachments>
      <disk_attachment>
        <disk id="456">
          <name>mydisk</name>
          <format>cow</format>
          <sparse>true</sparse>
        </disk>
      </disk_attachment>
    </disk_attachments>
  </vm>
</template>

模板可以创建为现有模板的子版本。这需要新模板 的名称和 vm 属性，以及新模板版本的 base_template 和 version_name 属性。base_template 和 version_name 属性必须在 template 部分括起的 version 部分中 指定。使用 id 或 name 属性识别虚拟机。 

<template>
  <name>mytemplate</name>
  <vm id="123"/>
  <version>
    <base_template id="456"/>
    <version_name>mytemplate_001</version_name>
  </version>
</template>

模板的目标存储域可以通过以下两种方式之一来自定义：

  1. 全局，在请求级别.请求必须列出要在存储域上创建所需的磁盘附件。如果没有列出磁盘附加，将忽略全局存储域参数。 

    <template>
  <name>mytemplate</name>
  <storage_domain id="123"/>
  <vm id="456">
    <disk_attachments>
      <disk_attachment>
        <disk id="789">
          <format>cow</format>
          <sparse>true</sparse>
        </disk>
      </disk_attachment>
    </disk_attachments>
  </vm>
</template>

  2. 按每个磁盘附加.为每个磁盘附加指定所需的存储域。指定全局存储定义将根据磁盘附加规格覆盖存储域。 

    <template>
  <name>mytemplate</name>
  <vm id="123">
    <disk_attachments>
      <disk_attachment>
        <disk id="456">
          <format>cow</format>
          <sparse>true</sparse>
          <storage_domains>
             <storage_domain id="789"/>
          </storage_domains>
        </disk>
      </disk_attachment>
    </disk_attachments>
  </vm>
</template>
Expand
表 6.744. 参数摘要
名称类型方向概述

clone_permissions

布尔值

in

指定虚拟机的权限是否应复制到模板。

seal

布尔值

in

密封模板。

模板

Template

in/Out

有关模板或模板版本的信息。

6.244.1.1. clone_permissions
复制链接

指定虚拟机的权限是否应复制到模板。

如果提供了此可选参数，并且其值为 true，则虚拟机的权限（只有直接虚拟机的权限，而不是继承的参数）将复制到创建的模板。例如，要从 myvm 虚拟机创建模板复制其权限，请发送如下请求： 

POST /ovirt-engine/api/templates?clone_permissions=true

这样的请求正文： 

<template>
  <name>mytemplate<name>
  <vm>
    <name>myvm<name>
  </vm>
</template>
6.244.1.2. seal
复制链接

密封模板。

如果提供了此可选参数，并且其值为 true，则模板将在创建后密封。

封装会从文件系统中删除所有特定于主机的配置：SSH 密钥、UDEV 规则、MAC 地址、系统 ID、主机名等，从而更加轻松地使用模板来创建多个虚拟机，无需人工干预。

目前，仅支持 Linux 操作系统的密封。

6.244.2. 列出 GET
复制链接

返回虚拟机模板列表。

例如： 

GET /ovirt-engine/api/templates

将返回虚拟机和虚拟机模板的列表。

无法保证返回的模板列表的顺序。

Expand
表 6.745. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的模板的最大数量。

search

字符串

in

用于限制返回的模板的查询字符串。

templates

template[]

out

虚拟机模板列表。

6.244.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.244.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.244.2.3. Max
复制链接

设置要返回的模板的最大数量。如果未指定，则返回所有模板。

6.245. UnmanagedNetwork
复制链接

Expand
表 6.746. 方法概述
名称概述

get

 

remove

 

6.245.1. 获取 GET
复制链接

Expand
表 6.747. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network

UnmanagedNetwork

out

 
6.245.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.245.2. 删除 DELETE
复制链接

Expand
表 6.748. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.246. UnmanagedNetworks
复制链接

Expand
表 6.749. 方法概述
名称概述

list

返回主机的非受管网络列表。

6.246.1. 列出 GET
复制链接

返回主机的非受管网络列表。

网络返回列表的顺序无法保证。

Expand
表 6.750. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

网络

UnmanagedNetwork[]

out

 
6.246.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.246.1.2. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.247. 用户
复制链接

在系统中管理系统的用户的服务。使用此服务获取用户详细信息或删除用户。要添加新用户，请使用 第 6.250 节 “用户”。

Expand
表 6.751. 方法概述
名称概述

get

获取系统用户信息.

remove

删除系统用户。

update

更新用户的信息。

6.247.1. 获取 GET
复制链接

获取系统用户信息.

使用方法： 

GET /ovirt-engine/api/users/1234

将返回用户信息： 

<user href="/ovirt-engine/api/users/1234" id="1234">
  <name>admin</name>
  <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/>
  <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
  <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
  <department></department>
  <domain_entry_id>23456</domain_entry_id>
  <email>user1@domain.com</email>
  <last_name>Lastname</last_name>
  <namespace>*</namespace>
  <principal>user1</principal>
  <user_name>user1@domain-authz</user_name>
  <domain href="/ovirt-engine/api/domains/45678" id="45678">
    <name>domain-authz</name>
  </domain>
</user>
Expand
表 6.752. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

user

用户

out

系统用户.

6.247.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.247.2. 删除 DELETE
复制链接

删除系统用户。

使用方法： 

DELETE /ovirt-engine/api/users/1234
Expand
表 6.753. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.247.3. 更新 PUT
复制链接

更新用户的信息。

只有 user_options 字段才能更新。

例如，更新用户选项： 

PUT /ovirt-engine/api/users/123

这样的请求正文： 

<user>
   <user_options>
      <property>
         <name>test</name>
         <value>["any","JSON"]</value>
      </property>
   </user_options>
</user>
重要

自引擎版本 4.4.5 起，此操作已弃用，仅用于向后兼容。以后会将其移除。请改为使用选项端点。

Expand
表 6.754. 参数摘要
名称类型方向概述

user

用户

in/Out

 

6.248. UserOption
复制链接

Expand
表 6.755. 方法概述
名称概述

get

返回 JSON 类型的用户配置文件属性。

remove

删除 JSON 类型的现有属性。

6.248.1. 获取 GET
复制链接

返回 JSON 类型的用户配置文件属性。

请求示例（针对标识符为 123 和选项为 456的用户）： 

GET /ovirt-engine/api/users/123/options/456

其结果将是以下 XML 文档： 

  <user_option href="/ovirt-engine/api/users/123/options/456" id="456">
    <name>SomeName</name>
    <content>["any", "JSON"]</content>
    <user href="/ovirt-engine/api/users/123" id="123"/>
  </user_option>
Expand
表 6.756. 参数摘要
名称类型方向概述

选项

UserOption

out

 

6.248.2. 删除 DELETE
复制链接

删除 JSON 类型的现有属性。

请求示例（针对标识符为 123 和选项为 456的用户）： 

DELETE /ovirt-engine/api/users/123/options/456

6.249. UserOptions
复制链接

Expand
表 6.757. 方法概述
名称概述

add

添加类型为 JSON 的新用户配置文件属性。

list

返回 JSON 类型的用户配置文件属性列表。

6.249.1. 添加 POST
复制链接

添加类型为 JSON 的新用户配置文件属性。

请求示例（针对标识符为 123 的用户） ： 

POST /ovirt-engine/api/users/123/options

payload: 

  <user_option>
    <name>SomeName</name>
    <content>["any", "JSON"]</content>
  </user_option>
Expand
表 6.758. 参数摘要
名称类型方向概述

选项

UserOption

in/Out

 

6.249.2. 列出 GET
复制链接

返回 JSON 类型的用户配置文件属性列表。

请求示例（针对标识符为 123 的用户） ： 

GET /ovirt-engine/api/users/123/options

其结果将是以下 XML 文档： 

<user_options>
  <user_option href="/ovirt-engine/api/users/123/options/456" id="456">
    <name>SomeName</name>
    <content>["any", "JSON"]</content>
    <user href="/ovirt-engine/api/users/123" id="123"/>
  </user_option>
</user_options>
Expand
表 6.759. 参数摘要
名称类型方向概述

选项

UserOption[]

out

 

6.250. 用户
复制链接

此服务用于管理系统中的用户。

Expand
表 6.760. 方法概述
名称概述

add

从目录服务添加用户.

list

列出系统中的所有用户。

6.250.1. 添加 POST
复制链接

从目录服务添加用户.

例如，要从 my extension-authz 授权供应商添加 my user 用户，发送类似如下的请求： 

POST /ovirt-engine/api/users

这样的请求正文： 

<user>
  <user_name>myuser@myextension-authz</user_name>
  <domain>
    <name>myextension-authz</name>
  </domain>
</user>

如果您正在使用 Active Directory，则必须将用户主体名称(UPN)传递为 用户名，后跟授权提供程序名称。由于 错误 1147900，您需要提供用户 UPN 的 principal 参数。

例如，从 myextension-authz 授权供应商添加带有 UPN myuser@mysubdomain.mydomain.com 的用户，发送如下的请求正文： 

<user>
  <principal>myuser@mysubdomain.mydomain.com</principal>
  <user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name>
  <domain>
    <name>myextension-authz</name>
  </domain>
</user>
Expand
表 6.761. 参数摘要
名称类型方向概述

user

用户

in/Out

 

6.250.2. 列出 GET
复制链接

列出系统中的所有用户。

使用方法： 

GET /ovirt-engine/api/users

将返回用户列表： 

<users>
  <user href="/ovirt-engine/api/users/1234" id="1234">
    <name>admin</name>
    <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/>
    <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
    <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
    <domain_entry_id>23456</domain_entry_id>
    <namespace>*</namespace>
    <principal>user1</principal>
    <user_name>user1@domain-authz</user_name>
    <domain href="/ovirt-engine/api/domains/45678" id="45678">
      <name>domain-authz</name>
    </domain>
  </user>
</users>

无法保证返回的用户列表的顺序。

Expand
表 6.762. 参数摘要
名称类型方向概述

case_sensitive

布尔值

in

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大用户数。

search

字符串

in

用于限制返回的用户的查询字符串。

用户

user[]

out

用户列表。

6.250.2.1. case_sensitive
复制链接

指明是否应该在考虑大小写的情况下使用 search 参数执行搜索。默认值为 true，这意味着会考虑这个情况。如果要搜索忽略大小写的操作，将其设置为 false。

6.250.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.250.2.3. Max
复制链接

设置要返回的最大用户数。如果未指定，则返回所有用户。

6.251. VirtualFunctionAllowedNetwork
复制链接

Expand
表 6.763. 方法概述
名称概述

get

 

remove

 

6.251.1. 获取 GET
复制链接

Expand
表 6.764. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

network

Network

out

 
6.251.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.251.2. 删除 DELETE
复制链接

Expand
表 6.765. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.252. VirtualFunctionAllowedNetworks
复制链接

Expand
表 6.766. 方法概述
名称概述

add

 

list

返回网络列表。

6.252.1. 添加 POST
复制链接

Expand
表 6.767. 参数摘要
名称类型方向概述

network

Network

in/Out

 

6.252.2. 列出 GET
复制链接

返回网络列表。

网络返回列表的顺序无法保证。

Expand
表 6.768. 参数摘要
名称类型方向概述

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大网络数。

网络

network[]

out

 
6.252.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.252.2.2. Max
复制链接

设置要返回的最大网络数。如果没有指定，则会返回所有网络。

6.253. VM
复制链接

Expand
表 6.769. 方法概述
名称概述

autopincpuandnumanodes

在虚拟机上应用自动 CPU 和 NUMA 配置。

cancelmigration

此操作将停止虚拟机到另一物理主机的任何迁移。

clone

 

commitsnapshot

将虚拟机永久恢复为预览快照的状态。

detach

将虚拟机从池中分离.

export

导出虚拟机。

freezefilesystems

冻结虚拟机文件系统.

get

检索虚拟机的描述。

logon

启动自动用户登录，以从外部控制台访问虚拟机。

维护

在托管引擎虚拟机上设置全局维护模式。

migrate

将虚拟机迁移到另一物理主机.

previewsnapshot

将虚拟机临时恢复为快照的状态。

reboot

将重新引导请求发送到虚拟机.

remove

删除虚拟机，包括它所连接的虚拟磁盘。

reordermacaddresses

 

reset

将重置请求发送到虚拟机.

截屏

捕获虚拟机当前状态的截图。

shutdown

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

start

启动虚拟机.

stop

此操作会强制虚拟机关闭。

suspend

此操作会将虚拟机状态保存到磁盘并停止它。

thawfilesystems

thaws 虚拟机文件系统.

ticket

生成时间敏感身份验证令牌，用于访问虚拟机的显示。

undosnapshot

在预览快照前，将虚拟机恢复到其具有的状态。

update

更新系统中给定虚拟机 ID 的虚拟机。

6.253.1. autopincpuandnumanodes POST
复制链接

在虚拟机上应用自动 CPU 和 NUMA 配置。

重要

由于引擎的 4.5 版已弃用，因此仅保留以向后兼容。以后会将其移除。改为使用 PUT，后跟 更新操作。

请求的示例： 

POST /ovirt-engine/api/vms/123/autopincpuandnumanodes

这样的请求正文： 

<action>
  <optimize_cpu_settings>true</optimize_cpu_settings>
</action>
Expand
表 6.770. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行分离操作。

optimize_cpu_settings

布尔值

in

指定如何应用自动 CPU 和 NUMA 配置。

6.253.1.1. optimize_cpu_settings
复制链接

指定如何应用自动 CPU 和 NUMA 配置。如果设为 true，将调整 CPU 拓扑以适合虚拟机固定主机硬件。否则，它将使用 VM CPU 拓扑。

6.253.2. 取消迁移 POST
复制链接

此操作将停止虚拟机到另一物理主机的任何迁移。 

POST /ovirt-engine/api/vms/123/cancelmigration

取消迁移操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>
Expand
表 6.771. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步取消迁移。

6.253.3. 克隆 POST
复制链接

Expand
表 6.772. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行克隆。

discard_snapshots

布尔值

in

当虚拟机应折叠快照时，请使用 discard_snapshots 参数。

storage_domain

StorageDomain

in

虚拟机磁盘将要复制到的存储域。

vm

VM

in

 
6.253.3.1. discard_snapshots
复制链接

当虚拟机应折叠快照时，请使用 discard_snapshots 参数。默认值为 true。

6.253.4. commitsnapshot POST
复制链接

将虚拟机永久恢复为预览快照的状态。

详情请查看 preview_snapshot 操作。

Expand
表 6.773. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步提交快照。

6.253.5. 分离 POST
复制链接

将虚拟机从池中分离. 

POST /ovirt-engine/api/vms/123/detach

detach 操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>
Expand
表 6.774. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行分离操作。

6.253.6. 导出 POST
复制链接

导出虚拟机。

虚拟机可以导出到导出域。例如，要将虚拟机 123 导出到导出域 myexport ： 

POST /ovirt-engine/api/vms/123/export

这样的请求正文： 

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

由于引擎的版本 4.2，也可以将虚拟机导出为虚拟设备(OVA)。例如，要将虚拟机 123 导出为名为 myvm.ova 的 OVA 文件，该文件位于主机 myhost 上的 /home/ovirt/ 目录中： 

POST /ovirt-engine/api/vms/123/export

这样的请求正文： 

<action>
  <host>
    <name>myhost</name>
  </host>
  <directory>/home/ovirt</directory>
  <filename>myvm.ova</filename>
</action>
注意

在尝试导出域中的任何操作之前，确认导出操作已经完成。

Expand
表 6.775. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导出。

discard_snapshots

布尔值

in

当虚拟机应折叠所有快照时，请使用 discard_snapshots 参数。

专用

布尔值

in

当应导出虚拟机时，请使用 专用 参数，即使导出域中已存在另一个副本（覆盖）。

storage_domain

StorageDomain

in

（导出）要将虚拟机导出到的存储域.

6.253.7. freezefilesystems POST
复制链接

冻结虚拟机文件系统.

此操作会在对正在运行的虚拟机执行实时快照时，使用 QEMU 客户机代理冻结虚拟机的文件系统。通常，由经理自动执行此操作，但是必须使用 OpenStack 卷(Cinder)磁盘的虚拟机 API 手动执行此操作。

例如： 

POST /ovirt-engine/api/vms/123/freezefilesystems
 
<action/>
Expand
表 6.776. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行冻结。

6.253.8. 获取 GET
复制链接

检索虚拟机的描述。

Expand
表 6.777. 参数摘要
名称类型方向概述

all_content

布尔值

in

指明是否应将虚拟机的所有属性包含在响应中。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

next_run

布尔值

in

指示返回的结果是否将虚拟机描述为当前正在运行，或者是否使用已执行的修改描述虚拟机，但只有在虚拟机重启后才会生效。

ovf_as_ova

布尔值

in

指明结果是否应该公开显示在该虚拟机的 OVA 文件中时的 OVF。

vm

VM

out

虚拟机的描述.

6.253.8.1. all_content
复制链接

指明是否应将虚拟机的所有属性包含在响应中。

默认情况下排除以下属性：

  • console
  • initial.configuration.data - 描述虚拟机的 OVF 文档。
  • rng_source
  • soundcard
  • virtio_scsi

例如，要检索虚拟机 '123' 的完整表示法： 

GET /ovirt-engine/api/vms/123?all_content=true
注意

这些属性默认不包含在内，因为它们会降低性能。这些属性很少被使用，需要对数据库进行额外的查询。仅在需要时使用此参数，因为它会降低性能。

6.253.8.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.253.8.3. next_run
复制链接

指示返回的结果是否将虚拟机描述为当前正在运行，或者是否使用已执行的修改描述虚拟机，但只有在虚拟机重启后才会生效。默认值为 false。

如果该参数包含在请求中，但没有值，则假设该值为 true。以下请求： 

GET /vms/{vm:id};next_run

等同于使用值 true ： 

GET /vms/{vm:id};next_run=true
6.253.8.4. ovf_as_ova
复制链接

指明结果是否应该公开显示在该虚拟机的 OVA 文件中时的 OVF。描述虚拟机的 OVF 文档。这个参数仅在设置了 all_content=True 时才有效。OVF 将显示在 initial .configuration.data 中。

例如： 

GET /vms/{vm:id}?all_content=true&ovf_as_ova=true

6.253.9. 登录 POST
复制链接

启动自动用户登录，以从外部控制台访问虚拟机。

此操作要求安装 ovirt-guest-agent-gdm-plugin 和 ovirt-guest-agent-pam -module 软件包，并在虚拟机上运行 ovirt-guest-agent 服务。

用户需要相应的用户权限才能从外部控制台访问虚拟机。

例如： 

POST /ovirt-engine/api/vms/123/logon

请求正文： 

<action/>
Expand
表 6.778. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行登录。

6.253.10. 维护 POST
复制链接

在托管引擎虚拟机上设置全局维护模式。

此操作对其他虚拟机没有影响。

例如： 

POST /ovirt-engine/api/vms/123/maintenance
 
<action>
  <maintenance_enabled>true<maintenance_enabled/>
</action>
Expand
表 6.779. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行全局维护操作。

maintenance_enabled

布尔值

in

指明是否应启用或禁用全局维护。

6.253.11. 迁移 POST
复制链接

将虚拟机迁移到另一物理主机.

例如： 

POST /ovirt-engine/api/vms/123/migrate

要指定将虚拟机迁移到的特定主机： 

<action>
  <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
Expand
表 6.780. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行迁移。

cluster

Cluster

in

指定虚拟机应迁移到的集群。

force

布尔值

in

指定虚拟机应迁移，即使虚拟机被定义为不可迁移。

host

主机

in

指定虚拟机应迁移到的特定主机。

migrate_vms_in_affinity_closure

布尔值

in

还使用此虚拟机迁移正强制关联组中的所有其他虚拟机，这些虚拟机在同一主机上运行。

6.253.11.1. cluster
复制链接

指定虚拟机应迁移到的集群。这是可选参数。默认情况下，虚拟机迁移到同一集群内的另一台主机上。

警告

不支持实时迁移到另一集群。在尝试迁移前，请强烈考虑目标集群的硬件架构和网络架构。

6.253.11.2. force
复制链接

指定虚拟机应迁移，即使虚拟机被定义为不可迁移。这是可选参数。默认情况下，设置为 false。

6.253.11.3. 主机
复制链接

指定虚拟机应迁移到的特定主机。这是可选参数。默认情况下，Red Hat Virtualization Manager 会自动选择用于在同一集群中迁移的默认主机。如果 API 用户需要特定的主机，用户可以使用 id 或 name 参数指定主机。

6.253.11.4. migrate_vms_in_affinity_closure
复制链接

还使用此虚拟机迁移正强制关联组中的所有其他虚拟机，这些虚拟机在同一主机上运行。

默认值为 false。

6.253.12. previewsnapshot POST
复制链接

将虚拟机临时恢复为快照的状态。

快照通过 snapshot.id 参数来 指示。它会被临时恢复，以便可以检查内容。完成该检查后，可以使用 commit_snapshot 方法使虚拟机的状态变为永久，或使用 undo_snapshot 方法丢弃。

Expand
表 6.781. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该预览。

磁盘

disk[]

in

指定快照预览中包含的磁盘。

lease

StorageDomainLease

in

指定要在快照预览中使用的租用存储域 ID。

restore_memory

布尔值

in

 

snapshot

snapshot

in

 

vm

VM

in

 
6.253.12.1. 磁盘
复制链接

指定快照预览中包含的磁盘。

对于每个磁盘参数，还需要指定其 image_id。

例如：要使用标识符 456 预览快照，其中包括一个标识符为 111 的磁盘 ， 其 image_id 为 222，发送类似如下的请求： 

POST /ovirt-engine/api/vms/123/previewsnapshot

请求正文： 

<action>
  <disks>
    <disk id="111">
      <image_id>222</image_id>
    </disk>
  </disks>
  <snapshot id="456"/>
</action>
6.253.12.2. lease
复制链接

指定要在快照预览中使用的租用存储域 ID。如果没有传递租期参数，则将使用预览的快照租用存储域。如果使用空存储域参数传递租期参数，则快照预览不会使用租用。如果租用参数与存储域参数传递，则存储域 ID 只能是属于其中一个虚拟机快照的租用域 ID 之一。这是一个可选参数，默认设置为 null

6.253.13. 重启 POST
复制链接

将重新引导请求发送到虚拟机.

例如： 

POST /ovirt-engine/api/vms/123/reboot

reboot 操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>

要重新引导虚拟机，即使备份正在运行，该操作应包含"强制"元素。

例如，强制重新引导虚拟机 123: 

POST /ovirt-engine/api/vms/123/reboot
 
<action>
    <force>true</force>
</action>
Expand
表 6.782. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重新引导。

force

布尔值

in

指明是否应强制重新引导虚拟机，即使它正在运行备份。

6.253.14. 删除 DELETE
复制链接

删除虚拟机，包括它所连接的虚拟磁盘。

例如，要删除标识符为 123 的虚拟机： 

DELETE /ovirt-engine/api/vms/123
Expand
表 6.783. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

detach_only

布尔值

in

指明是否应先分离并保留所连接的虚拟磁盘，而不是被删除。

force

布尔值

in

指明是否应强制删除虚拟机。

6.253.14.1. force
复制链接

指明是否应强制删除虚拟机。

如果没有将此标志设为 true，则无法删除带有锁定磁盘镜像的锁定虚拟机和虚拟机。

6.253.15. reordermacaddresses POST
复制链接

Expand
表 6.784. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行该操作。

6.253.16. 重置 POST
复制链接

将重置请求发送到虚拟机.

例如： 

POST /ovirt-engine/api/vms/123/reset

重置操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>
Expand
表 6.785. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行重置。

6.253.17. 截屏 POST
复制链接

捕获虚拟机当前状态的截图。

例如： 

POST /ovirt-engine/api/vms/123/screenshot

截屏操作不会采取任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>

6.253.18. 关闭 POST
复制链接

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

例如： 

POST /ovirt-engine/api/vms/123/shutdown

关闭操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>

要关闭虚拟机，即使备份正在运行，该操作应包括"强制"元素。

例如，强制关闭虚拟机 123: 

POST /ovirt-engine/api/vms/123/shutdown
 
<action>
    <force>true</force>
</action>
Expand
表 6.786. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行关机。

force

布尔值

in

指明即使备份正在为其运行，也是否应强制关闭虚拟机。

reason

字符串

in

虚拟机被停止的原因。

6.253.18.1. reason
复制链接

虚拟机被停止的原因。关闭虚拟机时由用户设置（可选）。

6.253.19. 启动 POST
复制链接

启动虚拟机.

如果虚拟环境已完成，并且虚拟机包含运行所需的所有组件，则可以启动它。

本例启动虚拟机： 

POST /ovirt-engine/api/vms/123/start

通过请求正文： 

<action/>
Expand
表 6.787. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行启动操作。

authorized_key

AuthorizedKey

in

 

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

pause

布尔值

in

如果设为 true，则以暂停模式启动虚拟机。

use_cloud_init

布尔值

in

如果设为 true，初始化类型将设为 cloud-init。

use_ignition

布尔值

in

如果设为 true，初始化类型将设置为 Ignition。

use_initialization

布尔值

in

如果设为 true，则初始化类型由虚拟机的操作系统设置。

use_sysprep

布尔值

in

如果设置为 true，初始化类型将设置为 Sysprep。

vm

VM

in

此特定运行的虚拟机的定义。

volatile

布尔值

in

表示即使 guest 启动重启，此运行配置也会被丢弃。

6.253.19.1. pause
复制链接

如果设为 true，则以暂停模式启动虚拟机。默认值为 false。

6.253.19.2. use_cloud_init
复制链接

如果设为 true，初始化类型将设为 cloud-init。默认值为 false。详情请查看此信息。

6.253.19.3. use_ignition
复制链接

如果设为 true，初始化类型将设置为 Ignition。默认值为 false。详情请查看此信息。

6.253.19.4. use_initialization
复制链接

如果设为 true，则初始化类型由虚拟机的操作系统设置。Windows 将设置为 Sysprep，Linux 设置为 cloud-init，并将红帽 CoreOS 设置为 Ignition。如果明确设置了任何初始化类型（useCloudInit、useSysprep 或 useIgnition），它们将获得优先权，并且忽略此标志。默认值为 false。

6.253.19.5. use_sysprep
复制链接

如果设置为 true，初始化类型将设置为 Sysprep。默认值为 false。详情请查看此信息。

6.253.19.6. vm
复制链接

此特定运行的虚拟机的定义。

例如： 

<action>
  <vm>
    <os>
      <boot>
        <devices>
          <device>cdrom</device>
        </devices>
      </boot>
    </os>
  </vm>
</action>

这将只针对这个特定启动将引导设备设置为 CDROM。虚拟机关闭后，该定义将被恢复。

6.253.19.7. 易失性
复制链接

表示即使 guest 启动重启，此运行配置也会被丢弃。默认值为 false。

6.253.20. 停止 POST
复制链接

此操作会强制虚拟机关闭。

例如： 

POST /ovirt-engine/api/vms/123/stop

stop 操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>

要停止虚拟机，即使备份正在运行，该操作应包含 'force' 元素。

例如，强制停止虚拟机 123: 

POST /ovirt-engine/api/vms/123/stop
 
<action>
    <force>true</force>
</action>
Expand
表 6.788. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应当异步执行停止操作。

force

布尔值

in

指明虚拟机是否应该被强制停止，即使它正在运行备份。

reason

字符串

in

虚拟机被停止的原因。

6.253.20.1. reason
复制链接

虚拟机被停止的原因。关闭虚拟机时由用户设置（可选）。

6.253.21. 挂起 POST
复制链接

此操作会将虚拟机状态保存到磁盘并停止它。启动暂停的虚拟机，并通过 start 操作恢复虚拟机状态。

例如： 

POST /ovirt-engine/api/vms/123/suspend

挂起的操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>
Expand
表 6.789. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行暂停操作。

6.253.22. thawfilesystems POST
复制链接

thaws 虚拟机文件系统.

此操作会在对正在运行的虚拟机执行实时快照时，使用 QEMU 客户机代理修改虚拟机的文件系统。通常，由经理自动执行此操作，但是必须使用 OpenStack 卷(Cinder)磁盘的虚拟机 API 手动执行此操作。

例如： 

POST /api/vms/123/thawfilesystems
 
<action/>
Expand
表 6.790. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应当异步执行 thaw 文件系统操作。

6.253.23. ticket POST
复制链接

生成时间敏感身份验证令牌，用于访问虚拟机的显示。

例如： 

POST /ovirt-engine/api/vms/123/ticket

客户端提供的操作可选包括所需的 ticket 值和/或到期时间（以秒为单位）。

response 指定使用的实际票据值和到期时间。 

<action>
  <ticket>
    <value>abcd12345</value>
    <expiry>120</expiry>
  </ticket>
</action>
重要

如果虚拟机配置为仅支持一个图形协议，则生成的身份验证令牌将对该协议有效。但是，如果虚拟机配置为支持多个协议、VNC 和 SPICE，则身份验证令牌将仅对 SPICE 协议有效。

要获取特定协议（如 VNC）的身份验证令牌，请使用 该服务 的 ticket 方法，它通过发送请求来管理虚拟机的图形控制台： 

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket
Expand
表 6.791. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行生成票据。

ticket

ticket

in/Out

 

6.253.24. undosnapshot POST
复制链接

在预览快照前，将虚拟机恢复到其具有的状态。

详情请查看 preview_snapshot 操作。

Expand
表 6.792. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行撤消快照操作。

6.253.25. 更新 PUT
复制链接

更新系统中给定虚拟机 ID 的虚拟机。

Expand
表 6.793. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

next_run

布尔值

in

指明是否应立即将更新应用到虚拟机，或者是否应当在虚拟机重启后应用更新。

vm

VM

in/Out

 
6.253.25.1. next_run
复制链接

指明是否应立即将更新应用到虚拟机，或者是否应当在虚拟机重启后应用更新。默认值为 false，因此默认情况下会立即应用更改。

6.254. VmApplication
复制链接

此服务提供有关虚拟机中安装的应用程序的信息。

Expand
表 6.794. 方法概述
名称概述

get

返回有关应用的信息。

6.254.1. 获取 GET
复制链接

返回有关应用的信息。

Expand
表 6.795. 参数摘要
名称类型方向概述

应用

Application

out

有关应用的信息。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

6.254.1.1. 应用
复制链接

有关应用的信息。

该信息包含包含应用 名称的 name 属性（这是任意字符串，可能还包含其他信息，如版本）和 vm 属性（标识虚拟机）。

例如，类似如下的请求： 

GET /ovirt-engine/api/vms/123/applications/789

可返回如下信息： 

<application href="/ovirt-engine/api/vms/123/applications/789" id="789">
  <name>ovirt-guest-agent-common-1.0.12-3.el7</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>
6.254.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.255. VmApplications
复制链接

此服务提供有关虚拟机中安装的应用程序的信息。

Expand
表 6.796. 方法概述
名称概述

list

返回虚拟机中安装的应用列表。

6.255.1. 列出 GET
复制链接

返回虚拟机中安装的应用列表。

无法保证返回的应用程序列表的顺序。

Expand
表 6.797. 参数摘要
名称类型方向概述

应用程序

application[]

out

虚拟机中安装的应用程序列表。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大应用程序数。

6.255.1.1. 应用程序
复制链接

虚拟机中安装的应用程序列表。

例如，类似如下的请求： 

GET /ovirt-engine/api/vms/123/applications/

可返回类似如下的列表： 

<applications>
  <application href="/ovirt-engine/api/vms/123/applications/456" id="456">
    <name>kernel-3.10.0-327.36.1.el7</name>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </application>
  <application href="/ovirt-engine/api/vms/123/applications/789" id="789">
    <name>ovirt-guest-agent-common-1.0.12-3.el7</name>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </application>
</applications>
6.255.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.255.1.3. Max
复制链接

设置要返回的最大应用程序数。如果没有指定，则会返回所有应用程序。

6.256. VmBackup
复制链接

管理虚拟机的备份的服务。

Expand
表 6.798. 方法概述
名称概述

Finish

完成虚拟机备份实体。

get

返回有关虚拟机备份的信息。

6.256.1. 最终 POST
复制链接

完成虚拟机备份实体。

最终备份、解锁资源并执行清理。使用 id '123' 和 id '456' 发送请求（如下所示）的备份完成虚拟机： 

POST /ovirt-engine/api/vms/123/backups/456/finalize

请求正文如下： 

<action />

6.256.2. 获取 GET
复制链接

返回有关虚拟机备份的信息。

Expand
表 6.799. 参数摘要
名称类型方向概述

backup

Backup

out

有关虚拟机备份实体的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.256.2.1. backup
复制链接

有关虚拟机备份实体的信息。 

<backups>
  <backup id="backup-uuid">
    <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
    <link href="/ovirt-engine/api/vms/vm-uuid/backups/backup-uuid/disks" rel="disks"/>
    <status>initializing</status>
    <creation_date>
 </backup>
</backups>
6.256.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.257. VmBackupDisk
复制链接

Expand
表 6.800. 方法概述
名称概述

get

检索磁盘的描述。

6.257.1. 获取 GET
复制链接

检索磁盘的描述。

Expand
表 6.801. 参数摘要
名称类型方向概述

disk

Disk

out

磁盘的描述。

follow

字符串

in

指明应遵循哪些内联链接。

6.257.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.258. VmBackupDisks
复制链接

Expand
表 6.802. 方法概述
名称概述

list

返回备份中的磁盘列表。

6.258.1. 列出 GET
复制链接

返回备份中的磁盘列表。

Expand
表 6.803. 参数摘要
名称类型方向概述

磁盘

disk[]

out

检索的磁盘列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

6.258.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.258.1.2. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.259. VmBackups
复制链接

列出虚拟机的备份。

Expand
表 6.804. 方法概述
名称概述

add

将新的备份实体添加到虚拟机。

list

虚拟机备份列表。

6.259.1. 添加 POST
复制链接

将新的备份实体添加到虚拟机。

例如，要从检查点 id 之前-checkpoint-uuid 开始为虚拟机启动新的增量备份，请发送类似如下的请求： 

POST /ovirt-engine/api/vms/123/backups

这样的请求正文： 

<backup>
  <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
  <disks>
      <disk id="disk-uuid" />
      ...
  </disks>
</backup>

响应正文： 

<backup id="backup-uuid">
    <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
    <to_checkpoint_id>new-checkpoint-uuid</to_checkpoint_id>
    <disks>
        <disk id="disk-uuid" />
        ...
        ...
    </disks>
    <status>initializing</status>
    <creation_date>
</backup>

要提供所创建的备份的 ID，请发送类似如下的请求： 

POST /ovirt-engine/api/vms/123/backups

这样的请求正文： 

<backup id="backup-uuid">
  <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
  <disks>
      <disk id="disk-uuid" />
      ...
  </disks>
</backup>
Expand
表 6.805. 参数摘要
名称类型方向概述

backup

Backup

in/Out

有关虚拟机备份实体的信息。

require_consistency

布尔值

in

指明如果虚拟机无法停止，备份是否会失败。

use_active

布尔值

in

指明是否使用活动卷来执行备份。

6.259.1.1. require_consistency
复制链接

指明如果虚拟机无法停止，备份是否会失败。

如果 requireConsistency=True VM 备份失败（如果无法冻结虚拟机）。

REST API 调用应如下所示： 

POST /ovirt-engine/api/vms/123/backups?require_consistency=true

requireConsistency 标志的默认值为 false。

6.259.1.2. use_active
复制链接

指明是否使用活动卷来执行备份。

如果将 useActive=False 创建用于备份操作的快照。

REST API 调用应如下所示： 

POST /ovirt-engine/api/vms/123/backups?use_active=false

useActive 标志的默认值为 false。

6.259.2. 列出 GET
复制链接

虚拟机备份列表。

Expand
表 6.806. 参数摘要
名称类型方向概述

Backups

backup[]

out

有关虚拟机备份实体的信息。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大虚拟机备份数。

6.259.2.1. Backups
复制链接

有关虚拟机备份实体的信息。 

<backups>
  <backup id="backup-uuid">
    <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
    <disks>
      <disk id="disk-uuid" />
      ...
      ...
    </disks>
    <status>initiailizing</status>
    <creation_date>
 </backup>
</backups>
6.259.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.259.2.3. Max
复制链接

设置要返回的最大虚拟机备份数。如果未指定，则返回所有虚拟机备份。

6.260. VmCdrom
复制链接

管理虚拟机的 CDROM 设备。

更改和弹出磁盘应始终使用 update 方法，以更改 file 属性的值。

Expand
表 6.807. 方法概述
名称概述

get

返回有关此 CDROM 设备的信息。

update

更新有关此 CDROM 设备的信息。

6.260.1. 获取 GET
复制链接

返回有关此 CDROM 设备的信息。

该信息由 cdrom 属性组成，其中包含对 CDROM 设备、虚拟机和插入磁盘的引用。

如果插入了磁盘，则 file 属性将包含对 ISO 镜像的引用： 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <file id="mycd.iso"/>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>

如果没有插入磁盘，则不会报告 file 属性： 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>
Expand
表 6.808. 参数摘要
名称类型方向概述

cdrom

cdrom

out

有关 CDROM 设备的信息。

current

布尔值

in

指明操作是否应该返回当前正在运行的虚拟机的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.260.1.1. current
复制链接

指明操作是否应该返回当前正在运行的虚拟机的信息。此参数是可选的，默认值为 false。

6.260.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.260.2. 更新 PUT
复制链接

更新有关此 CDROM 设备的信息。

它可以通过更改 file 属性的值来更改或弹出磁盘。例如，要插入或更改磁盘发送如下请求： 

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000

正文应包含 file 属性的新值： 

<cdrom>
  <file id="mycd.iso"/>
</cdrom>

本示例中 id 属性 mycd.iso 的值应当与附加 ISO 存储域中可用的文件对应。

要弹出磁盘，请使用带有空 id 的文件 ： 

<cdrom>
  <file id=""/>
</cdrom>

默认情况下，上述操作会在下一次启动后永久更改虚拟机可见的磁盘，但它们对当前运行的虚拟机没有任何影响。如果要更改当前正在运行的虚拟机可见的磁盘，请添加 current=true 参数。例如，要弹出当前磁盘发送如下请求： 

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true

这样的请求正文： 

<cdrom>
  <file id=""/>
</cdrom>
重要

使用 current=true 参数所做的更改永远不会保留，因此在虚拟机重启后它们不会有任何影响。

Expand
表 6.809. 参数摘要
名称类型方向概述

cdrom

cdrom

in/Out

有关 CDROM 设备的信息。

current

布尔值

in

指明更新应应用到当前正在运行的虚拟机，还是在下次启动后应用到虚拟机。

6.260.2.1. current
复制链接

指明更新应应用到当前正在运行的虚拟机，还是在下次启动后应用到虚拟机。这个参数是可选的，默认值为 false，这表示默认情况下，更新仅在下一次引导后才会生效。

6.261. VmCdroms
复制链接

管理虚拟机的 CDROM 设备。

目前虚拟机只有一个 CDROM 设备。无法添加新设备，并且无法删除现有设备，因此无法 添加 或删除 方法。更改和弹出 CDROM 磁盘，可使用管理 CDROM 设备的服务的 更新方法。

Expand
表 6.810. 方法概述
名称概述

add

将 cdrom 添加到由给定 ID 标识的虚拟机中。

list

返回虚拟机的 CDROM 设备列表。

6.261.1. 添加 POST
复制链接

将 cdrom 添加到由给定 ID 标识的虚拟机中。

Expand
表 6.811. 参数摘要
名称类型方向概述

cdrom

cdrom

in/Out

 

6.261.2. 列出 GET
复制链接

返回虚拟机的 CDROM 设备列表。

CD-ROM 设备返回列表的顺序不受保证。

Expand
表 6.812. 参数摘要
名称类型方向概述

cdroms

Cdrom[]

out

虚拟机的 CDROM 设备列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大 CDROM 数。

6.261.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.261.2.2. Max
复制链接

设置要返回的最大 CDROM 数。如果没有指定，则返回所有 CDROM。

6.262. VmCheckpoint
复制链接

管理虚拟机的检查点的服务。

Expand
表 6.813. 方法概述
名称概述

get

返回有关虚拟机检查点的信息。

remove

删除虚拟机检查点实体。

6.262.1. 获取 GET
复制链接

返回有关虚拟机检查点的信息。

Expand
表 6.814. 参数摘要
名称类型方向概述

checkpoint

checkpoint

out

有关虚拟机检查点实体的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.262.1.1. checkpoint
复制链接

有关虚拟机检查点实体的信息。 

<checkpoint id="checkpoint-uuid">
 <link href="/ovirt-engine/api/vms/vm-uuid/checkpoints/checkpoint-uuid/disks" rel="disks"/>
 <parent_id>parent-checkpoint-uuid</parent_id>
 <creation_date>xxx</creation_date>
 <vm href="/ovirt-engine/api/vms/vm-uuid" id="vm-uuid"/>
</checkpoint>
6.262.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.262.2. 删除 DELETE
复制链接

删除虚拟机检查点实体。

从 libvirt 和数据库中删除检查点。

Expand
表 6.815. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.263. VmCheckpointDisk
复制链接

Expand
表 6.816. 方法概述
名称概述

get

检索磁盘的描述。

6.263.1. 获取 GET
复制链接

检索磁盘的描述。

Expand
表 6.817. 参数摘要
名称类型方向概述

disk

Disk

out

磁盘的描述。

follow

字符串

in

指明应遵循哪些内联链接。

6.263.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.264. VmCheckpointDisks
复制链接

Expand
表 6.818. 方法概述
名称概述

list

返回检查点中的磁盘列表。

6.264.1. 列出 GET
复制链接

返回检查点中的磁盘列表。

Expand
表 6.819. 参数摘要
名称类型方向概述

磁盘

disk[]

out

检索的磁盘列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

6.264.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.264.1.2. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.265. VmCheckpoints
复制链接

列出虚拟机的检查点。

Expand
表 6.820. 方法概述
名称概述

list

虚拟机检查点列表。

6.265.1. 列出 GET
复制链接

虚拟机检查点列表。

要获取一个带有 id '123' 的虚拟机的检查点列表，请按如下所示发送请求： 

GET /ovirt-engine/api/vms/123/checkpoints
Expand
表 6.821. 参数摘要
名称类型方向概述

checkpoints

checkpoint[]

out

有关虚拟机检查点实体的信息。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大虚拟机检查点数。

6.265.1.1. checkpoints
复制链接

有关虚拟机检查点实体的信息。 

<checkpoints>
  <checkpoint id="checkpoint-uuid">
    <link href="/ovirt-engine/api/vms/vm-uuid/checkpoints/checkpoint-uuid/disks" rel="disks"/>
    <parent_id>parent-checkpoint-uuid</parent_id>
    <creation_date>xxx</creation_date>
    <vm href="/ovirt-engine/api/vm-uuid" id="vm-uuid"/>
 </checkpoint>
</checkpoints>
6.265.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.265.1.3. Max
复制链接

设置要返回的最大虚拟机检查点数。如果没有指定，则返回所有虚拟机检查点。

6.266. VmDisk
复制链接

Expand
表 6.822. 方法概述
名称概述

激活

 

取消激活

 

export

 

get

 

Move

 

减少

减少磁盘镜像的大小。

remove

将磁盘从虚拟机分离。

update

 

6.266.1. 激活 POST
复制链接

Expand
表 6.823. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行激活。

6.266.2. 取消激活 POST
复制链接

Expand
表 6.824. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行取消激活。

6.266.3. 导出 POST
复制链接

Expand
表 6.825. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行导出。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

6.266.4. 获取 GET
复制链接

Expand
表 6.826. 参数摘要
名称类型方向概述

disk

Disk

out

 

follow

字符串

in

指明应遵循哪些内联链接。

6.266.4.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.266.5. 移动 POST
复制链接

Expand
表 6.827. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移动。

filter

布尔值

in

指明是否应根据用户的权限过滤结果。

6.266.6. 减少 POST
复制链接

减少磁盘镜像的大小。

在逻辑卷中调用 less（即，这仅适用于块存储域）。这适用于附加到未运行虚拟机的浮动磁盘和磁盘。无需指定大小，因为会自动计算最佳大小。

Expand
表 6.828. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.266.7. 删除 DELETE
复制链接

将磁盘从虚拟机分离。

注意

在 API 版本 3 中，这曾用于从系统完全删除磁盘，但从版本 4 开始，它不会。如果您需要完全删除它，请使用顶级磁盘服务的删除方法。

Expand
表 6.829. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.266.8. 更新 PUT
复制链接

Expand
表 6.830. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

disk

Disk

in/Out

 

6.267. vmdisks
复制链接

Expand
表 6.831. 方法概述
名称概述

add

 

list

返回虚拟机的磁盘列表。

6.267.1. 添加 POST
复制链接

Expand
表 6.832. 参数摘要
名称类型方向概述

disk

Disk

in/Out

 

6.267.2. 列出 GET
复制链接

返回虚拟机的磁盘列表。

无法保证返回的磁盘列表的顺序。

Expand
表 6.833. 参数摘要
名称类型方向概述

磁盘

disk[]

out

 

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大磁盘数。

6.267.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.267.2.2. Max
复制链接

设置要返回的最大磁盘数。如果没有指定，则返回所有磁盘。

6.268. VmGraphicsConsole
复制链接

Expand
表 6.834. 方法概述
名称概述

get

检索虚拟机的图形控制台配置。

proxyticket

 

remoteviewerconnectionfile

生成与 remote-viewer 客户端兼容的 文件。

remove

从虚拟机中删除图形控制台。

ticket

生成时间敏感身份验证令牌，以访问此虚拟机的控制台。

6.268.1. 获取 GET
复制链接

检索虚拟机的图形控制台配置。

重要

默认情况下，如果没有指定 当前 参数，返回的数据对应于下一次虚拟机执行。在系统的当前实施中，这意味着不会填充 地址 和端口 属性，因为系统不知道将什么地址和端口用于下一次执行。由于在大多数情况下需要这些属性，因此强烈建议您明确包含 当前 参数，值为 true。

Expand
表 6.835. 参数摘要
名称类型方向概述

console

GraphicsConsole

out

有关虚拟机的图形控制台的信息。

current

布尔值

in

指定返回的数据应当与下一次虚拟机执行或当前执行对应。

follow

字符串

in

指明应遵循哪些内联链接。

6.268.1.1. current
复制链接

指定返回的数据应当与下一次虚拟机执行或当前执行对应。

重要

地址和 端口 属性将不会填充，除非值为 true。

例如，要获取当前执行虚拟机的数据，包括 地址 和端口 属性，请发送如下所示的请求： 

GET /ovit-engine/api/vms/123/graphicsconsoles/456?current=true

默认值为 false。

6.268.1.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.268.2. proxyticket POST
复制链接

Expand
表 6.836. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行生成票据。

proxy_ticket

ProxyTicket

out

 

6.268.3. remoteviewerconnectionfile POST
复制链接

生成与 remote-viewer 客户端兼容的 文件。

使用以下请求为图形控制台生成远程查看器连接文件：请注意，只有在虚拟机正在运行时，此操作才会生成 文件。 

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/remoteviewerconnectionfile

remoteviewerconnectionfile 操作不执行任何特定于操作的参数，因此请求正文应包含空 操作 ： 

<action/>

响应中包含 文件，可用于 remote-viewer 客户端。 

<action>
  <remote_viewer_connection_file>
    [virt-viewer]
    type=spice
    host=192.168.1.101
    port=-1
    password=123456789
    delete-this-file=1
    fullscreen=0
    toggle-fullscreen=shift+f11
    release-cursor=shift+f12
    secure-attention=ctrl+alt+end
    tls-port=5900
    enable-smartcard=0
    enable-usb-autoshare=0
    usb-filter=null
    tls-ciphers=DEFAULT
    host-subject=O=local,CN=example.com
    ca=...
  </remote_viewer_connection_file>
</action>

例如，要获取远程查看器连接文件的内容并将其保存到临时文件中，用户可以按如下方式使用 oVirt Python SDK： 

# Find the virtual machine:
vm = vms_service.list(search='name=myvm')[0]

# Locate the service that manages the virtual machine, as that is where
# the locators are defined:
vm_service = vms_service.vm_service(vm.id)

# Find the graphic console of the virtual machine:
graphics_consoles_service = vm_service.graphics_consoles_service()
graphics_console = graphics_consoles_service.list()[0]

# Generate the remote viewer connection file:
console_service = graphics_consoles_service.console_service(graphics_console.id)
remote_viewer_connection_file = console_service.remote_viewer_connection_file()

# Write the content to file "/tmp/remote_viewer_connection_file.vv"
path = "/tmp/remote_viewer_connection_file.vv"
with open(path, "w") as f:
    f.write(remote_viewer_connection_file)

当您创建远程 viewer 连接文件时，您可以连接到虚拟机图形控制台，如下所示： 

#!/bin/sh -ex

remote-viewer --ovirt-ca-file=/etc/pki/ovirt-engine/ca.pem /tmp/remote_viewer_connection_file.vv
Expand
表 6.837. 参数摘要
名称类型方向概述

remote_viewer_connection_file

字符串

out

包含与 remote-viewer 客户端兼容的 文件。

6.268.3.1. remote_viewer_connection_file
复制链接

包含与 remote-viewer 客户端兼容的 文件。

用户可以使用此属性的内容创建 文件，该文件可以传递到 remote-viewer 客户端以连接到虚拟机图形控制台。

6.268.4. 删除 DELETE
复制链接

从虚拟机中删除图形控制台。

Expand
表 6.838. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.268.5. ticket POST
复制链接

生成时间敏感身份验证令牌，以访问此虚拟机的控制台。 

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket

客户端提供的操作可选包括所需的 ticket 值和/或到期时间（以秒为单位）。

在所有情况下，响应都指定使用的实际票据值和到期时间。 

<action>
  <ticket>
    <value>abcd12345</value>
    <expiry>120</expiry>
  </ticket>
</action>
Expand
表 6.839. 参数摘要
名称类型方向概述

ticket

ticket

in/Out

生成可用于访问此控制台的票据。

6.269. VmGraphicsConsoles
复制链接

Expand
表 6.840. 方法概述
名称概述

add

向虚拟机添加新图形控制台。

list

列出虚拟机的所有配置的图形控制台。

6.269.1. 添加 POST
复制链接

向虚拟机添加新图形控制台。

Expand
表 6.841. 参数摘要
名称类型方向概述

console

GraphicsConsole

in/Out

 

6.269.2. 列出 GET
复制链接

列出虚拟机的所有配置的图形控制台。

重要

默认情况下，如果没有指定 当前 参数，返回的数据对应于下一次虚拟机执行。在系统的当前实施中，这意味着不会填充 地址 和端口 属性，因为系统不知道将什么地址和端口用于下一次执行。由于在大多数情况下需要这些属性，因此强烈建议您明确包含 当前 参数，值为 true。

无法保证返回的图形控制台列表的顺序。

Expand
表 6.842. 参数摘要
名称类型方向概述

consoles

GraphicsConsole[]

out

虚拟机的图形控制台列表。

current

布尔值

in

指定返回的数据应当与下一次虚拟机执行或当前执行对应。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大控制台数。

6.269.2.1. current
复制链接

指定返回的数据应当与下一次虚拟机执行或当前执行对应。

重要

地址和 端口 属性将不会填充，除非值为 true。

例如，要获取当前执行虚拟机的数据，包括 地址 和端口 属性，请发送如下所示的请求： 

GET /ovirt-engine/api/vms/123/graphicsconsoles?current=true

默认值为 false。

6.269.2.2. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.269.2.3. Max
复制链接

设置要返回的最大控制台数。如果没有指定，则返回所有控制台。

6.270. VmHostDevice
复制链接

此服务用于管理附加到虚拟机的个别主机设备。

Expand
表 6.843. 方法概述
名称概述

get

检索有关附加到给定虚拟机的特定主机设备的信息。

remove

从给定的虚拟机中删除此主机设备的附件。

6.270.1. 获取 GET
复制链接

检索有关附加到给定虚拟机的特定主机设备的信息。

例如： 

GET /ovirt-engine/api/vms/123/hostdevices/456
 
<host_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
  <name>pci_0000_04_00_0</name>
  <capability>pci</capability>
  <iommu_group>30</iommu_group>
  <placeholder>true</placeholder>
  <product id="0x13ba">
    <name>GM107GL [Quadro K2200]</name>
  </product>
  <vendor id="0x10de">
    <name>NVIDIA Corporation</name>
  </vendor>
  <host href="/ovirt-engine/api/hosts/543" id="543"/>
  <parent_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
    <name>pci_0000_00_03_0</name>
  </parent_device>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</host_device>
Expand
表 6.844. 参数摘要
名称类型方向概述

device

HostDevice

out

检索与给定虚拟机连接的主机设备相关的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.270.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.270.2. 删除 DELETE
复制链接

从给定的虚拟机中删除此主机设备的附件。

注意

如果此设备充当 IOMMU 占位符，则无法删除（删除只会导致 占位符 标记设为 true）。请注意，所有 IOMMU 占位符设备会在没有其他非占位符设备时自动删除（特定 IOMMU 组中的所有设备都将被分离）。 

DELETE /ovirt-engine/api/vms/123/hostdevices/456
Expand
表 6.845. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.271. VmHostDevices
复制链接

用于管理附加到虚拟机的主机设备的服务。

Expand
表 6.846. 方法概述
名称概述

add

将目标设备附加到给定的虚拟机。

list

列出分配到给定虚拟机的主机设备。

6.271.1. 添加 POST
复制链接

将目标设备附加到给定的虚拟机。

例如： 

POST /ovirt-engine/api/vms/123/hostdevices

使用类型为 HostDevice 的请求正文，例如 

<host_device id="123" />
注意

成功附加主机设备的一个必要条件是虚拟机必须固定到一个主机。然后相对于此主机获取设备 ID。

注意

附加作为较大 IOMMU 组一部分的 PCI 设备将导致从该 IOMMU 组附加其余设备作为"占位符"。然后，使用设置为 true 的 HostDevice 类型的 占位符 属性来识别这些设备。

如果您希望附加已充当 IOMMU 占位符的设备，只需为其发出明确的添加操作，并且其 占位符 标志将被清除，并且该设备可以被虚拟机访问。

Expand
表 6.847. 参数摘要
名称类型方向概述

device

HostDevice

in/Out

要附加到给定虚拟机的主机设备。

6.271.2. 列出 GET
复制链接

列出分配到给定虚拟机的主机设备。

无法保证返回的设备列表的顺序。

Expand
表 6.848. 参数摘要
名称类型方向概述

device

HostDevice[]

out

检索到附加到给定虚拟机的主机设备列表。

follow

字符串

in

指明应遵循哪些内联链接。

max

整数

in

设置要返回的最大设备数。

6.271.2.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.271.2.2. Max
复制链接

设置要返回的最大设备数。如果没有指定，则返回所有设备。

6.272. VmMediatedDevice
复制链接

Expand
表 6.849. 方法概述
名称概述

get

检索虚拟机中介质设备的配置。

remove

从虚拟机中删除介质设备。

update

更新有关介质设备的信息。

6.272.1. 获取 GET
复制链接

检索虚拟机中介质设备的配置。

Expand
表 6.850. 参数摘要
名称类型方向概述

device

VmMediatedDevice

out

有关虚拟机的介质设备的信息。

follow

字符串

in

指明应遵循哪些内联链接。

6.272.1.1. follow
复制链接

指明应遵循哪些内联链接。这些链接引用的对象将在当前请求中获取。详情请查看此处。

6.272.2. 删除 DELETE
复制链接

从虚拟机中删除介质设备。

Expand
表 6.851. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行移除。

6.272.3. 更新 PUT
复制链接

更新有关介质设备的信息。

您可以使用 specParams 元素更新信息。

例如，要更新介质设备，请发送如下请求： 

PUT /ovirt-engine/api/vms/123/mediateddevices/00000000-0000-0000-0000-000000000000
<vm_mediated_device>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>

使用响应正文： 

<vm_mediated_device href="/ovirt-engine/api/vms/123/mediateddevices/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>
Expand
表 6.852. 参数摘要
名称类型方向概述

async

布尔值

in

指明是否应异步执行更新。

device

VmMediatedDevice

in/Out

有关介质设备的信息。

6.272.3.1. device
复制链接

有关介质设备的信息。

请求数据必须包含 specParams 属性。响应数据包含有关更新的介质设备的完整信息。

6.273. VmMediatedDevices
复制链接

此服务管理虚拟机的介质设备。

Expand<