3.8. リンクの移動

API は リンク として関連するオブジェクトへの参照を返します。たとえば、仮想マシンを取得すると、ディスクアタッチメントとネットワークインターフェイスカードへのリンクが含まれます。

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <link rel="diskattachments" href="/ovirt-engine/api/vms/123/diskattachments"/>
  <link rel="nics" href="/ovirt-engine/api/vms/123/nics"/>
  ...
</vm>

リンク したオブジェクトの完全な説明は、別の要求を送信することで取得できます。

GET /ovirt-engine/api/vms/123/diskattachments
GET /ovirt-engine/api/vms/123/nics

ただし、状況によっては、API を使用するアプリケーションが同じ要求でリンクされた情報を取得する方が便利な場合があります。追加のネットワークのラウンドトリップが原因でオーバーヘッドが許容できない範囲になったり、複数の要求が原因でアプリケーションのコードが許容できない範囲で複雑化する場合に便利です。これらのユースケースでは、API は、アプリケーションが要求を 1 つだけ使用してリンクされた情報を取得できるようにする follow パラメーターを提供します。

follow パラメーターの値は、コンマで区切られた文字列のリストです。これらの各文字列は、リンクされたオブジェクトの パス です。たとえば、上記の例でディスクの割り当てと NIC を取得するには、要求は以下のようになります。

GET /ovirt-engine/api/vms/123?follow=disk_attachments,nics

これにより、以下のような応答が返されます。

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789"/>
    </disk_attachment>
    ...
  </disk_attacments>
  <nics>
    <nic id="234" href="/ovirt-engine/api/vms/123/nics/234">
      <name>eth0</name>
      <interface>virtio</interface>
      <linked>true</linked>
      <mac>
        <address>00:1a:4a:16:01:00</address>
      </mac>
      <plugged>true</plugged>
    </nic>
    ...
  </nics>
  ...
</vm>

リンクされたオブジェクトへのパスは、前の例のように 1 つの単語とすることも、ドットで区切った単語シーケンスで、入れ子データを要求することもできます。たとえば、前述の例では、ディスク割り当ての説明すべてを取得するために disk_attachments を使用しましたが、各ディスク割り当てにはディスクへのリンクが含まれていますが、各ディスク割当にはそのディスクへのリンクが含まれており、リンクは フォロー されていませんでした。また、ディスクへのリンクをたどるには、以下の要求を使用できます。

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk

これにより、以下の応答が生成されます。

<vm id="123" href="/ovirt-engine/api/vms/123">
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789">
        <name>mydisk</name>
        <description>My disk</description>
        <actual_size>0</actual_size>
        <format>raw</format>
        <sparse>true</sparse>
        <status>ok</status>
        <storage_type>image</storage_type>
        <total_size>0</total_size>
        ...
      </disk>
    </disk_attachment>
    ...
  </disk_attachments>
  ...
</vm>

パスは、必要に応じて階層を深くすることができます。たとえば、ディスクの統計も取得するには、以下のコマンドを実行します。

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics

複数のパス要素と複数のパスを組み合わせることができます。たとえば、ディスクの割り当てとネットワークインターフェイスカードを、どちらも統計で取得するには、次のコマンドを実行します。

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics,nics.statistics