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

Oracle VM Server for SPARC の XML インタフェースには、次の異なる 2 つの形式があります。

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

• 受信メッセージのステータスおよびこのメッセージ内で要求されているアクションに基づいて Logical Domains Manager が応答するための形式。

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

要求メッセージ

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

<LDM_interface version="1.3">
  <cmd>
    <action>Place command here</action>
    <options>Place options for certain commands here</options>
    <arguments>Place arguments for certain commands here</arguments>
    <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> タグには、Example 19–1 に示すようなバージョン属性が含まれている必要があります。

<cmd> タグ

ドキュメントでは、<LDM_interface> タグ内に 1 つ以上の <cmd> タグが含まれている必要があります。各 <cmd> セクションには、<action> タグを 1 つのみ含める必要があります。この <action> タグは、実行するコマンドを記述するために使用します。各 <cmd> タグに 1 つ以上の <data> タグを含めて、コマンドの処理対象のオブジェクトを記述する必要があります。

また、<cmd> タグには <options> タグも含めることができます。このタグは、一部のコマンドに関連付けられたオプションおよびフラグを指定するために使用されます。次のコマンドにはオプションが使用されます。

• ldm remove-domain コマンドには –a オプションを使用できます。

• ldm bind-domain コマンドには、–f オプションを使用できます。

• ldm add-vdsdev コマンドには、–f オプションを使用できます。

• ldm cancel-operation コマンドには、migration または reconf オプションを使用できます。

• ldm add-spconfig コマンドには、–r autosave-name オプションを使用できます。

• ldm remove-spconfig コマンドには、–r オプションを使用できます。

• ldm list-spconfig コマンドには、–r [autosave-name] オプションを使用できます。

• ldm stop-domain コマンドでは、次のタグを使用してコマンド引数を設定できます。

  • <force> は –f オプションを表します。

  • <halt> は –h オプションを表します。

  • <message> は –m オプションを表します。

  • <quick> は –q オプションを表します。

  • <reboot> は –r オプションを表します。

  • <timeout> は –t オプションを表します。

  このタグにはコンテンツ値を指定できません。ただし、–t および –m オプションには、null 以外の値 (<timeout>10</timeout> や <message>Shutting down now</message> など) を指定する必要があります。

次の XML の例は、リブートメッセージを含むリブートリクエストを ldm stop-domain コマンドに渡す方法を示しています。

<action>stop-domain</action>
<arguments>
    <reboot/>
    <message>my reboot message</message>
</arguments>

<data> タグ

各 <data> セクションには、指定したコマンドに関連するオブジェクトの記述を含めます。<data> セクションの形式は、Open Virtualization Format (OVF) ドラフト仕様の XML スキーマ部分に基づいています。このスキーマは、<References> タグ (Oracle VM Server for SPARC では未使用)、<Content> セクション、および <Section> セクションを含む <Envelope> セクションを定義します。

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

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

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

2 つの追加の OVF タイプによって、OVF 仕様のスキーマを使用して、すべてのタイプのオブジェクトを適切に定義できます。

• <gprop:GenericProperty> タグ

• <Binding> タグ

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

応答メッセージ

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

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