API Explorer
API Explorer
Introduction
What's New
Appliance Management
Application Data Management
Asset Management
Asset Metadata
Authentication and Authorization
Cloud Disaster Recovery
Compliance
Copy Management
Credentials Management
Discovery
File Level Restore
Installation
Inventory Source Management
Kubernetes Data Management
Licenses Management
Location Management
Log Management
Monitoring
Protection Policies
Recovery and Reuse Management
Remote Service
Search Clusters
Secrets Manager
Server Disaster Recovery
Storage Management
Telemetry Setting
Upgrade
User Security Management
Virtual Machine Data Management
Whitelist Management

Restore - VM image level restore

VM restore to original

Basic Flow (Login → get asset by name → get asset copies → get specific copy by id → perform restore to original)

1. Login

Use the login API to retrieve the access token. See the tutorial for authentication and authorization.

2. Get assets by name

Gets information about an asset given its name.

URI Operation Description Return Codes
/api/v2/assets?filter= GET Returns one or more assets matching the filter criteria (filters are optional).
filter example: /api/v2/assets?filter=name eq “example-VM-1”
200 OK
404 Not Found
401 Not Authorized
curl --request GET \
  --url https://<your-ppdm-server>:8443/api/v2/assets?filter=name eq "ca-test-2" \
  --header 'content-type: application/json'
  • access_token from the Login API call
  • filter for the VM name

Sample response:

OK (200)

{
  "page" : {
    "size" : 1,
    "number" : 1,
    "totalPages" : 1,
    "totalElements" : 1
  },
  "content" : [ {
    "id" : "be85fb95-27a4-51c3-af6d-d5bd1c9b865f",
    "name" : "ca-test-2",
    "type" : "VMWARE_VIRTUAL_MACHINE",
    "userTags" : null,
    "dataTargetIds" : null,
    "assetGroupId" : null,
    "protectionLifeCycleId" : "0bec4ea0-fb47-4c7b-9683-cc7f7a9b7c85",
    "protectionPolicyId" : "0bec4ea0-fb47-4c7b-9683-cc7f7a9b7c85",
    "credentialId" : null,
    "deleted" : false,
    "protectable" : true,
    "size" : 437657285,
    "details" : {
      "vm" : {
        "guestOS" : "Other 3.x Linux (64-bit)",
        "datacenter" : "datacenter_1",
        "resourcePool" : "resource_pool_1",
        "hostName" : "ca-esxi-1.dev.com",
        "folder" : "folder_1",
        "primaryIpAddress" : "xx.xx.xx.xx",
        "vmBiosUuid" : "4228746b-505b-623d-dcd1-fa8ce7931796",
        "dnsName" : "ca-test-2",
        "vcenterName" : "ca-vcenter-1.dev.com",
        "inventorySourceName" : "ca-vcenter-1",
        "esxName" : "ca-esxi-1.dev.com",
        "clusterName" : "cluster_1",
        "protectedApplication" : "NONE",
        "disks" : [ {
          "name" : "[datastore1] ca-test-2/ca-test-2.vmdk",
          "sizeInBytes" : 17179869184,
          "label" : "Hard disk 1",
          "key" : 2000,
          "thinProvisioned" : true,
          "excluded" : false
        } ],
        "externalId" : "50285697-0cd8-d3a8-46b2-9475ed232b03",
        "datastore" : [ {
          "datastoreMoref" : "Datastore:datastore-16",
          "datastoreName" : "datastore1"
        } ]
      }
    },
    "ruleId" : null,
    "createdAt" : "2019-10-21T21:10:10.406Z",
    "updatedAt" : "2019-10-24T02:00:26.536Z",
    "_embedded" : {
      "protectionPolicy" : {
        "id" : "0bec4ea0-fb47-4c7b-9683-cc7f7a9b7c85",
        "name" : "vm_test2",
        "type" : "ACTIVE",
        "protectionEngine" : "VMDIRECT"
      }
    },
    "ruleName" : null
  } ]
}
  • The first id is used as assetId in subsequent calls.
  • Remember the disks section under “vm” when doing Restore Individual Disks (Section 3 of the document).

3. Get asset copies

