DescribeDedicatedHosts - 查询专有宿主机详细信息 - 云服务器 ECS

本接口用于查询一台或多台专有宿主机的详细信息。通过该接口，您可以获取包括专有宿主机的物理性能指标、机器码、使用状态以及已创建的ECS实例列表等信息。您能够根据具体需求，通过指定相关参数，如专有宿主机ID列表、专有宿主机集群ID、宿主机名称、状态等，精准地查询所需的专有宿主机详细信息，为高效管理和优化云计算资源提供有力支持。

接口说明

您可以通过以下任一方式查询一台或多台专有宿主机的详细信息：

指定DedicatedHostIds查询专有宿主机的详细信息。
指定DedicatedHostClusterId查询专有宿主机集群内专有宿主机的详细信息。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

ecs:DescribeDedicatedHosts

get

DedicatedHost

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

DedicatedHost

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

无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	专有宿主机所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。	cn-hangzhou
ZoneId	string	否	可用区 ID。您可以调用 DescribeZones 查看最新的阿里云可用区列表。	cn-hangzhou-g
DedicatedHostIds	string	否	专有宿主机 ID 列表。最多支持 100 个 ID ，ID 之间用半角逗号（,）隔开。	["dh-bp165p6xk2tlw61e**", "dh-bp1f9vxmno7emy96**"]
DedicatedHostName	string	否	专有宿主机的名称。	MyDDHTestName
Status	string	否	专有宿主机的使用状态。取值范围： Available：运行中。专有宿主机的正常运行状态。 UnderAssessment：物理机风险，即故障潜伏期，其物理机处于可用状态，但可能导致专有宿主机中的 ECS 实例出现问题。 PermanentFailure：永久性故障，专有宿主机不可用。 TempUnavailable：宿主机临时不可用。 Redeploying：宿主机恢复中。默认值：Available。	Available
DedicatedHostType	string	否	专有宿主机的规格。您可以调用 DescribeDedicatedHostTypes 接口获得最新的专有宿主机规格列表。	ddh.g5
LockReason	string	否	专有宿主机被锁定的原因。取值范围： financial：因欠费被锁定。 security：因安全原因被锁定。	financial
PageNumber	integer	否	说明该参数即将下线，推荐您使用 NextToken 与 MaxResults 完成分页查询操作。	1
PageSize	integer	否	说明该参数即将下线，推荐您使用 NextToken 与 MaxResults 完成分页查询操作。	10
ResourceGroupId	string	否	专有宿主机所在资源组 ID。使用该参数过滤资源时，资源数量不能超过 1000 个。说明不支持默认资源组过滤。	rg-aek3b6jzp66****
Tag	array<object>	否	标签列表。列表长度范围：0~20。
	object	否
Key	string	否	专有宿主机的标签键。一旦传入该值，则不允许为空字符串。最多支持 128 个字符，不能以`aliyun`和`acs:`开头，不能包含`http://`或`https://`。	TestKey
Value	string	否	专有宿主机的标签值。一旦传入该值，可以为空字符串。最多支持 128 个字符，不能包含`http://`或者`https://`。	TestValue
DedicatedHostClusterId	string	否	专有宿主机集群 ID。	dc-bp12wlf6am0vz9v2****
SocketDetails	string	否	是否展示 Socket 维度容量信息。您可以通过 Socket 维度容量信息查看剩余资源信息（vCPU、内存使用量、剩余量和总量信息），从而判断是否可以创建出对应规格的 ECS 实例。取值范围： true：展示。仅部分规格的 DDH 支持显示 Socket 维度资源信息，详情请参见查看和导出 DDH 信息。 false：不展示。重要每个 DDH 一般有两个 CPU，每个 CPU 对应的编号为 Socket 0、Socket 1。在独享的 DDH 中，为保证 DDH 上的 ECS 发挥最大性能，ECS 不会跨 Socket 创建，即 ECS 仅会基于一个 Socket 创建。如果其中一个 Socket 剩余的算力资源大于等于待创建的 ECS 规格，ECS 将创建成功。如果每个 Socket 剩余的算力资源小于待创建的 ECS 规格，ECS 将创建失败。虽然 DDH 上两个 Socket 剩余的资源大于 ECS 规格，但是仍然无法创建出 ECS 实例。	true
NextToken	string	否	查询凭证（Token）。取值为上一次调用该接口返回的 NextToken 参数值，初次调用接口时无需设置该参数。	e71d8a535bd9cc11
MaxResults	integer	否	分页查询时每页的最大条目数。一旦设置该参数，即表示使用 MaxResults 与 NextToken 组合参数的查询方式。最大值为 100。默认值为 10。	10
QueryInventory	boolean	否

