Hitachi

JP1 Version 12 JP1/Operations Analytics REST API Reference Guide


2.17.1 Obtaining Virtual Machine List

This API acquires a list of virtual machines.

This API request can also be used as follows to get information on demand.

1. Overview

Instead of getting virtual machine information that is collected during regular collection cycles, use this API request to get information that is up-to-date as of the time the request is executed.

2. Limitations

(a) Information can only be acquired on demand from virtual machines in a vCenter. In addition, only the following information, which is in the VirtualMachines table that follows, can be acquired:

- instanceID

- name

- ipAddress

- description

- clusterName

- hypervisorName

- hostName

(b) Query parameters cannot be specified.

3. Setting Method

See the section describing the system property file (Argus.properties), in the JP1/Operations Analytics Configuration and Administration Guide.

Execution permission

Admin, Modify

API version

v1

Request format

GET http[s]://host:port/Analytics/version/objects/VirtualMachines

Request body

Not applicable.

Response body

The structure of the response body and the object attributes are as follows:
{
        "data":[{
            "instanceID":"...",
            "name":"...",
            "ipAddress":"...",
            "status":"...",
            "monitorStatus":"...",
            "description":"...",
            "componentType":"...",
            "collectorID":"...",
            "collectorName":"...",
            "autoCollectionType":"...",
            "clusterName":"...",
            "hypervisorType":"...",
            "hypervisorDetailType":"...",
            "hypervisorID":"...",
            "hypervisorName":"...",
            "hypervisorMonitorStatus":"...",
            "hostName":"...",
            "thresholdProfileID":"...",
            "thresholdProfileName":"...",
            "originalThresholdProfileID":"...",
            "groupIDs":["...", ...],
            "groupNames":["...", ...],
            "gradeNames":["...", ...],
            "gradeOrders":["...", ...],
            "usedCredentialID":"...",
            "usedCredentials":"...",
            "accessPointType":"...",
            "accessPointSnmpVersion":"...",
            "accessPointIpAddress":"...",
            "accessPointUser":"...",
            "pluginId":"..."
        },
        :
        ],
        "pagination":{
            "page":"...",
            "pageSize":"...",
            "numPages":"...",
            "totalCount":"..."
        },
        "count":"...",
        "errorInfo":[{
            "nodeName":"...",
            "message":"...",
            "messageID":"..."
        },
        :
        ]
}

Collections (Type: Collections)

Attribute

Type

Description

data

VirtualMachine[]

A list of VirtualMachine objects. For details about VirtualMachine, see the table below.

pagination

Pagination

Page information. This parameter is displayed only when the relevant resource exists.

count

int

Number of data items that meet the conditions.

errorInfo

FailedNodes[]

A list of FailedNodes objects. For details about FailedNodes, see the table below.

data (Type: VirtualMachine)

Attribute

Type

Description

instanceID

long

ID of the virtual machine

name

string

Name of the virtual machine

ipAddress

string

IP Address set for the virtual machine

status

enum

Status of the virtual machine

(For details about the specifiable values, see the table NodeStatusType in List of enumerators.)

The specifiable values are as follows:

  • Normal
  • Warning
  • Error
  • Unreachable
  • Unknown
  • NotMonitored

monitorStatus

enum

Monitoring status of the virtual machine

(For details about the specifiable values, see the table ComponentMonitorType in List of enumerators.)

The specifiable values are as follows:

  • InUse
  • NotMonitored

description

string

Detailed information about the virtual machine

componentType

enum

Type of the virtual machine.

(For details about the specifiable values, see the table ComponentType in List of enumerators.)

The specifiable values are as follows:

  • VIRTUAL_MACHINE
  • GENERIC_VIRTUALMACHINE

collectorID

long

ID for identifying a collector used for detection

collectorName

string

Name of a collector used for detection

autoCollectionType

enum

Settings for periodic executions of the collector.

(For details about the specifiable values, see the table ConnectType in List of enumerators.)

The specifiable values are as follows:

  • AutoConnect
  • NotAutoConnect

clusterName

string

Name of the Cluster that the virtual machine belongs to

hypervisorType

enum

Type of hypervisor that the virtual machine belongs to

