第 3 章使用软件开发套件

3.1. 使用 Python 连接 API
复制链接

要使用 Python 连接到 REST API，您需要从 ovirtsdk.api 模块中创建一个 API 类的实例（instance）。要实现这个任务，需要在脚本的开始部分首先导入这个类。

from ovirtsdk.api import API

from ovirtsdk.api import API

Copy to Clipboard

Toggle word wrap

API 类的构造函数支持以下参数：

url

指定要连接到的 Manager 的 URL（包括 /api 路径）。这个参数是必需的。

username

指定连接时使用的用户名（使用 UPD 格式）。这个参数是必需的。

password

指定 username 参数提供的用户的密码。这个参数是必需的。

kerberos

使用有效 Kerberos ticket 验证连接。有效值为 True 和 False。这个参数是自选的。

key_file

指定一个 PEM 格式的密钥文件。这个密钥文件包括了 cert_file 指定的证书的私人密钥。这个参数是可选的。

cert_file

指定一个 PEM 格式的客户端证书。这个证书被用来在服务器上建立客户端的身份。这个选项是可选的。

ca_file

指定服务器证书颁发机构的证书文件。除非 insecure 参数被设置为 True，这个参数是必需的。

port

指定连接使用的端口（当 url 参数没有提供相应信息时有效）。这个参数是可选的。

timeout

一个请求的超时时间（以秒为单位）。这个选项是可选的。

persistent_auth

指定是否为连接建立持久性验证。有效值是 True 和 False。这个参数是可选的，默认值是 False。

insecure

允许通过没有证书颁发机构的 SSL 进行连接。有效值包括 True 和 False。如果 insecure 参数被设置为 False（默认的值），必须在连接时提供 ca_file 来建立安全的连接。

在使用这个选项时需要格外小心。如果使用不当，可能会被"中间人攻击“所利用来进行服务器身份欺骗。

filter

指定是否启用基于用户权限的过滤器。有效值是 True 和 False。如果 filter 参数被设置为 False（默认值），所使用的用户验证信息必须是管理员用户。如果 filter 参数被设置为 True，则任何用户都可以使用，Manager 会根据用户的权限决定用户可以进行什么操作。

debug

指定这个连接是否启用调试（debug）模式。有效值是 True 和 False。这个参数是可选的。

您可以通过创建并使用多个 ovirtsdk.API Python 项实例来和多个 Red Hat Virtualization Managers 进行交流。

这个示例脚本创建一个 API类的实例，使用 test() 方法检查连接是否工作正常，然后使用 disconnect() 方法断开连接。

from ovirtsdk.api import API

api_instance = API ( url="https://rhevm31.demo.redhat.com",
                     username="admin@internal",
                     password="Password",
                     ca_file="/etc/pki/ovirt-engine/ca.pem")

print "Connected successfully!"

api_instance.disconnect()

from ovirtsdk.api import API

api_instance = API ( url="https://rhevm31.demo.redhat.com",
                     username="admin@internal",
                     password="Password",
                     ca_file="/etc/pki/ovirt-engine/ca.pem")

print "Connected successfully!"

api_instance.disconnect()

Copy to Clipboard

Toggle word wrap

有关 API 类所支持的方法的完整列表，请参考 ovirtsdk.api 模块的 pydoc 输出结果。

pydoc ovirtsdk.api

$ pydoc ovirtsdk.api

Copy to Clipboard

Toggle word wrap

3.2. 资源和集合
复制链接

所有使用 REST 的 API 都包括两个关键的概念，您需要对它们有所了解：

Collections

集合就是相同类型的一组资源。API 提供了顶级集合和子集合。hosts 集合是一个顶级集合的例子，它包括了虚拟环境中的所有虚拟主机。host.nics 集合是子集合的一个例子，它包括了附加到一个主机资源上的所有网络接口卡。

集合提供了多个方法来添加资源（add）、获得资源（get）和列出资源（list）。

Resources

REST API 中的资源就是一个带有固定接口的对象，它包括了一组和它所代表的特定资源类型相关的属性。所有资源的接口提供了更新资源（update）和删除资源（delete）的方法。另外，一些资源还额外支持只适用于它们的某些操作，如 Host 资源有一个 approve 方法。

3.3. 从集合中获取资源
复制链接

使用 get 和 list 方法可以从集合中获取资源。

get

从集合中获取一个单一资源。要被获取的资源是由参数中所提供的名称决定的。get 方法可以使用以下参数：

name - 从集合中获取的资源名称。
id - 从集合中获取的资源的 GUID。

list

从集合中获取一组资源。要获得的资源由所提供的条件所决定。list 方法支持以下参数：

