Protocolo XML

Después de completar la inicialización de la comunicación, los mensajes definidos en XML de Dominios lógicos se envían a continuación. Existen dos tipos generales de mensajes XML:

• Solicitud y respuesta de mensajes, utilice la etiqueta <LDM_interface>. Este tipo de mensaje XML se usa para los comandos de comunicación y obtener resultados del Dominios lógicos Manager, análogo a los comandos de ejecución usando la interfaz de línea de comandos (CLI). Esta etiqueta también se usa para el registro y anulación de registro de eventos.

• Los mensajes de evento usan la etiqueta <LDM_event>. Este tipo de mensaje XML se usa para informar de manera asincrónica de los eventos publicados por el Dominios lógicos Manager.

Mensajes de solicitud y respuesta

La interfaz XML en el Dominios lógicos tiene dos formatos diferentes:

• Un formato para enviar comandos al Dominios lógicos Manager

• Otro formato para el Dominios lógicos Manager para responder sobre el estado del mensaje entrante y las acciones necesarias para ese mensaje.

Los dos formatos comparten muchas estructuras XML comunes, pero están separados en esta sección para entender mejor las diferencias entre ellos.

Mensajes de solicitud

Una solicitud de XML entrante al Dominios lógicos Manager en el nivel más básico incluye una descripción de un solo comando, operando en un solo objeto. Las solicitudes más complicadas pueden manejar múltiples comandos y múltiples objetos por comando. A continuación se muestra la estructura de un comando XML básico.

Ejemplo 17-1 Formato de un solo comando operando en un solo objeto

<LDM_interface version="1.0">
  <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>

La etiqueta<LDM_interface>

Todos los comandos enviados al Dominios lógicos Manager deben empezar por la etiqueta <LDM_interface>. Cualquier documento enviado al Dominios lógicos Manager debe tener sólo una etiqueta <LDM_interface> contenida en el mismo. La etiqueta <LDM_interface> debe incluir un atributo de versión, tal como muestra el Ejemplo 17-1.

La etiqueta <cmd>

En la etiqueta <LDM_interface>, el documento debe contener al menos una etiqueta <cmd>. Cada sección <cmd> debe tener sólo una etiqueta <action>. Use la etiqueta <action> para describir qué comando ejecutar. Cada etiqueta <cmd> debe incluir al menos una etiqueta <data> para describir los objetos en los que debe operar el comando.

La etiqueta <cmd> también puede tener una etiqueta <option>, que se usa para las opciones y etiquetas que están asociadas con algunos comandos. Los siguientes comandos usan las opciones:

• El comando remove-domain puede usar la opción -a.

• El comando stop-domain puede usar la opción -f.

• El comando cancel-operation puede usar la opción migration o reconf.

• El comando add-spconfig puede usar la opción -r autosave-name.

• El comando remove-spconfig puede usar la opción -r.

• El comando list-spconfig puede usar la opción -r [autosave-name].

La etiqueta <data>

Cada sección <data> contiene una descripción de un objeto pertinente al comando especificado. El formato de la sección de datos se basa en la porción del esquema XML del borrador de especificación del formato abierto de virtualización (OVF). Este esquema define una sección <Envelope> que contiene una etiqueta <References> (no usada por Dominios lógicos) y secciones <Content> y <Section>.

Para Dominios lógicos, la sección <Content> se usa para identificar y describir un dominio especial. El nombre de dominio en el id= attribute del nodo <Content> identifica el dominio. En la sección <Content> hay una o varias secciones <Section> que describen los recursos del dominio según lo necesita un comando específico.

Si sólo necesita identificar un nombre de dominio, no necesita usar las etiquetas <Section>. Por el contrario, si no se necesita ningún identificador de dominio para el comando, debe incluir una sección <Section>, que describa los recursos necesarios para el comando, fuera de la sección <Content>, pero dentro de la sección <Envelope>.

Una sección <data> no necesita contener una etiqueta <Envelope> en casos donde la información del objeto puede deducirse. Esta situación afecta sobre todo al seguimiento de todos los objetos aplicables a una acción, y a las solicitudes de registro y eliminación del registro de los eventos.

Para permitir el uso del esquema de especificación OVF para definir correctamente todos los tipos de objetos, se han definido dos OVF adicionales:

• Etiqueta <gprop:GenericProperty>

• Etiqueta <Binding>

La etiqueta <gprop:GenericProperty> se ha definido para manejar cualquier propiedad del objeto para la que la especificación OVF no tiene una definición. El nombre de la propiedad se define en el atributo key= del nodo y el valor de la propiedad son los contenidos del nodo. La etiqueta <binding> se usa en la salida del subcomando list-bindings para definir los recursos que están enlazados a otros recursos.

Mensajes de respuesta

Una respuesta XML saliente corresponde estrechamente con la estructura de solicitud entrante en términos de los comandos y objetos incluidos, con adición de una sección <Response> para cada objeto y comando especificado, así como una sección general <Response> para la solicitud. Las secciones <Response> ofrecen información sobre el estado y el mensaje, como se describe en el Ejemplo 17-2. A continuación se incluye la estructura de una respuesta a una solicitud XML básica.

Ejemplo 17-2 Formato de una respuesta a un comando único operando en un objeto único

<LDM_interface version="1.0">
  <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>

Respuesta general

Esta sección <response>, que es el descendiente directo de la sección <LDM_interface>, indica el éxito o fallo general de toda la solicitud. A menos que el documento XML esté mal formado, la sección <response> incluye sólo una etiqueta <status>. Si este estado de respuesta indica un resultado correcto, todos los comandos en todos los objetos se han efectuado correctamente. Si este estado de respuesta es un fallo y no hay etiqueta <resp_msg>, entonces uno de los comandos incluidos en la solicitud original falla. La etiqueta <resp_msg> se usa sólo para describir algún problema con el mismo documento XML.

Respuesta de comando

La sección <response> bajo la sección <cmd> alerta al usuario del éxito o fallo de este comando particular. La etiqueta <status> muestra si ese comando es correcto o falla. Como con la respuesta general, si el comando falla, la sección <response> incluye sólo una etiqueta <resp_msg> si los contenidos de la sección <cmd> de la solicitud está mal formada. En caso contrario, el estado de fallo significa que uno de los objetos contra el que se ha ejecutado el comando ha provocado un fallo.

Respuesta de objeto

Finalmente, cada sección <data> en la sección <cmd> también tiene una sección <response>. Este muestra si el comando que se ejecuta en este objeto específico es satisfactorio o falla. Si el estado de la respuesta es SUCCESS, no hay etiqueta <resp_msg> en la sección <response>. Si el estado es FAILURE, hay una o más etiquetas <resp_msg> en el campo <response>, dependiendo de los errores detectados cuando se ha ejecutado el comando contra ese objeto. Los errores de objeto pueden derivar de problemas detectados cuando se ha ejecutado el comando, o el objeto está mal formado o es desconocido.

Además de la sección <response>, la sección <data> puede contener otra información. Esta información está en el mismo formato que el campo entrante <data>, que describe el objeto que ha provocado el fallo. Véase La etiqueta <data>. Esta información adicional es especialmente útil en los siguientes casos:

• Cuando un comando falla contra una sección especial <data> pero pasa cualquier sección adicional <data>

• Cuando una sección <data> vacía se pasa en un comando y falla para algunos comandos pero pasa para otros