(For details about the specifiable values, see the table ArgusNodeType in List of enumerators.)

The specifiable values are as follows:

  • SERVER_ESX
  • SERVER_HYPERV
  • GENERIC_HYPERVISOR

hypervisorDetailType

string

Detail type of the hypervisor that the virtual machine belongs to

hypervisorID

long

ID of the hypervisor that the virtual machine belongs to

hypervisorName

string

Name of the hypervisor that the virtual machine belongs to

hypervisorMonitorStatus

enum

Monitoring status of the hypervisor that the virtual machine belongs to

(For details about the specifiable values, see the table ManagementLevelType in List of enumerators.)

The specifiable values are as follows:

  • New
  • Manage
  • ignore
  • MonitorOff

hostName

string

The name of host which is installed on virtual machine

thresholdProfileID

long

ID of the threshold profile assigned to the virtual machine

thresholdProfileName

string

Name of the threshold profile assigned to the virtual machine

originalThresholdProfileID

string

Original threshold profile ID of the threshold profile assigned to the virtual machine

groupIDs

long[]

ID of the consumer assigned to the virtual machine

groupNames

string[]

Name of the consumer assigned to the virtual machine

gradeNames

string[]

Name of the grade of the consumer assigned to the virtual machine

gradeOrders

integer[]

Priority of the grade of the consumer assigned to the virtual machine

usedCredentialID

long

ID for identifying authentication information used for detection

usedCredentials

string

Name of authentication information used for detection

accessPointType

enum

Type of the protocol or collector for authentication information used for detection.

(For details about the specifiable values, see the table ProtocolType in List of enumerators.)

The specifiable values are as follows:

  • WMI
  • SNMP
  • VCENTER

accessPointSnmpVersion

enum

SNMP version of credential

(For details about the specifiable values, see the table SnmpVersion in List of enumerators.)

The specifiable values are as follows:

  • V1_V2C
  • V3

accessPointIpAddress

string

IP address or host name used for connections to monitoring targets or management software

accessPointUser

string

User ID used for connections to monitoring targets or management software

pluginId

string

ID for the plug-in applied to the hypervisor that the virtual machine belongs to.

pagination (Type: Pagination)

Attribute

Type

Description

page

integer

page

pageSize

integer

Size of the pages

numPages

integer

Number of the pages

totalCount

integer

Number of the objects

errorInfo (Type: FailedNodes)

Attribute

Type

Description

nodeName

string

Name of the node

message

string

Message

messageID

string

ID of the message

Status codes

Status code

Reason phrase

Description

200

OK

Success.

401

Unauthorized

No login privilege.

403

Forbidden

No reference privilege.

408

Request Timeout

The processing on the server timed out.

412

Precondition Failed

- The server is not available.

(The following only occur during on-demand acquisition of information.)

- There is a problem in the connection with the vCenter server.

- The vCenter server is not working properly.

500

Internal Server Error

Server processing error.

Example code

[Request Header]
GET /Analytics/v1/objects/VirtualMachines HTTP/1.1
Host: JP1OAServer:22015
User-Agent: curl/7.63.0
Content-Type: application/json
Accept: application/json
Authorization: Basic c3lzdGVtOm1hbmFnZXI=
Accept-Language: ja

[Response Header]
HTTP/1.1 200 OK
Date: Fri, 06 Sep 2019 09:39:34 GMT
Server: Cosminexus HTTP Server
Cache-Control: no-cache
WWW-Authenticate: HSSO dac7fb616da3768ba63e98b322264fa36e708f_ZAlDSFUHGHp9UB8WcRQLdA==_V0810
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block 
X-Content-Type-Options: nosniff
Transfer-Encoding: chunked
Content-Type: application/json