**kwargs - 允许进行基于关键字过滤的额外参数字典。
query - 和 Red Hat Virtualization 用户接口中所使用的查询相同的查询。
max - 可以获得的资源的最大数量。
case_sensitive - 指定搜索条件是否区分大小写（True 区分大小写或 False 不区分大小写，默认值是 True）。

3.4. 从集合中获取特定资源
复制链接

在这些示例中，使用 get 方法从集合中获取特定资源。

例 3.1. 获取特定名称的资源

使用 get 方法中的 name 参数从 datacenters 集合中获取 Default 数据中心：

dc = api.datacenters.get("Default")

dc = api.datacenters.get("Default")

Copy to Clipboard

Toggle word wrap

它等同于：

dc = api.datacenters.get(name="Default")

dc = api.datacenters.get(name="Default")

Copy to Clipboard

Toggle word wrap

使用头中包括 all-content 的 get 请求可以获得的额外信息。

例 3.2. 在特定资源中获取额外信息

vm = api.vms.get(name="VM01", all_content=True)

vm = api.vms.get(name="VM01", all_content=True)

Copy to Clipboard

Toggle word wrap

3.5. 从集合中获取资源列表
复制链接

在这些示例中，使用 list 方法从集合中获取一个资源列表。

例 3.3. 获取一个集合中的所有资源列表

获取 datacenters 集合中的所有资源列表。list 的 query 参数可以允许使用基于引擎的查询。这些查询的格式与管理门户和用户门户中所使用的查询格式完全相同。query 参数也提供了设置查询结果分页的功能。

dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
while(len(dc_page_current) != 0):
    dc_list = dc_list + dc_page_current
    dc_page_index = dc_page_index + 1
    dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)

dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
while(len(dc_page_current) != 0):
    dc_list = dc_list + dc_page_current
    dc_page_index = dc_page_index + 1
    dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)

Copy to Clipboard

Toggle word wrap

在这个示例中，datacenters 集合中的资源列表被保存在本地定义的 dc_list 列表变量中。

警告

集合的 list 方法所能获得的结果数量仅由 Red Hat Virtualization Manager 的 SearchResultsLimit 配置值决定。

如需 list 返回所有资源，您可以使用这个示例中所使用的方法来对结果进行分页。

或使用 list 中的 max 参数来指定您需要获取的结果数量的最大值。

例 3.4. 在一个集合中获取一组和关键字过滤器项匹配的资源列表

获取 datacenters 集合中的、存储类型为 nfs 的资源列表。在这个示例中，使用了 query 参数和 **kwargs 参数。query 参数被用来进行分页；**kwargs 参数被用来进行基于存储类型的过滤。

dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
while(len(dc_page_current) != 0):
    dc_list = dc_list + dc_page_current
    dc_page_index = dc_page_index + 1
    dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})

dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
while(len(dc_page_current) != 0):
    dc_list = dc_list + dc_page_current
    dc_page_index = dc_page_index + 1
    dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})

Copy to Clipboard

Toggle word wrap

在这个示例中，datacenters 集合中的、存储类型为 nfs 的资源列表被保存在本地定义的 dc_list 列表变量中。

3.6. 为集合添加一个资源
复制链接

使用集合的 add 方法以及相应的参数可以为这个集合添加一个资源。提供给 add 方法的参数使用 ovirtsdk.xml.params 模块中的一个项实例。

例 3.5. 为集合添加一个资源

在这个例子中，一个虚拟机资源被创建。

vm_params = params.VM(name="DemoVM",
                      cluster=api.clusters.get("Default"),
                      template=api.templates.get("Blank"),
                      memory=536870912)
vm = api.vms.add(vm_params)

vm_params = params.VM(name="DemoVM",
                      cluster=api.clusters.get("Default"),
                      template=api.templates.get("Blank"),
                      memory=536870912)
vm = api.vms.add(vm_params)

Copy to Clipboard

Toggle word wrap

这个例子所创建的虚拟机在现阶段还无法运行，但它展示了创建 Red Hat Virtualization 资源的以下过程：

创建一个参数项实例来代表要被创建的资源类型。
指定资源要被添加到的集合。
调用集合的 add 方法，使用操作项作为一个参数。

以下参数项也会带有它们自己的复杂参数。

例 3.6. 复杂参数

在这个示例中，一个运行在版本 4.1 完全兼容模式下的 NFS 数据中心被创建。要实现这个操作，首先需要创建一个 ovirtsdk.xml.params.Version 项。然后，在创建 ovirtsdk.xml.params.DataCenter 项实例中使用这个项（包括了要被创建的数据中心的参数）。最后，使用 datacenters 集合的 add 方法创建资源。

