DescribeDedicatedHosts-阿里云帮助中心

This operation queries the details of one or more dedicated hosts, including physical performance metrics, the machine ID, status, and the ECS instances running on each host. You can filter the results by parameters such as dedicated host IDs, a dedicated host cluster ID, host name, or status. Use this information to efficiently manage and optimize your cloud resources.

Operation description

API

Query details for one or more dedicated hosts by specifying one of the following parameters:

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 is located. You can call the DescribeRegions operation to get the latest list of Alibaba Cloud regions.	cn-hangzhou
ZoneId	string	No	The ID of the zone. You can call the DescribeZones operation to get the latest list of Alibaba Cloud zones.	cn-hangzhou-g
DedicatedHostIds	string	No	The IDs of the dedicated hosts. The value is a JSON array of strings. You can specify up to 100 dedicated host IDs.	["dh-bp165p6xk2tlw61e**", "dh-bp1f9vxmno7emy96**"]
DedicatedHostName	string	No	The name of the dedicated host.	MyDDHTestName
Status	string	No	The status of the dedicated host. Valid values: Available: The dedicated host is running as expected. UnderAssessment: The dedicated host is under risk assessment for its underlying physical machine. The host remains available but may have 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. Default value: Available.	Available
DedicatedHostType	string	No	The type of the dedicated host. You can call the DescribeDedicatedHostTypes operation to get the latest list of dedicated host types.	ddh.g5
LockReason	string	No	The reason 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 instead.	1
PageSize	integer	No	Note This parameter is deprecated. Use `NextToken` and `MaxResults` for pagination instead.	10
ResourceGroupId	string	No	The ID of the resource group to which the dedicated host belongs. When you use this parameter to filter resources, a maximum of 1,000 resources can be returned. Note Filtering by the default resource group is not supported.	rg-aek3b6jzp66****
Tag	array<object>	No	The tags of the dedicated host. You can specify up to 20 tags.
	object	No
Key	string	No	The tag key cannot be an empty string. It can be up to 128 characters long and cannot start with `aliyun` or `acs:`. It also cannot contain `http://` or `https://`.	TestKey
Value	string	No	The tag value can be an empty string. It can be up to 128 characters long and cannot contain `http://` or `https://`.	TestValue
DedicatedHostClusterId	string	No	The ID of the dedicated host cluster.	dc-bp12wlf6am0vz9v2****
SocketDetails	string	No	Specifies whether to return capacity information by socket. This information includes the used, available, and total vCPUs and memory resources on each socket, which helps you determine whether an ECS instance of a specific type can be created. Valid values: true: Returns capacity information by socket. This feature is supported only for specific dedicated host types. For more information, see View and export information about a dedicated host. false: Does not return capacity information by socket. Important A dedicated host typically has two CPUs, identified as socket 0 and socket 1. To ensure maximum performance, an ECS instance on a dedicated host is created on a single socket and does not span across multiple sockets. An ECS instance can be created if a single socket has sufficient resources for the instance type. The instance cannot be created if no single socket meets the resource requirements, even if the total available resources across both sockets are sufficient.	true
NextToken	string	No	The pagination token. Set this parameter to the `NextToken` value returned from a previous call to retrieve the next page of results. You do not need to specify this parameter for the first request.	e71d8a535bd9cc11
MaxResults	integer	No	The maximum number of entries to return per page. When you set this parameter, you must use it with the `NextToken` parameter for pagination. Maximum value: 100. Default value: 10.	10
QueryInventory	boolean	No

Response elements

Element	Type	Description	Example
	object
PageSize	integer	The number of entries per page.	1
RequestId	string	The request ID.	7654525A-9964-4ABB-8BCD-98F8835E809A
PageNumber	integer	The page number of the dedicated host list.	5
TotalCount	integer	The total number of dedicated hosts.	3
NextToken	string	The returned query token. If the value of this parameter is empty, no more results are returned.	e71d8a535bd9cc11
DedicatedHosts	object
DedicatedHost	array<object>	The details of the dedicated hosts.
	array<object>	The ID of the managed private space to which the dedicated host belongs.
CreationTime	string	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.ManagedPrivateSpaceId	string	The ID of the managed private space to which the dedicated host belongs.	mps-iq81z6pkbqjx61php46e
Status	string	The status of the dedicated host. Valid values: Available: The dedicated host is running as normal. UnderAssessment: The dedicated host is being assessed for risks. Although the dedicated host is available, the ECS instances on the dedicated host may be affected. PermanentFailure: The dedicated host has a permanent failure and is unavailable.	Available
Cores	integer	The number of physical cores per CPU.	3
AutoPlacement	string	Indicates whether the dedicated host is added to the automatic deployment resource pool. Valid values: on: The dedicated host is added to the automatic deployment resource pool. off: The dedicated host is not added to the automatic deployment resource pool. For more information about automatic deployment, see Automatic deployment.	on
GPUSpec	string	The GPU model.	gpu
AutoReleaseTime	string	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.	2017-01-01T12:00Z
ChargeType	string	The billing method of the dedicated host.	Prepaid
CpuOverCommitRatio	number	The CPU overcommit ratio. Valid values: 1 to 5.	1
ActionOnMaintenance	string	The policy used to migrate the instances on the dedicated host when the dedicated host fails. Valid values: Migrate: The instances are migrated to another physical machine and the instances that were in the Running state before the failure are restarted. Stop: The instances are stopped. If the dedicated host is confirmed to be irreparable, the instances are migrated to another physical machine 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
SaleCycle	string	The unit of the subscription period. Valid values: Month Year	Month
PhysicalGpus	integer	The number of physical GPUs.	10
RegionId	string	The region ID of the dedicated host.	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 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
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 zone ID.	cn-hangzhou-g
DedicatedHostId	string	The ID of the dedicated host.	dh-bp165p6xk2tlw61e****
Sockets	integer	The number of physical CPUs.	5
MachineId	string	The machine code of the dedicated host.	12aaa123456ff19dec12345d3026e****
Instances	object
Instance	array<object>	The 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 to which the instance belongs.	0,1
InstanceOwnerId	integer	The ID of the ECS instance owner.	128************0
OperationLocks	object
OperationLock	array<object>	The reasons why the dedicated host was locked.
	object
LockReason	string	The reason why the dedicated host was locked. 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	The information about the tag.
TagValue	string	The value of the tag.	TestValue
TagKey	string	The key of the tag.	TestKey
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	The instance families supported by the dedicated host.
	string	The instance family supported by the dedicated host.	ecs.g5
SupportedCustomInstanceTypeFamilies	object
SupportedCustomInstanceTypeFamily	array	The custom instance families supported by the dedicated host.
	string	A custom instance family supported by the dedicated host.	ecs.ddh6s.custom
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	The instance types supported by the dedicated host.
	string	An 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 local disks.	i2
TotalMemory	number	The total memory capacity. Unit: GiB.	1024
TotalLocalStorage	integer	The total capacity of 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 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 socket index.	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 families. Note This parameter is required.
AvailableInstanceCapacity	integer	The number of available instances of the instance type.
NetworkAttributes	object	The network attributes of the dedicated host.
UdpTimeout	integer	The UDP session timeout period. Unit: seconds. Only 60 is supported.	60
SlbUdpTimeout	integer	The timeout period of a UDP session for SLB. Unit: seconds. Only 60 is supported.	60
HostDetailInfo	object	This parameter is deprecated. We recommend that you use other parameters to ensure compatibility.
SerialNumber	string	This parameter is deprecated. We recommend that you use other parameters to ensure compatibility.	null
DedicatedHostOwnerId	integer	The 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.