synology_apm.sdk.models.workload module

Workload data models.

class synology_apm.sdk.models.workload.Workload(workload_id, name, category, namespace, last_backup_at, is_retired, protected_data_bytes, *, status, plan, backup_progress=None, items_backed_up=None, backup_server=None, backup_copy_destination=None, backup_copy_data_bytes=0)

Bases: object

Base class for all Workloads.

Variables:

  • workload_id (str) – Unique workload identifier within APM.

  • name (str) – Display name.

  • category (synology_apm.sdk.enums.WorkloadCategory) – Business domain (MACHINE / M365 / GWS).

  • namespace (str) – Namespace of the owning backup server.

  • last_backup_at (datetime.datetime | None) – Time of the last successful backup; None if never backed up.

  • is_retired (bool) – Whether the workload is retired.

  • protected_data_bytes (int) – Protected data size in bytes.

  • status (synology_apm.sdk.enums.WorkloadStatus) – Current backup status. RETIRED for workloads under a Retirement Plan.

  • plan (synology_apm.sdk.models.protection_plan.ProtectionPlan | synology_apm.sdk.models.retirement_plan.RetirementPlan) – The plan currently applied to this workload (protection or retirement). Only plan_id and name are guaranteed; category is additionally guaranteed only when the plan is a ProtectionPlan (absent on RetirementPlan). Other fields are None unless the full plan was separately fetched via the plans / retirement_plans collection.

  • backup_progress (int | None) – Backup progress percentage (0–100); set for PC/PS/VM when BACKING_UP, else None.

  • items_backed_up (int | None) – Number of items backed up; set for FS/M365/GWS when BACKING_UP, None for PC/PS/VM.

  • backup_server (synology_apm.sdk.models.location.LocationInfo | None) – Backup server location info; None if unknown.

  • backup_copy_destination (synology_apm.sdk.models.location.LocationInfo | None) – Backup Copy destination location info; None if not configured.

  • backup_copy_data_bytes (int) – Backup Copy storage space in bytes; 0 if no Backup Copy is configured.

workload_id: str
name: str
category: WorkloadCategory
namespace: str
last_backup_at: datetime | None
is_retired: bool
protected_data_bytes: int
status: WorkloadStatus
plan: ProtectionPlan | RetirementPlan
backup_progress: int | None = None
items_backed_up: int | None = None
backup_server: LocationInfo | None = None
backup_copy_destination: LocationInfo | None = None
backup_copy_data_bytes: int = 0
property is_backing_up: bool

Whether a backup job is currently running.

to_dict()

Return a JSON-safe dict representation of the fields common to all Workload subclasses.

class synology_apm.sdk.models.workload.MachineWorkload(workload_id, name, category, namespace, last_backup_at, is_retired, protected_data_bytes, workload_type, agent_version, *, status, plan, backup_progress=None, items_backed_up=None, backup_server=None, backup_copy_destination=None, backup_copy_data_bytes=0, verify_status=None, device_uuid=None, ip_address=None, inventory_name=None, inventory_type=None, fs_config=None)

Bases: Workload

Device backup Workload (category=MACHINE).

Covers PCs, physical servers, VMs, and file servers (PC / PS / VM / FS sub-types). The category field is always WorkloadCategory.MACHINE.

Variables:

  • workload_type (synology_apm.sdk.enums.MachineWorkloadType) – Device sub-type (PC / PS / VM / FS).

  • agent_version (str | None) – Installed agent version (PC/PS); None for VM and FS.

  • verify_status (synology_apm.sdk.enums.VerifyStatus | None) – Most recent backup verification result (PS/VM only); None for PC/FS.

  • device_uuid (str | None) – Device UUID (PC/PS/VM); None for FS.

  • ip_address (str | None) – IP address reported by the agent (PC/PS); None for VM and FS.

  • inventory_name (str | None) – Hypervisor inventory name where the VM resides (VM only, and only when linked to a hypervisor inventory); None otherwise.

  • inventory_type (synology_apm.sdk.enums.HypervisorType | None) – Hypervisor type of the inventory the VM resides in (VM only, and only when linked to a hypervisor inventory); None otherwise.

  • fs_config (synology_apm.sdk.models.workload.FileServerConfig | None) – File server connection and scope config (FS only); None for PC/PS/VM.