v_params = params.Version(major=4, minor=0)
dc_params = params.DataCenter(name="DemoDataCenter", storage_type="NFS", version=v_params)
dc = api.datacenters.add(dc_params)

v_params = params.Version(major=4, minor=0)
dc_params = params.DataCenter(name="DemoDataCenter", storage_type="NFS", version=v_params)
dc = api.datacenters.add(dc_params)

Copy to Clipboard

Toggle word wrap

3.7. 更新集合中的资源
复制链接

要更新一个资源，您需要先从集合中获得它，然后修改所需的参数，为资源调用 update 方法来保存所做的修改。对参数的修改操作是通过使用所获取的资源的 set_* 方法进行的。

例 3.7. 更新资源

在这个示例中，名为 DemoDataCenter 的数据中心的描述信息被更新。

dc = api.datacenters.get("DemoDataCenter")
dc.set_description("This data center description provided using the Python SDK")
dc.update()

dc = api.datacenters.get("DemoDataCenter")
dc.set_description("This data center description provided using the Python SDK")
dc.update()

Copy to Clipboard

Toggle word wrap

3.8. 从集合中删除资源
复制链接

要删除一个资源，您需要先从集合中获得它，然后调用 delete 方法来删除它。

例 3.8. 从集合中删除资源

从 vms 集合中删除一个名为 DemoVM 的虚拟机：

vm = api.vms.get("DemoVM")
vm.delete()

vm = api.vms.get("DemoVM")
vm.delete()

Copy to Clipboard

Toggle word wrap

3.9. 错误处理
复制链接

当错误发生时，软件开发套件会使用异常（exception）来标识这些错误。软件开发套件定义了除标准 Python 异常外的额外异常。这些异常位于 ovirtsdk.infrastructure.errors 模块中：

ConnectionError: 在传输层错误发生时出现。
DisconnectedError: 当试图在断开连接后使用 SDK 时出现。
ImmutableError: 当一个 SDK 实例已经在相同的域中存在时初始 SDK 会出现这个错误。只适用于 SDK 3.2 或更高版本。
NoCertificatesError: 当 --insecure 是 'False'，而没有提供 CA 时出现。
RequestError: 在有 oVirt 服务器错误时出现
UnsecuredConnectionAttemptError: 当服务器运行 HTTPS 而使用 HTTP 时出现。
MissingParametersError: 在没有为 get() 方法提供 id 或 name 参数的情况下出现。

这些异常的捕获和处理方法与其它 Python 异常的捕获和处理方法完全相同：

例 3.9. 捕获一个 ConnectionError 异常

from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="https://_HOST_",
              user="_USER_,
              pass="_PASS_,
              ca_file="/etc/pki/ovirt-engine/ca.pem")
except ConnectionError, err:
print "Connection failed: %s" % err

from ovirtsdk.api import API
from ovirtsdk.xml import params

try:
    api = API(url="https://_HOST_",
              user="_USER_,
              pass="_PASS_,
              ca_file="/etc/pki/ovirt-engine/ca.pem")
except ConnectionError, err:
print "Connection failed: %s" % err

Copy to Clipboard

Toggle word wrap

3.1. 使用 Python 连接 API
复制链接

3.2. 资源和集合
复制链接

3.3. 从集合中获取资源
复制链接

3.4. 从集合中获取特定资源
复制链接

3.5. 从集合中获取资源列表
复制链接

3.6. 为集合添加一个资源
复制链接

3.7. 更新集合中的资源
复制链接

3.8. 从集合中删除资源
复制链接

3.9. 错误处理
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 3 章 使用软件开发套件

3.1. 使用 Python 连接 API复制链接链接已复制到粘贴板!

3.2. 资源和集合复制链接链接已复制到粘贴板!

3.3. 从集合中获取资源复制链接链接已复制到粘贴板!

3.4. 从集合中获取特定资源复制链接链接已复制到粘贴板!

3.5. 从集合中获取资源列表复制链接链接已复制到粘贴板!

3.6. 为集合添加一个资源复制链接链接已复制到粘贴板!

3.7. 更新集合中的资源复制链接链接已复制到粘贴板!

3.8. 从集合中删除资源复制链接链接已复制到粘贴板!

3.9. 错误处理复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 3 章使用软件开发套件

3.1. 使用 Python 连接 API
复制链接

3.2. 资源和集合
复制链接

3.3. 从集合中获取资源
复制链接

3.4. 从集合中获取特定资源
复制链接

3.5. 从集合中获取资源列表
复制链接

3.6. 为集合添加一个资源
复制链接

3.7. 更新集合中的资源
复制链接

3.8. 从集合中删除资源
复制链接

3.9. 错误处理
复制链接