Queries the details of one or more dedicated hosts, including the physical performance specifications, machine codes, and service states of the dedicated hosts, and Elastic Compute Service (ECS) instances that are created on the dedicated hosts.

Description

You can use one of the following methods to query the details of one or more dedicated hosts:

  • Specify the DedicatedHostIds parameter to query the details of specified dedicated hosts.
  • Specify the DedicatedHostClusterId parameter to query the details of the dedicated hosts in a dedicated host cluster.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeDedicatedHosts

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

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.

ZoneId String No cn-hangzhou-g

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

DedicatedHostIds String No ["dh-bp165p6xk2tlw61e****", "dh-bp1f9vxmno7emy96****"]

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

DedicatedHostName String No MyDDHTestName

The name of the dedicated host.

Status String No Available

The service state of the dedicated host. Valid values:

  • Available: The dedicated host is running normally.
  • UnderAssessment: The dedicated host is at risk, which may cause issues to ECS instances on the dedicated host.
  • PermanentFailure: The dedicated host has permanent failures and is unusable.
  • TempUnavailable: The dedicated host is temporarily unusable.
  • Redeploying: The dedicated host is being restored.

Default value: Available.

DedicatedHostType String No ddh.g5

The type of the dedicated host. You can call the DescribeDedicatedHostTypes operation to obtain the most recent list of dedicated host types.

LockReason String No financial

The reason why the dedicated host is locked. Valid values:

  • financial: The dedicated host is locked due to overdue payments.
  • security: The dedicated host is locked due to security reasons.
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.

ResourceGroupId String No rg-aek3b6jzp66****

The ID of the resource group to which the dedicated host belongs. When this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group can be displayed in the response.

Note Resources in the default resource group are displayed in the response regardless of how this parameter is set.
Tag.N.Key String No TestKey

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

Tag.N.Value String No TestValue

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

DedicatedHostClusterId String No dc-bp12wlf6am0vz9v2****

The ID of the dedicated host cluster.

Response parameters

Parameter Type Example Description
PageSize Integer 1

The number of entries returned per page.

RequestId String 7654525A-9964-4ABB-8BCD-98F8835E809A

The ID of the request.

PageNumber Integer 5

The page number of the returned page.

TotalCount Integer 3

The total number of dedicated hosts.

DedicatedHosts Array of DedicatedHost

Details about the dedicated hosts.

DedicatedHost
CreationTime String 2018-01-01T12: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.

SchedulerOptions.ManagedPrivateSpaceId String mps-iq81z6pkbqjx61php46e

The ID of the managed private space to which the dedicated host belongs.

Status String Available

The service state of the dedicated host. Valid values:

  • Available: The dedicated host is running normally.
  • UnderAssessment: The dedicated host is at risk, which may cause issues to ECS instances on the dedicated host.
  • PermanentFailure: The dedicated host has permanent failures and is unusable.
Cores Integer 3

The number of cores in a single CPU.

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 the "Automatic deployment" section in Functions and features.

GPUSpec String gpu

The GPU model.

AutoReleaseTime String 2017-01-01T12:00Z

The automatic release time of the dedicated host. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC.

ChargeType String Prepaid

The billing method of the dedicated host.

CpuOverCommitRatio Float 1

The CPU overcommit ratio.

ActionOnMaintenance String Migrate

The policy used to migrate the instances deployed on the dedicated host when the dedicated host fails. Valid values:

  • Migrate: The instances are migrated to another physical server. Instances that are not in the Stopped state when the dedicated host fails are restarted after migration.
  • Stop: The instances are stopped. If the dedicated host cannot be repaired, the instances are migrated to another physical server and restarted.

If the dedicated host has cloud disks attached, the default value is Migrate. If the dedicated host has local disks attached, the default value is Stop.

SaleCycle String Month

The unit of the subscription period. Valid values:

  • Month
  • Year
PhysicalGpus Integer 10

The number of physical GPUs.

RegionId String cn-hangzhou

The region ID of the dedicated host.

DedicatedHostName String MyDDHTestName

The name of the dedicated host.

Description String this-is-my-DDH

The description of the dedicated host.

DedicatedHostClusterId String dc-bp12wlf6am0vz9v2****

The ID of the dedicated host cluster to which the dedicated host belongs.

ExpiredTime String 2019-01-01T12: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.

DedicatedHostType String ddh.g5

The type of the dedicated host.

ResourceGroupId String rg-aek3b6jzp66****

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

ZoneId String cn-hangzhou-g

The zone ID of the dedicated host.

DedicatedHostId String dh-bp165p6xk2tlw61e****

The ID of the dedicated host.

Sockets Integer 5

The number of physical CPUs.

MachineId String 12aaa123456ff19dec12345d3026e****

The machine code of the dedicated host.

Instances Array of Instance

Details about the ECS instances that were created on the dedicated host.

Instance
InstanceType String ecs.g5.large

The instance type of the ECS instance created on the dedicated host.

InstanceId String i-bp14ot0ykf8w13a1****

The ID of the ECS instance created on the dedicated host.

OperationLocks Array of OperationLock

