Searching virtualized system instances

Search instances of virtualized systems.

Method and URI

To search VMware instances with a search string, use a GET method and a URI:

POST    https://{hostname|IP}/api/hypervisor/search

Parameters

Parameter 1: resourceType

The resource type to search with. In the web user interface, you can select one from the View: drop-down list.

  • Value: Use one of the following value:

Search target

Value

Virtual machines and templates

vm

Datastore

volume

Tags

tag

Tags and categories

tagcategory

  • Type: System string. Required. Available in the web user interface.

Parameter 2: from

  • Value: hlo

  • Type: System string. Required.

Parameter 3: filter

Optionally, you may use a filter to specify the search target. If this parameter is not used, IBM Spectrum Protect Plus searches within all virtual machines. You can use the filter operation parameters that are described in Filter.

  • Example value: To search within instances that are associated with none of SLA policies, use the following filter parameter:

[
    {
        "property": "unprotected",
        "value":    "true",
        "op":       "="
    }
]
  • Example value: To search with instances that are associated with the SLA policy, Gold, use the following parameter:

[
    {
        "property": "storageProfileName",
        "value":    "Gold",
        "op":       "="
    }
]
  • Type: Array. Available in the web user interface.

Data

Data 1: name

The search string. The name value can contain the following wildcard characters:

Wildcard character

Description

* (asterisk)

Matches zero or more characters.

? (question mark)

Matches any single character at the present position.

  • Example value: sales-*

  • Type: String. Required. Available in the web user interface.

Data 2: hypervisorType

The type of virtualized system servers.

  • Value: Use one of the following value:

Virtualized system

Value

VMware vCenter

vmware

Hyper-V

hyperv

Amazon EC2

awsec2

  • Type: String. Required. Available in the web user interface.

Example: Search VMware instances for virtual machines with a specific SLA policy

Assume that you have VMware assests in IBM Spectrum Protect Plus. You want to retrieve names of all virtual machines with the following properties:

  • Resource type: Virtual machines and templates

  • Filter:

    • SLA policy: Diamond

  • Hypervisor type: VMware

  • Name: \*-dallas?

The string with the wildcard characters represents the name beginning with zero or more of any characters, followed by -dallas, and ending with any single character.

_params = {
    "resourceType": "vm",
    "from": "hlo",
    "filter": {
        [
            {
                "property": "storageProfileName",
                "value":    "Diamond",
                "op":       "="
            }
        ]
    }
}

_data = f'''{{
    "name": "*-dallas?",
    "hypervisorType": "vmware"
}}'''

requests.post('https://' + spp_ipv4 + '/api/hypervisor/search',
    headers={...}, params=_params, data=_data, verify=...)
_images/refmanageprotection_vmware_search01.png

Figure 22 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the VMware pane, fill the search string with the search field, set the filter if needed, and click Search.

The request prompts a response that is structured as shown, with the HTTP status of 200 (OK).

