VMware vSphere Web Services SDK编程指南（四）- vSphere API 编程模型（二）

vSphere API 编程模型（二）

---

本章节主要包括以下内容：

■ vSphere Client-Server 架构
■ vSphere API 作为一个 Web 服务
■ 访问托管对象（Managed Object）
■ 访问 vSphere 服务器数据

由于内容较多，分两篇文章翻译，此篇接前一篇继续

---

3. 访问托管对象（Managed Object）

客户端应用程序通过 ServiceInstance 托管对象及其关联的ServiceContent 数据对象获得对托管对象的访问。
ServiceContent 数据对象包含到服务、管理实体及清单根目录（root folder）的托管对象引用。

ServiceInstance 托管对象是 ESX/ESXi 和 vCenter Server 系统清单的根对象，服务器创建 ServiceInstance 和管理实体在虚拟环境提供服务。管理视图如： LicenseManager、
PerformanceManager 和 ViewManager。

ServiceInstance 是主要的访问服务清单的入口。客户端应用程序首先连接到一个服务器，然后创建一个对 ServiceInstance 的引用。连接上服务器之后，你可以调用 ServiceInstance.RetrieveServiceContent 方法得到一个 ServiceContent 数据对象。ServiceContent 对象提供了到vSphere 托管对象服务的访问。
参阅 Java 示例应用程序概述，以获得连接到服务器的示例，并使用 ServiceInstance 引用获取 ServiceContent 对象。

下图显示了 ServiceInstance 和 ServiceContent 对象的对象模型，图表显示了一些 ServiceContent 托管对象引用及引用的目标的对象，每一个托管对象引用在服务器上标识一个特定的托管对象包括它的类型和值(其 value 属性是隐式的字符串) 。

ManagedObjectReference 数据对象

4. 访问 vSphere 服务器数据

要获得虚拟基础设施的相关信息，你可以重新获取托管对象属性，托管对象属性可以是一个简单数据类型，如 integer 或 string 数据，或者是复杂数据类型如包含一系列属性数据对象。

4.1 从服务器获取信息

通过对托管理对象的引用，你可以获得关于服务器端存清单对象状态的信息，并根据值填充客户端数据对象。可以使用以下方法之一：

■ 使用访问器（getter）。客户代理接口为每个对象属性提供了getter 方法，可以用这些方法获取对象值。

■ 使用 PropertyCollector 定位到服务器上的一个选定点，获取指定的属性值。可查看 PropertyCollector 了解更多有关 PropertyCollector 的信息。

■ 使用 SearchIndex 托管对象获取到你感兴趣的管理实体的托管对象引用，SearchIndex 可返回指定托管对象实体-ComputeResource、Datacenter、 Folder、 HostSystem、ResourcePool、VirtualMachine 的托管对象引用，通过给定一个清单路径，IP 地址或DNS名称。

---

重要： 可以使用 API 方法操作 vSphere 清单上的托管对象，在一个托管对象中更新属性的方法也可以更新其他托管对象的属性。服务器对清单执行异步更新，当方法返回给调用者时，该清单是否被完全更新无法保证。使用 PropertyCollector 方法 WaitForUpdatesEx 获取属性的更改。

---

4.2 使用数据结构

属性包含在给定时间点上有关服务器端对象的信息，一个属性值可能是下列类型中的一个：

• 简单数据类型，如 string， boolean 或 integer 等数据类型。
  例如：ManagedEntity 托管对象有一个 name 属性，其值为 string 类型。

• 简单数据类型数组或数据对象。
  例如： HostSystem 托管对象包含由该物理机承载的虚拟机的托管对象引用(一种数据对象类型)的数组；
  SessionManager 托管对象有一个 sessionList 属性，该属性是 UserSession 数据对象的数组。