The reasons why the resources of the dedicated host were locked.

OperationLock
LockReason String financial

The reason why the dedicated host was locked. Valid values:

  • financial: The dedicated host was locked due to overdue payments.
  • security: The dedicated host was locked due to security reasons.
Tags Array of Tag

The tags of the dedicated host.

Tag
TagValue String TestValue

The tag value of the dedicated host.

TagKey String TestKey

The tag key of the dedicated host.

SupportedInstanceTypeFamilies Array of String ecs.g5

The ECS instance families supported by the dedicated host.

SupportedCustomInstanceTypeFamilies Array of String ecs.ddh6s.custom

The custom ECS instance families supported by the dedicated host.

SupportedInstanceTypesList Array of String ecs.g5.large

The ECS instance types supported by the dedicated host.

Capacity Object

The performance specifications of the dedicated host.

AvailableMemory Float 25

The amount of available memory space. Unit: GiB.

LocalStorageCategory String i2

The category of the local disks.

TotalMemory Float 1024

The total capacity of the memory. Unit: GiB.

TotalLocalStorage Integer 512

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

TotalVcpus Integer 56

The total number of vCPUs.

TotalVgpus Integer 10

The total number of vGPUs.

AvailableLocalStorage Integer 65

The amount of available space on the local disks. Unit: GiB.

AvailableVcpus Integer 5

The number of available vCPUs.

AvailableVgpus Integer 2

The number of available vGPUs.

NetworkAttributes Object

The network attributes of the dedicated host.

UdpTimeout Integer 60

The timeout period of the UDP session that was established between a user and an Alibaba Cloud service on the dedicated host. Unit: seconds. Valid value: 60.

SlbUdpTimeout Integer 60

The timeout period of the UDP session that was established between Server Load Balancer (SLB) and the dedicated host. Unit: seconds. Valid value: 60.

HostDetailInfo Object

This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.

SerialNumber String null

This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.

Examples

Sample requests

http(s)://ecs.aliyuncs.com/?Action=DescribeDedicatedHosts
&RegionId=cn-hangzhou
&ZoneId=cn-hangzhou-g
&DedicatedHostIds=["dh-bp165p6xk2tlw61e****", "dh-bp1f9vxmno7emy96****"]
&DedicatedHostName=MyDDHTestName
&Status=Available
&DedicatedHostType=ddh.g5
&LockReason=financial
&PageNumber=1
&PageSize=10
&ResourceGroupId=rg-aek3b6jzp66****
&Tag=[{"Key":"TestKey","Value":"TestValue"}]
&DedicatedHostClusterId=dc-bp12wlf6am0vz9v2****
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeDedicatedHostsResponse>
    <TotalCount>1</TotalCount>
    <DedicatedHosts>
        <DedicatedHost>
            <PhysicalGpus>0</PhysicalGpus>
            <MachineId>73aaa79494ff19dec79446d3026e****</MachineId>
            <DedicatedHostId>dh-bp165p6xk2tlw61e****</DedicatedHostId>
            <Description/>
            <ResourceGroupId/>
            <SupportedCustomInstanceTypeFamilies>
            </SupportedCustomInstanceTypeFamilies>
            <NetworkAttributes/>
            <GPUSpec/>
            <DedicatedHostName>MyDDHTestName</DedicatedHostName>
            <Capacity>
                <AvailableVgpus>0</AvailableVgpus>
                <LocalStorageCategory/>
                <TotalVgpus>0</TotalVgpus>
                <TotalMemory>768</TotalMemory>
                <AvailableMemory>768</AvailableMemory>
                <AvailableVcpus>104</AvailableVcpus>
                <TotalVcpus>104</TotalVcpus>
                <AvailableLocalStorage>0</AvailableLocalStorage>
                <TotalLocalStorage>0</TotalLocalStorage>
            </Capacity>
            <ExpiredTime>2999-09-08T16:00Z</ExpiredTime>
            <SaleCycle/>
            <Status>Available</Status>
            <ZoneId>cn-hangzhou-h</ZoneId>
            <AutoPlacement>on</AutoPlacement>
            <DedicatedHostType>ddh.r6</DedicatedHostType>
            <OperationLocks>
            </OperationLocks>
            <Cores>52</Cores>
            <Instances>
            </Instances>
            <Sockets>2</Sockets>
            <ChargeType>PostPaid</ChargeType>
            <SupportedInstanceTypeFamilies>
                <SupportedInstanceTypeFamily>ecs.c6</SupportedInstanceTypeFamily>
                <SupportedInstanceTypeFamily>ecs.g6</SupportedInstanceTypeFamily>
                <SupportedInstanceTypeFamily>ecs.ic6</SupportedInstanceTypeFamily>
                <SupportedInstanceTypeFamily>ecs.r6</SupportedInstanceTypeFamily>
            </SupportedInstanceTypeFamilies>
            <ActionOnMaintenance>Migrate</ActionOnMaintenance>
            <CreationTime>2020-04-15T07:12Z</CreationTime>
            <RegionId>cn-hangzhou</RegionId>
            <SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.26xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.3xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.2xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.13xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.6xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.4xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.16xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.13xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.26xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.26xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.3xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.13xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.16xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.4xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.16xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.6xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6.large</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.2xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.2xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.3xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.6xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.4xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6.large</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.large</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.4xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.3xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.6xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.2xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.ic6.large</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6-dbeni.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6nv.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.c6vn.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.r6vn.8xlarge</SupportedInstanceTypesList>
                <SupportedInstanceTypesList>ecs.g6-nfveni.large</SupportedInstanceTypesList>
            </SupportedInstanceTypesList>
            <DedicatedHostClusterId/>
            <AutoReleaseTime/>
        </DedicatedHost>
    </DedicatedHosts>
    <RequestId>9E9354D4-C89E-4A82-A70E-3EEAD6007885</RequestId>
    <PageSize>10</PageSize>
    <PageNumber>1</PageNumber>
</DescribeDedicatedHostsResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalCount" : 1,
  "DedicatedHosts" : {
    "DedicatedHost" : [ {
      "PhysicalGpus" : 0,
      "MachineId" : "73aaa79494ff19dec79446d3026e****",
      "DedicatedHostId" : "dh-bp165p6xk2tlw61e****",
      "Description" : "",
      "ResourceGroupId" : "",
      "SupportedCustomInstanceTypeFamilies" : {
        "SupportedCustomInstanceTypeFamily" : [ ]
      },
      "NetworkAttributes" : { },
      "GPUSpec" : "",
      "DedicatedHostName" : "MyDDHTestName",
      "Capacity" : {
        "AvailableVgpus" : 0,
        "LocalStorageCategory" : "",
        "TotalVgpus" : 0,
        "TotalMemory" : 768,
        "AvailableMemory" : 768,
        "AvailableVcpus" : 104,
        "TotalVcpus" : 104,
        "AvailableLocalStorage" : 0,
        "TotalLocalStorage" : 0
      },
      "ExpiredTime" : "2999-09-08T16:00Z",
      "SaleCycle" : "",
      "Status" : "Available",
      "ZoneId" : "cn-hangzhou-h",
      "AutoPlacement" : "on",
      "DedicatedHostType" : "ddh.r6",
      "OperationLocks" : {
        "OperationLock" : [ ]
      },
      "Cores" : 52,
      "Instances" : {
        "Instance" : [ ]
      },
      "Sockets" : 2,
      "ChargeType" : "PostPaid",
      "SupportedInstanceTypeFamilies" : {
        "SupportedInstanceTypeFamily" : [ "ecs.c6", "ecs.g6", "ecs.ic6", "ecs.r6" ]
      },
      "ActionOnMaintenance" : "Migrate",
      "CreationTime" : "2020-04-15T07:12Z",
      "RegionId" : "cn-hangzhou",
      "SupportedInstanceTypesList" : {
        "SupportedInstanceTypesList" : [ "ecs.g6.26xlarge", "ecs.g6.3xlarge", "ecs.g6.8xlarge", "ecs.g6.2xlarge", "ecs.g6.13xlarge", "ecs.g6.6xlarge", "ecs.c6.8xlarge", "ecs.g6.4xlarge", "ecs.g6.xlarge", "ecs.g6.16xlarge", "ecs.c6.13xlarge", "ecs.c6.26xlarge", "ecs.r6.xlarge", "ecs.r6.26xlarge", "ecs.r6.3xlarge", "ecs.r6.13xlarge", "ecs.r6.16xlarge", "ecs.r6.4xlarge", "ecs.c6.16xlarge", "ecs.r6.6xlarge", "ecs.g6.large", "ecs.c6.2xlarge", "ecs.r6.2xlarge", "ecs.c6.xlarge", "ecs.c6.3xlarge", "ecs.c6.6xlarge", "ecs.c6.4xlarge", "ecs.c6.large", "ecs.r6.large", "ecs.r6.8xlarge", "ecs.ic6.4xlarge", "ecs.ic6.8xlarge", "ecs.ic6.xlarge", "ecs.ic6.3xlarge", "ecs.ic6.6xlarge", "ecs.ic6.2xlarge", "ecs.ic6.large", "ecs.r6-dbeni.8xlarge", "ecs.g6nv.8xlarge", "ecs.c6vn.8xlarge", "ecs.r6vn.8xlarge", "ecs.g6-nfveni.large" ]
      },
      "DedicatedHostClusterId" : "",
      "AutoReleaseTime" : ""
    } ]
  },
  "RequestId" : "9E9354D4-C89E-4A82-A70E-3EEAD6007885",
  "PageSize" : 10,
  "PageNumber" : 1
}

Error codes

HttpCode Error code Error message Description
400 InvalidStatus.ValueNotSupported The pecified dedicated host status is not supported. The error message returned because the 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.
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.
403 InvalidDedicatedHostIds.Malformed The amount of specified dedicatedHostIds exceeds the limit. The error message returned because more than 100 dedicated host IDs are specified in the DedicatedHostIds value.
404 InvalidLockReason.NotFound The specified LockReason is not found The error message returned because the specified LockReason parameter does not exist.

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