Gets a list of all the copies that a particular asset has.

Property Type Description Obtained by
assetId (required) String Unique identifier for a specific asset Previous call (Get asset by name)
URI Operation Description Return Codes
/api/v2/assets/{{assetId}}/copies GET Returns a list of copies/backups that this asset has 200 OK
404 Not Found
401 Not Authorized
curl --request GET \
  --url https://<your-ppdm-server>:8443/api/v2/assets/be85fb95-27a4-51c3-af6d-d5bd1c9b865f/copies?pageSize=2 \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}'
  • access_token from the Login API call
  • assetId for the previous call
  • If you want to retore from a specific storage system, you can add a filter to the query: filter=storageSystemId eq "the Storage System id you want to restore from"

Sample response:

OK (200)

{
  "page" : {
    "size" : 2,
    "number" : 1,
    "totalPages" : 11,
    "totalElements" : 22
  },
  "content" : [ {
    "id" : "8cd274de-4687-5478-9cf2-477a9187966c",
    "createTime" : "2019-10-28T18:02:33.201Z",
    "storageSystemId" : "32b3aa41-9d14-4d18-8514-899401d1b18d",
    "size" : 435159040,
    "state" : null,
    "protectionCreated" : true,
    "copyType" : "FULL",
    "copyConsistency" : "CRASH_CONSISTENT",
    "retentionLock" : "ALL_COPIES_UNLOCKED",
    "retentionTime" : "2019-11-03T00:00:00Z",
    "retierTime" : null,
    "replicatedCopy" : false,
    "adhocBackup" : false,
    "partialCopy" : false,
    "partialCopyDescription" : null,
    "details" : {
      "arraySubType" : "DATADOMAINSYSTEM",
      "arraySerialNo" : "AUDVHSHKJAS67W",
      "vmBackup" : {
        "disks" : [ {
          "excluded" : false,
          "capacityInBytes" : 17179869184,
          "controller" : 0,
          "backupIndex" : 1,
          "provisioningType" : "THIN",
          "controllerType" : "SCSI",
          "unitNumber" : 0,
          "label" : "Hard disk 1",
          "key" : 2000
        } ],
        "backupId" : "eyJWZXJzaW9uIjoxLCJWaW1VVUlEIjoiN2M4NTRmMzgtN2FmYy00ZjU4LWE4OTYtMDFmZDE1ZGEwNzU3IiwiVm1VVUlEIjoiNTAyODU2OTctMGNkOC1kM2E4LTQ2YjItOTQ3NWVkMjMyYjAzIiwiVGltZSI6IjIwMTktMTAtMjhUMTg6MDA6NTYuNTYzODE1NjE4WiJ9Cg==",
        "protectionEngineType" : "VMDIRECT",
        "transportModeUsed" : "HOTADD",
        "syntheticFull" : false,
        "quiesceStatus" : "COPY",
        "diskBackupCount" : 1,
        "diskTotalCount" : 1,
        "partialCopy" : false
      },
      "storageClass" : "Protection"
    },
    "baseCopyId" : null,
    "logCount" : "0",
    "exportedCopyCount" : null,
    "location" : "LOCAL",
    "externalId" : null,
    "restoreTargetCompatibilities" : null
  }, {
    "id" : "36efe60e-8a05-516e-a7f0-7f21576e28e2",
    "createTime" : "2019-10-28T15:01:01.095Z",
    "storageSystemId" : "32b3aa41-9d14-4d18-8514-899401d1b18d",
    "size" : 435159040,
    "state" : null,
    "protectionCreated" : true,
    "copyType" : "FULL",
    "copyConsistency" : "CRASH_CONSISTENT",
    "retentionLock" : "ALL_COPIES_UNLOCKED",
    "retentionTime" : "2019-11-03T00:00:00Z",
    "retierTime" : null,
    "replicatedCopy" : false,
    "adhocBackup" : false,
    "partialCopy" : false,
    "partialCopyDescription" : null,
    "details" : {
      "arraySubType" : "DATADOMAINSYSTEM",
      "arraySerialNo" : "AUDVHSHKJAS67W",
      "vmBackup" : {
        "disks" : [ {
          "excluded" : false,
          "capacityInBytes" : 17179869184,
          "controller" : 0,
          "backupIndex" : 1,
          "provisioningType" : "THIN",
          "controllerType" : "SCSI",
          "unitNumber" : 0,
          "label" : "Hard disk 1",
          "key" : 2000
        } ],
        "backupId" : "eyJWZXJzaW9uIjoxLCJWaW1VVUlEIjoiN2M4NTRmMzgtN2FmYy00ZjU4LWE4OTYtMDFmZDE1ZGEwNzU3IiwiVm1VVUlEIjoiNTAyODU2OTctMGNkOC1kM2E4LTQ2YjItOTQ3NWVkMjMyYjAzIiwiVGltZSI6IjIwMTktMTAtMjhUMTU6MDA6MTguNzg5ODU4ODc5WiJ9Cg==",
        "protectionEngineType" : "VMDIRECT",
        "transportModeUsed" : null,
        "syntheticFull" : true,
        "quiesceStatus" : "COPY",
        "diskBackupCount" : 1,
        "diskTotalCount" : 1,
        "partialCopy" : false
      },
      "storageClass" : "Protection"
    },
    "baseCopyId" : null,
    "logCount" : "0",
    "exportedCopyCount" : null,
    "location" : "LOCAL",
    "externalId" : null,
    "restoreTargetCompatibilities" : null
  } ]
}
  • Any of the IDs inside the content can be used as copyId in subsequent calls.