workload_type: MachineWorkloadType
agent_version: str | None
verify_status: VerifyStatus | None = None
device_uuid: str | None = None
ip_address: str | None = None
inventory_name: str | None = None
inventory_type: HypervisorType | None = None
fs_config: FileServerConfig | None = None
backup_copy_data_bytes: int = 0
backup_copy_destination: LocationInfo | None = None
backup_progress: int | None = None
backup_server: LocationInfo | None = None
property is_backing_up: bool

Whether a backup job is currently running.

items_backed_up: int | None = None
to_dict()

Return a JSON-safe dict representation of the fields common to all Workload subclasses.

workload_id: str
name: str
category: WorkloadCategory
namespace: str
last_backup_at: datetime | None
is_retired: bool
protected_data_bytes: int
status: WorkloadStatus
plan: ProtectionPlan | RetirementPlan
class synology_apm.sdk.models.workload.M365UserInfo(user_principal_name)

Bases: object

User information for a Mailbox / OneDrive / TeamsChat Workload.

user_principal_name: str
property label: str

Standard identifier for the M365 user (User Principal Name).

to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.M365SiteInfo(site_url, site_name)

Bases: object

Site information for a SharePoint Site Workload.

site_url: str
site_name: str
property label: str

Standard identifier for the SharePoint site (Site URL).

to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.M365TeamInfo(team_id, team_name, web_url)

Bases: object

Team information for a Teams Workload.

team_id: str
team_name: str
web_url: str
property label: str

Standard identifier for the Teams workload (Team Web URL).

to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.M365GroupInfo(group_id, display_name, mail)

Bases: object

Group information for a Group Exchange (M365 Group / shared mailbox) Workload.

group_id: str
display_name: str
mail: str
property label: str

Standard identifier for the M365 Group (group mail address).

to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.M365Workload(workload_id, name, category, namespace, last_backup_at, is_retired, protected_data_bytes, workload_type, tenant_id, info, *, status, plan, backup_progress=None, items_backed_up=None, backup_server=None, backup_copy_destination=None, backup_copy_data_bytes=0)

Bases: Workload

Microsoft 365 SaaS backup Workload (category=M365).

Each M365Workload represents one service for one account. The category field is always WorkloadCategory.M365.

Variables:
workload_type: M365WorkloadType
tenant_id: str
info: M365UserInfo | M365SiteInfo | M365TeamInfo | M365GroupInfo
backup_copy_data_bytes: int = 0
backup_copy_destination: LocationInfo | None = None
backup_progress: int | None = None
backup_server: LocationInfo | None = None
property is_backing_up: bool

Whether a backup job is currently running.

items_backed_up: int | None = None
to_dict()

Return a JSON-safe dict representation of the fields common to all Workload subclasses.

workload_id: str
name: str
category: WorkloadCategory
namespace: str
last_backup_at: datetime | None
is_retired: bool
protected_data_bytes: int
status: WorkloadStatus
plan: ProtectionPlan | RetirementPlan
class synology_apm.sdk.models.workload.GWSUserInfo(email)

Bases: object

User information for a Mail / Drive / Contact / Calendar Workload.

email: str
property label: str

Standard identifier for the GWS user (email address).

to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.GWSSharedDriveInfo(drive_id, drive_name)

Bases: object

Shared Drive information for a Shared Drive Workload.

drive_id: str
drive_name: str
property label: str

Standard identifier for the Shared Drive (drive name).

to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.GWSWorkload(workload_id, name, category, namespace, last_backup_at, is_retired, protected_data_bytes, workload_type, domain, info, backup_user=None, is_anomaly=False, *, status, plan, backup_progress=None, items_backed_up=None, backup_server=None, backup_copy_destination=None, backup_copy_data_bytes=0)

Bases: Workload

Google Workspace SaaS backup Workload (category=GWS).

Each GWSWorkload represents one service for one user or shared drive. The category field is always WorkloadCategory.GWS.

Variables:
workload_type: GWSWorkloadType
domain: str
info: GWSUserInfo | GWSSharedDriveInfo
backup_user: str | None = None
is_anomaly: bool = False
backup_copy_data_bytes: int = 0
backup_copy_destination: LocationInfo | None = None
backup_progress: int | None = None
backup_server: LocationInfo | None = None
property is_backing_up: bool

