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 file level restore

The File Level Restore (FLR) APIs consist of these function calls:

REST API HTTP method Description
/api/v2/flr-sessions POST Creates a FLR session.
/api/v2/flr-sessions/{id} DELETE Terminates and deletes the FLR session.
/api/v2/flr-sessions/{id} PUT Changes the configuration of the FLR session. Used to change the directory for browing either the source or target.
/api/v2/flr-sessions/{id} GET Retrieves the configuration of the browse session, that is, the current directory, browsing the source or target.
/api/v2/flr-sessions/{id}/files GET Retrieves a list of files in the current directory on the source or the target.
/api/v2/flr-sessions/{id}/tasks POST Initiates the restore of specified directories/files. Returns a task that can be monitored for status.
/api/v2/flr-sessions-batch POST Submits multiple FLR requests in a single batch.

The steps in a typical FLR work flow include:

  1. Create FLR session. Monitor the returned task for completion.
  2. Browse the source and target and save a list of the files or directories (or both) to be restored. Browsing the source and target are not strictly necessary. Browsing the copy can be omitted if the file list is known before the restore is done. Browsing the target is not needed if the restoreToOriginalPath is used during the restore or if the target directory is known before the the file restore is done. The source (that is, the copy) and target VM can be browsed in any order or even interleaved. No requirement exists to browse one before the other.
  3. Restore the files.
  4. Delete FLR session. Delete is automatically done if the restore files API is called. Also, the session automatically times out according to the timeout value that you specified when the session was created.

The following shows more detailed information about the FLR APIs:

Create FLR session

Initiate an FLR mount session.

curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions \
  --header 'content-type: application/json' \
  --data '{
    "copyId": "<ID of the copy to mount>",
    "targetVmAssetId" : "<asset Id of the target VM>",
    "targetUser" : "<user on targetVM>",
    "targetPassword" : "<password of user>",
    "timeout" : "<timeout in seconds>", (Optional - default 300 seconds)
    "removeAgent" : "<true/false"> (Optional - default false) 
  }'
  • The copyId is the UUID of a PowerProtect Data Manager copy.
  • targetVmAssetId is the PowerProtect Data Manager UUID of the VM to restore to. It does not have to be the original VM, but it does have to exist.
  • targetUser/targetPassword must be Administrator/root to support installing the agent on guest OS and managing mounts.
  • Mounts the copy (all disks) on the target in a folder.
  • timeout is optional and defaults to 300 seconds.
  • If removeAgent is true, the FLR agent is removed when the FLR session is deleted.

Sample response:

Accepted (202)

{
  "flrSessionId": "xxxxxx",
  "taskId": "yyy-yyy"
}
  • Returns a taskId (referred to as activityId). You can monitor the task for progress and completion status.

Show FLR session state

Returns the FLR session state.

curl --request GET \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions/{id} \
  --header 'content-type: application/json'

Sample response:

OK (200)

{
  "browseDest" : <true or false>,
  "directory" : ""
}

Modify FLR session state

Changes the type of browse session and the current working directory for GET calls.

curl --request PUT \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions/{id} \
  --header 'content-type: application/json' \
  --data '{
    "browseDest" : <true or false>,
    "directory" : ""
  }'
  • If browseDest is true, then only directories are returned from subsequent GET calls.

  • The directory is relative to the mount location on the guest VM and must not start with a leading “/”. The initial GET call returns a list of folders where the disks in the backup are mounted. All subsequent PUT calls should pass in paths that start with one of these disk folders.

Sample response:

OK (200)

{
  "browseDest" : <true or false>,
  "directory" : ""
}

Retrieve directory listing

Get the contents of a directory.

The example shows the top level listing returned when PUT is called with a directory of “”. In this example, it is showing a single disk on a linux VM. For a Windows VM, it shows disks as folders like “00-C$”, “00-D$”, and so on.

This API supports standard PowerProtect pagination since a given directory may contain a large number of files.

Only directories are returned when browsing the destination.

curl --request GET \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions/{id}/files \
  --header 'content-type: application/json'
  • This API does not have a request body, but it does support optional path parameters: page, pageSize, filter, and orderby.

  • page is the number of the page of files to return. A large directory is divided into individual pages that are retrieved separately.

  • pageSize is the maximum number of files that appear in a page.

  • A filter is used to limit the list of files returned by the get files API. Filters are specified as path parameter in the URL by using the keyword “filter” (preceded by a “?” character) then followed by a “=” sign, then the filter string on the URL. An example of a filter is: /api/v2/flr-sessions/files?filter=’…’. The results can be filtered on the file attributes: “name”, “size”, and “type”. A name filter is a string of alphanumeric characters. Wild cards can be used in a name filter. For example, the filter ‘name lk “ho”’ returns the list of files that begin with the string “ho”.

  • The operand of a size filter must be an integer. For example, ‘filter=size gt 512’ returns all files greater than 512 bytes. The operands of the type field are limited to the values: “directory”, “symlink”, and “file”. The filter ‘type eq symlink’ only returns symbolic link files.

  • Supported operators are: “eq”, “ne”, “gt”, “ge”, “lt”, “le”, “lk” and “%”. The filter string must be a URL-encoded string. Spaces and special characters are replaced with their URL-encoded equivalents. For example, a space character is replaced with the string “%20”. Only one filter can be specified at a time. For example, the (non-URL-encoded) filter ‘filter= name lk “ho2”’ is supported while the filter of ‘filter=name lk “ho”&filter=size gt 512”’ is not.

  • orderby indicates how files are listed. ASC indicates ascending alphabetical order while DESC indicates descending alphabetical order. The default is ASC.