4. Get copy by ID

Gets information about a copy given its ID.

Property Type Description Obtained by
copyId (required) String Unique identifier for a specific asset copy Carried over by user from previous call (get asset copies)
URI Operation Description Return Codes
/api/v2/copies/{{copyid}} GET Returns information about a specific copy given its ID 200 OK
404 Not Found
401 Not Authorized
curl --request GET \
  --url https://<your-ppdm-server>:8443/api/v2/copies/8cd274de-4687-5478-9cf2-477a9187966c \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}'
  • access_token from the Login API call
  • copyId for the previous call

Sample response:

OK (200)

{
  "id" : "8cd274de-4687-5478-9cf2-477a9187966c",
  "createTime" : "2019-10-28T18:02:33.201Z",
  "storageSystemId" : "32b3aa41-9d14-4d18-8514-899401d1b18d",
  "size" : 435159040,
  "state" : null,
  "protectionCreated" : true,
  "copyType" : "FULL",
  "copyConsistency" : "CRASH_CONSISTENT",
  "retentionLock" : "ALL_COPIES_UNLOCKED",
  "retentionTime" : "2019-11-03T00:00:00Z",
  "retierTime" : null,
  "replicatedCopy" : false,
  "adhocBackup" : false,
  "partialCopy" : false,
  "partialCopyDescription" : null,
  "details" : {
    "arraySubType" : "DATADOMAINSYSTEM",
    "arraySerialNo" : "AUDVHSHKJAS67W",
    "vmBackup" : {
      "disks" : [ {
        "excluded" : false,
        "capacityInBytes" : 17179869184,
        "controller" : 0,
        "backupIndex" : 1,
        "provisioningType" : "THIN",
        "controllerType" : "SCSI",
        "unitNumber" : 0,
        "label" : "Hard disk 1",
        "key" : 2000
      } ],
      "backupId" : "eyJWZXJzaW9uIjoxLCJWaW1VVUlEIjoiN2M4NTRmMzgtN2FmYy00ZjU4LWE4OTYtMDFmZDE1ZGEwNzU3IiwiVm1VVUlEIjoiNTAyODU2OTctMGNkOC1kM2E4LTQ2YjItOTQ3NWVkMjMyYjAzIiwiVGltZSI6IjIwMTktMTAtMjhUMTg6MDA6NTYuNTYzODE1NjE4WiJ9Cg==",
      "protectionEngineType" : "VMDIRECT",
      "transportModeUsed" : "HOTADD",
      "syntheticFull" : false,
      "quiesceStatus" : "COPY",
      "diskBackupCount" : 1,
      "diskTotalCount" : 1,
      "partialCopy" : false
    },
    "storageClass" : "Protection"
  },
  "baseCopyId" : null,
  "logCount" : "0",
  "exportedCopyCount" : null,
  "location" : "LOCAL",
  "externalId" : null,
  "restoreTargetCompatibilities" : null
}
  • Remember the disks section under “vmBackup” when doing Restore Individual Disks (Section 3 of the document)