返回参数

名称	类型	描述	示例值
	object
PageSize	integer	输入时设置的每页行数。	1
RequestId	string	请求 ID。	7654525A-9964-4ABB-8BCD-98F8835E809A
PageNumber	integer	专有宿主机列表的页码。	5
TotalCount	integer	专有宿主机总数。	3
NextToken	string	本次调用返回的查询凭证（Token）。当使用 MaxResults 和 NextToken 方式进行分页查询，且该返回值为空时，表示无更多返回的数据信息。	e71d8a535bd9cc11
DedicatedHosts	object
DedicatedHost	array<object>	专有宿主机的详细信息集合。
	array<object>	专有宿主机所属托管资源池（Managed Private Space）ID。
CreationTime	string	专有宿主机的创建时间。按照ISO 8601标准表示，并需要使用 UTC+0 时间，格式为`yyyy-MM-ddTHH:mmZ`。	2018-01-01T12:00Z
SchedulerOptions.ManagedPrivateSpaceId	string	专有宿主机所属托管资源池（Managed Private Space）ID。	mps-iq81z6pkbqjx61php46e
Status	string	专有宿主机的使用状态。可能值： Available：运行中。专有宿主机的正常运行状态。 UnderAssessment：物理机风险，即故障潜伏期，其物理机处于可用状态，但可能导致专有宿主机中的 ECS 实例出现问题。 PermanentFailure：故障。永久性故障，专有宿主机不可用。	Available
Cores	integer	单个 CPU 的核数。	3
AutoPlacement	string	专有宿主机是否加入自动部署资源池。取值范围： on：加入自动部署资源池。 off：不加入自动部署资源池。关于自动部署的更多信息，请参见自动部署功能介绍。	on
GPUSpec	string	GPU 型号。	gpu
AutoReleaseTime	string	自动释放时间。按照ISO 8601标准表示，并需要使用 UTC+0 时间，格式为`yyyy-MM-ddTHH:mmZ`。	2017-01-01T12:00Z
ChargeType	string	专有宿主机的计费方式。	Prepaid
CpuOverCommitRatio	number	CPU 超卖比。取值范围为：1~5。	1
ActionOnMaintenance	string	当专有宿主机发生故障时，为其所宿实例设置迁移方案。取值范围： Migrate：专有宿主机整机迁移至另一物理服务器，并对故障前非关机状态的实例进行启动。 Stop：在当前专有宿主机上停止实例，确认无法修复专有宿主机后，迁移实例到其他物理机并重新启动实例。当专有宿主机上挂载云盘存储时，默认值为 Migrate；当专有宿主机上挂载本地盘存储时默认值为 Stop。	Migrate
SaleCycle	string	包年包月单位。可能值： Month。 Year。	Month
PhysicalGpus	integer	物理 GPU 数量。	10
RegionId	string	专有宿主机所在地域 ID。	cn-hangzhou
DedicatedHostName	string	专有宿主机的名称。	MyDDHTestName
Description	string	专有宿主机的描述信息。	this-is-my-DDH
DedicatedHostClusterId	string	专有宿主机所在的专有宿主机集群 ID。	dc-bp12wlf6am0vz9v2****
ExpiredTime	string	包年包月专有宿主机的到期时间。按照ISO 8601标准表示，并需要使用 UTC+0 时间，格式为`yyyy-MM-ddTHH:mmZ`。	2019-01-01T12:00Z
DedicatedHostType	string	专有宿主机的规格类型。	ddh.g5
ResourceGroupId	string	专有宿主机所在资源组 ID。	rg-aek3b6jzp66****
ZoneId	string	可用区 ID。	cn-hangzhou-g
DedicatedHostId	string	专有宿主机 ID。	dh-bp165p6xk2tlw61e****
Sockets	integer	物理处理器（CPU）数量。	5
MachineId	string	专有宿主机机器码。	12aaa123456ff19dec12345d3026e****
Instances	object
Instance	array<object>	专有宿主机上创建的 ECS 实例列表。
	object	专有宿主机上创建的 ECS 实例。
