All Products
Search
Document Center

Elastic Compute Service:DescribeDedicatedHosts

Last Updated:Feb 04, 2024

Queries the information about 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.

Operation description

You can use one of the following methods to query the information about dedicated hosts:

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

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

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

cn-hangzhou
ZoneIdstringNo

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

cn-hangzhou-g
DedicatedHostIdsstringNo

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

["dh-bp165p6xk2tlw61e****", "dh-bp1f9vxmno7emy96****"]
DedicatedHostNamestringNo

The name of the dedicated host.

MyDDHTestName
StatusstringNo

The service state of the dedicated host. Valid values:

  • Available: The dedicated host is running normally.
  • UnderAssessment: The dedicated host is available but has potential risks that may cause the ECS instances on the dedicated host to fail.
  • PermanentFailure: The dedicated host encounters permanent failures and is unavailable.
  • TempUnavailable: The dedicated host is temporarily unavailable.
  • Redeploying: The dedicated host is being restored.

Default value: Available.

Available
DedicatedHostTypestringNo

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

ddh.g5
LockReasonstringNo

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

The number of entries per page.

Default value: 1.

1
PageSizeintegerNo

The page number.

Valid values: 1 to 100.

Default value: 10.

10
ResourceGroupIdstringNo

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.
rg-aek3b6jzp66****
Tagobject []No

The tags of the dedicated host.

KeystringNo

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

TestKey
ValuestringNo

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

TestValue
DedicatedHostClusterIdstringNo

The ID of the dedicated host cluster.

dc-bp12wlf6am0vz9v2****
SocketDetailsstringNo

Whether to display socket capacity information

true

Response parameters

ParameterTypeDescriptionExample
object
PageSizeinteger

The number of entries per page.

1
RequestIdstring

The ID of the request.

7654525A-9964-4ABB-8BCD-98F8835E809A
PageNumberinteger

The page number.

5
TotalCountinteger

The total number of dedicated hosts.

3
DedicatedHostsobject []

The queried dedicated hosts.

CreationTimestring

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.

2018-01-01T12:00Z
SchedulerOptions.ManagedPrivateSpaceIdstring

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

mps-iq81z6pkbqjx61php46e
Statusstring

The state of the dedicated host. Valid values:

  • Available: The dedicated host is running normally.
  • UnderAssessment: The dedicated host is available but has potential risks that may cause the ECS instances on the dedicated host to fail.
  • PermanentFailure: The dedicated host has permanent failures and is unavailable.
Available
Coresinteger

The number of physical cores per CPU.

3
AutoPlacementstring

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.

on
GPUSpecstring

The GPU model.

gpu
AutoReleaseTimestring

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

2017-01-01T12:00Z
ChargeTypestring

The billing method of the dedicated host.

Prepaid
CpuOverCommitRatiofloat

The CPU overcommit ratio.

1
ActionOnMaintenancestring

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.
  • Stop: The instances are stopped. If the dedicated host cannot be restored, 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.

Migrate
SaleCyclestring

The unit of the subscription period. Valid values:

  • Month
  • Year
Month
PhysicalGpusinteger

The number of physical GPUs.

10
RegionIdstring

The region ID of the dedicated host.

cn-hangzhou
DedicatedHostNamestring

The name of the dedicated host.

MyDDHTestName
Descriptionstring

The description of the dedicated host.

this-is-my-DDH
DedicatedHostClusterIdstring

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

dc-bp12wlf6am0vz9v2****
ExpiredTimestring

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.

2019-01-01T12:00Z
DedicatedHostTypestring

The type of the dedicated host.

ddh.g5
ResourceGroupIdstring

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

rg-aek3b6jzp66****
ZoneIdstring

The zone ID of the dedicated host.

cn-hangzhou-g
DedicatedHostIdstring

The ID of the dedicated host.

dh-bp165p6xk2tlw61e****
Socketsinteger

The number of physical CPUs.

5
MachineIdstring

The machine code of the dedicated host.

12aaa123456ff19dec12345d3026e****
Instancesobject []

The ECS instances that were created on the dedicated host.

InstanceTypestring

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

ecs.g5.large
InstanceIdstring

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

i-bp14ot0ykf8w13a1****
SocketIdstring

The ID of the socket to which the instance belongs.

0,1
OperationLocksobject []

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

LockReasonstring

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

  • financial
  • security
financial
Tagsobject []

The tags of the dedicated host.

TagValuestring

The tag value of the dedicated host.

TestValue
TagKeystring

The tag key of the dedicated host.

TestKey
SupportedInstanceTypeFamiliesarray

The ECS instance families that are supported by the dedicated host.

string

The ECS instance families that are supported by the dedicated host.

ecs.g5
SupportedCustomInstanceTypeFamiliesarray

The custom ECS instance families that are supported by the dedicated host.

string

The custom ECS instance families that are supported by the dedicated host.

ecs.ddh6s.custom
SupportedInstanceTypesListarray

The ECS instance types that are supported by the dedicated host.

string

The ECS instance types that are supported by the dedicated host.

ecs.g5.large
Capacityobject

The performance specifications of the dedicated host.

AvailableMemoryfloat

The amount of available memory space. Unit: GiB.

25
LocalStorageCategorystring

