XML 协议

完成通信初始化后，接下来会发送 Logical Domains 定义的 XML 消息。有以下两种常规 XML 消息类型：

• 请求和响应消息使用 <LDM_interface> 标记。此类型的 XML 消息用于传送命令并从 Logical Domains Manager 获取返回的结果，类似于使用命令行界面 (command-line interface, CLI) 执行命令。此标记还用于事件的注册和注销。

• 事件消息使用 <LDM_event> 标记。此类型的 XML 消息用于异步报告 Logical Domains Manager 发布的事件。

请求和响应消息

结合到 Logical Domains 中的 XML 接口有两种不同的格式：

• 一种格式用于向 Logical Domains Manager 中发送命令

• 另一种格式用于 Logical Domains Manager 响应传入消息的状态以及该消息内请求的操作。

这两种格式共享许多共同的 XML 结构，但为了更好地理解它们之间的差异，在此分别对它们进行讨论。

请求消息

对 Logical Domains Manager 的最基本的传入 XML 请求包括在单个对象上执行的单个命令的描述。更加复杂的请求可以处理多个命令以及每个命令对应的多个对象。下面是 XML 基本命令的结构。

示例 17-1 在单个对象上执行的单个命令的格式

<LDM_interface version="1.3">
  <cmd>
    <action>Place command here</action>
    <option>Place options for certain commands here</option>
    <data version="3.0">
      <Envelope>
        <References/>
        <!-- Note a <Section> section can be here instead of <Content> -->
        <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name">
          <Section xsi:type="ovf:ResourceAllocationSection_type">
            <Item>
              <rasd:OtherResourceType>LDom Resource Type</rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">Property Value</gprop:GenericProperty>
            </Item>
          </Section>
          <!-- Note: More Sections sections can be placed here -->
        </Content>
      </Envelope>
    </data>
    <!-- Note: More Data sections can be placed here -->
  </cmd>
  <!-- Note: More Commands sections can be placed here -->
</LDM_interface>

<LDM_interface> 标记

发送给 Logical Domains Manager 的所有命令都必须以 <LDM_interface> 标记开头。发送到 Logical Domains Manager 的任何文档内必须仅包含一个 <LDM_interface> 标记。<LDM_interface> 标记必须包含如示例 17-1 所示的版本属性。

<cmd> 标记

在 <LDM_interface> 标记内，文档必须至少包含一个 <cmd> 标记。每个 <cmd> 段必须仅包含一个 <action> 标记。<action> 标记用于描述要运行的命令。每个 <cmd> 标记必须至少包含一个 <data> 标记，用于描述要在其上执行命令的对象。

<cmd> 标记还可以包含一个 <option> 标记，用于与某些命令关联的选项和标志。下列命令使用选项：

• remove-domain 命令可使用 -a 选项。

• stop-domain 命令可使用 -f 选项。

• cancel-operation 命令可使用 migration 或 reconf 选项。

• add-spconfig 命令可使用 -r autosave-name 选项。

• remove-spconfig 命令可使用 -r 选项。

• list-spconfig 命令可使用 -r [autosave-name] 选项。

<data> 标记

每个 <data> 段都包含与指定命令相关的对象的描述。数据段的格式基于开放虚拟化格式 (Open Virtualization Format, OVF) 规范草案中的 XML 模式部分。该模式定义了一个 <Envelope> 段（其中包含一个 <References> 标记，未被 Logical Domains 使用）以及 <Content> 和 <Section> 段。

对于 Logical Domains，<Content> 段用于标识和描述特定域。<Content> 节点的 id= 属性中的域名用于标识域。<Content> 段中有一个或多个 <Section> 段，它们根据特定命令需要来描述域的资源。

如果您仅需要标识一个域名，则无需使用任何 <Section> 标记。相反，如果命令不需要任何域标识符，则需要提供一个 <Section> 段（在 <Content> 段之外，但仍在 <Envelope> 段之内）来描述命令所需的资源。

