全部产品
Search
文档中心

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

更新时间:Nov 29, 2024

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

接口说明

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

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

调试

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

授权信息

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

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

标签列表。列表长度范围:0~20。

object
Keystring

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

TestKey
Valuestring

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

TestValue
DedicatedHostClusterIdstring

专有宿主机集群 ID。

dc-bp12wlf6am0vz9v2****
SocketDetailsstring

是否展示 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
    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>

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

    DedicatedHostobject

    专有宿主机所属托管资源池(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~5。

    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 实例。

    Instanceobject
    InstanceTypestring

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

    ecs.g5.large
    InstanceIdstring

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

    i-bp14ot0ykf8w13a1****
    SocketIdstring

    实例所处的 Socket 的序号。

    0,1
    InstanceOwnerIdlong

    ECS 实例所有者的用户 ID。

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

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

    OperationLockobject
    LockReasonstring

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

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

    专有宿主机的标签。

    Tagobject
    TagValuestring

    专有宿主机的标签值。

    TestValue
    TagKeystring

    专有宿主机的标签键。

    TestKey
    SupportedInstanceTypeFamiliesarray

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

    SupportedInstanceTypeFamilystring

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

    ecs.g5
    SupportedCustomInstanceTypeFamiliesarray

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

    SupportedCustomInstanceTypeFamilystring

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

    ecs.ddh6s.custom
    SupportedInstanceTypesListarray

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

    SupportedInstanceTypesListstring

    专有宿主机支持的 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 维度容量信息。

    SocketCapacityobject
    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 返回结构发生变更查看变更详情