全部产品
Search
文档中心

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

更新时间:Jul 09, 2024

调用DescribeDedicatedHosts查询一台或多台专有宿主机的详细信息,包括物理性能指标、机器码、使用状态和已创建的ECS实例列表等。

接口说明

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

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

调试

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

授权信息

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

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:DescribeDedicatedHostsREAD
  • DedicatedHost
    acs:ecs:{#regionId}:{#accountId}:ddh/*
  • DedicatedHost
    acs:ecs:{#regionId}:{#accountId}:ddh/{#ddhId}

请求参数

名称类型必填描述示例值
RegionIdstring

专有宿主机所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou
ZoneIdstring

可用区 ID。您可以调用 DescribeZones 查看最新的阿里云可用区列表。

cn-hangzhou-g
DedicatedHostIdsstring

专有宿主机 ID 列表。单次最多支持 100 个 ID ,ID 之间用半角逗号(,)隔开。

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

专有宿主机的名称。

MyDDHTestName
Statusstring

专有宿主机的使用状态。取值范围:

  • Available:运行中。专有宿主机的正常运行状态。

  • UnderAssessment:物理机风险,即故障潜伏期,其物理机处于可用状态,但可能导致专有宿主机中的 ECS 实例出现问题。

  • PermanentFailure:永久性故障,专有宿主机不可用。

  • TempUnavailable:宿主机临时不可用。

  • Redeploying:宿主机恢复中。

默认值:Available。

Available
DedicatedHostTypestring

专有宿主机的规格。您可以调用 DescribeDedicatedHostTypes 接口获得最新的专有宿主机规格表。

ddh.g5
LockReasonstring

专有宿主机被锁定的原因。取值范围:

  • financial:因欠费被锁定。
  • security:因安全原因被锁定。
financial
PageNumberinteger

响应信息的页码数。

默认值:1。

1
PageSizeinteger

响应信息的每页行数。

最大值:100。

默认值:10。

10
ResourceGroupIdstring

专有宿主机所在资源组 ID。使用该参数过滤资源时,资源数量不能超过 1000 个。

说明 不支持默认资源组过滤。
rg-aek3b6jzp66****
Tagarray<object>

标签列表。

object
Keystring

专有宿主机的标签键。N 的取值范围:1~20。一旦传入该值,则不允许为空字符串。最多支持 128 个字符,不能以aliyunacs:开头,不能包含http://https://

TestKey
Valuestring

专有宿主机的标签值。N 的取值范围:1~20。一旦传入该值,可以为空字符串。最多支持 128 个字符,不能包含http://或者https://

TestValue
DedicatedHostClusterIdstring

专有宿主机集群 ID。

dc-bp12wlf6am0vz9v2****
SocketDetailsstring

是否展示 Socket 维度容量信息。取值范围:

  • true:展示。
  • false:不展示。
true
NextTokenstring

查询凭证(Token)。取值为上一次调用该接口返回的 NextToken 参数值,初次调用接口时无需设置该参数。

e71d8a535bd9cc11
MaxResultsinteger

分页查询时每页的最大条目数。一旦设置该参数,即表示使用 MaxResults 与 NextToken 组合参数的查询方式。

最大值为 100。

默认值为 10。

10

返回参数

名称类型描述示例值
object
PageSizeinteger

输入时设置的每页行数。

1
RequestIdstring

请求 ID。

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

专有宿主机列表的页码。

5
TotalCountinteger

专有宿主机总数。

3
NextTokenstring

本次调用返回的查询凭证(Token)。当使用 MaxResults 和 NextToken 方式进行分页查询,且该返回值为空时,表示无更多返回的数据信息。

e71d8a535bd9cc11
DedicatedHostsarray<object>

专有宿主机的详细信息集合。

object

专有宿主机所属托管资源池(Managed Private Space)ID。

CreationTimestring

专有宿主机的创建时间。按照ISO 8601标准表示,并需要使用 UTC+0 时间,格式为yyyy-MM-ddTHH:mmZ

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

专有宿主机所属托管资源池(Managed Private Space)ID。

mps-iq81z6pkbqjx61php46e
Statusstring

专有宿主机的使用状态。可能值:

  • Available:运行中。专有宿主机的正常运行状态。

  • UnderAssessment:物理机风险,即故障潜伏期,其物理机处于可用状态,但可能导致专有宿主机中的 ECS 实例出现问题。

  • PermanentFailure:故障。永久性故障,专有宿主机不可用。

Available
Coresinteger

单个 CPU 的核数。

3
AutoPlacementstring

专有宿主机是否加入自动部署资源池。取值范围:

  • on:加入自动部署资源池。

  • off:不加入自动部署资源池。

关于自动部署的更多信息,请参见自动部署功能介绍

on
GPUSpecstring

GPU 型号。

gpu
AutoReleaseTimestring

自动释放时间。按照ISO 8601标准表示,并需要使用 UTC+0 时间,格式为yyyy-MM-ddTHH:mmZ

2017-01-01T12:00Z
ChargeTypestring

专有宿主机的计费方式。

Prepaid
CpuOverCommitRatiofloat

CPU 超卖比。

1
ActionOnMaintenancestring

当专有宿主机发生故障时,为其所宿实例设置迁移方案。取值范围:

  • Migrate:专有宿主机整机迁移至另一物理服务器,并对故障前非关机状态的实例进行启动。

  • Stop:在当前专有宿主机上停止实例,确认无法修复专有宿主机后,迁移实例到其他物理机并重新启动实例。

当专有宿主机上挂载云盘存储时,默认值为 Migrate;当专有宿主机上挂载本地盘存储时默认值为 Stop。

Migrate
SaleCyclestring

包年包月单位。可能值:

  • Month。
  • Year。
Month
PhysicalGpusinteger

物理 GPU 数量。

10
RegionIdstring

专有宿主机所在地域 ID。

cn-hangzhou
DedicatedHostNamestring

专有宿主机的名称。

MyDDHTestName
Descriptionstring

专有宿主机的描述信息。

this-is-my-DDH
DedicatedHostClusterIdstring

专有宿主机所在的专有宿主机集群 ID。

dc-bp12wlf6am0vz9v2****
ExpiredTimestring

包年包月专有宿主机的到期时间。按照ISO 8601标准表示,并需要使用 UTC+0 时间,格式为yyyy-MM-ddTHH:mmZ

2019-01-01T12:00Z
DedicatedHostTypestring

专有宿主机的规格类型。

ddh.g5
ResourceGroupIdstring

专有宿主机所在资源组 ID。

rg-aek3b6jzp66****
ZoneIdstring

可用区 ID。

cn-hangzhou-g
DedicatedHostIdstring

专有宿主机 ID。

dh-bp165p6xk2tlw61e****
Socketsinteger

物理处理器(CPU)数量。

5
MachineIdstring

专有宿主机机器码。

12aaa123456ff19dec12345d3026e****
Instancesarray<object>

专有宿主机上创建的 ECS 实例。

object
InstanceTypestring

专有宿主机上创建的 ECS 实例规格信息。

ecs.g5.large
InstanceIdstring

专有宿主机上创建的 ECS 实例 ID。

i-bp14ot0ykf8w13a1****
SocketIdstring

实例所处的 Socket 的序号。

0,1
InstanceOwnerIdlong

ECS 实例所有者的用户 ID。

128************0
OperationLocksarray<object>

专有宿主机资源被锁定原因。

object
LockReasonstring

专有宿主机被锁定的原因。可能值:

  • financial:因欠费被锁定。
  • security:因安全原因被锁定。
financial
Tagsarray<object>

专有宿主机的标签。

object
TagValuestring

专有宿主机的标签值。

TestValue
TagKeystring

专有宿主机的标签键。

TestKey
SupportedInstanceTypeFamiliesarray

专有宿主机支持的 ECS 实例规格族。

string

专有宿主机支持的 ECS 实例规格族。

ecs.g5
SupportedCustomInstanceTypeFamiliesarray

专有宿主机支持的自定义实例规格族。

string

专有宿主机支持的自定义实例规格族。

ecs.ddh6s.custom
SupportedInstanceTypesListarray

专有宿主机支持的 ECS 实例规格。

string

专有宿主机支持的 ECS 实例规格。

ecs.g5.large
Capacityobject

专有宿主机性能指标集合。

AvailableMemoryfloat

剩余的内存容量,单位:GiB。

25
LocalStorageCategorystring

本地盘类型。

i2
TotalMemoryfloat

内存总容量,单位:GiB。

1024
TotalLocalStorageinteger

本地盘总容量,单位:GiB。

512
TotalVcpusinteger

vCPU 总核数。

56
TotalVgpusinteger

总虚拟 GPU 数量。

10
AvailableLocalStorageinteger

剩余的本地盘容量。单位:GiB。

65
AvailableVcpusinteger

剩余的 vCPU 核数。

5
AvailableVgpusinteger

可用虚拟 GPU 数量。

2
SocketCapacitiesarray<object>

Socket 维度容量信息。

object
SocketIdinteger

Socket 序号。

1
AvailableMemoryfloat

剩余内存容量,单位:GiB。

65
TotalMemoryfloat

内存总容量,单位:GiB。

128
AvailableVcpuinteger

剩余的 vCPU 核数。

64
TotalVcpuinteger

vCPU 总核数。

128
NetworkAttributesobject

专有宿主机的网络属性值。

UdpTimeoutinteger

UDP 超时时间。单位:S。当前仅支持 60S。

60
SlbUdpTimeoutinteger

SLB UDP 超时时间。单位:S。当前仅支持 60S。

60
HostDetailInfoobject

该参数即将被弃用,为提高兼容性,建议您尽量使用其他参数。

SerialNumberstring

该参数即将被弃用,为提高兼容性,建议您尽量使用其他参数。

null
DedicatedHostOwnerIdlong

专有宿主机所有者的用户 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
              }
            ]
          }
        },
        "NetworkAttributes": {
          "UdpTimeout": 60,
          "SlbUdpTimeout": 60
        },
        "HostDetailInfo": {
          "SerialNumber": "null"
        },
        "DedicatedHostOwnerId": 0
      }
    ]
  }
}

错误码

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

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

变更历史

变更时间变更内容概要操作
2024-04-11OpenAPI 错误码发生变更、OpenAPI 入参发生变更、OpenAPI 返回结构发生变更查看变更详情
2023-03-16OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情