DescribeDedicatedHosts - 查詢Dedicated Host詳細資料 - Elastic Compute Service

本介面用於查詢一台或多台Dedicated Host的詳細資料。通過該介面，您可以擷取包括Dedicated Host的物理效能指標、機器碼、使用狀態以及已建立的ECS執行個體列表等資訊。您能夠根據具體需求，通過指定相關參數，如Dedicated HostID列表、Dedicated Host叢集ID、宿主機名稱、狀態等，精準地查詢所需的Dedicated Host詳細資料，為高效管理和最佳化雲端運算資源提供有力支援。

介面說明

您可以通過以下任一方式查詢一台或多台Dedicated Host的詳細資料：

指定DedicatedHostIds查詢Dedicated Host的詳細資料。
指定DedicatedHostClusterId查詢Dedicated Host叢集內Dedicated Host的詳細資料。

調試

您可以在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	是	Dedicated Host所屬的地區 ID。您可以調用 DescribeRegions 查看最新的阿里雲地區列表。	cn-hangzhou
ZoneId	string	否	可用性區域 ID。您可以調用 DescribeZones 查看最新的阿里雲可用性區域列表。	cn-hangzhou-g
DedicatedHostIds	string	否	Dedicated Host ID 列表。最多支援 100 個 ID ，ID 之間用半形逗號（,）隔開。	["dh-bp165p6xk2tlw61e**", "dh-bp1f9vxmno7emy96**"]
DedicatedHostName	string	否	Dedicated Host的名稱。	MyDDHTestName
Status	string	否	Dedicated Host的使用狀態。取值範圍： Available：運行中。Dedicated Host的正常運行狀態。 UnderAssessment：物理機風險，即故障潛伏期，其物理機處於可用狀態，但可能導致Dedicated Host中的 ECS 執行個體出現問題。 PermanentFailure：永久性故障，Dedicated Host不可用。 TempUnavailable：宿主機臨時不可用。 Redeploying：宿主機恢複中。預設值：Available。	Available
DedicatedHostType	string	否	Dedicated Host的規格。您可以調用 DescribeDedicatedHostTypes 介面獲得最新的Dedicated Host規格列表。	ddh.g5
LockReason	string	否	Dedicated Host被鎖定的原因。取值範圍： financial：因欠費被鎖定。 security：因安全原因被鎖定。	financial
PageNumber	integer	否	說明該參數即將下線，推薦您使用 NextToken 與 MaxResults 完成分頁查詢操作。	1
PageSize	integer	否	說明該參數即將下線，推薦您使用 NextToken 與 MaxResults 完成分頁查詢操作。	10
ResourceGroupId	string	否	Dedicated Host所在資源群組 ID。使用該參數過濾資源時，資源數量不能超過 1000 個。說明不支援預設資源群組過濾。	rg-aek3b6jzp66****
Tag	array<object>	否	標籤列表。列表長度範圍：0~20。
	object	否
Key	string	否	Dedicated Host的標籤鍵。一旦傳入該值，則不允許為空白字串。最多支援 128 個字元，不能以`aliyun`和`acs:`開頭，不能包含`http://`或`https://`。	TestKey
Value	string	否	Dedicated Host的標籤值。一旦傳入該值，可以為空白字串。最多支援 128 個字元，不能包含`http://`或者`https://`。	TestValue
DedicatedHostClusterId	string	否	Dedicated Host叢集 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	Dedicated Host列表的頁碼。	5
TotalCount	integer	Dedicated Host總數。	3
NextToken	string	本次調用返回的查詢憑證（Token）。當使用 MaxResults 和 NextToken 方式進行分頁查詢，且該傳回值為空白時，表示無更多返回的資料資訊。	e71d8a535bd9cc11
DedicatedHosts	object
DedicatedHost	array<object>	Dedicated Host的詳細資料集合。
	array<object>	Dedicated Host所屬託管資源集區（Managed Private Space）ID。