在可以推断出对象信息的情况下，<data> 段不需要包含 <Envelope> 标记。此情况主要适用于对监控适用于操作的所有对象的请求以及事件注册和注销请求。

为允许使用 OVF 规范的模式来正确定义所有类型的对象，定义了两种附加的 OVF 类型：

• <gprop:GenericProperty> 标记

• <Binding> 标记

<gprop:GenericProperty> 标记被定义用于处理 OVF 规范未包含其定义的任意对象的属性。属性名称在节点的 key= 属性中定义，属性的值是节点的内容。<binding> 标记在 list-bindings 子命令输出使用，用于定义绑定到其他资源的资源。

响应消息

从包含的命令和对象上来讲，传出 XML 响应的结构与传入请求的结构很相似，只是添加了针对指定的每个对象和命令的 <Response> 段以及针对请求的总体 <Response> 段。<Response> 段提供如示例 17-2 所述的状态和消息信息。下面是对基本 XML 请求的响应的结构。

示例 17-2 对单个对象上执行的单个命令的响应的格式

<LDM_interface version="1.3">
  <cmd>
    <action>Place command here</action>
    <data version="3.0">
      <Envelope>
        <References/>
        <!-- Note a <Section> section can be here instead of <Content> -->
        <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name">
          <Section xsi:type="ovf:ResourceAllocationSection_type">
            <Item>
              <rasd:OtherResourceType>
                LDom Resource Type
              </rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">
                Property Value
            </gprop:GenericProperty>
            </Item>
          </Section>
          <!-- Note: More <Section> sections can be placed here -->
        </Content>
      </Envelope>
      <response>
        <status>success or failure</status>
        <resp_msg>Reason for failure</resp_msg>
      </response>
    </data>
    <!-- Note: More Data sections can be placed here -->
    <response>
      <status>success or failure</status>
      <resp_msg>Reason for failure</resp_msg>
    </response>
  </cmd>
  <!-- Note: More Command sections can be placed here -->
  <response>
    <status>success or failure</status>
    <resp_msg>Reason for failure</resp_msg>
  </response>
</LDM_interface>

总体响应

此 <response> 段是 <LDM_interface> 段的直接子级，用于指示整个请求的整体成功或失败。除非传入 XML 文档格式错误，否则，<response> 段仅包含一个 <status> 标记。如果此响应状态指示成功，则说明所有对象上的所有命令都已成功。如果此响应状态为失败且没有 <resp_msg> 标记，则说明原始请求中的其中一个命令失败。<resp_msg> 标记仅用于描述 XML 文档自身的一些问题。

命令响应

<cmd> 段下的 <response> 段通知用户特定命令是成功还是失败。<status> 标记显示命令是成功还是失败。与总响应一样，如果命令失败，<response> 段仅包含一个 <resp_msg> 标记（如果请求的 <cmd> 段的内容格式错误）。否则，失败状态表示针对其运行该命令的其中一个对象导致了故障。

对象响应

最后，<cmd> 段中的每个 <data> 段还包含一个 <response> 段。它显示在此特定对象上运行的命令是成功还是失败。如果响应的状态是 SUCCESS，则 <response> 段中不会出现 <resp_msg> 标记。如果状态是 FAILURE，则 <response> 字段中会出现一个或多个 <resp_msg> 标记，具体取决于针对该对象运行命令时遇到的错误。运行命令时出现问题、对象格式错误或未知均可导致对象错误。

除 <response> 段外，<data> 段还可以包含其他信息。此信息的格式与传入 <data> 字段的格式相同，用于描述导致失败的对象。请参见 <data> 标记。此附加信息在以下情况下非常有用：

• 当某命令针对特定 <data> 段失败而针对所有其他 <data> 段成功时

• 当空的 <data> 段传入命令并对一些域失败，而对其他域成功时