synology_apm.sdk.collections.machine module¶

Machine category collections: MachineCollection / MachineWorkloadCollection.

class synology_apm.sdk.collections.machine.MachineCollection(session)¶

Bases: object

Entry collection for Machine category backup resources.

Accessed via APMClient.machine; should not be instantiated directly. Provides workloads and plans sub-collections.

property workloads: MachineWorkloadCollection¶: Access the MachineWorkloadCollection.

property plans: MachinePlanCollection¶: Access the MachinePlanCollection.

class synology_apm.sdk.collections.machine.MachineWorkloadCollection(session)¶

Bases: _VersionMixin

Collection interface for managing device backup Workloads (PC/PS/VM/FS).

Accessed via APMClient.machine.workloads; should not be instantiated directly.

get() fetches a single Workload by workload_id + namespace; get_by_name() looks up a Workload by display name via keyword search and exact match. Neither performs a full list-all scan.

async list(workload_types=None, namespace=None, plan=None, is_retired=False, name_contains=None, hypervisor_id=None, limit=500, offset=0)¶

List device Workloads with optional filtering.

Parameters:

workload_types (list[MachineWorkloadType] | None) – Filter by one or more sub-types (PC / PS / VM / FS); None returns all sub-types.
namespace (str | None) – Return only workloads on a specific backup server (matches workload.namespace).
plan (list[ProtectionPlan | RetirementPlan] | None) – Restrict results to workloads assigned to one of the given plans (OR logic).
is_retired (bool) – Retirement filter: True → retired workloads only. False → protected workloads only (default).
name_contains (str | None) – Name keyword (partial match, case-insensitive).
hypervisor_id (str | None) – Filter VM workloads by hypervisor inventory UUID. Only meaningful for VM workloads.
limit (int) – Maximum records to return (default 500).
offset (int) – Pagination start offset (default 0).

Returns:

(list of Workload, total count matching the filter)

Return type:

tuple[list[MachineWorkload], int]

async get(workload_id, namespace)¶

Fetch a device Workload by ID (direct lookup, no list scan).

Parameters:

workload_id (str) – Workload ID.
namespace (str) – Backup server namespace.

Raises:

ResourceNotFoundError – No workload matches the given workload_id + namespace.

async get_by_name(name, is_retired=False)¶

Fetch a device Workload by display name (keyword search + exact match).

Parameters:

name (str) – Workload display name (exact match, case-insensitive).
is_retired (bool) – True=retired only, False=protected workloads only (default).

Raises:

ResourceNotFoundError – Not found, or name is ambiguous (multiple matches).

async backup_now(workload)¶

Trigger an on-demand backup for a device Workload.

Parameters:: workload (Workload) – Workload object (obtained via get()).
Raises:: InvalidOperationError – The workload is already retired.

async cancel_backup(workload)¶

Cancel the running backup for a device Workload.

Parameters:: workload (Workload) – Workload object (obtained via get()).
Raises:: InvalidOperationError – The workload is already retired.

async add_file_server(request)¶

Parameters:

request (FileServerAddRequest) – FileServerAddRequest describing the file server to register.

Raises:

DuplicateWorkloadError – The file server is already enrolled in the same plan on the same backup server.
AuthenticationError – Session expired.
APIError – Unexpected error from APM.

async update_file_server(workload, request)¶

Update the connection settings and backup scope of an existing File Server workload.

Server type cannot be changed after creation.

Pass None for login_password to keep the existing stored password.

Parameters:

workload (MachineWorkload) – MachineWorkload with workload_type == FS.
request (FileServerUpdateRequest) – FileServerUpdateRequest describing the desired new state.

Raises:

InvalidOperationError – workload is not an FS workload.
DuplicateWorkloadError – The updated IP conflicts with another file server in the same plan.
AuthenticationError – Session expired.
APIError – Unexpected error from APM.

async get_verification_video_url(workload, version)¶

Return a time-limited download URL for the backup verification video of a version.

Only PS and VM workloads produce verification videos; call this only when version.verify_status == VerifyStatus.SUCCESS.

Parameters:

workload (MachineWorkload) – MachineWorkload object (obtained via get()).
version (WorkloadVersion) – WorkloadVersion whose verify_status is SUCCESS.

Returns:

A time-limited HTTPS URL; pass directly to apm.download_file().

Raises:

APIError – APM rejected the request or no verification video exists for this version.

Return type:

str

async retire(workload, plan)¶

Retire a Workload (apply a retirement policy; irreversible).

Parameters:

workload (Workload) – Workload object (obtained via get(); must not be already retired).
plan (RetirementPlan) – RetirementPlan object (obtained via apm.retirement_plans.get() or get_by_name()).

Raises:

InvalidOperationError – The workload is already retired, or APM rejected the retirement because the workload is in a state that does not allow it (e.g., still initializing).

async delete(workload)¶

Delete a Machine Workload from APM.

Parameters:

workload (MachineWorkload) – MachineWorkload to delete. Active and retired workloads are both supported.

Raises:

InvalidOperationError – APM rejected the delete because the workload is in a state that does not allow deletion (e.g., still initializing).
AuthenticationError – Session expired.
APIError – Unexpected error from APM.

async change_plan(workload, plan)¶

Change the Protection Plan or Retirement Plan assigned to a Workload.

Parameters:

workload (Workload) – Workload object (obtained via get() or get_by_name()).
plan (ProtectionPlan | RetirementPlan) – ProtectionPlan (workload must not be retired, and its category must match the workload’s category) or RetirementPlan (workload must already be retired).

Raises:

InvalidOperationError – The plan type does not match the workload’s retirement state, the plan’s category does not match the workload’s category, or APM rejected the change because the workload is in a state that does not allow it (e.g., still initializing).

async get_latest_version(workload)¶

Get the latest backup version for a Workload (list DESC, first result).

Parameters:: workload (Workload) – Workload object (obtained via get()).
Raises:: ResourceNotFoundError – No backup versions exist yet.

async get_version(workload, version_id)¶

Search for a backup version by version_id and return it when found.

Pages through results (50 per page); complements get_latest_version(). The returned WorkloadVersion contains full location data suitable for lock_version() / unlock_version().

Parameters:

workload (Workload) – Workload object (obtained via get()).
version_id (str) – Target version ID.

Raises:

ResourceNotFoundError – The specified version_id was not found.

async list_versions(workload, limit=20, offset=0, since=None, until=None)¶

List backup version history for a Workload (descending order, newest first).

Parameters:

workload (Workload) – Workload object (obtained via get()).
limit (int) – Maximum versions to return.
offset (int) – Pagination start offset (default 0).
since (datetime | None) – Return only versions created after this time.
until (datetime | None) – Return only versions created before this time.

Returns:

Tuple of (versions, total) where total is the count of all matching versions (before limit/offset are applied).

Return type:

tuple[list[WorkloadVersion], int]

async lock_version(version)¶

Lock a backup version to prevent deletion by retention rules.

Parameters:: version (WorkloadVersion) – WorkloadVersion with location data, as returned by list_versions(), get_latest_version(), or get_version().
Raises:: APIError – The version has no location data, or APM rejected the lock operation.

async unlock_version(version)¶

Unlock a backup version, allowing retention rules to delete it.

Parameters:: version (WorkloadVersion) – WorkloadVersion with location data, as returned by list_versions(), get_latest_version(), or get_version().
Raises:: APIError – The version has no location data, or APM rejected the unlock operation.