synology_apm.sdk.collections.remote_storages module

RemoteStorageCollection — collection interface for managing remote storage devices.

class synology_apm.sdk.collections.remote_storages.RemoteStorageCollection(session)

Bases: object

Collection interface for managing remote storage devices in APM.

Accessed via APMClient.remote_storages; should not be instantiated directly.

async list()

List all remote storage devices.

Returns all results at once; pagination is not available for this resource.

Returns:

ListResult of (list of RemoteStorage, total count)

Return type:

ListResult[RemoteStorage]

async get(storage_id)

Fetch a remote storage device by ID.

Parameters:

storage_id (str) – Remote storage UUID.

Raises:

ResourceNotFoundError – The specified remote storage does not exist.

async get_by_name(name)

Fetch a remote storage device by display name or endpoint.

Matches in order: case-insensitive name → case-insensitive endpoint; returns the first match.

Parameters:

name (str) – Display name or endpoint.

Raises:

ResourceNotFoundError – No remote storage with an exact match was found.

async add(request)

Register a new remote storage device.

For S3 Compatible storages, no region or virtual-host configuration is required. For ActiveProtect Vault storages, only credentials and endpoint are required — no vault name or display name input is needed. For Amazon S3, Amazon S3 China, C2 Object Storage, and Wasabi storages, only credentials and bucket name are required — no endpoint input is needed. For Azure Blob Storage and Azure Blob Storage China, register using the target Microsoft Entra application’s tenant ID, application (client) ID, and client secret, along with the storage account and container name.

Set trust_self_signed=True on GenericS3StorageAddRequest or APVStorageAddRequest when the endpoint uses a self-signed certificate. Endpoint-free request types do not expose this field — their endpoints use CA-signed certificates.

For re-adding a previously encrypted vault, pass the saved encryption key in relink_encryption_key; leave it “” for a fresh vault — the returned result will include the newly issued key.

If the vault contains pre-existing backup catalogs from a previous APM setup, provide unmanaged_retirement_plan to relink them. If catalogs are detected and unmanaged_retirement_plan is not set, RemoteStorageUnmanagedCatalogError is raised before any storage is created.

Returns:

RemoteStorageAddResult with the registered storage, the encryption key (if encryption_enabled is True; store it securely — it cannot be retrieved later), and relink_warning (non-None when catalog relinking was attempted but failed; the storage is registered but the catalogs remain unlinked).

Raises:
Return type:

RemoteStorageAddResult

async update(storage, request)

Update the access credentials for a remote storage device.

Only credentials and endpoint can be changed. Display name, storage type, and encryption settings are immutable once set at registration.

trust_self_signed applies to S3_COMPATIBLE and ACTIVE_PROTECT_VAULT storages — set True to auto-fetch and pin the endpoint’s self-signed TLS certificate. Leave False for all other storage types; their endpoints are CA-signed.

For AZURE_BLOB and AZURE_BLOB_CHINA storages, pass an AzureBlobStorageUpdateRequest with the Microsoft Entra application’s tenant ID, application (client) ID, and secret; the storage account and container are immutable and carried over automatically.

Parameters:
Returns:

Updated RemoteStorage reflecting the current connection state.

Raises:
Return type:

RemoteStorage

async delete(storage)

Delete a remote storage device.

Parameters:

storage (RemoteStorage) – RemoteStorage to delete (obtained via get() or get_by_name()).

Raises: