2.3. サービス

get メソッドは、単一のオブジェクトの表現を取得します。

次の例では、識別子が 123 の仮想マシンの表現を見つけて取得します。

# Find the service that manages the virtual machine:
vms_service = system_service.vms_service
vm_service = vms_service.vm_service('123')

# Retrieve the representation of the virtual machine:
vm = vm_service.get

結果は、対応するタイプのインスタンスになります。この場合、結果は Ruby クラス Vm のインスタンスになります。

一部のサービスの get メソッドは、オブジェクトの表現を取得する方法や、複数の表現がある場合にどの表現を取得するかを制御する追加のパラメーターをサポートします。

たとえば、起動後に仮想マシンの将来の状態を取得したい場合があります。仮想マシンを管理するサービスの get メソッドは、next_run ブール値パラメーターをサポートします。

# Retrieve the representation of the virtual machine; not the
# current one, but the one that will be used after the next
# boot:
vm = vm_service.get(next_run: true)

詳細は、ソフトウェア開発キットの リファレンス ドキュメントを参照してください。

オブジェクトを取得できない場合、ソフトウェア開発キットはエラーの詳細を含む エラー 例外を発生させます。これは、存在しないオブジェクトを取得しようとした場合に発生します。

次の例では、service locator メソッドは成功しますが、get メソッドでは例外が発生します。

# Find the service that manages a virtual machine that does
# not exist. This will succeed.
vm_service = vms_service.vm_service('non_existent_VM')

# Retrieve the virtual machine. This will raise an exception.
vm = vm_service.get

list メソッドは、コレクション内の複数のオブジェクトの表現を取得します。

# Find the service that manages the collection of virtual
# machines:
vms_service = system_service.vms_service
vms = vms_service.list

結果は、対応するタイプのインスタンスを含む Ruby 配列です。上記の例では、Ruby の Vm クラスのインスタンスの一覧が応答として返されます。

一部のサービスの list メソッドは、追加のパラメーターをサポートします。

たとえば、ほとんどすべてのトップレベルコレクションは、結果をフィルタリングするための search パラメーターと、サーバーから返される結果の数を制限するための max パラメーターをサポートしています。

vms = vms_service.list(search: 'name=my*', max: 10)

結果のリストが空の場合、戻り値は空の Ruby 配列になります。nil になることはありません。

結果のリストを取得できない場合、SDK は失敗の詳細を含む エラー 例外を発生させます。

add メソッドは、コレクションに新しい要素を追加します。追加するオブジェクトを記述する関連タイプのインスタンスを受け取り、それを追加するリクエストを送信し、追加されたオブジェクトを記述したタイプのインスタンスを返します。

# Add the virtual machine:
vm = vms_service.add(
  OvirtSDK4::Vm.new(
    name: 'myvm',
    cluster: {
      name: 'mycluster'
    },
    template: {
      name: 'mytemplate'
    }
  )
)

追加した仮想マシンでアクションを実行する必要がある場合は、それを管理するサービスを見つけて、サービスロケーターを呼び出す必要があります。

# Add the virtual machine:
vm = vms_service.add(
  ...
)

# Find the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Start the virtual machine:
vm_service.start

ほとんどのオブジェクトの作成は非同期タスクです。たとえば、新しい仮想マシンを作成する場合、add メソッドは、仮想マシンが完全に作成されて使用できるようになる前に、仮想マシンを返します。オブジェクトが完全に作成されるまで、オブジェクトのステータスをポーリングする必要があります。仮想マシンの場合、ステータスが DOWN になるまでチェックすることを意味します。

推奨されるアプローチは、仮想マシンを作成し、新しい仮想マシンを管理するサービスを見つけて、仮想マシンのステータスが DOWN になるまでステータスを繰り返し取得し、すべてのディスクが作成されたことを示すことです。

# Add the virtual machine:
vm = vms_service.add(
  ...
)

# Find the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Wait until the virtual machine is DOWN, indicating that all the
# disks have been created:
loop do
  sleep(5)
  vm = vm_service.get
  break if vm.status == OvirtSDK4::VmStatus::DOWN
end

オブジェクトを作成できない場合、SDK は失敗の詳細を含む エラー 例外を発生させます。nil を返すことはありません。

Update メソッドは、既存のオブジェクトを更新します。実行する更新を記述した関連タイプのインスタンスを受け取り、それを更新するリクエストを送信し、更新されたオブジェクトを記述したタイプのインスタンスを返します。

次の例では、service locator メソッドが仮想マシンを管理しているサービスを検索し、update メソッドがその名前を更新します。

# Find the virtual machine and the service that
# manages it:
vm = vms_service.list(search: 'name=myvm').first
vm_service = vms_service.vm_service(vm.id)

# Update the name:
updated_vm = vms_service.update(
  OvirtSDK4::Vm.new(
    name: 'newvm'
  )
)

オブジェクトを更新するときは、更新する属性のみを更新します。

vm = vm_service.get
vm.name = 'newvm'

オブジェクト全体を更新しないでください。

# Retrieve the current representation:
vms_service.update(vm)

仮想マシンのすべての属性を更新することはリソースの浪費であり、サーバー側で予期しないバグを引き起こす可能性があります。

一部のサービスの Update メソッドは、更新の方法または内容を制御するために使用できる追加のパラメーターをサポートします。たとえば、仮想マシンのメモリーを現在の状態ではなく、次に起動したときに更新したい場合があります。仮想マシンを管理するサービスの update メソッドは、next_run ブール値パラメーターをサポートします。

vm = vm_service.update(
  OvirtSDK4::Vm.new(
    memory: 1073741824
  ),
  next_run: true
)

更新を実行できない場合、SDK は失敗の詳細を含む エラー 例外を発生させます。nil を返すことはありません。

Remove メソッドは、既存のオブジェクトを削除します。これらは単一のオブジェクトを管理するサービスのメソッドであり、サービスは削除するオブジェクトをすでに認識しているため、通常はパラメーターをサポートしません。

vm_service = vms_service.vm_service('123')
vms_service.remove

一部の remove メソッドは、削除する方法または内容を制御するパラメーターをサポートしています。たとえば、detach_only ブール値パラメーターを使用して、ディスクを保持しながら仮想マシンを削除することができます。

vm_service.remove(detach_only: true)

オブジェクトが正常に削除された場合、remove メソッドは nil を返します。削除されたオブジェクトは返されません。

オブジェクトを削除できない場合、SDK は失敗の詳細を含む エラー 例外を発生させます。

上記の方法とは別に、追加のアクションメソッドがあります。仮想マシンを管理するサービスには、仮想マシンを開始および停止するメソッドがあります。

vm_service.start

一部のアクションメソッドには、操作を変更するパラメーターが含まれています。たとえば、start メソッドは use_cloud_init パラメーターをサポートします。

vm_service.start(use_cloud_init: true)

ほとんどのアクションメソッドは、成功すると nil を返し、失敗すると エラー を発生させます。ただし、一部のアクションメソッドは値を返します。たとえば、ストレージドメインを管理するサービスには、ストレージドメインがすでにデータセンターにアタッチされているかどうかを確認する is_attached アクションメソッドがあります。is_attached アクションメソッドはブール値を返します。

sds_service = system_service.storage_domains_service
sd_service = sds_service.storage_domain_service('123')
if sd_service.is_attached
  ...
end

各サービスでサポートされているアクションメソッド、それらのパラメーター、および戻り値については、ソフトウェア開発キットの リファレンスドキュメント を参照してください。