You can call this operation to query the details of one or more dedicated hosts, including the physical performance metrics, machine code, service status, and a list of all ECS instances that are created.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
RegionId String Yes cn-hangzhou

The region ID of the dedicated host. You can call the DescribeRegions operation to query the most recent region list.

Action String No DescribeDedicatedHosts

The operation that you want to perform. Set the value to DescribeDedicatedHosts.

DedicatedHostIds String No ["dh- xxxxxxxxx", "dh- yyyyyyyyy", … "dh- zzzzzzzzz"]

The list of the dedicated host IDs. You can include up to 100 IDs in a single request. Separate multiple IDs with commas (,).

DedicatedHostName String No myDDH

The name of the dedicated host.

DedicatedHostType String No ddh.g5

The type of the dedicated host.

PageNumber Integer No 1

The number of the page to return.

Default value: 1.

PageSize Integer No 10

The number of entries to return on each page. Maximum value: 100.

Default value: 10.

Status String No Available

The service status of the dedicated host. Valid values:

  • Available: The dedicated host is available for use. Default value: Available.
  • Under-Assessment: The dedicated host has a potential failure and may fail when it is used.
  • Permanent-Failure: The dedicated host has a permanent failure and cannot be used.
Tag.N.Key String No usage

The key of tag N of the dedicated host. Valid values of N: 1 to 20. It cannot be an empty string. It can be up to 128 characters in length, cannot start with acs: or aliyun, and cannot contain http:// or https://.

Tag.N.Value String No test

The value of tag N of the dedicated host. Valid values of N: 1 to 20. It can be an empty string. It can be up to 128 characters in length, cannot start with acs: or aliyun, and cannot contain http:// or https://.

ZoneId String No cn-hangzhou-g

The ID of the zone.

Response parameters

Parameter Type Example Description
DedicatedHosts

The list of details of the dedicated hosts.

DedicatedHost

The details of the dedicated host.

ActionOnMaintenance String Migrate

The policy used to migrate the instances from the dedicated host when the dedicated host fails or needs to be repaired online. Valid values:

  • Migrate: Instances are migrated to another physical server and restarted.

    If the dedicated host is attached with disks that are not local disks, the default value is Migrate.

  • Stop: Instances on the dedicated host are stopped. If the dedicated host cannot be repaired, the instances are migrated to another physical server and restarted.

    If the dedicated host is attached with local disks, the default value is Stop.

AutoPlacement String on

Indicates whether the dedicated host was added to the resource pool for automatic deployment. Valid values:

  • on: The dedicated host was added to the resource pool for automatic deployment.
  • off: The dedicated host was not added to the resource pool for automatic deployment.

For more information about automatic deployment, see Automatic deployment.

Capacity

The performance specifications of the dedicated host.

AvailableLocalStorage Integer 65

The available space of the local disk. Unit: GiB.

AvailableMemory Float 25

The available space of memory. Unit: GiB.

AvailableVcpus Integer 5

The number of available vCPUs.

LocalStorageCategory String i2

The type of the local disk.

TotalLocalStorage Integer 512

The total capacity of the local disk. Unit: GiB.

TotalMemory Float 1024

The total capacity of memory. Unit: GiB.

TotalVcpus Integer 56

The total number of vCPUs.

ChargeType String Prepaid

The billing method for the dedicated host.

Cores Integer 3

The number of physical cores of the dedicated host.

CreationTime String 2018-01-01T12:00:00Z

The time when the dedicated host was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

DedicatedHostId String dh-xxxxxxxxxxxxxxxxxxxxxx

The ID of the dedicated host.

DedicatedHostName String myDDH

The name of the dedicated host.

DedicatedHostType String ddh.g5

The type of the dedicated host.

Description String this-is-my-DDH

The description of the dedicated host.

ExpiredTime String 2019-01-01T12:00:00Z

The expiration time of the subscription dedicated host. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Instances

The list of the ECS instances that were created on the dedicated host.

Instance

The ECS instance that was created on the dedicated host.

InstanceId String i-xxxxxxxxxxxxxxxxxxxxxx

The ID of the ECS instance.

InstanceType String ecs.g5

The instance type of the ECS instance.

MachineId String d7a1xxxxxxxxxxxxxx1bbdb

The machine code of the dedicated host.

NetworkAttributes

The network attributes of the dedicated host.

OperationLocks

The reasons for locking the resources of the dedicated host.

OperationLock

The reason for locking the resources of the dedicated host.

LockReason String financial

The reason for locking the resources. Possible value: financial (the resources are locked because of overdue payments).

RegionId String cn-hangzhou

The region ID of the dedicated host.

ResourceGroupId String rg-xxxxxxxxxxxxxxxxxxxxx

The ID of the resource group to which the dedicated host belongs.

Sockets Integer 5

The number of physical CPUs.

Status String Available

The service status of the dedicated host. Valid values: Available | Under-Assessment | Permanent-Failure.

SupportedInstanceTypeFamilies ecs.g5

The list of ECS instance families supported by the dedicated host.

SupportedInstanceTypeFamily

