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 Elastic Compute Service (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 latest region list.

Action String No DescribeDedicatedHosts

The operation that you want to perform. Set this parameter to DescribeDedicatedHosts.

DedicatedHostIds String No dh-xxxxxxxxxxxxxxxxx

The list of the dedicated host IDs. Specify the dedicated host IDs in a JSON array, for example, "dh-xxxxxxxxx", "dh-yyyyyyyy", ... "dh-zzzzzzzzz". Separate the 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. This is the default value.
  • Under-Assessment: The dedicated host has potential failures and may fail when it is used.
  • Permanent-Failure: The dedicated host has permanent failures and cannot be used.
Tag.N.Key String No usage

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

Tag.N.Value String No test

The Nth tag value 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 and it cannot start with aliyun, acs:, 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 about 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 is added to the resource pool for automatic deployment.
  • off: The dedicated host is 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 the memory. Unit: GiB.

AvailableVcpus Integer 5

The number of available vCPUs.

LocalStorageCategory String i2

The type of the local disks.

TotalLocalStorage Integer 512

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

TotalMemory Float 1024

The total capacity of the memory. Unit: GiB.

TotalVcpus Integer 56

The total number of vCPUs.

ChargeType String Prepaid

The billing method of the dedicated host.

Cores Integer 3

The number of physical cores in a CPU.

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:mmZ format. The time is displayed in UTC+0.

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:mmZ format. The time is displayed in UTC+0.

Instances

The list of the ECS instances that are deployed on the dedicated host.

Instance

The ECS instance that is deployed on the dedicated host.

InstanceId String i-xxxxxxxxxxxxxxxxxxxxxx

The ID of the ECS instance.

InstanceType String ecs.g5

The instance family 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 reasons for locking the resources of the dedicated host.

LockReason String financial

The reason for locking the resources. Possible value: financial (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, and Permanent-Failure.

SupportedInstanceTypeFamilies ecs.g5

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

SupportedInstanceTypeFamily

The ECS instance family 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 tags of the dedicated host.

Tag

The tag of the dedicated host.

ZoneId String cn-hangzhou-g

The zone ID of the instance.

PageNumber Integer 5

The current page number of the dedicated host list.

PageSize Integer 1

The number of entries per page.

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

The ID of the request.

TotalCount Integer 3

The total number of 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 specified disk 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 disk Ids exceeds the limit. The error message returned because the number of dedicated host IDs specified in DedicatedHostIds exceeds the upper limit. DedicatedHostIds supports a maximum of 100 IDs.
400 InvalidParameter.DedicatedHostIds The specified parameter DedicatedHostName is not valid. The error message returned because the specified DedicatedHostIds 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 RegionId 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 LockReason does not exist.

For more information about error codes, see API Error Center.