5. Restore to original

Performs the restore to original on an asset given an associated copyId.

Property Type Description Obtained by
copyId (required) String Unique identifier for a specific asset copy Carried over by user from previous call (get asset copies)
description String Description of the restore User input
restoreType (required) String Restore type descriptor Must be set to TO_PRODUCTION User input
URI Operation Description Return Codes
/api/v2/restored-copies POST Creates a task to perform the restore to original function and runs it 201 Created
404 Not Found
401 Not Authorized
curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/restored-copies \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}' \
  --data '{
    "description": "Restore VM to Production",
    "copyId": "{{copyId}}",
    "restoreType": "TO_PRODUCTION"
  }'
  • access_token from the Login API call
  • copyId for the previous call

Sample response:

Created (201)

{
  "id": "d61a6661-9a62-43ca-a07b-d3b6d9e1644b",
  "description": "Restore VM to Production",
  "state": "WAITING",
  "status": "UNKNOWN",
  "restoreType": "TO_PRODUCTION",
  "copyId": "36efe60e-8a05-516e-a7f0-7f21576e28e2",
  "startTime": "2019-10-28T17:59:07.167Z",
  "completionTime": null,
  "expirationTime": null,
  "restoredCopiesDetails": {},
  "activityId": "feae507a-1e44-4936-8c53-d98ba0453115"
}

Summary

The basic workflow for restore to original using the PowerProtect Data Manager API is as follows. First, log in to PowerProtect Data Manager to get an access_token to use for subsequent calls and gain access to the rest of the API. After that, get the asset information by requesting a GET on the asset by its name. This request is used to acquire the assetId, which is then used to view asset copies. Get a copyId by carrying it over from the list of copies (from the list, pick a copy and parse the JSON response for any ID). Finally, perform restore to original by attaching the copyId to the body and sending a POST request to {{url}}/api/v2/restored-copies.

VM restore to new

Basic Flow (Login → get asset by name → get asset copies → get specific copy by id → get inventory source → perform restore to new)

The first 4 steps are same as before:

  1. Login
  2. Get assets by name
  3. Get asset copies
  4. Get copy by ID

5. Get inventory source

Gets information about one or more inventory sources.

URI Operation Description Return Codes
/api/v2/inventory-sources GET Returns information about the inventory sources associated with the given PowerProtect Data Manager appliance 200 OK
404 Not Found
401 Not Authorized
curl --request GET \
  --url https://<your-ppdm-server>:8443/api/v2/inventory-sources?filter type eq "VCENTER"&pageSize=1&page=2 \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}'
  • access_token from the Login API call

Sample response:

OK (200)

{
  "page": {
    "size": 1,
    "number": 2,
    "totalPages": 5,
    "totalElements": 5
  },
  "content": [
    {
      "id": "53fcb6a2-9843-4fcd-b457-409c720d092e",
      "name": "ca-vcenter-1",
      "version": "6.7.0",
      "type": "VCENTER",
      "lastDiscovered": "2019-10-21T21:45:40.914Z",
      "lastDiscoveryResult": {
        "status": "OK",
        "summaries": [
          "Discovery Type: VCENTER  Resource Type: ESX_CLUSTER  Sub-Type: none  Total Assets: 1  New Assets: 1",
          "Discovery Type: VCENTER  Resource Type: ESX_HOST  Sub-Type: none  Total Assets: 1  New Assets: 1",
          "Discovery Type: VCENTER  Resource Type: VIRTUALMACHINE  Sub-Type: VIRTUALMACHINE  Total Assets: 5  New Assets: 5"
        ]
      },
      "lastDiscoveryTaskId": "d6ba8098-0a70-40dc-9a7a-a3b132747d9d",
      "address": "ca-vcenter-1.dev.com",
      "port": 443,
      "credentials": {
        "id": "36a1d1ba-c0c6-4563-a1ba-31a8a0d559ed"
      },
      "details": {
        "customAppGroup": null,
        "vCenter": {
          "internal": false,
          "hosting": false,
          "cloudType": "NONE",
          "vSphereUiIntegration": false
        }
      },
      "local": false
    }
  ]
}
  • The id that is associated with vCenter is used as vcenterInventorySourceId for subsequent calls.
  • Add filter type eq "VCENTER" to list vCenters only.

