3.6. サービス

サービスは、API がサポートするオブジェクトで取得、更新、削除、および実行を行うサーバーの一部です。

関連するサービスには、以下の 2 つのタイプがあります。

各サービスは、サーバー内の特定の パス からアクセスできます。たとえば、システムで利用可能な仮想マシンのコレクションを管理するサービスは、パス /vms に、仮想マシン 123 を管理するサービスは、パス /vms/123 にあります。

種類が何であってもサービスには、実行できる操作を表す メソッド のセットがあります。オブジェクトのコレクションを管理するサービスは通常、list と add メソッドをサポートします。特定のオブジェクトを管理するサービスには、通常、get、update メソッド、および remove メソッドがあります。さらに、サービスには、あまり一般的ではない操作を表す action メソッドも含まれることがあります。たとえば、Vm サービスには、仮想マシンの起動に使用される start メソッドがあります。

通常のメソッドでは、メソッドの名前と HTTP メソッドの名前の間で直接マッピングされます。

HTTP 要求で使用されるパスは、接頭辞が /ovirt-engine/api のサービスのパスです。

たとえば、仮想マシンを 一覧表示 するリクエストは、HTTP GET メソッドとパス /vms を使用して、以下のように指定します。

GET /ovirt-engine/api/vms

アクションメソッドの場合には、HTTP メソッドは常に POST になり、メソッドの名前が接尾辞としてパスに追加されます。たとえば、仮想マシン 123 を起動する要求は、HTTP POST メソッドとパス /vms/123/start を使用して以下のように指定します。

POST /ovirt-engine/api/vms/123/start

メソッドごとにパラメーターセットがあります。

パラメーターは 2 つのカテゴリーに分類されます。

たとえば、仮想マシンを追加する操作 (こちら を参照) には、vm、clone、および clone_permissions の 3 つのパラメーターがあります。追加するオブジェクトを記述するため、主要パラメーターは vm です。clone および clone_permissions パラメーターはセカンダリーパラメーターです。

入力に使用する主要パラメーターは、HTTP 要求の本文に含める必要があります。たとえば、仮想マシンを追加する場合は、Vm タイプの vm パラメーターをリクエスト本文に含める必要があります。つまり、すべての HTTP の情報が含まれる、仮想マシン追加の完全な要求は、以下のようになります。

POST /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
</vm>

出力に使用すると、主要なパラメーターは応答ボディーに含まれます。たとえば、仮想マシンを追加する場合、vm パラメーターは応答ボディーに含まれます。そのため、完全な応答ボディーは以下のようになります。

HTTP/1.1 201 Created
Content-Type: application/xml

<vm href="/ovirt-engine/api/vms/123" id="123">
  <name>myvm</name>
  <description>My VM</description>
  ...
</vm>

セカンダリーパラメーターは (後に説明している action メソッドを除く) 入力のみが可能で、クエリーパラメーターとして組み込む必要があります。たとえば、clone パラメーターが true に設定された仮想マシンを追加する場合に、完全な要求は以下のようになります。

POST /ovirt-engine/api/vms?clone=true HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
</vm>

action メソッドにはセカンダリーパラメーターだけが含まれます。これらは入出力に使用でき、action 要素でラップされたリクエスト本文に含める必要があります。たとえば、仮想マシンを起動する action メソッド (こちら を参照) には、仮想マシンの起動方法を記述する vm パラメーターと、ゲスト OS を設定するために cloud-init を使用するかどうかを指定する use_cloud_init パラメーターがあります。そのため、XML を使用する場合には、cloud-init を使用して仮想マシン 123 を起動する完全な要求は以下のようになります。

POST /ovirt-engine/api/vms/123/start HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<action>
  <use_cloud_init>true</use_cloud_init>
  <vm>
    <initialization>
      <nic_configurations>
        <nic_configuration>
          <name>eth0</name>
          <on_boot>true</on_boot>
          <boot_protocol>static</boot_protocol>
          <ip>
            <address>192.168.0.100</address>
            <netmask>255.255.255.0</netmask>
            <gateway>192.168.0.1</netmask>
          </ip>
        </nic_configuration>
      </nic_configurations>
      <dns_servers>192.168.0.1</dns_servers>
    </initialization>
  </vm>
</action>