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

Manage retention time for existing copy

This tutorial describes how to set up the retention time for an existing copy. The following API is used:

PUT /api/v2/copies/{id}

To set up the retention time, you must first retrieve all copies for the specified asset in the PowerProtect Data Manager. A copy is a backup of the asset.

Login

Use the login API to retrieve the access token. For more details, see the tutorial for authentication and authorization.

Get assets by name

Assets are customer properties that must be protected. Examples include VMware machine, database, file system volumes, and so on.

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'
  • 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 for assetId in subsequent calls.

Get asset copies

Retrieves a list of all the copies for the specified asset.

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/{{assetId}}/copies?pageSize=2 \
  --header 'content-type: application/json' \
  --header 'Authorization:  {{access_token}}'
  • access_token from the Login API call
  • assetId from the previous call

Sample response:

OK (200)

{
  "page" : {
    "size" : 1,
    "number" : 1,
    "totalPages" : 1,
    "totalElements" : 1
  },
  "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
  }]
}
  • Any of the IDs inside the content can be used for copyId in subsequent calls.

Update retention time for a copy

Set up the retention time for the specified copy.

Property Type Description Sample Data
copyId (required) String Unique identifier for a specific asset copy Previous call (get asset copies)
retentiontime String The retention time to be updated. The retention date should be greater than current value. 2019-11-13T16:00:00.000Z
URI Operation Description Return Codes
/api/v2/copies/{{copyID}} PUT Update the retention time 200 OK
400 Valid Request
401 Request not allowed
403 Not Authorized
curl --request PUT \
  --url https://<your-ppdm-server>:8443/api/v2/copies/{{copyId}} \
  --header 'content-type: application/json' \

Request body:

{
    "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
}

Sample response:

Accept (202)

{
  "taskId": null
}

Update retention time by batch

Set up the retention time for copies.

Property Type Description Sample Data
id String Mark number of copies 1
body object Contains copy ID and update retention time “body”: {
“id”: “XXXX-XXXX-XXXX-XXXX-XXXX”,
“retentionTime”: 2020-09-30T16:00:00.000Z
}
URI Operation Description Return Codes
/api/v2/copies-batch PATCH Update the retention time by batch 200 OK
400 Valid Request
401 Request not allowed
403 Not Authorized
curl --request PATCH \
  --url https://<your-ppdm-server>:8443/api/v2/copies-batch \
  --header 'content-type: application/json' \

Request body:

{
    "requests": [
        {
            "id": "0",
            "body": {
                "id": "xxxx-xxxx-xxxx-xxx0",
                "retentionTime": 2020-09-30T16:00:00.000Z
            }
        },
		{
            "id": "1",
            "body": {
                "id": "xxxx-xxxx-xxxx-xxx1",
                "retentionTime": 2020-09-30T16:00:00.000Z
            }
        },
		{
            "id": "2",
            "body": {
                "id": "xxxx-xxxx-xxxx-xxx2",
                "retentionTime": 2020-09-30T16:00:00.000Z
            }
        }
    ]
}

Sample response:

Accept (202)

{
  "taskId": null
}