6. Get Morefs for vCenter

Gets the managed object references (Moref) for the supplied vCenter.

URI Parameter to Get
POST https://<vcenter_host>/rest/com/vmware/cis/session Use Basic Auth to login, get value from body, set to Header vmware-api-session-id for next calls.
GET https://<vcenter_host>/rest/vcenter/datacenter value.datacenter → datacenterMoref
GET https://<vcenter_host>/rest/vcenter/cluster value.cluster → clusterMoref
GET https://<vcenter_host>/rest/vcenter/host value.host → hostMoref
GET https://<vcenter_host>/rest/vcenter/datastore value.datastore → dataStoreMoref
  • NOTE: These objects are attained from vSphere API, not PowerProtect Data Manager public API. Ensure that you review VMware documentation to get more information about these specific calls. https://vdc-repo.vmware.com/vmwb-repository/dcr-public/1cd28284-3b72-4885-9e31-d1c6d9e26686/71ef7304-a6c9-43b3-a3cd-868b2c236c81/doc/index.html

7. Restore to new

Performs the restore to new on an asset given its associated copyId and a vCenter inventorySourceId.

Property Type Description Obtained by
copyId (required) String Unique identifier for a specific asset copy Carried over by user from previous call (get asset copies)
description String Description of the restore User input
restoreType (required) String Restore type descriptor Must be set to TO_ALTERNATE User input
restoredCopiesDetails (required) JSON Details for the newly created restored copy. Includes target VM information such as vcenterInventorySourceId, vmName, dataCenterMoref, clusterMoref, hostMoref, dataStoreMoref, vmPowerOn, vmReconnectNic vcenterInventorySourceId is found from the previous call. The remaining properties do not need to be modified.
URI Operation Description Return Codes
/api/v2/restored-copies POST Creates a task to perform restore to new and executes it 201 Created
404 Not Found
401 Not Authorized
curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/restored-copies \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}' \
  --data '{
    "description": "Restore VM to New",
    "copyId": "{{copyId}}",
    "restoreType": "TO_ALTERNATE",
    "restoredCopiesDetails": {
      "targetVmInfo": {
        "inventorySourceId": "{{vcenterInventorySourceId}}",
        "vmName": "My New VM!!!",
        "dataCenterMoref": "datacenter-2",
        "clusterMoref": "domain-c7",
        "hostMoref": "host-15",
        "dataStoreMoref": "datastore-16",
        "vmPowerOn": true,
        "vmReconnectNic": false
      }
    }
  }'
  • access_token from the Login API call
  • copyId from the previous call
  • vcenterInventorySourceId from the previous call
  • Morefs from the previous call

Sample response:

Created (201)

{
  "id": "5d800e93-602b-4f9f-809b-ff3f4387837f",
  "description": "Restore VM to New",
  "state": "WAITING",
  "status": "UNKNOWN",
  "restoreType": "TO_ALTERNATE",
  "copyId": "8cd274de-4687-5478-9cf2-477a9187966c",
  "startTime": "2019-10-28T22:12:00.067Z",
  "completionTime": null,
  "expirationTime": null,
  "restoredCopiesDetails": {
    "targetVmInfo": {
      "inventorySourceId": "53fcb6a2-9843-4fcd-b457-409c720d092e",
      "vmName": "My New VM!!!",
      "dataCenterMoref": "datacenter-2",
      "clusterMoref": "domain-c7",
      "hostMoref": "host-15",
      "dataStoreMoref": "datastore-16",
      "vmPowerOn": true,
      "vmReconnectNic": false
    }
  },
  "activityId": "feae507a-1e44-4936-8c53-d98ba0453115"
}

Summary

