XML プロトコル

通信の初期化が完了すると、次に Logical Domains 定義の XML メッセージが送信されます。XML メッセージには、次の 2 つの一般的なタイプがあります。

• <LDM_interface> タグを使用する要求メッセージと応答メッセージ。このタイプの XML メッセージは、コマンドの伝達と、Logical Domains Manager からの結果の取得に使用されます。これはコマンド行インタフェース (Command-Line Interface、CLI) を使用したコマンドの実行に類似しています。このタグは、イベントの登録および登録解除にも使用されます。

• <LDM_event> タグを使用するイベントメッセージ。このタイプの XML メッセージは、Logical Domains Manager によって送信されたイベントを非同期に報告するために使用されます。

要求メッセージと応答メッセージ

Logical Domains の XML インタフェースには、次の異なる 2 つの形式があります。

• Logical Domains Manager にコマンドを送信するための形式。

• 受信メッセージの状態およびこのメッセージ内で要求されている処理に基づいて Logical Domains Manager が応答するための形式。

2 つの形式の XML 構造の多くは共通していますが、両者の違いをよく理解するために、ここでは別々に取り扱います。

要求メッセージ

Logical Domains Manager への受信 XML 要求には、もっとも基本的なレベルで、1 つのオブジェクトで動作する 1 つのコマンドの記述が含まれています。要求が複雑になると、1 つのコマンドで複数のコマンドと複数のオブジェクトを処理できます。基本的な XML コマンドの構造は次のとおりです。

例 17-1 1 つのオブジェクトで動作する 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> タグは 1 つのみである必要があります。<LDM_interface> タグには、例 17-1に示すようなバージョン属性が含まれている必要があります。

<cmd> タグ

ドキュメントでは、<LDM_interface> タグ内に 1 つ以上の <cmd> タグが含まれている必要があります。各 <cmd> セクションには、<action> タグを 1 つのみ含める必要があります。この <action> タグは、実行するコマンドを記述するために使用します。各 <cmd> タグに 1 つ以上の <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 スキーマ部分に基づいています。このスキーマは、<References> タグ (Logical Domains では未使用)、<Content> セクション、および <Section> セクションを含む <Envelope> セクションを定義します。

Logical Domains の場合、<Content> セクションは、特定のドメインを指定および記述するために使用されます。<Content> ノードの id= 属性に指定するドメイン名で、ドメインが識別されます。<Content> セクション内には、特定のコマンドの必要に応じて、ドメインのリソースを記述するための <Section> セクションが 1 つ以上あります。

ドメイン名を指定するだけの場合は、<Section> タグを使用する必要はありません。逆に、コマンドでドメイン識別子が不要な場合は、そのコマンドで必要となるリソースを記述した <Section> セクションを、<Content> セクションの外側で、<Envelope> セクションの内側の位置に指定する必要があります。

オブジェクト情報が推測可能な場合は、<data> セクションに <Envelope> タグを含める必要はありません。この状況は主に、ある処理に該当するすべてのオブジェクトの監視要求、イベントの登録および登録解除の要求に当てはまります。

OVF 仕様のスキーマを使用して、すべてのタイプのオブジェクトを適切に定義できるように、さらに 2 つの OVF タイプが定義されています。

• <gprop:GenericProperty> タグ

• <Binding> タグ

<gprop:GenericProperty> タグは、OVF 仕様には定義がないオブジェクトのプロパティーを取り扱うために定義されました。プロパティー名はノードの key= 属性に定義され、プロパティーの値はノードの内容になります。<binding> タグは、ほかのリソースにバインドされたリソースを定義するために、list-bindings サブコマンド出力で使用されます。

応答メッセージ

送信 XML 応答は、含まれているコマンドおよびオブジェクトに関して受信要求と厳密に一致した構造を持ちますが、そのほかに、指定されている各オブジェクトおよび各コマンド用の <Response> セクションと、要求に対する全体の <Response> セクションが追加されています。<Response> セクションでは、例 17-2に示すようなステータスおよびメッセージ情報が提供されます。基本的な XML 要求に対する応答の構造は、次のとおりです。

例 17-2 1 つのオブジェクトで動作する 1 つのコマンドに対する応答の形式

<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> タグは、このコマンドが成功したか失敗したかを示します。全体の応答の場合と同様に、コマンドが失敗した場合で、要求の <cmd> セクションの内容の形式が不正なときは、<response> セクションには <resp_msg> タグのみが含まれます。それ以外の場合の失敗状態は、コマンドが実行されたオブジェクトのいずれかが原因で失敗したことを示しています。

オブジェクトの応答

最後に、<cmd> セクション内の各 <data> セクションにも、<response> セクションがあります。ここでは、この特定のオブジェクトで実行されたコマンドが成功したか失敗したかがわかります。応答の状態が SUCCESS の場合、<response> セクション内に <resp_msg> タグはありません。状態が FAILURE の場合、そのオブジェクトでのコマンドの実行時に発生したエラーに応じて、<response> フィールドには 1 つ以上の <resp_msg> タグがあります。オブジェクトエラーは、コマンドの実行時に検出された問題、または不正な形式または不明なオブジェクトが原因で発生する可能性があります。

<response> セクションのほかに、<data> セクションにその他の情報が含まれていることがあります。この情報は、受信 <data> フィールドと同じ形式で、失敗の原因となったオブジェクトを記述しています。「<data> タグ」 を参照してください。この追加情報は、次の場合に特に有用です。

• コマンドの実行が、特定の <data> セクションに対して失敗したが、別の <data> セクションに対しては成功した場合

• 空の <data> セクションがコマンドに渡されて、一部のドメインでは実行に失敗したが、ほかのドメインでは成功した場合