第 3 章 REST API 快速入门示例
本章介绍了一个示例，它演示了 REST API 能够设置基本的 Red Hat Virtualization 环境并创建虚拟机。
除了标准先决条件外，此示例还需要以下内容：
- A networked and configured Red Hat Virtualization Host;
- 包含要安装的所需虚拟机操作系统的 ISO 文件。本章使用 Red Hat Enterprise Linux Server 6 进行我们的安装 ISO 示例；以及
- Red Hat Virtualization 的 engine-iso-uploader 工具上传您选择的操作系统 ISO 文件。
本例使用 cURL 来通过客户端应用程序演示 REST 请求。请注意，任何支持 HTTP 请求的应用程序都可以替换 cURL。
重要的
为简单起见，本例中的 HTTP 请求标头省略
Host: 和 Authorization: 字段。但是，这些字段是必须的，需要特定于您的 Red Hat Virtualization Manager 安装的数据。
重要的
所有 cURL 示例包括身份验证详细信息的占位符(
USER:PASS)和证书位置(CERT)。确保通过 cURL 执行的所有请求均满足认证和身份验证要求。
备注
Red Hat Virtualization Manager 为每个资源的
id 属性生成全局唯一标识符(GUID)。本例中的标识符代码可能与 Red Hat Virtualization 环境中的标识符代码不同。
3.1. 示例：访问 API 条目点
以下请求检索 API 版本 3 的主入口点的表示。
例 3.1. 访问 API v3 入口点
Request （带有标头）：
GET /ovirt-engine/api HTTP/1.1 Version: 3 Accept: application/xml
请求（不带标头）：
GET /ovirt-engine/api/v3 HTTP/1.1 Accept: application/xml
curl 命令：
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] https://[RHEVM Host]:443/ovirt-engine/api
结果：
HTTP/1.1 200 OK
Content-Type: application/xml
<api>
<link rel="capabilities" href="/ovirt-engine/api/capabilities"/>
<link rel="clusters" href="/ovirt-engine/api/clusters"/>
<link rel="clusters/search" href="/ovirt-engine/api/clusters?search={query}"/>
<link rel="datacenters" href="/ovirt-engine/api/datacenters"/>
<link rel="datacenters/search" href="/ovirt-engine/api/datacenters?search={query}"/>
<link rel="events" href="/ovirt-engine/api/events"/>
<link rel="events/search" href="/ovirt-engine/api/events?search={query}"/>
<link rel="hosts" href="/ovirt-engine/api/hosts"/>
<link rel="hosts/search" href="/ovirt-engine/api/hosts?search={query}"/>
<link rel="networks" href="/ovirt-engine/api/networks"/>
<link rel="roles" href="/ovirt-engine/api/roles"/>
<link rel="storagedomains" href="/ovirt-engine/api/storagedomains"/>
<link rel="storagedomains/search" href="/ovirt-engine/api/storagedomains?search={query}"/>
<link rel="tags" href="/ovirt-engine/api/tags"/>
<link rel="templates" href="/ovirt-engine/api/templates"/>
<link rel="templates/search" href="/ovirt-engine/api/templates?search={query}"/>
<link rel="users" href="/ovirt-engine/api/users"/>
<link rel="groups" href="/ovirt-engine/api/groups"/>
<link rel="domains" href="/ovirt-engine/api/domains"/>
<link rel="vmpools" href="/ovirt-engine/api/vmpools"/>
<link rel="vmpools/search" href="/ovirt-engine/api/vmpools?search={query}"/>
<link rel="vms" href="/ovirt-engine/api/vms"/>
<link rel="vms/search" href="/ovirt-engine/api/vms?search={query}"/>
<special_objects>
<link rel="templates/blank"
href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000"/>
<link rel="tags/root"
href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000"/>
</special_objects>
<product_info>
<name>Red Hat Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="0" major="4"/>
</product_info>
<summary>
<vms>
<total>5</total>
<active>0</active>
</vms>
<hosts>
<total>1</total>
<active>1</active>
</hosts>
<users>
<total>1</total>
<active>1</active>
</users>
<storage_domains>
<total>2</total>
<active>2</active>
</storage_domains>
</summary>
</ovirt-engine/api>
重要
如果没有使用标头和 URL 前缀，服务器会自动选择版本。默认为版本
4。您可以使用 ENGINE_API_DEFAULT_VERSION 参数更改默认版本：
# echo "ENGINE_API_DEFAULT_VERSION=3" > \ /etc/ovirt-engine/engine.conf.d/99-set-default-version.conf # systemctl restart ovirt-engine
更改此参数会影响未明确指定版本的管理器的所有用户。
该入口点为用户提供了到虚拟化环境中的集合的链接。每个集合链接的
rel= 属性为每个链接提供一个参考点。本示例中的下一步将检查 datacenter 集合，该集合可通过 rel="datacenter" 链接获得。
入口点还包含其他数据，如
product_info、special_objects 和 summary。该数据在本示例之外的章节中阐述。