Sample response:

OK (200)

{
  "page": {
    "size": 1,
    "number": 1,
    "totalPages": 1,
    "totalElements": 1
  },
  "content": [
    {
      "name": "/etc",
      "type": "directory",
      "size": 52
    }
  ]
}

Restore Files

Restore one or more files or directories.

curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions/{id}/tasks \
  --header 'content-type: application/json' \
  --data '{
    "targetDirectory": "/tmp",
    "filePaths": [
      "/home/dsl/.gtkrc",
      "/home/dsl/.vimrc"
    ],
    "overwriteExisting" : <true/false> (Optional - default true),
    "restoreToOriginalPath" : <true/false> (Optional - default false)
  }'
  • targetDirectory is the folder where the files are restored. It does not have to be the original location. This folder should already exist.

  • filePaths is an array of paths rooted at one or more of the disk folders that are returned on the first call to browse. No calls to PUT are required if the caller knows the file path or paths. Otherwise, these paths are the same paths as returned by browse (GET) calls.

  • If any given path ends in a directory, then all files contained under that directory are restored.

  • When restoreToOriginalPath path is true, the files are restored to their original locations. In this case, the targetDirectory parameter must be null or empty. When restoreToOriginalPath is false, the files are restored to the directory that is specified by the targetDirectory parameter.

Sample response:

Accepted (202)

{
  "taskId": "yyy-yyy"
}

This API returns a taskId (referred to as activityId) that can be monitored for progress and status.

Delete the FLR session

Delete is automatically performed after the timeout that is specified when the session is created and when the restore files API is called.

The restore files API is called when the user wants to immediately close the FLR session.

This API unmounts the copy from the target VM.

Delete is not permitted if FLR is already in progress.

curl --request DELETE \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions/{id} \
  --header 'content-type: application/json'

Sample response:

Accepted (202)

{
  "taskId": "yyy-yyy"
}

This API returns a taskId (referred to as activityId) that can be monitored for progress and status.

Submit FLR requests in batch

You can submit multiple FLR requests in a single batch operation. Each FLR request in the batch is submitted as a separate FLR session. The batch operation creates a separate job within a job group for each FLR request. Each copy is mounted on the target VM and the selected files are restored. Then each copy is unmounted.

curl --request POST \
  --url https://<your-ppdm-server>:8443/api/v2/flr-sessions-batch \
  --header 'content-type: application/json'

Sample request:

{
  "requests": [
    {
      "id" : "1234",
      "body": {
        "copyId": "uuid5678",
        "removeAgent": false,
        "timeout": 300,
        "targetVMAssetId": "1234-3452345-123123",
        "targetUser": "admin",
        "targetPassword": "hunter2",
        "filePaths": [
          "/path/to/file/1",
          "/path/to/file/2"
        ],
        "overWriteExisting": true,
        "restoreToOriginalPath": true
      }
    },
    {
      "id" : "1234",
      "body": {
        "copyId": "uuid1234",
        "removeAgent": true,
        "timeout": 900,
        "targetVMAssetId": "1234-4356456-123123",
        "targetUser": "joe",
        "targetPassword": "foobar",
        "filesPaths": [
          "/path/to/file/1",
          "/path/to/file/2"
        ],
        "overWriteExisting": false,
        "restoreToOriginalPath": false,
        "targetDirectory": "/path/to/restore/"
      }
    }
  ]
}

The response body includes an array of response objects from each of the individual FLR requests in the batch operation. It lists a job group that contains a job for each entry in the array. Each job includes a task for mount and restore operations.

The 207 multi-status code represents a response for multiple, independent operations within a batch. It can contain multiple, separate, response codes, depending on the number of requests in the batch. Some request items can appear as errors in the response.

Sample response:

{
  "responses": [
    {
      "id": "1234",
      "status": 207,
      "body": {
        "activityId": "aaaaaa-bbbb-cccc-dddd-eeeeee"
      }
    },
    {
      "id": "5678",
      "status": 400,
      "body": {
        "error": {
          "code": xxx,
          "reason": "yyy",
          "remediation": "zzz",
          "timestamp": "1969-12-31T00:00:00Z"
        }
      }
    }
  ]
}