synology_apm.sdk.collections.m365 module¶

M365Collection — entry collection for M365 SaaS backup resources.

class synology_apm.sdk.collections.m365.M365WorkloadCollection(session)¶

Bases: _VersionMixin

Collection interface for managing M365 SaaS backup Workloads.

Accessed via APMClient.m365.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, UPN, or group email via keyword search and exact match. Neither performs a full list-all scan.

async list(tenant_id, workload_type, namespace=None, plan=None, keyword=None, is_retired=False, limit=500, offset=0)¶

List M365 Workloads of a given service sub-type for a tenant.

Parameters:

tenant_id (str) – Azure AD tenant ID (required).
workload_type (M365WorkloadType) – Service sub-type to list (EXCHANGE / ONEDRIVE / etc.).
namespace (str | None) – Return only workloads on a specific backup server (= workload.namespace). The SDK resolves the namespace to an internal backup server reference automatically.
plan (list[ProtectionPlan | RetirementPlan] | None) – Restrict results to workloads assigned to one of the given plans (OR logic).
keyword (str | None) – Name keyword (partial match).
is_retired (bool) – True = retired only; False = protected workloads only (default).
limit (int) – Maximum records to return (default 500).
offset (int) – Pagination start offset (default 0).

Returns:

(list of M365Workload, total count).

Raises:

ResourceNotFoundError – No backup server matching the specified namespace exists.

Return type:

tuple[list[M365Workload], int]

async get(workload_id, namespace, tenant_id, workload_type)¶

Fetch an M365 Workload by workload ID and backup server namespace.

Parameters:

workload_id (str) – Workload ID.
namespace (str) – Backup server namespace.
tenant_id (str) – Azure AD tenant ID.
workload_type (M365WorkloadType) – Service sub-type (EXCHANGE / ONEDRIVE / etc.).

Raises:

ResourceNotFoundError – No workload matches the given workload_id + namespace.

async get_by_name(name, tenant_id, workload_type, is_retired=False)¶

Fetch an M365 Workload by name, UPN, or group email (keyword search + exact match).

Parameters:

name (str) – Display name, UPN, or group email (exact match, case-insensitive); a workload ID is also accepted.
tenant_id (str) – Azure AD tenant ID; required to scope the search.
workload_type (M365WorkloadType) – Service sub-type (EXCHANGE / ONEDRIVE / etc.).
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 an M365 Workload.

Parameters:

workload (M365Workload) – M365Workload object (obtained via get()).

Raises:

InvalidOperationError – The workload is already retired.
APIError – APM rejected the backup request.

async cancel_backup(workload)¶

Cancel the running backup for an M365 Workload.

Parameters:

workload (M365Workload) – M365Workload object (obtained via get()).

Raises:

InvalidOperationError – The workload is already retired.
APIError – No backup in progress, or APM rejected the cancel request.

async retire(workload, plan)¶

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

Parameters:

workload (M365Workload) – M365Workload 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).
PermissionDeniedError – Insufficient permission to retire workloads.

async change_plan(workload, plan)¶

Change the Protection Plan or Retirement Plan assigned to an M365 Workload.

Parameters:

workload (M365Workload) – M365Workload 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 delete(workload)¶

Delete an M365 Workload from APM.

Parameters:

workload (M365Workload) – M365Workload to delete. Active and retired workloads are both supported. If the workload no longer exists, the call succeeds silently.

Raises:

InvalidOperationError – APM rejected the delete request.
AuthenticationError – Session expired.
APIError – Unexpected error from APM.

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.

class synology_apm.sdk.collections.m365.M365Collection(session)¶

Bases: object

Entry collection for M365 SaaS backup resources.

Accessed via APMClient.m365; should not be instantiated directly. Provides workloads, plans, exchange_export, and group_export sub-collections.

property workloads: M365WorkloadCollection¶: Access the M365WorkloadCollection.

property plans: M365PlanCollection¶: Access the M365PlanCollection.

property exchange_export: ExchangeExportCollection¶: Access the ExchangeExportCollection for Exchange mailbox PST export.

property group_export: GroupExportCollection¶: Access the GroupExportCollection for Group mailbox PST export.

property auto_backup_rules: M365AutoBackupRuleCollection¶: Access the M365AutoBackupRuleCollection for managing auto-backup rules.