• 预定义值的枚举类型，这些值可以是简单数据类型或数据对象的集合。
  例如：虚拟机的电源状态可以是这三种字符值的一种-poweredOn、 poweredOff 或者 suspended.

  属性的类型通常是字符型，但可能实际上期望是枚举封装的值之一。
  例如：当你设置 VirtualMachineConfigSpec 的 guestid 属性，你可以指定其中的 VirtualMachineGuestOSIdentifier 为字符型。

• 复杂数据类型。
  例如： HostProfileConfigInfo 对象包含数据对象、数据对象数组及字符数组。

4.3 访问属性值

要使用包含服务器数据的复合数据结构和数组：

■ 使用点表示法访问复合数据结构中的嵌套属性
■ 将无约束的属性值(xsd:anyType)转换为数组类型
■ 使用适当的键或索引值来访问数组值

复合数据结构中的嵌套属性和属性路径

vSphere 数据对象可以包括定义为复合数据类型的属性，如数据对象。嵌入的数据对象也可以包含数据对象的属性，属性可以嵌套到多个级别。

例如，下图显示了一个 UML VirtualMachine 托管对象的类图，它具有一个被定义为 xsd:dateTime 数据类型 runtime 属性。 VirtualMachine 对象还有一个 summary 属性，该属性是一个 VirtualMachineSummary 数据对象， VirtualMachineSummary 数据对象包含一个 VirtualMachineConfigSummary 数据对象的 config 属性。

VirtualMachine 托管对象 和 嵌入属性

要引用一个嵌套的属性，使用点符号来分隔定义路径到属性的序列中的对象名称，你的代码必须处理序列末尾引用的类型。

例如，你可以比较路径 summary.config.guestId (一个字符串值) 所引用的属性 和 在路径 summary.config (完整的 VirtualMachineSummary 数据对象) 所引用的属性。

下表显示了一些属性引用的例子，以及 VirtualMachine 托管对象的一些属性的对应的数据类型。

嵌套属性和数据类型

引用	数据类型
summary	VirtualMachineSummary 数据对象
summary.config	VirtualMachineConfigSummary 数据对象
summary.config.guestID	字符型

xsd:anyType 数组

vSphere API 使用 xsd:anyType 无约束的类型声明，vSphere 客户端必须映射 xsd:anyType 的值到明确的数据类型，一个 xsd:anyType 值可以表示一个单个数据值或者表示数组。
vSphere API 的 WSDL 为所有的数据值定义了数组类型，所以 vSphere 客户端可以发送或接收这些数据值。

当客户端发送数据到 vSphere 服务器，客户端发送的数据必须用明确的数据类型。
例如，客户端可以为一个 ScheduledTask 定义一个 MethodAction；
vSphere API 定义了对操作的参数(MethodActionArgument.value 属性) 作为类型 xsd:anyType，如果该操作接受了数组参数，则客户端必须设置相应的 MethodAction.argument[].value 为适当的数组类型。

当客户端从 vSphere 服务器接收 xsd:anyType 数据，它必须将数据转为明确的类型。
例如，PropertyCollector 的方法 RetrievePropertiesEx 返回一系列 ObjectContent 数据对象，ObjectContent.propSet 属性是 DynamicProperty 对象列表，其包含了请求的属性值，每个 DynamicProperty 对象包含一组 name-value 对。
value 属性（DynamicProperty.val）是 xsd:anyType 类型，它可以表示单个对象 或 对象数组。

当返回的值是一个单个对象如 Event、ManagedObjectReference 或 String，你可以将其直接转为合适类型的变量。
然而，当返回的值是对象数组，你就不能直接将 anyType 的值转为一个数组变量了。

当 PropertyCollector 返回数组数据，它将其作为 xsd:anyType 值来发送。
特定于语言的绑定包含数组对象的定义如 ArrayOfEvent、ArrayOfManagedObjectReference 和 ArrayOfString 以及对应的 get 方法。
要从类型 xsd:anyType 的属性中提取实际的数组，可将 DynamicProperty.val 转为合适的数组类型并使用匹配的 get 方法—如 getEvent(), getManagedObjectReference(), or getString()。

