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": {
        json.dumps([
            {
                "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 23 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": [],
            ...
        }
    ]
}