The basic workflow for restore to new using the PowerProtect Data Manager API is as follows. First, log in to PowerProtect Data Manager to get an access_token to use for subsequent calls and gain access to the rest of the API. After that, get the asset information by requesting a GET on the asset by its name. This request is used to acquire the assetId, which is then used to view asset copies. Get a copyId by carrying it over from the list of copies (from the list, pick a copy and parse the JSON response for any ID). Then, get a vcenterInventorySourceId by requesting a GET on inventory sources and using the ID that is associated with the vCenter. After that, get the morefs for the following in this order: datacenter, host, cluster, datastore). Finally, perform restore to new by attaching the copyId and vcenterInventorySourceId to the body and sending a POST request to {{url}}/api/v2/restored-copies.

VM restore individual disks

The first 4 steps are same as before:

  1. Login
  2. Get assets by name
  3. Get asset copies
  4. Get copy by ID

5. Restore individual disks

Performs the restore to original on an asset given one or more disks to restore.

Property Type Description Obtained by
copyId (required) String Unique identifier for a specific asset copy Carried over by user from previous call (get asset copies)
description String Description of the restore User input
restoreType (required) String Restore type descriptor Must be set to TO_PRODUCTION User input
restoredCopiesDetails (required) JSON Description for the copy VM that specifies which individual disks are being backed up
label: Disk name
provisioningType: enum describing disk provisioning type (THIN, THICK_EAGER, THICK_LAZY)
Disk information that is carried over by user from previous call (get asset by name)
URI Operation Description Return Codes
/api/v2/restored-copies POST Creates a task to perform the restore to original function and executes it 201 Created
404 Not Found
401 Not Authorized
curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/restored-copies \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}' \
  --data '{
    "description": "Restore VM to Production",
    "copyId": "{{copyId}}",
    "restoreType": "TO_PRODUCTION"
    "restoredCopiesDetails": {
      "targetVmInfo": {
          "disks": [
          {
            "label": "Hard disk 1",
            "provisioningType": "THIN"
          },
          {
            "label": "Hard disk 3",
            "provisioningType": "THICK_LAZY"
          }
          ],
          "recoverConfig": false
      }
  }'
  • access_token from the Login API call
  • disks information from previous call
    • user needs to get the label as well as the provisioningType (ENUM: either going to be THICK_LAZY, THICK_EAGER, or THIN)
  • copyId for the previous call
    • copyId should reflect a copy that has the specified disks backed up
  • restoredCopiesDetails should be completed to include the disks that to be restored (example in the request body below)
    • recoverConfig should be set to false to inform the API to only restore individual disk data

Sample response:

Created (201)

{
  "id": "97ca49dc-9b78-4b62-82b9-89165b4f967d",
  "description": "Restore VM to Production",
  "state": "WAITING",
  "status": "UNKNOWN",
  "restoreType": "TO_PRODUCTION",
  "copyId": "8cd274de-4687-5478-9cf2-477a9187966c",
  "startTime": "2019-10-29T21:59:02.835Z",
  "completionTime": null,
  "expirationTime": null,
  "restoredCopiesDetails": {
    "targetVmInfo": {
      "disks": [
        {
          "label": "Hard disk 1",
          "provisioningType": "THIN"
        },
        {
          "label": "Hard disk 3",
          "provisioningType": "THICK_LAZY"
        }
      ],
      "recoverConfig": false
    }
  },
  "activityId": "feae507a-1e44-4936-8c53-d98ba0453115"
}

Summary

The basic workflow for restore to original using the PowerProtect Data Manager API is as follows. First, log in to PowerProtect Data Manager to get an access_token to use for subsequent calls and gain access to the rest of the API. After that, get the asset information by requesting a GET on asset by name. This request is used to acquire the assetId, which is used to view asset copies, as well as disks information. Get a copyId by carrying it over from the list of copies (from the list, pick a copy and parse the JSON response for any ID). Ensure this copyId has backups of the disks to be restored. Finally, perform restore to original by attaching the copyId and the restoredCopiesDetails to the body and sending a POST request to {{url}}/api/v2/restored-copies.

Instant access

Basic Flow (Login → get asset by name → get asset copies → get specific copy by id → perform instant access restore)

The first 6 steps are same as before:

  1. Login
  2. Get assets by name
  3. Get asset copies
  4. Get copy by ID
  5. Get inventory source
  6. Get Morefs for vCenter

7. Instant access restore

Performs the instant access restore on a VM given its copy ID and a vCenter inventorySourceId.

Property Type Description Obtained by
copyId (required) String Unique identifier for a specific asset copy Carried over by user from previous call (get asset copies)
description String Description of the restore User input
restoreType (required) String Restore type descriptor Must be set to INSTANT_ACCESS User input
restoredCopiesDetails (required) JSON Details for the newly created restored copy. Includes target VM information such as vcenterInventorySourceId, vmName, dataCenterMoref, clusterMoref, hostMoref, vmPowerOn, vmReconnectNic vcenterInventorySourceId is found from the previous call. The remaining properties do not need to be modified.
URI Operation Description Return Codes
/api/v2/restored-copies POST Creates a task to perform instant access restore and executes it 201 Created
404 Not Found
401 Not Authorized
curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/restored-copies \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}' \
  --data '{
    "description": "Instant Access Restore",
    "copyId": "{{copyId}}",
    "restoreType": "INSTANT_ACCESS",
    "restoredCopiesDetails": {
      "targetVmInfo": {
        "inventorySourceId": "{{vcenterInventorySourceId}}",
        "vmName": "instant_access_attempt1",
        "dataCenterMoref": "datacenter-2",
        "clusterMoref": "domain-c7",
        "hostMoref": "host-15",
        "vmPowerOn": true,
        "vmReconnectNic": false
      }
    }
  }'
  • access_token from the Login API call
  • copyId for the previous call
  • vcenterInventorySourceId from the previous call
  • Morefs from the previous call