The category of local disks.

i2
TotalMemoryfloat

The total capacity of the memory. Unit: GiB.

1024
TotalLocalStorageinteger

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

512
TotalVcpusinteger

The total number of vCPUs.

56
TotalVgpusinteger

The total number of vGPUs.

10
AvailableLocalStorageinteger

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

65
AvailableVcpusinteger

The number of available vCPUs.

5
AvailableVgpusinteger

The number of available vGPUs.

2
SocketCapacitiesobject []

Socket capacity information.

SocketIdinteger

The ID of the socket.

1
AvailableMemoryfloat

Remaining memory capacity, unit: GiB.

65
TotalMemoryfloat

Total memory capacity, unit: GiB.

128
AvailableVcpuinteger

The remaining number of vCPU cores.

64
TotalVcpuinteger

Total number of vCPU cores.

128
NetworkAttributesobject

The network attributes of the dedicated host.

UdpTimeoutinteger

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.

60
SlbUdpTimeoutinteger

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

60
HostDetailInfoobject

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

SerialNumberstring

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

null

Examples

Sample success responses

JSONformat

{
  "PageSize": 1,
  "RequestId": "7654525A-9964-4ABB-8BCD-98F8835E809A",
  "PageNumber": 5,
  "TotalCount": 3,
  "DedicatedHosts": {
    "DedicatedHost": [
      {
        "CreationTime": "2018-01-01T12:00Z",
        "SchedulerOptions.ManagedPrivateSpaceId": "mps-iq81z6pkbqjx61php46e",
        "Status": "Available",
        "Cores": 3,
        "AutoPlacement": "on",
        "GPUSpec": "gpu",
        "AutoReleaseTime": "2017-01-01T12:00Z",
        "ChargeType": "Prepaid",
        "CpuOverCommitRatio": 1,
        "ActionOnMaintenance": "Migrate",
        "SaleCycle": "Month",
        "PhysicalGpus": 10,
        "RegionId": "cn-hangzhou",
        "DedicatedHostName": "MyDDHTestName",
        "Description": "this-is-my-DDH",
        "DedicatedHostClusterId": "dc-bp12wlf6am0vz9v2****",
        "ExpiredTime": "2019-01-01T12:00Z",
        "DedicatedHostType": "ddh.g5",
        "ResourceGroupId": "rg-aek3b6jzp66****",
        "ZoneId": "cn-hangzhou-g",
        "DedicatedHostId": "dh-bp165p6xk2tlw61e****",
        "Sockets": 5,
        "MachineId": "12aaa123456ff19dec12345d3026e****",
        "Instances": {
          "Instance": [
            {
              "InstanceType": "ecs.g5.large",
              "InstanceId": "i-bp14ot0ykf8w13a1****",
              "SocketId": "0,1",
              "InstanceOwnerId": 0
            }
          ]
        },
        "OperationLocks": {
          "OperationLock": [
            {
              "LockReason": "financial"
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        },
        "SupportedInstanceTypeFamilies": {
          "SupportedInstanceTypeFamily": [
            "ecs.g5"
          ]
        },
        "SupportedCustomInstanceTypeFamilies": {
          "SupportedCustomInstanceTypeFamily": [
            "ecs.ddh6s.custom"
          ]
        },
        "SupportedInstanceTypesList": {
          "SupportedInstanceTypesList": [
            "ecs.g5.large"
          ]
        },
        "Capacity": {
          "AvailableMemory": 25,
          "LocalStorageCategory": "i2",
          "TotalMemory": 1024,
          "TotalLocalStorage": 512,
          "TotalVcpus": 56,
          "TotalVgpus": 10,
          "AvailableLocalStorage": 65,
          "AvailableVcpus": 5,
          "AvailableVgpus": 2,
          "SocketCapacities": {
            "SocketCapacity": [
              {
                "SocketId": 1,
                "AvailableMemory": 65,
                "TotalMemory": 128,
                "AvailableVcpu": 64,
                "TotalVcpu": 128
              }
            ]
          }
        },
        "NetworkAttributes": {
          "UdpTimeout": 60,
          "SlbUdpTimeout": 60
        },
        "HostDetailInfo": {
          "SerialNumber": "null"
        },
        "DedicatedHostOwnerId": 0
      }
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidStatus.ValueNotSupportedThe pecified dedicated host status is not supported.The host is in a state that does not support the current operation.
400MissingParamter.RegionIdThe regionId should not be null.The RegionId parameter is required.
400InvalidParameter.DedicatedHostIdsThe specified parameter dedicatedHostIds is not valid.The specified DedicatedHostIds parameter is invalid.
400InvalidRegion.NotFoundThe specified parameter RegionId is not valid.The specified RegionId parameter is invalid.
400InvalidZone.NotFoundThe specified parameter ZoneId is not valid.The specified ZoneId parameter is invalid.
403InvalidDedicatedHostIds.MalformedThe amount of specified dedicatedHostIds exceeds the limit.More than 100 dedicated host IDs are specified in the DedicatedHostIds value.
404InvalidLockReason.NotFoundThe specified LockReason is not found.The specified lockout reason does not exist.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2023-03-16The Error code has changed. The response structure of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
Output ParametersThe response structure of the API has changed.