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.

async list(tenant_id, workload_type, namespace=None, plan=None, keyword=None, is_retired=False, status=None, 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 (list[str] | None) – Return only workloads on one or more backup servers (OR logic; = workload.namespace). The SDK resolves each namespace to an internal backup server reference automatically; a namespace with no matching backup server contributes no matches rather than raising.

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

• status (list[WorkloadStatus] | None) – Filter by one or more backup statuses (OR logic); None returns all statuses. WorkloadStatus.RETIRED is not accepted here — use is_retired=True instead.

• limit (int) – Maximum records to return (default 500).

• offset (int) – Pagination start offset (default 0).

Returns:

(list of M365Workload, total count).

Raises:

ValueError – WorkloadStatus.RETIRED was passed in status.

Return type:

ListResult[M365Workload]

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

Returns the first workload whose display name, UPN, or group email matches exactly (case-insensitive), without fetching further pages.

Parameters:

• name (str) – Display name, UPN, or group email (exact match, case-insensitive).

• 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 – No workload with an exact match was found.

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

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.

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:

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

Return type:

ListResult[WorkloadVersion]

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, group_export, and auto_backup_rules 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.