Sample response:

Created (201)

{
  "id": "0a581886-b980-400a-9d90-ff24cce6520d",
  "description": "Instant Access Restore",
  "state": "WAITING",
  "status": "UNKNOWN",
  "restoreType": "INSTANT_ACCESS",
  "copyId": "07decbd0-89f9-5c84-91a9-10281c0aabf7",
  "startTime": "2019-11-07T00:58:46.585Z",
  "completionTime": null,
  "expirationTime": null,
  "restoredCopiesDetails": {
    "targetVmInfo": {
      "inventorySourceId": "53fcb6a2-9843-4fcd-b457-409c720d092e",
      "vmName": "instant_access_attempt1",
      "dataCenterMoref": "datacenter-2",
      "clusterMoref": "domain-c7",
      "hostMoref": "host-15",
      "vmPowerOn": true,
      "vmReconnectNic": false
    }
  },
  "activityId": "feae507a-1e44-4936-8c53-d98ba0453115"
}

Summary

The basic workflow for restore to new using the PowerProtect Data Manager API is as follows. First, login to PowerProtect Data Manager to get an access_token to use for subsequent calls and gain access to the rest of the API. After that, get the asset information by requesting a GET on the asset by its name. This request is used to acquire the assetId, which is then used to view asset copies. Get a copyId by carrying it over from the list of copies (from the list, pick a copy and parse the JSON response for any ID). Then, get a vcenterInventorySourceId by requesting a GET on inventory sources and using the ID that is associated with the vCenter. After that, get the Morefs for the following in this order: datacenter, host, cluster, datastore. Finally, perform instant access restore by attaching the copyId and vcenterInventorySourceId to the body, setting the restoreType to “INSTANT_ACCESS” and sending a POST request to {{url}}/api/v2/restored-copies.

Extend instant access

Extend the instant access

Extends the time that an instant access VM is live given the copyId of the instant access VM and the number of days to extend.

Property Type Description Obtained by
restoredId (required) String Unique identifier for a specific instant access VM Carried over by user from previous call (instant access restore)
extendedDay (required) Integer Integer representing the number of days to extend the expiration of the instant access VM User input
URI Operation Description Return Codes
/api/v2/restored-copies/{{restoredId}}/expiration POST Creates a task to perform instant access restore and executes it 202 Accepted
404 Not Found
401 Not Authorized
curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/restored-copies/47f704d8-10a6-417d-94ad-336e311c6a74/expiration \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}' \
  --data '{
      "extendedDay": 1
  }'
  • access_token from the Login API call
  • restoredId for the previous restore call

