REST API - list

vcenter host: list

Returns information about at most 2500 visible (subject to permission checks) hosts in vCenter matching the vcenter.host.filter_spec.

Request:

HTTP request

GET https://{server}/rest/vcenter/host

?filter.datacenters.1=obj-103
&filter.datacenters.2=obj-103
&filter.names.1=string
&filter.names.2=string
&filter.folders.1=obj-103
&filter.folders.2=obj-103
&filter.hosts.1=obj-103
&filter.hosts.2=obj-103
&filter.connection_states.1=CONNECTED
&filter.connection_states.2=CONNECTED
&filter.standalone=true
&filter.clusters.1=obj-103
&filter.clusters.2=obj-103

Request Query Parameters:

Name	Type	Description
bold = required
filter	filter_spec	Optional. Specification of matching hosts for which information should be returned.
filter.hosts	string[]	Identifiers of hosts that can match the filter. Optional. If unset or empty, hosts with any identifier match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: `HostSystem`. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: `HostSystem`.
filter.names	string[]	Names that hosts must have to match the filter (see vcenter.host.summary.name). Optional. If unset or empty, hosts with any name match the filter.
filter.folders	string[]	Folders that must contain the hosts for the hosts to match the filter. Optional. If unset or empty, hosts in any folder match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: `Folder`. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: `Folder`.
filter.datacenters	string[]	Datacenters that must contain the hosts for the hosts to match the filter. Optional. If unset or empty, hosts in any datacenter match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: `Datacenter`. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: `Datacenter`.
filter.standalone	boolean	If true, only hosts that are not part of a cluster can match the filter, and if false, only hosts that are are part of a cluster can match the filter. Optional. If unset Hosts can match filter independent of whether they are part of a cluster or not. If this field is true and vcenter.host.filter_spec.clusters os not empty, no hosts will match the filter.
filter.clusters	string[]	Clusters that must contain the hosts for the hosts to match the filter. Optional. If unset or empty, hosts in any cluster and hosts that are not in a cluster match the filter. If this field is not empty and vcenter.host.filter_spec.standalone is true, no hosts will match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: `ClusterComputeResource`. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: `ClusterComputeResource`.
filter.connection_states	string[]	Connection states that a host must be in to match the filter (see vcenter.host.summary.connection_state. Optional. If unset or empty, hosts in any connection state match the filter.

Response:

HTTP Status Code: 200

Representation:

{
    "value" : [
        {
            "host" : "obj-103",
            "name" : "string",
            "connection_state" : "CONNECTED",
            "power_state" : "POWERED_ON"
        },
        {
            "host" : "obj-103",
            "name" : "string",
            "connection_state" : "CONNECTED",
            "power_state" : "POWERED_ON"
        }
    ]
}

Response Type:

Name	Type	Description
bold = required
value	summary[]	Commonly used information about the hosts matching the vcenter.host.filter_spec.
value[].host	string	Identifier of the host. When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: `HostSystem`. When operations return a value of this structure as a result, the field will be an identifier for the resource type: `HostSystem`.
value[].name	string	Name of the host.
value[].connection_state	string	Connection status of the host Defines the connection status of a host. Value is one of: CONNECTED: Host is connected to the vCenter Server DISCONNECTED: Host is disconnected from the vCenter Server NOT_RESPONDING: VirtualCenter is not receiving heartbeats from the server. The state automatically changes to connected once heartbeats are received again.
value[].power_state	string	Power state of the host Defines the power states of a host. Value is one of: POWERED_ON: The host is powered on. A host that is entering standby mode is also in this state. POWERED_OFF: The host was specifically powered off by the user through vCenter server. This state is not a cetain state, because after vCenter server issues the command to power off the host, the host might crash, or kill all the processes but fail to power off. STANDBY: The host was specifically put in standby mode, either explicitly by the user, or automatically by DPM. This state is not a cetain state, because after VirtualCenter issues the command to put the host in standby state, the host might crash, or kill all the processes but fail to enter standby mode. A host that is exiting standby mode is also in this state.Optional. It is only relevant when connection_state has value CONNECTED. This field is optional and it is only relevant when the value of `connection_state` is CONNECTED.

Errors:

HTTP Status Code	Type	Description
400	invalid_argument	if the vcenter.host.filter_spec.connection_states field contains a value that is not supported by the server.
500	unable_to_allocate_resource	if more than 2500 hosts match the vcenter.host.filter_spec.
503	service_unavailable	if the system is unable to communicate with a service to complete the request.
401	unauthenticated	if the user can not be authenticated.
403	unauthorized	if the user doesn't have the required privileges.