synology_apm.sdk.collections.protection_plans module¶

Protection Plan collections: ProtectionPlanCollection / MachinePlanCollection / M365PlanCollection.

Request-body construction lives in _protection_plan_builders.py; response parsing and the API↔enum string maps live in _protection_plan_parsers.py.

class synology_apm.sdk.collections.protection_plans.ProtectionPlanCollection(session)¶

Bases: object

Cross-domain collection for querying Protection Plans across all categories.

Accessed via APMClient.plans; should not be instantiated directly. To change the plan assigned to a specific workload, use APMClient.machine.workloads.change_plan() or APMClient.m365.workloads.change_plan() instead.

async list(category=None, name_contains=None, limit=500, offset=0)¶

List Protection Plans; supports cross-category queries.

Parameters:

category (WorkloadCategory | None) – WorkloadCategory filter; None (default) lists all categories.
name_contains (str | None) – Name keyword search.
limit (int) – Maximum number of records to return (default 500).
offset (int) – Pagination start offset (default 0).

Returns:

(list of ProtectionPlan, total count matching the filter)

Return type:

tuple[list[ProtectionPlan], int]

async get(plan_id)¶

Fetch a Protection Plan by UUID (category-agnostic).

Parameters:: plan_id (str) – Plan UUID.
Raises:: ResourceNotFoundError – The specified plan_id does not exist.

async get_by_name(name)¶

Fetch a Protection Plan by name (cross-category search).

Parameters:: name (str) – Plan name (exact match, case-insensitive).
Raises:: ResourceNotFoundError – The specified plan does not exist.

async create(request)¶

Create a Protection Plan (Machine or M365), dispatching by request type.

Parameters:: request (MachinePlanCreateRequest | M365PlanCreateRequest) – MachinePlanCreateRequest or M365PlanCreateRequest.
Returns:: The created plan with all fields populated.
Raises:: PlanNameConflictError – A plan with this name already exists.
Return type:: ProtectionPlan

async delete(plan)¶

Delete a Protection Plan by plan object or UUID.

Deleting a plan that does not exist is a no-op (the operation succeeds silently).

Parameters:: plan (ProtectionPlan | str) – ProtectionPlan object or plan UUID string.
Raises:: PlanInUseError – The plan is still assigned to workloads or used as a server template.

class synology_apm.sdk.collections.protection_plans.MachinePlanCollection(session)¶

Bases: _BasePlanCollection

Collection interface for managing device backup plans (Machine Protection Plans).

Accessed via APMClient.machine.plans; should not be instantiated directly. Handles only category=MACHINE plans; for other categories use the corresponding domain collection.

async create(request)¶

Create a Machine (DEVICE) Protection Plan.

Parameters:: request (MachinePlanCreateRequest) – Plan creation parameters.
Returns:: The created plan with all config fields populated.
Raises:: PlanNameConflictError – A plan with this name already exists.
Return type:: ProtectionPlan

async update(plan_id, request)¶

Update an existing Machine Protection Plan.

Parameters:

plan_id (str) – UUID of the plan to update.
request (MachinePlanCreateRequest) – New plan configuration.

Returns:

The updated plan with all config fields populated.

Raises:

PlanNameConflictError – The new name is already taken by another plan.

Return type:

ProtectionPlan

async delete(plan)¶

Delete a Protection Plan by plan object or UUID.

Deleting a plan that does not exist is a no-op (the operation succeeds silently).

Parameters:: plan (ProtectionPlan | str) – ProtectionPlan object or plan UUID string.
Raises:: PlanInUseError – The plan is still assigned to workloads or used as a server template.

async get(plan_id)¶

Fetch a Protection Plan by UUID.

Parameters:: plan_id (str) – Plan UUID.
Raises:: ResourceNotFoundError – No matching plan found.

async get_by_name(name)¶

Fetch a Protection Plan by name.

Parameters:: name (str) – Plan name (exact match, case-insensitive).
Raises:: ResourceNotFoundError – Plan not found.

async list(name_contains=None, limit=500, offset=0)¶

List Protection Plans.

Parameters:

name_contains (str | None) – Name fuzzy search. None = no filter.
limit (int) – Maximum records to return (default 500).
offset (int) – Pagination start offset (default 0).

Returns:

(list of ProtectionPlan, total count matching the filter)

Return type:

tuple[list[ProtectionPlan], int]

class synology_apm.sdk.collections.protection_plans.M365PlanCollection(session)¶

Bases: _BasePlanCollection

Collection interface for managing M365 backup plans.

Accessed via APMClient.m365.plans; should not be instantiated directly.

async create(request)¶

Create an M365 Protection Plan.

Parameters:: request (M365PlanCreateRequest) – Plan creation parameters.
Returns:: The created plan with all fields populated.
Raises:: PlanNameConflictError – A plan with this name already exists.
Return type:: ProtectionPlan

async update(plan_id, request)¶

Update an existing M365 Protection Plan.

Parameters:

plan_id (str) – UUID of the plan to update.
request (M365PlanCreateRequest) – New plan configuration.

Returns:

The updated plan with all fields populated.

Raises:

PlanNameConflictError – The new name is already taken by another plan.

Return type:

ProtectionPlan

async delete(plan)¶

Delete a Protection Plan by plan object or UUID.

Deleting a plan that does not exist is a no-op (the operation succeeds silently).

Parameters:: plan (ProtectionPlan | str) – ProtectionPlan object or plan UUID string.
Raises:: PlanInUseError – The plan is still assigned to workloads or used as a server template.

async get(plan_id)¶

Fetch a Protection Plan by UUID.

Parameters:: plan_id (str) – Plan UUID.
Raises:: ResourceNotFoundError – No matching plan found.

async get_by_name(name)¶

Fetch a Protection Plan by name.

Parameters:: name (str) – Plan name (exact match, case-insensitive).
Raises:: ResourceNotFoundError – Plan not found.

async list(name_contains=None, limit=500, offset=0)¶

List Protection Plans.

Parameters:

name_contains (str | None) – Name fuzzy search. None = no filter.
limit (int) – Maximum records to return (default 500).
offset (int) – Pagination start offset (default 0).

Returns:

(list of ProtectionPlan, total count matching the filter)

Return type:

tuple[list[ProtectionPlan], int]