Skip to main content
Delphix

Delphix Virtualization Engine Web Services API Examples (KBA6927)

 

 

KBA

KBA# 6927

This article has been created to provide API examples that are not documented in the published product documentation. You can use these example to achieve automation objectives. 

Pre-requisites

  1. Before you can use any Delphix Web Service APIs you need to create a session and then authenticate by providing valid Delphix account credentials. Please follow the procedures on the following page to authenticate: https://docs.delphix.com/docs/develo...authentication
  2. It is generally recommended to set the API session version to the highest level supported by your Delphix Engine.

How to determine if a snapshot is locked and what is holding onto it?

The following API options allow Delphix to see the difference in snapshots.

1. descendantVDBs: List of VDB containers that are provisioned from this snapshot:

e.g.
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/capacity/snapshot' \ -b ~/cookies2.txt --header 'Content-Type: application/json'

Note: cookies2.txt is a file that is generated when you authenticate to Delphix WebServices as per pre-requisites section

Result:

e.g.
.........
{
            "type": "SnapshotCapacityData",
            "snapshot": "ORACLE_SNAPSHOT-6",
            "snapshotTimestamp": "2021-07-04T10:30:34.852Z",
            "policyRetention": true,
            "manualRetention": 0,
            "descendantVDBs": [
                "ORACLE_DB_CONTAINER-7"
            ],
            "container": "ORACLE_DB_CONTAINER-1",
            "space": 3.1082496E7,
            "size": -1
        },
        {
            "type": "SnapshotCapacityData",
            "snapshot": "ORACLE_SNAPSHOT-4",
            "snapshotTimestamp": "2021-07-03T10:30:32.374Z",
            "policyRetention": true,
            "manualRetention": 0,
            "descendantVDBs": [],
            "container": "ORACLE_DB_CONTAINER-1",
            "space": 2.9475328E7,
            "size": -1
        }
        .......

2. retention: Retention policy, in days. A value of -1 indicates the snapshot should be kept forever:

e.g.
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/snapshot' \ -b ~/cookies2.txt --header 'Content-Type: application/json'

Result:

