synology_apm.sdk.client module

APMClient — main entry point for the APM Python SDK.

class synology_apm.sdk.client.APMClient(host, username, password, *, otp_code=None, device_id=None, verify_ssl=True, timeout=300.0, debug=False)

Bases: object

Main entry point for the APM Python SDK — manages connections and authentication.

Use the async with syntax to ensure the connection is properly closed and avoid session leaks.

Parameters:

  • host (str) – APM hostname or IP, supports host:port, e.g. “apm.corp.com” or “apm.corp.com:10443”. APM requires HTTPS; the SDK prepends the scheme automatically.

  • username (str) – Login account.

  • password (str) – Login password.

  • otp_code (str | None) – One-time two-factor authentication code. Only meaningful when registering a new trusted device — not needed on ordinary connections once a trusted device has been registered (see the device_id property).

  • device_id (str | None) – A previously-obtained trusted-device identifier that lets this login skip the two-factor code.

  • verify_ssl (bool) – Whether to verify the SSL certificate. Defaults to True. Set to False for self-signed certificates in test environments.

  • timeout (float) – Per-request timeout in seconds. Defaults to 300.

  • debug (bool) – When True, print every request and response to stderr. Defaults to False.

Examples

>>> async with APMClient("apm.corp.com", "admin", "pass") as apm:
...     workloads, total = await apm.machine.workloads.list()
...     print(f"{total} machine workloads found")
async connect()

Establish the connection and initialize the session.

Called automatically when using async with; no need to call manually. After login, verifies the host is the primary management server.

Raises:
async disconnect()

Log out and clean up the session. Safe to call multiple times (idempotent).

property my_server: BackupServer

The primary management server that this client is connected to.

Populated by connect(); always set after a successful connection.

Raises:

AuthenticationError – Not yet connected (connect() has not been called).

property device_id: str | None

The trusted-device id in effect after connect(), if two-factor authentication with a trusted device is in use for this connection.

None if two-factor authentication with a trusted device is not in use.

property machine: MachineCollection

Access MachineCollection, which manages Machine domain backup resources (workload + plan).

apm.machine.workloads → MachineWorkloadCollection apm.machine.plans → MachinePlanCollection

property m365: M365Collection

Access M365Collection, which manages M365 SaaS backup resources (workload + plan).

apm.m365.workloads → M365WorkloadCollection apm.m365.plans → M365PlanCollection apm.m365.exchange_export → ExchangeExportCollection apm.m365.group_export → GroupExportCollection apm.m365.auto_backup_rules → M365AutoBackupRuleCollection

property gws: GWSCollection

Access GWSCollection, which manages Google Workspace SaaS backup resources.

apm.gws.workloads → GWSWorkloadCollection apm.gws.plans → GWSPlanCollection apm.gws.auto_backup_rules → GWSAutoBackupRuleCollection

property saas: SaasCollection

Access SaasCollection, which lists all connected SaaS applications (M365 + GWS).

apm.saas.list() → list[M365TenantInfo | GWSDomainInfo]

property activities: ActivityCollection

Access the global ActivityCollection (site-wide activity records).

property backup_servers: BackupServerCollection

Access BackupServerCollection, which manages backup servers in the cluster.

property retirement_plans: RetirementPlanCollection

Access RetirementPlanCollection, which manages retirement plans.

property remote_storages: RemoteStorageCollection

Access RemoteStorageCollection, which manages remote storage devices (External Vaults).

property hypervisors: HypervisorCollection

Access HypervisorCollection, which manages hypervisor inventory servers.

property logs: LogCollection

Access LogCollection, which queries server-scoped logs.

All methods require a BackupServer to route to the target backup server. Obtain one via apm.backup_servers.get(id) or apm.backup_servers.get_by_name(name).

apm.logs.list_activity(server) → list[APMActivityLog] apm.logs.list_drive(server) → list[DriveLog] apm.logs.list_connection(server) → list[ConnectionLog] apm.logs.list_system(server) → list[SystemLog]

property tiering_plans: TieringPlanCollection

Access TieringPlanCollection, which manages tiering plans.

property plans: ProtectionPlanCollection

Access ProtectionPlanCollection for cross-category plan queries.

For category-specific CRUD (create / update / delete / apply), use APMClient.machine.plans or APMClient.m365.plans instead.

apm.plans.list() → list all plans apm.plans.list(category=…) → filter by WorkloadCategory apm.plans.get(id) → direct UUID lookup (category-agnostic) apm.plans.get_by_name(name) → exact name match (cross-category search)

async download_file(url, dest_path, on_progress=None)

Download a file from an APM-issued URL using the current session credentials.

Streams the file in 64 KB chunks so large PST files do not exhaust memory. The session cookie and SSL settings (verify_ssl) are applied automatically. A failed download never modifies an existing file at dest_path.

Parameters:

  • url (str) – Full HTTPS URL as returned by exchange_export/group_export’s get_download_url_by_*() or machine.workloads.get_verification_video_url().

  • dest_path (str) – Local filesystem path to write the file to.

  • on_progress (Callable[[int, int | None], None] | None) – Optional callback invoked after each chunk. Signature: on_progress(bytes_downloaded, total_bytes_or_none).

async get_site_info()

Fetch complete APM site information.

Makes concurrent calls to retrieve license info, cluster info, storage statistics, and workload statistics; also scans all backup servers to locate the Primary and Secondary Management Servers.

Returns:

SiteInfo object containing site_uuid, external_address, port, primary_management_server (BackupServer or None), secondary_management_server (BackupServer or None), site_storage (SiteStorageStats), and workload_usage (WorkloadUsageSummary).

Return type:

SiteInfo