2.6. サービスの使用

これらのサービスメソッドは、単一オブジェクトの表現を取得するために使用されます。次の例では、識別子が 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()

レスポンスは、対応するタイプのインスタンスです。この場合は、Python クラス ovirtsdk4.types.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)

詳細は、SDK の リファレンスドキュメント を参照してください。

何らかの理由でオブジェクトを取得できない場合、SDK は失敗の詳細とともに ovirtsdk4.Error 例外を発生させます。これには、オブジェクトが実際には存在しない状況も含まれます。get サービスメソッドを呼び出すと例外が発生するので注意してください。オブジェクトが存在しない場合でも、その呼び出しはサーバーにリクエストを送信しないため、サービスロケーターメソッドの呼び出しが失敗することはありません。以下に例を示します。

# Call the service that manages a non-existent virtual machine.
# This call will succeed.
vm_service = vms_service.vm_service('junk')

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

これらのサービスメソッドは、コレクションのオブジェクトの表現を取得します。この例では、システムの仮想マシンの完全なコレクションを取得します。

# Find the service that manages the collection of virtual
# machines:
vms_service = system_service.vms_service()

# List the virtual machines in the collection
vms = vms_service.list()

結果は、対応するタイプのインスタンスを含む Python リストになります。たとえば、この場合、結果はクラス ovirtsdk4.types.Vm のインスタンスのリストになります。

一部のサービスの list メソッドは、追加のパラメーターをサポートしています。たとえば、ほとんどすべてのトップレベルコレクションは、結果をフィルタリングするための search パラメーターや、サーバーから返される結果の数を制限するための max パラメーターをサポートしています。この例では、my で始まる仮想マシンの名前を取得し、結果数の上限は 10 です。

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

何らかの理由で返された結果のリストが空の場合、戻り値は空のリストになります。None になることはありません。

結果の取得中にエラーが発生した場合、SDK は失敗の詳細を含む ovirtsdk4.Error 例外を発生させます。

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

この例では、vm1 という新しい仮想マシンを追加しています。

from ovirtsdk4 import types

# Add the virtual machine:
vm = vms_service.add(
    vm=types.Vm(
        name='vm1',
        cluster=types.Cluster(
            name='Default'
        ),
        template=types.Template(
            name='mytemplate'
        )
    )
)

何らかの理由でオブジェクトを作成できない場合、SDK は失敗の詳細を含む ovirtsdk4.Error 例外を発生させます。None を返すことはありません。

# 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 になるまで確認する必要があります。

# 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 it is
# completely created:
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.DOWN:
        break

get メソッドで、ループを使用してオブジェクトのステータスを取得すると、ステータス属性が確実に更新されます。

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

この例では、仮想マシンの名前を vm1 から newvm に更新します。

from ovirtsdk4 import types

# Find the virtual machine, and then the service that
# manages it:
vm = vms_service.list(search='name=vm1')[0]
vm_service = vm_service.vm_service(vm.id)

# Update the name:
updated_vm = vm_service.update(
    vm=types.Vm(
        name='newvm'
    )
)

更新を実行する場合、オブジェクトの完全な表現を送信しないでください。更新する属性のみを送信します。以下は実行しないでください。

# Retrieve the complete representation:
vm = vm_service.get()

# Update the representation, in memory, without sending a request
# to the server:
vm.name = 'newvm'

# Send the update. Do *not* do this.
vms_service.update(vm)

完全な表現を送信すると、2 つの問題が発生します。

一部のサービスの update メソッドは、更新方法や更新対象を制御する追加のパラメーターをサポートしています。たとえば、仮想マシンの現在の状態と、次に仮想マシンが起動したときに使用される状態のどちらかを更新するとします。仮想マシンを管理するサービスの update メソッドは、next_run ブール値パラメーターをサポートします。

# Update the memory of the virtual machine to 1 GiB,
# not during the current run, but after next boot:
vm = vm_service.update(
    vm=types.Vm(
        memory=1073741824
    ),
    next_run=True
)

何らかの理由で更新を実行できない場合、SDK は失敗の詳細を含む ovirtsdk4.Error 例外を発生させます。None を返すことはありません。

この update メソッドによって返される Python オブジェクトは、関連するタイプのインスタンスです。これはサービスではなく、データのコンテナーです。この特定の例では、返されるオブジェクトは ovirtsdk4.types.Vm クラスのインスタンスになります。

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

この例では、識別子が 123 の仮想マシンを削除します。

# Find the virtual machine by name:
vm = vms_service.list(search='name=123')[0]

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

# Remove the virtual machine:
vm_service.remove()

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

# Remove the virtual machine while preserving the disks:
vm_service.remove(detach_only=True)

オブジェクトが正常に削除された場合、remove メソッドは None を返します。削除されたオブジェクトは返されません。何らかの理由でオブジェクトを削除できない場合、SDK は失敗の詳細を含む ovirtsdk4.Error 例外を発生させます。

仮想マシンの停止や起動など、さまざまな操作を実行するサービスメソッドもあります。

# Start the virtual machine:
vm_service.start()

これらのメソッドの多くには、操作を変更するパラメーターが含まれています。たとえば、仮想マシンを起動するメソッドは、cloud-init を使用して起動する場合、use_cloud_init パラメーターをサポートします。

# Start the virtual machine:
vm_service.start(cloud_init=True)

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

# Check if the storage domain is attached to a data center:
sds_service = system_service.storage_domains_service()
sd_service = sds_service.storage_domain_service('123')
if sd_service.is_attached():
    ...

SDK の リファレンスドキュメント で、各サービスでサポートされているアクションメソッド、それらが取るパラメーター、および返される値を確認してください。