The ECS instance family that is supported by the dedicated host.

SupportedInstanceTypesList ecs.g5

The list of ECS instance types supported by the dedicated host.

SupportedInstanceTypesList

The ECS instance type supported by the dedicated host.

Tags

The list of tags of the dedicated hosts.

Tag

The tag of the dedicated host.

TagKey String usage

The tag key of the dedicated host.

TagValue String forTest

The tag value of the dedicated host.

ZoneId String cn-hangzhou-g

The ID of the zone.

PageNumber Integer 5

The current page number of the dedicated host list.

PageSize Integer 1

The number of entries returned per page.

RequestId String C9E9EA51-6B74-409E-BA40-107126A200D4

The ID of the request.

TotalCount Integer 3

The total number of the dedicated hosts.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeDedicatedHosts
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

<DescribeDedicatedHostsResponse>
	  <PageNumber>1</PageNumber>
	  <DedicatedHosts>
		    <DedicatedHost>
			      <AutoPlacement>on</AutoPlacement>
			      <Instances></Instances>
			      <ZoneId>cn-hangzhou-g</ZoneId>
			      <Sockets>2</Sockets>
			      <Cores>48</Cores>
			      <DedicatedHostType>ddh.v5</DedicatedHostType>
			      <PhysicalGpus>0</PhysicalGpus>
			      <DedicatedHostName>ddh-1</DedicatedHostName>
			      <SaleCycle></SaleCycle>
			      <AutoReleaseTime></AutoReleaseTime>
			      <SupportedInstanceTypeFamilies>
				        <SupportedInstanceTypeFamily>ecs.v5</SupportedInstanceTypeFamily>
			      </SupportedInstanceTypeFamilies>
			      <NetworkAttributes></NetworkAttributes>
			      <DedicatedHostId>dh-bp1xxxxxxxxxxxxxg</DedicatedHostId>
			      <ChargeType>PostPaid</ChargeType>
			      <Description></Description>
			      <ResourceGroupId></ResourceGroupId>
			      <CreationTime>2019-08-06T07:40Z</CreationTime>
			      <Status>Available</Status>
			      <RegionId>cn-hangzhou</RegionId>
			      <GPUSpec></GPUSpec>
			      <ActionOnMaintenance>Migrate</ActionOnMaintenance>
			      <Capacity>
				        <AvailableVcpus>336</AvailableVcpus>
				        <TotalMemory>672</TotalMemory>
				        <AvailableVgpus>0</AvailableVgpus>
				        <TotalVgpus>0</TotalVgpus>
				        <TotalVcpus>336</TotalVcpus>
				        <AvailableLocalStorage>0</AvailableLocalStorage>
				        <TotalLocalStorage>0</TotalLocalStorage>
				        <LocalStorageCategory></LocalStorageCategory>
				        <AvailableMemory>672</AvailableMemory>
			      </Capacity>
			      <OperationLocks></OperationLocks>
			      <MachineId>3e4xxxxxxxxxxxxxxxx16</MachineId>
			      <SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m1.large</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m1.xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m1.2xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m1.3xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m1.4xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m2.xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m2.large</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m1.8xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m2.2xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m2.3xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m2.4xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m2.8xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m4.4xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m4.3xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m4.2xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m4.xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m4.large</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m4.8xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m8.large</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m8.xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m8.2xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m8.3xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m8.4xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.v5-c1m8.8xlarge</SupportedInstanceTypesList>
			      </SupportedInstanceTypesList>
			      <ExpiredTime>2999-09-08T16:00Z</ExpiredTime>
		    </DedicatedHost>
		    <DedicatedHost>
			      <AutoPlacement>on</AutoPlacement>
			      <Instances></Instances>
			      <ZoneId>cn-hangzhou-f</ZoneId>
			      <Sockets>2</Sockets>
			      <Cores>32</Cores>
			      <DedicatedHostType>ddh.sn1ne</DedicatedHostType>
			      <PhysicalGpus>0</PhysicalGpus>
			      <DedicatedHostName>ddh-2</DedicatedHostName>
			      <SaleCycle></SaleCycle>
			      <AutoReleaseTime></AutoReleaseTime>
			      <SupportedInstanceTypeFamilies>
				        <SupportedInstanceTypeFamily>ecs.sn1ne</SupportedInstanceTypeFamily>
			      </SupportedInstanceTypeFamilies>
			      <NetworkAttributes></NetworkAttributes>
			      <DedicatedHostId>dh-bpxxxxxxxxxxxxx</DedicatedHostId>
			      <ChargeType>PrePaid</ChargeType>
			      <Description></Description>
			      <ResourceGroupId></ResourceGroupId>
			      <CreationTime>2019-07-03T07:07Z</CreationTime>
			      <Status>Available</Status>
			      <RegionId>cn-hangzhou</RegionId>
			      <GPUSpec></GPUSpec>
			      <ActionOnMaintenance>Migrate</ActionOnMaintenance>
			      <Capacity>
				        <AvailableVcpus>56</AvailableVcpus>
				        <TotalMemory>112</TotalMemory>
				        <AvailableVgpus>0</AvailableVgpus>
				        <TotalVgpus>0</TotalVgpus>
				        <TotalVcpus>56</TotalVcpus>
				        <AvailableLocalStorage>0</AvailableLocalStorage>
				        <TotalLocalStorage>0</TotalLocalStorage>
				        <LocalStorageCategory></LocalStorageCategory>
				        <AvailableMemory>112</AvailableMemory>
			      </Capacity>
			      <OperationLocks></OperationLocks>
			      <MachineId>78cxxxxxxxxxxxxxxx8006d</MachineId>
			      <SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.large</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.2xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.4xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.8xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.3xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.6xlarge</SupportedInstanceTypesList>
				        <SupportedInstanceTypesList>ecs.sn1ne.22xlarge</SupportedInstanceTypesList>
			      </SupportedInstanceTypesList>
			      <ExpiredTime>2999-09-08T16:00Z</ExpiredTime>
		    </DedicatedHost>
	  </DedicatedHosts>
	  <TotalCount>2</TotalCount>
	  <PageSize>10</PageSize>
	  <RequestId>FCED4B7A-53D5-4C04-ABE3-26D4F3890D57</RequestId>