[Response Body]
{
  "data" : [ {
    "instanceID" : 17319,
    "name" : "centOS",
    "ipAddress" : "",
    "status" : "NotMonitored",
    "monitorStatus" : "NotMonitored",
    "description" : "centOS : 90ED2A51-DFA0-4506-AB4F-CB3A4DC8C3D5",
    "componentType" : "VIRTUAL_MACHINE",
    "hypervisorType" : "SERVER_HYPERV",
    "hypervisorID" : 450,
    "hypervisorName" : "hyper-v",
    "hypervisorMonitorStatus" : "MonitorOff",
    "thresholdProfileID" : 19,
    "thresholdProfileName" : "Default Profile for VM",
    "originalThresholdProfileID": 19,
    "groupIDs" : [ 0 ],
    "groupNames" : [ "#Unassigned Resources" ],
    "gradeNames" : [ "" ],
    "gradeOrders" : [ -1 ],
    "usedCredentialID" : 450,
    "usedCredentials" : "hyper-v-auth",
    "accessPointType" : "WMI",
    "accessPointIpAddress" : "10.197.64.10",
    "accessPointUser" : "administrator"
  }
    "instanceID" : 17218,
    "name" : "winsrv2012r2",
    "ipAddress" : "10.197.64.166",
    "status" : "Error",
    "monitorStatus" : "InUse",
    "description" : "winsrv2012r2 : 16A16D27-D419-45BC-AB42-B27CD28A0A20",
    "componentType" : "VIRTUAL_MACHINE",
    "hypervisorType" : "SERVER_HYPERV",
    "hypervisorID" : 450,
    "hypervisorName" : "hyper-v",
    "hypervisorMonitorStatus" : "MonitorOff",
    "hostName" : "WIN-KVR6P62HC7V",
    "thresholdProfileID" : 19,
    "thresholdProfileName" : "Default Profile for VM",
    "originalThresholdProfileID": 19,
    "groupIDs" : [ 0 ],
    "groupNames" : [ "#Unassigned Resources" ],
    "gradeNames" : [ "" ],
    "gradeOrders" : [ -1 ],
    "usedCredentialID" : 450,
    "usedCredentials" : "hyper-v-auth",
    "accessPointType" : "WMI",
    "accessPointIpAddress" : "10.197.64.10",
    "accessPointUser" : "administrator"
  }, {
    "instanceID" : 17021,
    "name" : "dns-server",
    "status" : "Normal",
    "monitorStatus" : "InUse",
    "componentType" : "GENERIC_VIRTUALMACHINE",
    "clusterName" : "AHV-Cluster",
    "hypervisorType" : "GENERIC_HYPERVISOR",
    "hypervisorDetailType" : "AHV",
    "hypervisorID" : 251,
    "hypervisorName" : "NTNX-SGH823XYVL-A",
    "hypervisorMonitorStatus" : "MonitorOff",
    "hostName" : "49b57856-061a-4bd0-8d1e-08be03981299",
    "groupIDs" : [ 0 ],
    "groupNames" : [ "#Unassigned Resources" ],
    "gradeNames" : [ "" ],
    "gradeOrders" : [ -1 ],
    "usedCredentialID" : 300,
    "usedCredentials" : "nutanix-credential",
    "accessPointType" : "SNMP",
    "accessPointSnmpVersion" : "V3",
    "accessPointIpAddress" : "10.197.64.111",
    "accessPointUser" : "admin",
    "pluginId" : "com.hitachi.software.ias.NutanixPlugin"
  }, {
    "instanceID" : 14541,
    "name" : "MONISRV",
    "ipAddress" : "",
    "status" : "Normal",
    "monitorStatus" : "InUse",
    "description" : "MONISRV : 4215f071-e007-48eb-0b25-2c1f7ea1f999",
    "componentType" : "VIRTUAL_MACHINE",
    "collectorID" : 452,
    "collectorName" : "vCenter_JP1OA",
    "autoCollectionType" : "AutoConnect",
    "hypervisorType" : "SERVER_ESX",
    "hypervisorID" : 43,
    "hypervisorName" : "10.197.64.31",
    "hypervisorMonitorStatus" : "Manage",
    "hostName" : "MONISRV",
    "thresholdProfileID" : 19,
    "thresholdProfileName" : "Default Profile for VM",
    "originalThresholdProfileID": 19,
    "groupIDs" : [ 0 ],
    "groupNames" : [ "#Unassigned Resources" ],
    "gradeNames" : [ "" ],
    "gradeOrders" : [ -1 ],
    "accessPointType" : "VCENTER",
    "accessPointIpAddress" : "10.197.64.10",
    "accessPointUser" : "admin"
  } ],
  "count" : 4
}