Protocole XML

A la fin de l'initialisation de la communication, les messages XML définis par Logical Domains sont envoyés. Il a deux types généraux de messages XML :

• Les messages de demande et de réponse utilisent la balise <LDM_interface>. Ce type de message XML est utilisé pour communiquer les commandes et obtenir les résultats de Logical Domains Manager, comme lors de l'exécution des commandes utilisant l'interface de ligne de commande (CLI). Cette balise est également utilisée pour l'enregistrement et l'annulation de l'enregistrement des événements.

• Les messages d'événement utilisent la balise <LDM_event>. Ce type de message XML est utilisé pour signaler de manière asynchrone les événements postés par Logical Domains Manager.

Messages de demande et de réponse

L'interface XML de Logical Domains a deux formats différents :

• Un format pour envoyer des commandes dans Logical Domains Manager

• Un autre format pour que Logical Domains Manager réponde sur l'état du message entrant et les actions demandées dans le message.

Ces deux formats partagent de nombreuses structures XML communes, mais sont séparés dans cette présentation pour une meilleure compréhension de leurs différences.

Messages de demande

Une demande XML entrante vers Logical Domains Manager à son niveau le plus basique comprend une description d'une seule commande, s'appliquant à un seul objet. Les demandes plus complexes peuvent traiter plusieurs commandes et plusieurs objets par commande. Vous trouverez ci-dessous la structure d'une commande XML basique.

Exemple 17-1 Format d'une commande unique s'appliquant sur un seul objet

<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>

Balise <LDM_interface>

Toutes les commandes envoyées au Logical Domains Manager doivent commencer par la balise <LDM_interface>. Tout document envoyé au Logical Domains Manager doit comporter une balise unique <LDM_interface> contenue dedans. La balise <LDM_interface> doit comprendre un attribut de version comme indiqué dans l'Exemple 17-1.

Balise <cmd>

Dans la balise <LDM_interface>, le document doit inclure au moins une balise <cmd>. Chaque section <cmd> doit comporter uniquement une seule balise <action>. Utilisez la balise <action> pour décrire la commande à exécuter. Chaque balise <cmd> doit inclure au moins une balise <data> pour décrire les objets sur lesquels la commande doit être appliquée.

La balise <cmd> peut également avoir une balise <option>, qui est utilisée pour les options et les indicateurs associés à certaines commandes. Les commandes suivantes utilisent des options :

• La commande remove-domain peut utiliser l'option -a.

• La commande stop-domain peut utiliser l'option -f.

• La commande cancel-operation peut utiliser l'option migration ou reconf.

• La commande add-spconfig peut utiliser l'option -r autosave-name.

• La commande remove-spconfig peut utiliser l'option -r.

• La commande list-spconfig peut utiliser l'option -r [autosave-name].

Balise <data>

Chaque section <data> contient une description d'un objet correspondant à la commande indiquée. Le format de la section de données repose sur la portion de schéma XML de la spécification brouillon OVF (Open Virtualization Format). Le schéma définit une section <Envelope> qui contient une balise <References> (non utilisée par Logical Domains) et des sections <Content> et <Section>.

Pour Logical Domains, la section <Content> est utilisée pour identifier et décrire un domaine particulier. Le nom de domaine dans l'attribut id= du noeud <content> identifie le domaine. Dans la section <Content>, il ya une ou plusieurs sections <Section> décrivant les ressources du domaine comme requis par la commande spécifique.

Si vous devez uniquement identifier un nom de domaine, il est alors inutile d'utiliser des balises <Section>. Au contraire de cela, si aucun identifiant de domaine n'est nécessaire pour la commande, vous devez alors fournir une section <Section>, décrivant les ressources nécessaires à la commande, en dehors de la section <Content>, mais toujours dans la section <Envelope>.

Une section <data> ne doit pas contenir une balise <Envelope> si les informations de l'objet peuvent être induites. Cette situation s'applique principalement aux demandes de surveillance de tous les objets applicables à une action, à l'enregistrement des événements et aux demandes d'annulation d'enregistrement.

Pour permettre l'utilisation du schéma de spécification OVF afin de définir correctement tous les types d'objets, deux types OVF supplémentaires ont été définis :

• Balise <gprop:GenericProperty>

• Balise <Binding>

La balise <gprop:GenericProperty> a été définie pour traiter la propriété de n'importe quel objet pour lequel la spécification OVF n'a pas de définition. Le nom de la propriété est défini dans l'attribut key= du noeud et la valeur de la propriété est le contenu du noeud. La balise <binding> est utilisée dans la sous-commande list-bindings pour définir les ressources liées à d'autres ressources.

Messages de réponse

Une réponse XML sortante correspond étroitement à la structure de la demande entrante en termes de commandes et d'objets inclus, en ajoutant une section <Response> pour chaque objet et commande indiqué, ainsi qu'une section globale <Response> pour la demande. Les sections <Response> fournissent des informations d'état et des messages d'informations, comme décrit dans l'Exemple 17-2. Vous trouverez ci-dessous la structure d'une réponse à une demande XML basique.

Exemple 17-2 Format d'une réponse à une commande unique s'appliquant sur un seul objet

<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>

Réponse globale

Cette section <response>, qui est l'enfant direct de la section <LDM_interface>, indique le succès ou l'échec global de toute la demande. A moins que le document XML entrant ne sont pas correctement formé, la section <response> comprend uniquement une balise <status>. Si l'état de la réponse indique un succès, toutes les commandes sur tous les objets ont abouti. Si cette réponse est un échec et qu'il n'y a pas de balise <resp_msg>, une des commandes inclue dans la demande d'origine a échoué. La balise <resp_msg> est utilisée uniquement pour décrire certains problèmes avec le document XML lui-même.

Réponse de la commande

La section <response> sous la section <cmd> alerte l'utilisateur du succès ou de l'échec de cette commande en particulier. La balise <status> indique si cette commande a abouti ou échoué. Tout comme pour la réponse globale, si la commande échoue, la section <response> comprend uniquement une balise <resp_msg> si le contenu de la section <cmd> de la demande n'est pas correctement formé. Sinon, l'état d'échec signifie qu'un des objets sur lesquels la commande a été exécutée a provoqué une erreur.

Réponse de l'objet

Enfin, la section <data> d'une section <cmd> comporte également une section <response>. Cela indique si la commande en cours d'exécution sur cet objet en particulier aboutit ou échoue. Si l'état de la réponse est SUCCESS, il n'y a pas de balise <resp_msg> dans la section <response>. Si l'état est FAILURE, il y a une ou plusieurs balises <resp_msg> dans la zone <response>, en fonction des erreurs rencontrées lors de l'exécution de la commande sur cet objet. Les erreurs des objets peuvent provenir de problèmes détectés lors de l'exécution de la commande ou d'un objet mal formé ou inconnu.

En plus de la section <response>, la section <data> peut contenir d'autres informations. Ces informations sont dans le même format qu'une zone <data> entrante, décrivant l'objet qui a provoqué l'erreur. Reportez-vous à la section Balise <data>. Ces informations supplémentaires sont surtout utiles dans les cas suivants :

• Lorsqu'une commande échoue sur une section <data> spécifique mais aboutit pour d'autres sections <data>

• Lorsqu'une section <data> est transmise dans une commande et échoue pour certains domaines, mais aboutit pour d'autres