e.g.
            .............
            "type": "OracleSnapshot",
            "reference": "ORACLE_SNAPSHOT-2",
            "namespace": null,
            "name": "@2021-06-10T22:35:34.323Z",
            "consistency": "INCONSISTENT",
            "missingNonLoggedData": false,
            "container": "ORACLE_DB_CONTAINER-1",
            .............
            },
            "retention": -1,
            "timeflow": "ORACLE_TIMEFLOW-1",
            "timezone": "America/New_York,EDT-0400",
            "version": "12.2.0.1.0",
            "runtime": {
                "type": "OracleSnapshotRuntime",
                "provisionable": true,
                "missingLogs": []
            .............

3. In Delphix 6.0.5.0,  deletionDependencies API was added :  this returns a tree of DeletionDependency nodes that represent the objects that needs to be deleted before the snapshot can be deleted.

e.g.
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/snapshot/ORACLE_SNAPSHOT-10/deletionDependencies' \ -b ~/cookies2.txt --header 'Content-Type: application/json'

Result:

e.g.
{
   "type":"OKResult",
   "status":"OK",
   "result":{
      "type":"DeletionDependency",
      "targetType":"TimeflowSnapshot",
      "targetReference":"ORACLE_SNAPSHOT-10",
      "namespaceName":null,
      "displayName":"2021-07-06T19:14:25.000+0000",
      "prerequisites":[
         
      ],
      "dependencies":[
         {
            "type":"TimeflowDeletionDependency",
            "targetType":"Timeflow",
            "targetReference":"ORACLE_TIMEFLOW-10",
            "namespaceName":null,
            "displayName":"DB_REFRESH@2021-07-06T13:30:50",
            "prerequisites":[
               {
                  "type":"DeletionDependencyPrerequisite",
                  "targetType":"Container",
                  "targetReference":"ORACLE_DB_CONTAINER-4",
                  "operationType":"REFRESH",
                  "namespaceName":null,
                  "displayName":"VCDO_YZA",
                  "locked":false
               }
            ],
            "dependencies":[
               
            ],
            "size":0.0,
            "locked":false,
            "containerName":"VCDO_YZA"
         }
      ],
      "size":8356352.0,
      "locked":false
   },
   "job":null,
   "action":null
}

How to upgrade the Delphix appliance using API calls?

To upgrade an engine using Web Services APIs, you need to run following sequence of API calls.

1. Upload an upgrade image. 

e.g.
curl -sv -X POST -F file=@<Upgrade bundle filename> http://<Your appliance name>/resources/json/system/uploadUpgrade -b ~/cookies2.txt --header 'Content-Type: application/json'

Note: cookies2.txt is a file that is generated when you authenticate to Delphix WebServices as per pre-requisites section

This is already documented in the product documentation here: https://docs.delphix.com/docs539/ref...-uploadupgrade

Result:

e.g.
{"status": "OK"}
$ 

2. To track the status of the above upload using an API call:

e.g.
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/action' \
-b ~/cookies2.txt --header 'Content-Type: application/json'

Result: "action" API returns all the actions history from which you can see actions related to "uploadUpgrade" API and those are:

e.g.
.........
{
    "type": "ListResult",
    "status": "OK",
    "result": [
        {
            "type": "Action",
            "reference": "ACTION-176",
            "namespace": null,
            "title": "UNPACK_VERSION",
            "details": "Unpack uploaded file \"1ce511c60a9efcb8a4287f0f431ec274.tar.gz\".",
            "startTime": "2021-07-29T19:02:15.593Z",
            "endTime": null,
            "user": "USER-1",
            "userAgent": null,
            "originIp": null,
            "parentAction": "ACTION-175",
            "actionType": "UNPACK_VERSION",
            "state": "WAITING",
            "workSource": "WEBSERVICE",
            "workSourceName": "sysadmin",
            "workSourcePrincipal": "sysadmin",
            "report": null,
            "failureDescription": null,
            "failureAction": null,
            "failureMessageCode": null
        },
        {
            "type": "Action",
            "reference": "ACTION-175",
            "namespace": null,
            "title": "REFRESH_VERSIONS",
            "details": "Refresh and prepare uploaded versions.",
            "startTime": "2021-07-29T19:02:14.466Z",
            "endTime": null,
            "user": "USER-1",
            "userAgent": "",
            "originIp": null,
            "parentAction": null,
            "actionType": "REFRESH_VERSIONS",
            "state": "WAITING",
            "workSource": "WEBSERVICE",
            "workSourceName": "sysadmin",
            "workSourcePrincipal": "sysadmin",
            "report": null,
            "failureDescription": null,
            "failureAction": null,
            "failureMessageCode": null
        }
.......

3. List the available versions and then extract the reference of the version that needs to be applied in next step:

e.g.
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/system/version' \ -b ~/cookies2.txt --header 'Content-Type: application/json'

Result:

e.g.
{
   "type":"ListResult",
   "status":"OK",
   "result":[
      {
         "type":"SystemVersion",
         "reference":"UPGRADE_VERSION-1",
         "namespace":null,
         "name":"5.3.8.1",
         "version":"5.3.8.1",
         "osVersion":"5.3.2019.11.09",
         "minOsVersion":"5.3.2019.03.04",
         "status":"CURRENTLY_RUNNING",
         "minVersion":"5.1.0.0",
         "buildDate":"2020-02-19T04:06:39.000Z",
         "installDate":"2020-03-11T23:12:18.000Z",
         "verifyDate":null,
         "osRunning":true
      },
      {
         "type":"SystemVersion",
         "reference":"UPGRADE_VERSION-2",
         "namespace":null,
         "name":"6.0.6.1",
         "version":"6.0.6.1",
         "osVersion":"Linux",
         "minOsVersion":"Linux",
         "status":"VERIFIED",
         "minVersion":"5.3.6.0",
         "buildDate":"2021-02-01T20:28:01.000Z",
         "installDate":null,
         "verifyDate":"2021-07-29T19:16:45.385Z",
         "osRunning":false
      }
   ],
   "job":null,
   "action":null,
   "total":2,
   "overflow":false
}

4. Retrieve the version reference that needs to be applied:

curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/system/version/UPGRADE_VERSION-2' \
-b ~/cookies2.txt --header 'Content-Type: application/json'

Result:

e.g.
{
   "type":"OKResult",
   "status":"OK",
   "result":{
      "type":"SystemVersion",
      "reference":"UPGRADE_VERSION-2",
      "namespace":null,
      "name":"6.0.6.1",
      "version":"6.0.6.1",
      "osVersion":"Linux",
      "minOsVersion":"Linux",
      "status":"VERIFIED",
      "minVersion":"5.3.6.0",
      "buildDate":"2021-02-01T20:28:01.000Z",
      "installDate":null,
      "verifyDate":"2021-07-29T19:16:45.385Z",
      "osRunning":false
   },
   "job":null,
   "action":null
}

5. To run verify version again, run this API:

curl --location --request POST 'http://<Your appliance name>/resources/json/delphix/system/version/UPGRADE_VERSION-2/verify' \
-b ~/cookies2.txt --header 'Content-Type: application/json'

Result:

e.g.
{
   "type":"OKResult",
   "status":"OK",
   "result":"",
   "job":"JOB-80",
   "action":"ACTION-181"
}

6. Apply an upgrade with the referenced version that you need to upgrade:

curl --location --request POST 'http://<Your appliance name>/resources/json/delphix/system/version/UPGRADE_VERSION-2/apply' \
-b ~/cookies2.txt --header 'Content-Type: application/json'

Result:

{
   "type":"OKResult",
   "status":"OK",
   "result":"",
   "job":"JOB-82",
   "action":"ACTION-183"
}

How to use APIs to retrieve the "Your Data" value displayed in the Storage Capacity screen?

To get the "your data" value that is seen in UI, you need to run following two APIs.

1. First, list all of the database objects:

e.g.
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/database' \ -b ~/cookies2.txt --header 'Content-Type: application/json'

Note: cookies2.txt is a file that is generated when you authenticate to Delphix WebServices as per pre-requisites section

This will return details about all of the databases on the engine:

e.g.
{
    "type": "ListResult",
    "status": "OK",
    "result": [
        {
            "type": "OracleDatabaseContainer",
            "reference": "ORACLE_DB_CONTAINER-1",
            "namespace": null,
            "name": "CDOMLOSR8325",
            "group": "GROUP-2",
            "provisionContainer": null,
            "currentTimeflow": "ORACLE_TIMEFLOW-1",
            "description": null,
            "runtime": {
                "type": "OracleDBContainerRuntime",
                "logSyncActive": true,
                "preProvisioningStatus": null,
                "crossPlatformScriptUploaded": false,
                "crossPlatformEligible": false
                ..............................
                ..............................

2. The part you are interested here is the reference key as bolded above. These references will need to be collected into a list and then formatted properly and passed to the second API endpoint as shown in this example:

e.g.
curl --location --request POST 'http://<Your appliance name>/resources/json/delphix/snapshot/space' \
--header 'Content-Type: application/json' \
-b ~/cookies2.txt \
--data-raw '{
   "objectReferences":[
      "ORACLE_DB_CONTAINER-1",
      "ORACLE_DB_CONTAINER-2"
],
   "type":"SnapshotSpaceParameters"
}'

This will return result as follows:

e.g.
{"type":"OKResult","status":"OK","result":{"type":"SnapshotSpaceResult","totalSize":5.278370304E9},"job":null,"action":null}

The totalSize value is what you are looking for. It will have to be reformatted to meet whatever output requirements you have. As an example, the following simple math will convert the value to GB:

e.g.
5278370304 / 1025 / 1024/ 1024    =>  4.915GB

How to list all databases in an environment similar to the list seen on the UI flow > Environment > Database tab?

To see the content of the database list similar to the list seen in the UI flow > Environment > Database tab, you need to run the following 3 steps.

1. You need to first list the repositories:

e.g. 
 curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/repository' -b ~/cookies2.txt --header 'Content-Type: application/json'

Note: cookies2.txt is a file that is generated when you authenticate to Delphix WebServices as per pre-requisites section

This returns an Oracle installations list for all the environments. You will have to note the desired environment for the next step.

e.g. 
{
    "type": "ListResult",
    "status": "OK",
    "result": [
        {
            "type": "OracleInstall",
            "reference": "ORACLE_INSTALL-1",
            "namespace": null,
            "name": "/u01/app/oracle/product/19.0.0.0/dbhome_1",
            "version": "19.3.0.0.0",
            "provisioningEnabled": true,
            "environment": "UNIX_HOST_ENVIRONMENT-1",
            "staging": false,
            "installationHome": "/u01/app/oracle/product/19.0.0.0/dbhome_1",
            "oracleBase": "/u01/app/oracle",
            "groupName": "oinstall",
            "groupId": 1000,
            "userName": "oracle",
            "userId": 1000,
            "bits": 64,
            "rac": false,
            "discovered": true,
            "logsyncPossible": null,
            "linkingEnabled": true
            ......................
            ......................

2. Filter the repositories for a desired environment:            

e.g. 
 curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/repository?environment=UNIX_HOST_ENVIRONMENT-1' -b ~/cookies2.txt --header 'Content-Type: application/json'

This returns the Oracle installations list for selected environment, just like you see in UI path > Environment > Databases

e.g.
{
    "type": "ListResult",
    "status": "OK",
    "result": [
        {
            "type": "OracleInstall",
            "reference": "ORACLE_INSTALL-1",
            "namespace": null,
            "name": "/u01/app/oracle/product/19.0.0.0/dbhome_1",
            "version": "19.3.0.0.0",
            "provisioningEnabled": true,
            "environment": "UNIX_HOST_ENVIRONMENT-1",
            "staging": false,
            "installationHome": "/u01/app/oracle/product/19.0.0.0/dbhome_1",
            "oracleBase": "/u01/app/oracle",
            "groupName": "oinstall",
            "groupId": 1000,
            "userName": "oracle",
            "userId": 1000,
            "bits": 64,
            "rac": false,
            "discovered": true,
            "logsyncPossible": null,
            "linkingEnabled": true
            ......................
            ......................

3. Finally list the databases for the desired environment

e.g. 
curl --location --request GET 'http://<Your appliance name>/resources/json/delphix/sourceconfig?environment=UNIX_HOST_ENVIRONMENT-1' \
-b ~/cookies2.txt -H "Content-Type: application/json"

This will list all the Oracle databases for the selected environment, just like you see in UI path > Environment > Databases.

e.g. 
{
"type": "ListResult",
"status": "OK",
"result": [
{
"type": "OracleSIConfig",
"reference": "ORACLE_SINGLE_CONFIG-3",
"namespace": null,
"name": "CDOMSHSRF2E1",
"linkingEnabled": true,
"discovered": true,
"environmentUser": "HOST_USER-1",
"repository": "ORACLE_INSTALL-1",
"user": null,
"credentials": {
"type": "PasswordCredential",
"password": null
....................
....................

 

 

Related Articles 

The following articles may provide more information or related information to this article: