Restore as virtual disks allows:
- restoring a group of revisions, previously identified.
- specifying the destination, either as a local disk or as a network share path, optionally with username and password to authenticate that network share.
Parameter Descriptions
The following table provides the parameters and descriptions.
Parameter | Description |
destination | Folder destination allows specifying a local path, or a network share path, in the case of a share, optionally with credentials (username and password), in case the shares requires them. If provided, the credentials necessitate Write permissions. Do not populate Credentials for local paths. |
diskFormat | Vhd or Vhdx. |
revisions | Array of integers representing the ids of the revisions to restore, identified by a prior call to the Browse volumes (which fetches also latest revision ids) or Browse volume revisions API for fetching revision IDs other than latest. Only a single revision per volume should be selected. |
Example POST
POST /v2/accounts/test_acc/computers/0000/restore/diskimage/standard/vhd
Online Operation
Response status: 204 (for online operation)
Response status: 400 Accepted
Example Response
{
"errors": [
"Could not create item.",
"[destination] is missing or invalid",
"[destination][path] must be a string"
"[destination][credentials][username] must be set to a string",
"[destination][credentials][password] must be set to a string",
"[destination][credentials] must not be specified for local paths.",
"[destination][path] is invalid: the provided path is neither local or remote",
"[diskformat] is missing or invalid. Allowed values are vhd, vhdx",
"[revisions] is missing or invalid",
"[revisions] must be a valid list of id integers"
]
}
Since this is an online-operation only (have a running agent) the following status code is displayed if you attempt the operation offline.
Offline Operation
Response status: 400 Accepted
Example Response
{
"errors": [
"Agent cannot be reached or is offline"
]
}
Error Codes
- When restored revision contains a boot volume and it was EFI, and the users chooses to restore as VHD: "UEFI-based systems can only be restored as VHDX files to ensure they are bootable on Windows Server 2012 R2 or above."
- When volumes over 2 TBs are being restored and VHD format is chosen: "Due to a limitation of the VHD file type, volumes greater than 2040 GB can only be restored as VHDX files."
- For destination creation:
¾ CreateFolderFailed: general error. Most likely a local volume is read only or cannot be written to due to permissions on the local file system
¾ Network shares only:
- BackupSetActions_NetworkShareInaccessible - network share address could not be reached
- BackupSetActions_NetworkPathNotFound - the network path could not be found
- BackupSetActions_NetworkShareInvalidAuth - username + password combination failed authentication
- BackupSetActions_NetworkShareNoWritePermissions - username and password ok, but no write permissions for the provided username on that share.
Restore Request Validations
If diskFormat = Vhd and SupportsVhdxFormat = false, error message: "Vhdx format is not supported by the host, choose Vhd format as long as other restrictions do not apply"
virtualSwitchId must be populated for ProductionRecovery and should not be present otherwise, error: "VirtualSwitchId can only be used for Production Recovery"
Example POST
POST /v2/accounts/test_acc/computers/0000/restore/diskimage/standard/vm
Input Parameters
{
"sessionId": "2bd04387-9e6d-49c7-8d32-d144af9a8d78",
"hostId": 2,
"recoveryType": "string",
"diskLocation": {
"path": "\\\\\\\\server1\\\\share1\\\\folder1",
"credentials": {
"userName": "user1",
"password": "passwordtext"
}
},
"diskFormat": "Vhdx",
"firmwareType": "Bios",
"hostProperties": {
"name": "TestComputer1",
"cores": 4,
"memory": 4096,
"virtualSwitchId": "C08CE7B8-9B3C-408E-8E30-5E16A3AEB444"
},
"revisions": [
0
]
}
Output Parameters
Response status: 204 No Content (for online operation).
Specific Validations
Validations are run by default. If skipValidations is true, however, they are skipped, and it is expected that the user has called the validation APIs separately (or that the input data is known to be valid hence validations aren't needed).
The various validations can be called separately as described in Restore Disk Image Standard as VM Validations.