</DescribeDedicatedHostsResponse>

JSON format

{
	"PageNumber":1,
	"DedicatedHosts":{
		"DedicatedHost":[
			{
				"DedicatedHostId":"dh-dedicatedhost1",
				"ChargeType":"PostPaid",
				"Description":"",
				"ResourceGroupId":"",
				"SupportInstanceTypeFamilies":{
					"SupportInstanceTypeFamily":[
						"ecs.se1ne"
					]
				},
				"Instances":{
					"Instance":[]
				},
				"ZoneId":"cn-beijing-c",
				"CreationTime":"2018-08-13T07:59Z",
				"Sockets":2,
				"Status":"Available",
				"Cores":32,
				"DedicatedHostType":"ddh.se1ne",
				"RegionId":"cn-beijing",
				"DedicatedHostName":"ddh-1",
				"SaleCycle":"",
				"Capacity":{
					"AvailableVcpus":56,
					"TotalMemory":448,
					"TotalVcpus":56,
					"TotalLocalStorage":0,
					"AvailableLocalStorage":0,
					"AvailableMemory":448,
					"LocalStorageCategory":""
				},
				"AutoReleaseTime":"",
				"MachineId":"xxxx",
				"OperationLocks":{
					"OperationLock":[]
				},
				"ExpiredTime":"2999-09-08T16:00Z"
			},
			{
				"DedicatedHostId":"dh-dedicatedhost2",
				"ChargeType":"PostPaid",
				"Description":"",
				"ResourceGroupId":"",
				"SupportInstanceTypeFamilies":{
					"SupportInstanceTypeFamily":[
						"ecs.se1ne"
					]
				},
				"Instances":{
					"Instance":[]
				},
				"ZoneId":"cn-beijing-c",
				"CreationTime":"2018-08-13T07:59Z",
				"Sockets":2,
				"Status":"Available",
				"Cores":32,
				"DedicatedHostType":"ddh.se1ne",
				"RegionId":"cn-beijing",
				"DedicatedHostName":"ddh-2",
				"SaleCycle":"",
				"Capacity":{
					"AvailableVcpus":56,
					"TotalMemory":448,
					"TotalVcpus":56,
					"TotalLocalStorage":0,
					"AvailableLocalStorage":0,
					"AvailableMemory":448,
					"LocalStorageCategory":""
				},
				"AutoReleaseTime":"",
				"MachineId":"f9b97axxxxxxxxxxxxxxxxx",
				"OperationLocks":{
					"OperationLock":[]
				},
				"ExpiredTime":"2999-09-08T16:00Z"
			}
		]
	},
	"TotalCount":2,
	"PageSize":10,
	"RequestId":"9D5CC4F5-921A-4E02-B971-0DAF703407BE"
}

Error codes

HTTP status code Error code Error message Description
400 InvalidStatus.ValueNotSupported The pecified dedicated host status is not supported. The error message returned because this operation is not supported while the dedicated host is in the current state.
400 MissingParamter.RegionId The regionId should not be null. The error message returned because the RegionId parameter is not specified.
403 InvalidDedicatedHostIds.Malformed The amount of specified dedicatedHostIds exceeds the limit. The error message returned because the number of dedicated host IDs specified in DedicatedHostIds exceeds the upper limit of 100.
400 InvalidParameter.DedicatedHostIds The specified parameter dedicatedHostIds is not valid. The error message returned because the specified DedicatedHostIds parameter is invalid.
400 InvalidRegion.NotFound The specified parameter RegionId is not valid. The error message returned because the specified RegionId parameter is invalid.
400 InvalidZone.NotFound The specified parameter ZoneId is not valid. The error message returned because the specified ZoneId parameter is invalid.
404 InvalidLockReason.NotFound The specified LockReason is not found The error message returned because the specified LockReason does not exist.

For a list of error codes, visit the API Error Center.