下面几部分提供了如何为一些数组类型转换返回值的示例。这些代码使用了用于 VMware vSphere Web Services SDK WSDL 的 JAX-WS-generated Java 绑定。每个代码片段都使用下面的逻辑：

■ 使用 DynamicProperty.getVal() 方法获取 anyType 属性值
■ 指定适当的数组类型来转换 anyType 值
■ 使用相应的 get 方法将 cast 操作的结果分配给 list 变量。

Event Array Example

/*
* Handling arrays of Event objects.
* Cast the return value to ArrayOfEvent and use getEvent().
*/
List[] eventList = ((ArrayOfEvent) dynamicProp.getVal()).getEvent();

ManagedObjectReference Array Example

/*
* Handling arrays of ManagedObjectReference objects.
* Cast the return value to ArrayOfManagedObjectReference and use getManagedObjectReference().
*/
List[] morList =
((ArrayOfManagedObjectReference)dynamicProp.getVal()).getManagedObjectReference();

String Array Example

/*
* Handling arrays of strings.
* Cast the return value to ArrayOfString and use getString().
*/
List[] stringList = ((ArrayOfString) dynamicProp.getVal()).getString();

索引数组和 Key-Based 数组属性

VMware vSphere 数据结构包括数组属性，它是可以被索引的数组或基于 key 的数组。

• 索引数组（Indexed arrays）, 通过使用索引来访问，索引数组用于简单数据类型的数组，其在数组中的位置不会改变。
  例如， AuthorizationManager 托管对象的 roleList 属性是一个角色授权的数组，添加一个新的角色到数组中不会改变已存在元素的索引位置。

• 基于 Key 数组（Key-based arrays）, 用于位置会改变的信息对象，一个 key-based 数组使用一个唯一的、不改变的值作为 key 来访问一个元素的值。通常 key 是一个字符串，但是整数也可以用来作为 key。
  例如，Event 数组使用整数作为 key。
  嵌套的属性也可以引用 key-based 数组中的条目。
  例如， a.b.c[“xyz”] ，引用属性 c 有 xyz 的 key 值。

  vSphere 管理对象模型使用 key-based 数组跟踪托管对象引用，key-based 数组属性的内容可以通过键属性的值来访问，或者在托管对象引用的情况下，通过它的值属性来访问。这些字段的值在数组的所有组件中都是惟一的。

4.4 Unset 可选属性

在 vSphere Web Services SDK 中的许多数据对象都有可选属性，这些属性可能由你的客户端应用程序设置或者由服务器进程或事件来设置。
如果你获取到一个数据对象，它有一个 unset 的可选属性，那么服务器将不会为这个可选属性返回值；
如果你调用一个访问器以获取该属性值，通过函数返回的值取决于你用的编程语言。
例如，如果你的编程语言是 Java 或 C#，那么你将获得这个 unset 属性值为 “null”。

下表列出了 HostFirewallInfo 数据对象的部分属性，当你查看 vSphere Web Services SDK API 引用中的属性时，你可以看到，可选属性被标记为红色星号。

数据对象 — HostFirewallInfo 属性

因为数据对象是许多不同构造的一部分，目前没有一个标准的方案对于什么时候一个可选属性应该被设置，如果一个可选属性没有设置，或者如果返回null值，将会发生什么。

4.5 在名称和路径中的转义字符

%用作一个转义字符，用于在字符串中嵌入特殊字符。
例如，%2F 转义为 / ；要在字符串中包含百分号，使用%%；

通往清单的路径从 root folder (ServiceContent.rootFolder 属性)开始，用斜杠表示。

特殊字符

字符	URL中
%	%25
/	%2F, %2f
\	%5C, %5c
-	%2D, %2d
.	%2E, %2e
“	%2B, %2b

---

原文：
VMware vSphere 6.5 Documentation Center：vSphere API Programming Model