Whether a backup job is currently running.

items_backed_up: int | None = None
to_dict()

Return a JSON-safe dict representation of the fields common to all Workload subclasses.

workload_id: str
name: str
category: WorkloadCategory
namespace: str
last_backup_at: datetime | None
is_retired: bool
protected_data_bytes: int
status: WorkloadStatus
plan: ProtectionPlan | RetirementPlan
class synology_apm.sdk.models.workload.FileServerPathSelector(path, excluded_paths=())

Bases: object

One path scope entry for a File Server backup.

Variables:

  • path (str) – Top-level path to back up; empty string means the whole file server root.

  • excluded_paths (tuple[str, ...]) – Sub-paths to exclude from backup within this path.

path: str
excluded_paths: tuple[str, ...] = ()
to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.FileServerConfig(host_ip, host_port, server_type, login_user, enable_vss, connection_timeout_seconds, selectors)

Bases: object

File server connection settings and backup scope.

Passwords are not included in this model.

Variables:
host_ip: str
host_port: int
server_type: FileServerType
login_user: str
enable_vss: bool
connection_timeout_seconds: int
selectors: tuple[FileServerPathSelector, ...]
to_dict()

Return a JSON-safe dict representation.

class synology_apm.sdk.models.workload.FileServerAddRequest(namespace, host_ip, server_type, plan_id, login_user, login_password, host_port=445, enable_vss=False, connection_timeout_seconds=180, trigger_backup=False, selectors=(FileServerPathSelector(path='', excluded_paths=()),))

Bases: object

Spec for registering one File Server workload in APM.

Variables:

  • namespace (str) – Backup server namespace of the backup server to register this file server with.

  • host_ip (str) – File server IP address.

  • server_type (synology_apm.sdk.enums.FileServerType) – File server protocol / OS type (FileServerType enum).

  • plan_id (str) – UUID of the Protection Plan to apply to this file server.

  • login_user (str) – Login account for the file server.

  • login_password (str) – Login password for the file server (must be non-empty).

  • host_port (int) – Port for the SMB/NAS connection (default 445).

  • enable_vss (bool) – Enable Windows VSS snapshot (SMB only; ignored for other types).

  • connection_timeout_seconds (int) – Connection timeout in seconds (default 180).

  • trigger_backup (bool) – Trigger an immediate backup after successful registration.

  • selectors (tuple[synology_apm.sdk.models.workload.FileServerPathSelector, ...]) – Backup scope selectors; defaults to whole file server root.

Raises:

ValueError – login_password must be non-empty.

namespace: str
host_ip: str
server_type: FileServerType
plan_id: str
login_user: str
login_password: str
host_port: int = 445
enable_vss: bool = False
connection_timeout_seconds: int = 180
trigger_backup: bool = False
selectors: tuple[FileServerPathSelector, ...] = (FileServerPathSelector(path='', excluded_paths=()),)
class synology_apm.sdk.models.workload.FileServerUpdateRequest(host_ip, login_user, login_password, host_port=445, enable_vss=False, connection_timeout_seconds=180, selectors=(FileServerPathSelector(path='', excluded_paths=()),))

Bases: object

Spec for updating an existing File Server workload in APM.

Server type cannot be changed after creation and is not included here.

Variables:

  • host_ip (str) – Updated file server IP address.

  • login_user (str) – Updated login account.

  • login_password (str | None) – Updated password; None keeps the existing stored password. Empty or whitespace-only string is rejected.

  • host_port (int) – Updated connection port (default 445).

  • enable_vss (bool) – Updated VSS setting (SMB only).

  • connection_timeout_seconds (int) – Updated connection timeout in seconds (default 180).

  • selectors (tuple[synology_apm.sdk.models.workload.FileServerPathSelector, ...]) – Updated backup scope selectors.

Raises:

ValueError – login_password is an empty or whitespace-only string (pass None to keep the existing password).

host_ip: str
login_user: str
login_password: str | None
host_port: int = 445
enable_vss: bool = False
connection_timeout_seconds: int = 180
selectors: tuple[FileServerPathSelector, ...] = (FileServerPathSelector(path='', excluded_paths=()),)