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

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
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.

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

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

DedicatedHostName String No MyDDHTestName

The name of the dedicated host.

Status String No Available

The service status of the dedicated host. Valid values:

  • Available: The dedicated host is available.
  • UnderAssessment: The dedicated host has a potential failure and may fail when it is used.
  • PermanentFailure: The dedicated host has a permanent failure and cannot be used.

Default value: Available

DedicatedHostType String No ddh.g5

The type of the dedicated host.

PageNumber Integer No 1

The number of the page to return. Pages start from page 1.

Default value: 1

PageSize Integer No 10

The number of entries to return on each page. Valid values: 1 to 100.

Default value: 10

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 contain http:// or https://. It cannot start with acs: or aliyun.

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 contain http:// or https://. It cannot start with acs: or aliyun.

Response parameters

Parameter Type Example Description
DedicatedHosts Array

The list of the dedicated hosts.

DedicatedHost
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 valus:

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

    If the dedicated host is attached with cloud 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 is 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.

AutoReleaseTime String 2017-01-01T12:00Z

The time scheduled for a created ECS instance to be automatically released. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC.

Capacity Struct

The collection of 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.

AvailableVgpus Integer 2

The number of available vGPUs.

LocalStorageCategory String i2

The category 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.

TotalVgpus Integer 10

The total number of vGPUs.

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: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.

DedicatedHostId String dh-bp165p6xk2tlw61e****

The ID of the dedicated host.

DedicatedHostName String MyDDHTestName

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: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.

GPUSpec String gpu

The GPU model.

Instances Array

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

Instance
InstanceId String i-bp14ot0ykf8w13a1****

The ID of the ECS instance that is deployed on the dedicated host.

InstanceType String ecs.g5.large

The instance type of the ECS instance that is deployed on the dedicated host.

MachineId String 12aaa123456ff19dec12345d3026e****

The machine code of the dedicated host.

NetworkAttributes Struct

The network attributes of the dedicated host.

SlbUdpTimeout Integer 60

The timeout period of the UDP session that is established to SLB.

UdpTimeout Integer 60

The timeout period of the UDP session.

OperationLocks Array

The reasons for locking the resources of the dedicated host.

OperationLock
LockReason String financial

The reason for locking the resource of the dedicated host. Example of valid values: financial. It indicates that the resource was locked due to overdue payments.

PhysicalGpus Integer 10

The number of physical GPUs.

RegionId String cn-hangzhou

The region ID of the dedicated host.

ResourceGroupId String rg-aek3b6jzp66****

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

SaleCycle String Month

The unit of the subscription billing method. Valid values:

  • Month
  • Year
Sockets Integer 5

The number of physical CPUs.

Status String Available

The service status of the dedicated host. Valid values:

  • Available
  • UnderAssessment
  • PermanentFailure
SupportedCustomInstanceTypeFamilies List ecs.ddh6s.custom

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

SupportedInstanceTypeFamilies List ecs.g5

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

SupportedInstanceTypesList List ecs.g5.large

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

Tags Array

The tags of the dedicated host.

Tag
TagKey String TestKey

The tag key of the dedicated host.

TagValue String TestValue

The tag value of the dedicated host.

ZoneId String cn-hangzhou-g

The zone ID of the dedicated host.

PageNumber Integer 5

The page number of the returned page.

PageSize Integer 1

The number of entries returned per page.

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

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>
      <TotalCount>1</TotalCount>
      <DedicatedHosts>
            <DedicatedHost>
                  <PhysicalGpus>0</PhysicalGpus>
                  <MachineId>12aaa123456ff19dec12345d3026e****</MachineId>
                  <DedicatedHostId>dh-bp165p6xk2tlw61e****</DedicatedHostId>
                  <Description></Description>
                  <ResourceGroupId></ResourceGroupId>
                  <SupportedCustomInstanceTypeFamilies>
            </SupportedCustomInstanceTypeFamilies>
                  <NetworkAttributes></NetworkAttributes>
                  <GPUSpec></GPUSpec>
                  <DedicatedHostName>MyDDHTestName</DedicatedHostName>
                  <Capacity>
                        <AvailableVgpus>0</AvailableVgpus>
                        <LocalStorageCategory></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></SaleCycle>
                  <Status>Available</Status>
                  <ZoneId>cn-hangzhou-g</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.13xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.16xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.4xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.8xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.6xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.2xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.large</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.3xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6.26xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.4xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.8xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.6xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.2xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.large</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.6xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.16xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.26xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.13xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.2xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.16xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.8xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.large</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.13xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.4xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.3xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.c6.3xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6.26xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.3xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.8xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.2xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.large</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.6xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.ic6.4xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.r6-dbeni.8xlarge</SupportedInstanceTypesList>
                        <SupportedInstanceTypesList>ecs.g6-nfveni.large</SupportedInstanceTypesList>
                  </SupportedInstanceTypesList>
                  <AutoReleaseTime></AutoReleaseTime>
            </DedicatedHost>
      </DedicatedHosts>
      <RequestId>7654525A-9964-4ABB-8BCD-98F8835E809A</RequestId>
      <PageSize>10</PageSize>
      <PageNumber>1</PageNumber>
</DescribeDedicatedHostsResponse>

JSON format

{
    "TotalCount": 1,
    "DedicatedHosts": {
        "DedicatedHost": [
            {
                "PhysicalGpus": 0,
                "MachineId": "12aaa123456ff19dec12345d3026e****",
                "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-g",
                "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.13xlarge",
                        "ecs.g6.16xlarge",
                        "ecs.g6.4xlarge",
                        "ecs.g6.8xlarge",
                        "ecs.g6.xlarge",
                        "ecs.g6.6xlarge",
                        "ecs.g6.2xlarge",
                        "ecs.g6.large",
                        "ecs.g6.3xlarge",
                        "ecs.g6.26xlarge",
                        "ecs.c6.4xlarge",
                        "ecs.c6.8xlarge",
                        "ecs.c6.6xlarge",
                        "ecs.c6.2xlarge",
                        "ecs.r6.large",
                        "ecs.c6.xlarge",
                        "ecs.r6.6xlarge",
                        "ecs.r6.16xlarge",
                        "ecs.r6.xlarge",
                        "ecs.c6.26xlarge",
                        "ecs.r6.13xlarge",
                        "ecs.r6.2xlarge",
                        "ecs.c6.16xlarge",
                        "ecs.r6.8xlarge",
                        "ecs.c6.large",
                        "ecs.c6.13xlarge",
                        "ecs.r6.4xlarge",
                        "ecs.r6.3xlarge",
                        "ecs.c6.3xlarge",
                        "ecs.r6.26xlarge",
                        "ecs.ic6.3xlarge",
                        "ecs.ic6.8xlarge",
                        "ecs.ic6.2xlarge",
                        "ecs.ic6.xlarge",
                        "ecs.ic6.large",
                        "ecs.ic6.6xlarge",
                        "ecs.ic6.4xlarge",
                        "ecs.r6-dbeni.8xlarge",
                        "ecs.g6-nfveni.large"
                    ]
                },
                "AutoReleaseTime": ""
            }
        ]
    },
    "RequestId": "7654525A-9964-4ABB-8BCD-98F8835E809A",
    "PageSize": 10,
    "PageNumber": 1
}

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 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 required 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 by the DedicatedHostIds parameter 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 parameter does not exist.

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