Sample response:

OK (200)

{}

Summary

The basic workflow for extending an instant access session is as follows. First, login to PowerProtect Data Manager to get an access_token to use for subsequent calls and gain access to the rest of the API. In order to perform an extension for instant access sessions, the user must have an instant access copy resource (see section 6). Once this resource is applied, get the restoredId by doing a GET call on restored copies. Finally, perform the extension by doing a POST request on restored copies (v2/restored-copies/{{restoreId}}/expiration) with the number of desired extended days in the body.

vMotion

The first login step is same as before:

  1. Login

2. Perform the vMotion

Moves the instant access VM data from a Data Domain system to a datastore.

Property Type Description Obtained by
restoredId (required) String Unique identifier for a specific instant access VM. Carried over by user from previous call (get restored copies)
description String Describes the task that is about to be created User input
targetHostMoref String Managed object reference for the target host. If not specified, original host of the instant access VM is used. User input (See section that describes how to get vCenter related Morefs)
targetDatastoreMoref String Managed object reference for the target host. If not specified, original datastore of the instant access VM is used. User input (See section that describes how to get vCenter related Morefs)
targetResourcePoolMoref String Managed object reference for the target host. If not specified, original resource pool of the instant access VM is used. User input (See section on how to get vCenter related Morefs)
disks Array Specified virtual disk mapping to perform the restore to. See section about restoring individual disks. User input (See section 4.6 that describes how to get vCenter related Morefs)
URI Operation Description Return Codes
/api/v2/restored-copies/{{restoredId}}/vmotion POST Creates and executes a task to move the data of an instant access VM from Data Domain storage to a datastore in a vCenter. 201 Created
404 Not Found
401 Not Authorized
curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/restored-copies/ddb00c2b-c5cf-4583-a811-6561692adb53/vmotion \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}' \
  --data '{
      "description": "Performing vMotion on IA VM",
      "targetHostMoref": "host-12",
      "targetDatastoreMoref": "datastore-13",
      "targetResourcePoolMoref": "resgroup-23"
  }'
  • access_token from the Login API call
  • restoreId for the previous call
  • Instant Access VM in Mounted state

Sample response:

Created (202)

{
  "activityId": "88830b50-8dca-49f7-84ec-77da08f80473"
}

GET the activity 88830b50-8dca-49f7-84ec-77da08f80473 return this:

{
  "id" : "88830b50-8dca-49f7-84ec-77da08f80473",
  "jobId" : "7c745954-77a0-4b5c-b1f9-588f6be4e3e7",
  "parentId" : "7c745954-77a0-4b5c-b1f9-588f6be4e3e7",
  "name" : "Performing vMotion on IA VM",
  "description" : "Performing vMotion on IA VM",
  "state" : "QUEUED",
  "hasSubtasks" : false,
  "createTime" : "2019-11-12T17:53:41.903Z",
  "progress" : 0,
  "canRetry" : false,
  "cancellable" : true,
  "hasLogs" : false,
  "additionalProperties" : {
    "legacyTaskName" : {
      "id" : null,
      "name" : "Mounted Copy Manage Live VM",
      "type" : null
    },
    "parentJob" : {
      "id" : "88830b50-8dca-49f7-84ec-77da08f80473",
      "name" : null,
      "type" : "JOB"
    },
    "cancelEligible" : {
      "id" : null,
      "name" : "true",
      "type" : null
    }
  }
}

Summary

The basic workflow for vMotion is as follows. First, the user must have an instant access VM readily available (see section 6). When that VM is in its Mounted state, acquire its restoreId by doing a GET request on restored copies. Finally, fill the body with some optional attributes like targetDatastoreMoref, targetHostMoref, targetResourcePoolMoref, and so on., and do a POST request on {{url}}/v2/restored-copies/{{restoreId}}/vmotion. This creates and runs a task to perform the vMotion, moving the instant access VM data from the Data Domain storage to the vCenter datastore.