CreationTime	string	Dedicated Host的建立時間。按照ISO 8601標準表示，並需要使用 UTC+0 時間，格式為`yyyy-MM-ddTHH:mmZ`。	2018-01-01T12:00Z
SchedulerOptions.ManagedPrivateSpaceId	string	Dedicated Host所屬託管資源集區（Managed Private Space）ID。	mps-iq81z6pkbqjx61php46e
Status	string	Dedicated Host的使用狀態。可能值： Available：運行中。Dedicated Host的正常運行狀態。 UnderAssessment：物理機風險，即故障潛伏期，其物理機處於可用狀態，但可能導致Dedicated Host中的 ECS 執行個體出現問題。 PermanentFailure：故障。永久性故障，Dedicated Host不可用。	Available
Cores	integer	單個 CPU 的核心數。	3
AutoPlacement	string	Dedicated Host是否加入自動部署資源集區。取值範圍： on：加入自動部署資源集區。 off：不加入自動部署資源集區。關於自動部署的更多資訊，請參見自動部署功能介紹。	on
GPUSpec	string	GPU 型號。	gpu
AutoReleaseTime	string	自動釋放時間。按照ISO 8601標準表示，並需要使用 UTC+0 時間，格式為`yyyy-MM-ddTHH:mmZ`。	2017-01-01T12:00Z
ChargeType	string	Dedicated Host的計費方式。	Prepaid
CpuOverCommitRatio	number	CPU 超賣比。取值範圍為：1~5。	1
ActionOnMaintenance	string	當Dedicated Host發生故障時，為其所宿執行個體設定遷移方案。取值範圍： Migrate：Dedicated Host整機遷移至另一物理伺服器，並對故障前非關機狀態的執行個體進行啟動。 Stop：在當前Dedicated Host上停止執行個體，確認無法修複Dedicated Host後，遷移執行個體到其他物理機並重新啟動執行個體。當Dedicated Host上掛載雲端硬碟儲存時，預設值為 Migrate；當Dedicated Host上掛載本地碟儲存時預設值為 Stop。	Migrate
SaleCycle	string	訂用帳戶單位。可能值： Month。 Year。	Month
PhysicalGpus	integer	物理 GPU 數量。	10
RegionId	string	Dedicated Host所在地區 ID。	cn-hangzhou
DedicatedHostName	string	Dedicated Host的名稱。	MyDDHTestName
Description	string	Dedicated Host的描述資訊。	this-is-my-DDH
DedicatedHostClusterId	string	Dedicated Host所在的Dedicated Host叢集 ID。	dc-bp12wlf6am0vz9v2****
ExpiredTime	string	訂用帳戶Dedicated Host的到期時間。按照ISO 8601標準表示，並需要使用 UTC+0 時間，格式為`yyyy-MM-ddTHH:mmZ`。	2019-01-01T12:00Z
DedicatedHostType	string	Dedicated Host的規格類型。	ddh.g5
ResourceGroupId	string	Dedicated Host所在資源群組 ID。	rg-aek3b6jzp66****
ZoneId	string	可用性區域 ID。	cn-hangzhou-g
DedicatedHostId	string	Dedicated Host ID。	dh-bp165p6xk2tlw61e****
Sockets	integer	物理處理器（CPU）數量。	5
MachineId	string	Dedicated Host機器碼。	12aaa123456ff19dec12345d3026e****
Instances	object
Instance	array<object>	Dedicated Host上建立的 ECS 執行個體列表。
	object	Dedicated Host上建立的 ECS 執行個體。
InstanceType	string	Dedicated Host上建立的 ECS 執行個體規格資訊。	ecs.g5.large
InstanceId	string	Dedicated Host上建立的 ECS 執行個體 ID。	i-bp14ot0ykf8w13a1****
SocketId	string	執行個體所處的 Socket 的序號。	0,1
InstanceOwnerId	integer	ECS 執行個體所有者的使用者識別碼。	128************0
OperationLocks	object
OperationLock	array<object>	Dedicated Host資源被鎖定原因列表。
	object
LockReason	string	Dedicated Host被鎖定的原因。可能值： financial：因欠費被鎖定。 security：因安全原因被鎖定。	financial
Tags	object
Tag	array<object>	Dedicated Host的標籤列表。
	object	標籤對資訊。
TagValue	string	Dedicated Host的標籤值。	TestValue
TagKey	string	Dedicated Host的標籤鍵。	TestKey
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	Dedicated Host支援的 ECS 執行個體規格類型系列列表。
	string	Dedicated Host支援的 ECS 執行個體規格類型系列。	ecs.g5
SupportedCustomInstanceTypeFamilies	object
SupportedCustomInstanceTypeFamily	array	Dedicated Host支援的自訂執行個體規格類型系列。
	string	Dedicated Host支援的自訂執行個體規格類型系列。	ecs.ddh6s.custom
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	Dedicated Host支援的 ECS 執行個體規格列表。
	string	Dedicated Host支援的 ECS 執行個體規格。	ecs.g5.large
Capacity	object	Dedicated Host效能指標集合。
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	Dedicated Host的網路屬性值。
UdpTimeout	integer	UDP 逾時時間。單位：S。當前僅支援 60S。	60
SlbUdpTimeout	integer	SLB UDP 逾時時間。單位：S。當前僅支援 60S。	60
HostDetailInfo	object	該參數即將被棄用，為提高相容性，建議您盡量使用其他參數。
SerialNumber	string	該參數即將被棄用，為提高相容性，建議您盡量使用其他參數。	null
DedicatedHostOwnerId	integer	Dedicated Host所有者的使用者識別碼。	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.	所指定的鎖定原因不存在

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。