Loading...

REST API - POST VM Restore

This operation initiates a restore operation for a virtual machine and returns the details for the restore job. You can perform an in-place restore or an out-of-place restore of a virtual machine, and you can restore guest files and folders.

Request

Syntax

POST <webservice>/v2/vsa/vm/{vmClientGUID}/recover HTTP/1.1
Host: <host name>
Accept: {application/xml|application/json}
Authtoken: <authentication token>
Content-type: application/xml

<restore_vm_template.xml>

where <webservice> is the root path used to route the API requests to the Web Server.

For more information, see Available Web Services for REST API.

Request Parameters

If the request is submitted with only the VM client GUID, the restore is submitted with default values using the most recent backup version. To set the restore options, include a request body.

Name

Description

vmClientGUID

The client GUID of the backed-up VM.

If the client GUID is not known, use the GET VM API to retrieve it from the strGUID parameter.

Request Headers

Name

Description

Host

The host name of the Web Server or Web Console used in the API request.

Accept

The format of the response. Valid values are: application/xml or application/json.

Authtoken

The authentication token received after successfully logging on. For details on receiving an authentication token, see Authentication.

Content-type

The media type contained in the request body.

Request Body

Name

Description

Element

powerOnVmAfterRestore (optional)

The option to start the virtual machine after it is restored.

Valid values are true/false.

VMRestoreReq

passUnconditionalOverride (optional)

The option to overwrite an existing virtual machine of the same name.

Valid values are true/false.

VMRestoreReq

inPlaceRestore

The option to restore backed-up data to the same client from which it was backed up.

Valid values are:

  • true, to perform an in-place restore
  • false, to perform an out-of-place restore

VMRestoreReq

jobId (optional)

Triggers a point-in-time restore from the job ID that is passed in the request. You can use GET Job to get a list of jobs.

VMRestoreReq

clientName (optional)

Applies to: out-of-place restore

Name of the Hypervisor to which the virtual machine must be restored.

destinationClient

esxHost (optional)

Applies to: out-of-place restore

Name of the ESX host in the VMware vCenter, to which the virtual machine must be restored.

vmware

dataStore (optional)

Applies to: out-of-place restore

Name of the datastore in the VMware vCenter, to which the virtual machine must be restored.

vmware

resourcePool (optional)

Applies to: out-of-place restore

Name of the resource pool in the VMware vCenter to which the virtual machine must be restored.

vmware

newName (optional)

New name for the restored virtual machine.

vmware

sourcePath

The location of the files on the source client.

vmFileLevelRestoreOptions

destPath

The location on the destination client where you want to restore the virtual machine.

vmFileLevelRestoreOptions

userName (optional)

Applies to: in-place restore

The username of the user (if user is not the client owner) who performs the in-place restore.

guestCredentials

password (optional)

Applies to: in-place restore

The password of the user (if user is not the client owner) who performs the in-place restore.

guestCredentials

Response

Response Parameters

Parameter

Description

taskId

The system-generated ID assigned to the task.

jobIds

The system-generated ID assigned to the job.

Examples

Sample Request

  • This request initiates an out-of-place restore.

    POST <webservice>/v2/vsa/vm/502d21a1-ae8b-a75e-exam-313ccc60ea03/recover HTTP/1.1
    Host: client.mydomain.com
    Accept: application/json
    Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
    0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
    8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
    40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
    68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
    3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
    Content-type: application/xml

    <Api_VMRestoreReq powerOnVmAfterRestore ="true" passUnconditionalOverride="false" inPlaceRestore="false">
      <destinationClient clientName="client001" />
        <destinationInfo>
          <vmware esxHost="esxHost001" dataStore="dataStore001" resourcePool="resourcePool001" />
        </destinationInfo>
    </Api_VMRestoreReq>

  • This request initiates an in-place restore.

    POST <webservice>/v2/vsa/vm/502d21a1-ae8b-a75e-exam-313ccc60ea03/recover HTTP/1.1
    Host: client.mydomain.com
    Accept: application/json
    Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
    0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
    8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
    40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
    68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
    3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
    Content-type: application/xml

    <Api_VMRestoreReq passUnconditionalOverride="false" inPlaceRestore="true">
    </Api_VMRestoreReq>

  • This request restores guest files.

    POST <webservice>/v2/vsa/vm/357129CC-4B66-4B35-8FA4-1CB7255F8F9E/recover HTTP/1.1
    Host: <host name>
    Accept: {application/json}
    Authtoken: <authentication token>
    Content-type: application/xml

    <VMRestoreReq passUnconditionalOverride="true" inPlaceRestore="false">
    <vmFileLevelRestoreOptions>
    <sourcePath>\357129CC-4B66-4B35-8FA4-1CB7255F8F9E\C\Program Files\Internet Explorer\IEXPLORE.EXE</sourcePath>
    <destPath>C:\</destPath>
    </vmFileLevelRestoreOptions>
    <destinationClient clientName = "rsnsanitycs"/>
    </VMRestoreReq>

    For the source path, include the GUID of the source VM.

Sample Response

{
  "taskId": 63814,
  "jobIds": [
    "131574"
  ]
}

Last modified: 7/16/2020 9:08:56 PM