DescribeDedicatedHosts-阿里云帮助中心

Use this operation to query details for one or more dedicated hosts. It returns information such as physical performance metrics, machine code, status, and a list of ECS instances on the hosts. You can filter the results by parameters like dedicated host IDs, dedicated host cluster ID, host name, or status to find specific hosts. This feature helps you efficiently manage and optimize your cloud computing resources.

Operation description

API

You can query the details of one or more dedicated hosts in one of the following ways:

Specify DedicatedHostIds to query specific dedicated hosts.
Specify DedicatedHostClusterId to query all dedicated hosts in a dedicated host cluster.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:DescribeDedicatedHosts

get

DedicatedHost

acs:ecs:{#regionId}:{#accountId}:ddh/*

DedicatedHost

acs:ecs:{#regionId}:{#accountId}:ddh/{#ddhId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The ID of the region where the dedicated host resides. Call the `DescribeRegions` operation to get the latest list of Alibaba Cloud regions.	cn-hangzhou
ZoneId	string	No	The zone ID. Call the `DescribeZones` operation to get the latest list of Alibaba Cloud zones.	cn-hangzhou-g
DedicatedHostIds	string	No	The IDs of dedicated hosts. You can specify up to 100 dedicated host IDs in a JSON array.	["dh-bp165p6xk2tlw61e**", "dh-bp1f9vxmno7emy96**"]
DedicatedHostName	string	No	The name of the dedicated host.	MyDDHTestName
Status	string	No	The state of the dedicated host. Valid values: `Available`: The dedicated host is running as expected. `UnderAssessment`: The dedicated host is being assessed for physical hardware risks. The host is available but may have hardware issues that could affect its ECS instances. `PermanentFailure`: The dedicated host has a permanent failure and is unavailable. `TempUnavailable`: The dedicated host is temporarily unavailable. `Redeploying`: The dedicated host is being redeployed. The default value is `Available`.	Available
DedicatedHostType	string	No	The dedicated host type. Call the `DescribeDedicatedHostTypes` operation to get the latest list of dedicated host types.	ddh.g5
LockReason	string	No	The reason that the dedicated host is locked. Valid values: `financial`: The dedicated host is locked due to an overdue payment. `security`: The dedicated host is locked for security reasons.	financial
PageNumber	integer	No	Note This parameter is deprecated. Use `NextToken` and `MaxResults` for pagination.	1
PageSize	integer	No	Note This parameter is deprecated. Use `NextToken` and `MaxResults` for pagination.	10
ResourceGroupId	string	No	The ID of the resource group to which the dedicated host belongs. When you use this parameter to filter resources, the number of resources cannot exceed 1,000. Note Filtering by the default resource group is not supported.	rg-aek3b6jzp66****
Tag	array<object>	No	The tags used to filter dedicated hosts. You can specify up to 20 tags.
	object	No
Key	string	No	The tag key. The key can be up to 128 characters long. It cannot be an empty string, start with `aliyun` or `acs:`, or contain `http://` or `https://`.	TestKey
Value	string	No	The tag value. The value can be up to 128 characters long and cannot contain `http://` or `https://`. You can leave the value empty.	TestValue
DedicatedHostClusterId	string	No	The ID of the dedicated host cluster.	dc-bp12wlf6am0vz9v2****
SocketDetails	string	No	Specifies whether to return socket-level capacity information. You can use the information to check the remaining vCPU and memory resources and determine whether an ECS instance of a specific instance type can be created on the dedicated host. Valid values: `true`: returns the information. Only specific dedicated host types support this feature. For more information, see View and export information about dedicated hosts. `false`: does not return the information. Important A dedicated host typically has two CPUs, which correspond to Socket 0 and Socket 1. To maximize performance, an ECS instance created on a dedicated host is allocated to a single socket and does not span sockets. If the remaining resources on a socket are sufficient for the specified ECS instance type, the instance can be created. If the remaining resources on each socket are insufficient for the specified ECS instance type, the instance cannot be created, even if the total remaining resources on both sockets are sufficient.	true
NextToken	string	No	The token used to retrieve the next page of results. Do not set this parameter for the first request. For subsequent requests, set this parameter to the `NextToken` value returned from the previous response.	e71d8a535bd9cc11
MaxResults	integer	No	The maximum number of results to return per page. Maximum value: 100. Default value: 10.	10
QueryInventory	boolean	No

Response elements

Element	Type	Description	Example
	object
PageSize	integer	The number of entries returned on each page.	1
RequestId	string	The request ID.	7654525A-9964-4ABB-8BCD-98F8835E809A
PageNumber	integer	The current page number.	5
TotalCount	integer	The total number of dedicated hosts.	3
NextToken	string	The token used to retrieve the next page of results. An empty value indicates that no more results are available.	e71d8a535bd9cc11
DedicatedHosts	object
DedicatedHost	array<object>	The details of the dedicated hosts.
	array<object>	Details of a dedicated host.
CreationTime	string	The time when the dedicated host was created. The time is in UTC and formatted as `yyyy-MM-ddTHH:mmZ` in compliance with the ISO 8601 standard.	2018-01-01T12:00Z
SchedulerOptions.ManagedPrivateSpaceId	string	The ID of the managed private space to which the dedicated host belongs.	mps-iq81z6pkbqjx61php46e
Status	string	The state of the dedicated host. Valid values: `Available`: The dedicated host is running as expected. `UnderAssessment`: The dedicated host is under risk assessment. The underlying physical machine is available but has potential issues that could affect the ECS instances running on it. `PermanentFailure`: The dedicated host has a permanent failure and is unavailable.	Available
Cores	integer	The number of cores per physical CPU.	3
AutoPlacement	string	Specifies whether the dedicated host is in the auto-placement resource pool. Valid values: `on`: The dedicated host is added to the resource pool for auto-placement. `off`: The dedicated host is not added to the resource pool for auto-placement. For more information about auto-placement, see Auto-placement.	on
GPUSpec	string	The GPU model.	gpu
AutoReleaseTime	string	The time when the dedicated host is automatically released. The time is in UTC and formatted as `yyyy-MM-ddTHH:mmZ` in compliance with the ISO 8601 standard.	2017-01-01T12:00Z
ChargeType	string	The billing method of the dedicated host.	Prepaid
CpuOverCommitRatio	number	The CPU overcommitment ratio. Valid values: 1 to 5.	1
ActionOnMaintenance	string	The policy for migrating instances on the dedicated host during a host failure. Valid values: `Migrate`: Migrates the instances to another physical machine. Instances that were running before the failure are restarted. `Stop`: Stops the instances on the failed dedicated host. After the host is confirmed to be irreparable, the instances are migrated to another physical machine and then restarted. The default value is `Migrate` if the dedicated host uses cloud disks, and `Stop` if it uses local disks.	Migrate
SaleCycle	string	The unit of the subscription billing cycle. Valid values: Month Year	Month
PhysicalGpus	integer	The number of physical GPUs.	10
RegionId	string	The ID of the region where the dedicated host resides.	cn-hangzhou
DedicatedHostName	string	The name of the dedicated host.	MyDDHTestName
Description	string	The description of the dedicated host.	this-is-my-DDH
DedicatedHostClusterId	string	The ID of the dedicated host cluster to which the dedicated host belongs.	dc-bp12wlf6am0vz9v2****
ExpiredTime	string	The expiration time of the dedicated host. The time is in UTC and formatted as `yyyy-MM-ddTHH:mmZ` in compliance with the ISO 8601 standard.	2019-01-01T12:00Z
DedicatedHostType	string	The type of the dedicated host.	ddh.g5
ResourceGroupId	string	The ID of the resource group to which the dedicated host belongs.	rg-aek3b6jzp66****
ZoneId	string	The ID of the zone where the dedicated host is located.	cn-hangzhou-g
DedicatedHostId	string	The ID of the dedicated host.	dh-bp165p6xk2tlw61e****
Sockets	integer	The number of physical CPUs (sockets).	5
MachineId	string	The machine code of the dedicated host.	12aaa123456ff19dec12345d3026e****
Instances	object
Instance	array<object>	A list of ECS instances on the dedicated host.
	object	An ECS instance on the dedicated host.
InstanceType	string	The instance type of the ECS instance.	ecs.g5.large
InstanceId	string	The ID of the ECS instance.	i-bp14ot0ykf8w13a1****
SocketId	string	The index of the socket that hosts the instance.	0,1
InstanceOwnerId	integer	The user ID of the ECS instance owner.	128************0
OperationLocks	object
OperationLock	array<object>	The reasons for the lock on the dedicated host.
	object
LockReason	string	The reason for the lock. Valid values: `financial`: The dedicated host was locked due to an overdue payment. `security`: The dedicated host was locked for security reasons.	financial
Tags	object
Tag	array<object>	The tags of the dedicated host.
	object	A key-value pair that makes up a tag.
TagValue	string	The value of the tag.	TestValue
TagKey	string	The key of the tag.	TestKey
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	The ECS instance type families supported by the dedicated host.
	string	The instance type family supported by the dedicated host.	ecs.g5
SupportedCustomInstanceTypeFamilies	object
SupportedCustomInstanceTypeFamily	array	The custom instance type families supported by the dedicated host.
	string	The custom instance type family supported by the dedicated host.	ecs.ddh6s.custom
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	The ECS instance types supported by the dedicated host.
	string	The instance type supported by the dedicated host.	ecs.g5.large
Capacity	object	The resource capacity of the dedicated host.
AvailableMemory	number	The available memory capacity. Unit: GiB.	25
LocalStorageCategory	string	The category of the local disk.	i2
TotalMemory	number	The total memory capacity. Unit: GiB.	1024
TotalLocalStorage	integer	The total capacity of the local disks. Unit: GiB.	512
TotalVcpus	integer	The total number of vCPUs.	56
TotalVgpus	integer	The total number of vGPUs.	10
AvailableLocalStorage	integer	The available capacity of the local disks. Unit: GiB.	65
AvailableVcpus	integer	The number of available vCPUs.	5
AvailableVgpus	integer	The number of available vGPUs.	2
SocketCapacities	object
SocketCapacity	array<object>	The capacity of each socket.
	object
SocketId	integer	The index of the socket.	1
AvailableMemory	number	The available memory capacity. Unit: GiB.	65
TotalMemory	number	The total memory capacity. Unit: GiB.	128
AvailableVcpu	integer	The number of available vCPUs.	64
TotalVcpu	integer	The total number of vCPUs.	128
AvailableInstanceTypes	object
AvailableInstanceType	array<object>	The information about the available instance types.
	object	The information about an available instance type.
InstanceType	string	The instance type. For more information, see Instance type families. Note
AvailableInstanceCapacity	integer	The number of available instances of the specified instance type.
NetworkAttributes	object	The network attributes of the dedicated host.
UdpTimeout	integer	The timeout period of the UDP session. Unit: seconds. Only 60 is supported.	60
SlbUdpTimeout	integer	The timeout period of the SLB UDP session. Unit: seconds. Only 60 is supported.	60
HostDetailInfo	object	This parameter is deprecated. We recommend that you use other parameters to ensure future compatibility.
SerialNumber	string	This parameter is deprecated. We recommend that you use other parameters to ensure future compatibility.	null
DedicatedHostOwnerId	integer	The user ID of the dedicated host owner.	100************7

Examples

Success response

JSON format

{
  "PageSize": 1,
  "RequestId": "7654525A-9964-4ABB-8BCD-98F8835E809A",
  "PageNumber": 5,
  "TotalCount": 3,
  "NextToken": "e71d8a535bd9cc11",
  "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
              }
            ]
          },
          "AvailableInstanceTypes": {
            "AvailableInstanceType": [
              {
                "InstanceType": "",
                "AvailableInstanceCapacity": 0
              }
            ]
          }
        },
        "NetworkAttributes": {
          "UdpTimeout": 60,
          "SlbUdpTimeout": 60
        },
        "HostDetailInfo": {
          "SerialNumber": "null"
        },
        "DedicatedHostOwnerId": 0
      }
    ]
  }
}

Error codes

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

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.