{
    "links": {...},
    "total": 2,
    "vms": [
        {
            "links": {...},
            "name": "vsnap-dallas1",
            "type": "vm",
            "association": null,
            "protectionInfo": null,
            "recoveryInfo": null,
            "recoveryPoint": null,
            "siteId": null,
            "autoProvisionedsubPolicyName": null,
            "rbacPath": "root:0/hypervisor.all:0/hypervisor.type:vmware/hypervis
or:1004/vdc:717dafb25bbbca30d8dc72ed3cbf81f0/vfld:716779e50daefc126bbaed0ef3c36
22d/vm:8848ad8c1d38ef880cb892a5570d50f5",
            "rbacPathId": 4146,
            "extInfo": null,
            "location": "/vmware-dallas1.bluemachines.com.invalid/Dallas - DataC
enter1/Production folder",
            "metadataPath": "/MS:1004/DC:717dafb25bbbca30d8dc72ed3cbf81f0/FLDR:7
16779e50daefc126bbaed0ef3c3622d/VM:8848ad8c1d38ef880cb892a5570d50f5",
            "inHLO": true,
            "hypervisorType": "vmware",
            "hypervisorKey": "1004",
            "hypervisorManagementServerID": "1004",
            "nativeKey": "vm-104786",
            "cloudType": null,
            "tags": [],
            "tagCategories": [],
            "metadataPathVmHost": "/MS:1004/DC:717dafb25bbbca30d8dc72ed3cbf81f0/
CLUST:14100077601aaa13a1fdf555a065d58f/HOST:735cda83d7290ea7fa685ae7cdc3e95c/VM
:8848ad8c1d38ef880cb892a5570d50f5",
            "rbacPathVmHost": "root:0/hypervisor.all:0/hypervisor.type:vmware/hy
pervisor:1004/vdc:717dafb25bbbca30d8dc72ed3cbf81f0/vcluster:14100077601aaa13a1f
df555a065d58f/vhost:735cda83d7290ea7fa685ae7cdc3e95c/vm:8848ad8c1d38ef880cb892a
5570d50f5",
            "rbacPathIdVmHost": 4147,
            "alternatePaths": [
                {
                    "rbacPath": "root:0/hypervisor.all:0/hypervisor.type:vmware/
hypervisor:1004/vtagcategory:a6068ad43059b6b6fc3a0986ba7a0bed/vtag:a3269bb10cfb
e7a1588a5a3a5b3637de/vm:8848ad8c1d38ef880cb892a5570d50f5",
                    "rbacPathId": 4148,
                    "metadataPath": "/MS:1004/TAGCATEGORY:a6068ad43059b6b6fc3a09
86ba7a0bed/TAG:a3269bb10cfbe7a1588a5a3a5b3637de/VM:8848ad8c1d38ef880cb892a5570d
50f5"
                }
            ],
            "powerSummary": {
                "powerState": "ON",
                "lastPowerOnTime": null,
                "lastPowerOffTime": null,
                "lastSuspendTime": null,
                "uptime": 1574371737324
            },
            "storageSummary": {
                "commited": 80351072860,
                "uncommited": 92048196830,
                "shared": 78085357568
            },
            "hypervisorHostKey": "735cda83d7290ea7fa685ae7cdc3e95c",
            "volumes": [
                {
                    "name": "IBM_Flash_System-Dallas",
                    "key": "00613cbaf57e385be9853046d07271f5",
                    "configVolume": true
                },
                {
                    "name": "isoImages",
                    "key": "ece8716493cd0d5b7283552b67bf263c",
                    "configVolume": false
                }
            ],
            "hypervisorFolderKey": "716779e50daefc126bbaed0ef3c3622d",
            "hypervisorFolderPath": "Production folder",
            "uniqueId": "4209f06b-f688-c4af-90d2-e93b6e40f270:5009d293-7abc-4b48
-4a29-818f3045445e",
            "profileId": null,
            "keyId": null,
            "keyProviderId": null,
            "configFilePath": "[SG_STORAGE] sales-apac/sales-apac.vmx",
            "fileDirPath": null,
            "datacenter": {
                "name": "BlueMachines_vCenter_Dallas1",
                "key": "717dafb25bbbca30d8dc72ed3cbf81f0"
            },
            "cluster": {
                "name": "PS_SEcluster",
                "key": "14100077601aaa13a1fdf555a065d58f"
            },
            "vmGroup": null,
            "resourcePool": {
                "name": "Resources",
                "key": "784eb71414bd617fdb01be7f5d7acd50"
            },
            "cpu": 1,
            "coresPerCpu": 1,
            "memory": 2147483648,
            "vmVersion": "vmx-13",
            "customAttributes": {},
            "vmStorageUtilization": null,
            "configInfo": {
                "name": null,
                "type": null,
                "association": null,
                "protectionInfo": null,
                "recoveryInfo": null,
                "recoveryPoint": null,
                "siteId": null,
                "autoProvisionedsubPolicyName": null,
                "rbacPath": null,
                "rbacPathId": null,
                "extInfo": null,
                "location": null,
                "metadataPath": null,
                "inHLO": true,
                "hypervisorType": null,
                "hypervisorKey": null,
                "hypervisorManagementServerID": null,
                "nativeKey": null,
                "cloudType": null,
                "tags": null,
                "tagCategories": null,
                "metadataPathVmHost": null,
                "rbacPathVmHost": null,
                "rbacPathIdVmHost": null,
                "alternatePaths": null,
                "vmId": null,
                "osName": null,
                "osVersion": null,
                "hostName": null,
                "vmToolsStatus": "NOT_INSTALLED",
                "guestNetworkInfo": [],
                "windows": false,
                "linux": false,
                "nativeObject": {},
                "hypervisorHostKey": null,
                "volumeId": null,
                "volumes": [],
                "protected": false,
                "systemHold": false,
                "id": null
            },
            "attachments": [],
            "vmMetadata": {},
            "encrypted": false,
            "hypervisorHostname": "vmware-singapore1.bluemachines.com.invalid",
            "vmPoolDedupCompressionInfo": null,
            "windows": false,
            "template": false,
            "linux": false,
            "versionId": "vm.8848ad8c1d38ef880cb892a5570d50f5.1578038400234",
            "nativeObject": {},
            "volumeId": null,
            "protected": false,
            "systemHold": false,
            "id": "8848ad8c1d38ef880cb892a5570d50f5",
            "config": {
                "name": null,
                "type": null,
                "association": null,
                "protectionInfo": null,
                "recoveryInfo": null,
                "recoveryPoint": null,
                "siteId": null,
                "autoProvisionedsubPolicyName": null,
                "rbacPath": null,
                "rbacPathId": null,
                "extInfo": null,
                "location": null,
                "metadataPath": null,
                "inHLO": true,
                "hypervisorType": null,
                "hypervisorKey": null,
                "hypervisorManagementServerID": null,
                "nativeKey": null,
                "cloudType": null,
                "tags": null,
                "tagCategories": null,
                "metadataPathVmHost": null,
                "rbacPathVmHost": null,
                "rbacPathIdVmHost": null,
                "alternatePaths": null,
                "vmId": null,
                "osName": null,
                "osVersion": null,
                "hostName": null,
                "vmToolsStatus": "NOT_INSTALLED",
                "guestNetworkInfo": [],
                "windows": false,
                "linux": false,
                "nativeObject": {},
                "hypervisorHostKey": null,
                "volumeId": null,
                "volumes": [],
                "protected": false,
                "systemHold": false,
                "id": null
            },
            "resourceType": "vm",
            "storageProfiles": [],
            "copies": null
        },
        {
            "links": {...},
            "name": "oracle-dallas2",
            "type": "vm",
            "association": null,
            "protectionInfo": null,
            "recoveryInfo": null,
            "recoveryPoint": null,
            "siteId": null,
            "autoProvisionedsubPolicyName": null,
            "rbacPath": "root:0/hypervisor.all:0/hypervisor.type:vmware/hypervis
or:1004/vdc:717dafb25bbbca30d8dc72ed3cbf81f0/vfld:716779e50daefc126bbaed0ef3c36
22d/vm:2648550a670c6d383cba0d369ae4f91c",
            "rbacPathId": 5310,
            "extInfo": null,
            "location": "/vmware-dallas1.bluemachines.com.invalid/Dallas - Datac
enter1/Production folder",
            "metadataPath": "/MS:1004/DC:717dafb25bbbca30d8dc72ed3cbf81f0/FLDR:7
16779e50daefc126bbaed0ef3c3622d/VM:2648550a670c6d383cba0d369ae4f91c",
            "inHLO": true,
            "hypervisorType": "vmware",
            "hypervisorKey": "1004",
            "hypervisorManagementServerID": "1004",
            "nativeKey": "vm-123790",
            "cloudType": null,
            "tags": [],
            "tagCategories": [],
            ...
        }
    ]
}