InstanceType	string	专有宿主机上创建的 ECS 实例规格信息。	ecs.g5.large
InstanceId	string	专有宿主机上创建的 ECS 实例 ID。	i-bp14ot0ykf8w13a1****
SocketId	string	实例所处的 Socket 的序号。	0,1
InstanceOwnerId	integer	ECS 实例所有者的用户 ID。	128************0
OperationLocks	object
OperationLock	array<object>	专有宿主机资源被锁定原因列表。
	object
LockReason	string	专有宿主机被锁定的原因。可能值： financial：因欠费被锁定。 security：因安全原因被锁定。	financial
Tags	object
Tag	array<object>	专有宿主机的标签列表。
	object	标签对信息。
TagValue	string	专有宿主机的标签值。	TestValue
TagKey	string	专有宿主机的标签键。	TestKey
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	专有宿主机支持的 ECS 实例规格族列表。
	string	专有宿主机支持的 ECS 实例规格族。	ecs.g5
SupportedCustomInstanceTypeFamilies	object
SupportedCustomInstanceTypeFamily	array	专有宿主机支持的自定义实例规格族。
	string	专有宿主机支持的自定义实例规格族。	ecs.ddh6s.custom
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	专有宿主机支持的 ECS 实例规格列表。
	string	专有宿主机支持的 ECS 实例规格。	ecs.g5.large
Capacity	object	专有宿主机性能指标集合。
AvailableMemory	number	剩余的内存容量，单位：GiB。	25
LocalStorageCategory	string	本地盘类型。	i2
TotalMemory	number	内存总容量，单位：GiB。	1024
TotalLocalStorage	integer	本地盘总容量，单位：GiB。	512
TotalVcpus	integer	vCPU 总核数。	56
TotalVgpus	integer	总虚拟 GPU 数量。	10
AvailableLocalStorage	integer	剩余的本地盘容量。单位：GiB。	65
AvailableVcpus	integer	剩余的 vCPU 核数。	5
AvailableVgpus	integer	可用虚拟 GPU 数量。	2
SocketCapacities	object
SocketCapacity	array<object>	Socket 维度容量信息列表。
	object
SocketId	integer	Socket 序号。	1
AvailableMemory	number	剩余内存容量，单位：GiB。	65
TotalMemory	number	内存总容量，单位：GiB。	128
AvailableVcpu	integer	剩余的 vCPU 核数。	64
TotalVcpu	integer	vCPU 总核数。	128
AvailableInstanceTypes	object
AvailableInstanceType	array<object>	可用的实例规格信息列表
	object	可用的实例规格信息。
InstanceType	string	实例规格。取值请参见实例规格族。说明该参数为必选参数。
AvailableInstanceCapacity	integer	可用的实例规格容量。
NetworkAttributes	object	专有宿主机的网络属性值。
UdpTimeout	integer	UDP 超时时间。单位：S。当前仅支持 60S。	60
SlbUdpTimeout	integer	SLB UDP 超时时间。单位：S。当前仅支持 60S。	60
HostDetailInfo	object	该参数即将被弃用，为提高兼容性，建议您尽量使用其他参数。
SerialNumber	string	该参数即将被弃用，为提高兼容性，建议您尽量使用其他参数。	null
DedicatedHostOwnerId	integer	专有宿主机所有者的用户 ID。	100************7

示例

正常返回示例

JSON格式

{
  "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
      }
    ]
  }
}

错误码

HTTP status code	错误码	错误信息	描述
400	InvalidStatus.ValueNotSupported	The pecified dedicated host status is not supported.	当前宿主机状态不支持此操作。
400	MissingParamter.RegionId	The regionId should not be null.	参数 RegionId 不得为空。
400	InvalidParameter.DedicatedHostIds	The specified parameter dedicatedHostIds is not valid.	指定的参数 DedicatedHostIds 无效。
400	InvalidRegion.NotFound	The specified parameter RegionId is not valid.	RegionId 参数不合法。
400	InvalidZone.NotFound	The specified parameter ZoneId is not valid.	指定的ZoneId不合法。
403	InvalidDedicatedHostIds.Malformed	The amount of specified dedicatedHostIds exceeds the limit.	参数 DedicatedHostIds 中的数据最多设置100个。
404	InvalidLockReason.NotFound	The specified LockReason is not found.	所指定的锁定原因不存在

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。