synology_apm.sdk.client module

APMClient — main entry point for the APM Python SDK.

class synology_apm.sdk.client.APMClient(host, username, password, *, 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.

  • 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 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

property saas: SaasCollection

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

apm.saas.list() → list[SaasTenant]

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.

apm.retirement_plans.list() → list[RetirementPlan] apm.retirement_plans.get(id) → RetirementPlan apm.retirement_plans.get_by_name(name) → RetirementPlan

property remote_storages: RemoteStorageCollection

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

apm.remote_storages.list() → list[RemoteStorage] apm.remote_storages.get(id) → RemoteStorage

property hypervisors: HypervisorCollection

Access HypervisorCollection, which manages hypervisor inventory servers.

apm.hypervisors.list() → list[Hypervisor] apm.hypervisors.get(id) → Hypervisor

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.

apm.tiering_plans.list() → list[TieringPlan] apm.tiering_plans.get(id) → TieringPlan apm.tiering_plans.get_by_name(name) → TieringPlan

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.

Parameters:

  • url (str) – Full HTTPS URL as returned by exchange_export.get_download_url_by_*().

  • 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).

Raises:
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).

Raises:
Return type:

SiteInfo