synology_apm.sdk.collections.gws module

GWSCollection — entry collection for Google Workspace SaaS backup resources.

class synology_apm.sdk.collections.gws.GWSWorkloadCollection(session)

Bases: _VersionMixin

Collection interface for managing Google Workspace SaaS backup Workloads.

Accessed via APMClient.gws.workloads; should not be instantiated directly.

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

List GWS Workloads of a given service sub-type for a domain.

Parameters:

• domain (str) – Google Workspace domain (required).

• workload_type (GWSWorkloadType) – Service sub-type to list (MAIL / DRIVE / CONTACT / CALENDAR / SHARED_DRIVE).

• 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 GWSWorkload, total count).

Raises:

ValueError – WorkloadStatus.RETIRED was passed in status.

Return type:

ListResult[GWSWorkload]

async get(workload_id, namespace, domain, workload_type)

Fetch a GWS Workload by workload ID and backup server namespace.

Parameters:

• workload_id (str) – Workload ID.

• namespace (str) – Backup server namespace.

• domain (str) – Google Workspace domain.

• workload_type (GWSWorkloadType) – Service sub-type (MAIL / DRIVE / CONTACT / CALENDAR / SHARED_DRIVE).

Raises:

ResourceNotFoundError – No workload matches the given workload_id + namespace.

async get_by_name(name, domain, workload_type, is_retired=False)

Fetch a GWS Workload by name or email (keyword search + exact match).

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

Parameters:

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

• domain (str) – Google Workspace domain; required to scope the search.

• workload_type (GWSWorkloadType) – Service sub-type (MAIL / DRIVE / CONTACT / CALENDAR / SHARED_DRIVE).

• 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 a GWS Workload.

Parameters:

workload (GWSWorkload) – GWSWorkload 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 a GWS Workload.

Parameters:

workload (GWSWorkload) – GWSWorkload 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 a GWS Workload (apply a retirement policy; irreversible).

Parameters:

• workload (GWSWorkload) – GWSWorkload 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 a GWS Workload.

Parameters:

• workload (GWSWorkload) – GWSWorkload 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 a GWS Workload from APM.

Parameters:

workload (GWSWorkload) – GWSWorkload 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.gws.GWSCollection(session)

Bases: object

Entry collection for Google Workspace SaaS backup resources.

Accessed via APMClient.gws; should not be instantiated directly. Provides workloads, plans, and auto_backup_rules sub-collections.

property workloads: GWSWorkloadCollection

Access the GWSWorkloadCollection.

property plans: GWSPlanCollection

Access the GWSPlanCollection.

property auto_backup_rules: GWSAutoBackupRuleCollection

Access the GWSAutoBackupRuleCollection for managing auto-backup rules.