DescribeDedicatedHosts - Elastic Compute Service

本介面用於查詢一台或多台專屬宿主機的詳細資訊。透過該介面，您可以獲取包括專屬宿主機的實體效能指標、機器碼、使用狀態以及已建立的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>	否	專屬宿主機詳細資訊。	false
	object	否
Key	string	否	專屬宿主機的標籤鍵。一旦傳入該值，則不允許為空字串。最多支援 128 個字元，不能以 `aliyun` 和 `acs:` 開頭，不能包含 `http://` 或 `https://`。	TestKey
Value	string	否	專屬宿主機的標籤值。一旦傳入該值，可以為空字串。最多支援 128 個字元，不能包含 `http://` 或者 `https://`。	TestValue
DedicatedHostClusterId	string	否	標籤列表。列表長度範圍：0~20。	dc-bp12wlf6am0vz9v2****
SocketDetails	string	否	專屬宿主機叢集 ID。	dc-bp12wlf6am0vz9v2****
NextToken	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
MaxResults	integer	否	查詢憑證（Token）。取值為上一次呼叫該介面返回的 NextToken 參數值，初次呼叫介面時無需設定該參數。	e71d8a535bd9cc11
QueryInventory	boolean	否	分頁查詢時每頁的最大項目數。一旦設定該參數，即表示使用 MaxResults 與 NextToken 組合參數的查詢方式。最大值為 100。預設值為 10。	10
		否

返回參數

名稱	類型	描述	樣本值
	object
DedicatedHosts	object
DedicatedHost	array<object>	專屬宿主機的詳細資訊集合。
	array<object>	專屬宿主機所屬託管資源池（Managed Private Space）ID。
ActionOnMaintenance	string	當專屬宿主機發生故障時，為其所託管執行個體設定遷移方案。取值範圍： Migrate：專屬宿主機整機遷移至另一實體伺服器，並對故障前非關機狀態的執行個體進行啟動。 Stop：在當前專屬宿主機上停止執行個體，確認無法修復專屬宿主機後，遷移執行個體到其他實體機並重新啟動執行個體。當專屬宿主機上掛載雲端硬碟儲存時，預設值為 Migrate；當專屬宿主機上掛載本機磁碟儲存時預設值為 Stop。	Migrate
AutoPlacement	string	專屬宿主機是否加入自動部署資源池。取值範圍： on：加入自動部署資源池。 off：不加入自動部署資源池。關於自動部署的更多資訊，請參見自動部署功能介紹。	on
AutoReleaseTime	string	自動釋放時間。按照ISO 8601標準表示，並需要使用 UTC+0 時間，格式為`yyyy-MM-ddTHH:mmZ`。	2017-01-01T12:00Z
Capacity	object	專屬宿主機效能指標集合。
AvailableInstanceTypes	object
AvailableInstanceType	array<object>	可用的執行個體規格資訊清單。
	object	可用的執行個體規格資訊。
AvailableInstanceCapacity	integer	可用的執行個體規格容量。
InstanceType	string	執行個體規格。取值請參見執行個體規格族。說明該參數為必選參數。
AvailableLocalStorage	integer	剩餘的本機磁碟容量。單位：GiB。	65
AvailableMemory	number	剩餘的記憶體容量，單位：GiB。	25
AvailableVcpus	integer	剩餘的 vCPU 核心數。	5
AvailableVgpus	integer	可用虛擬 GPU 數量。	2
LocalStorageCategory	string	本機磁碟類型。	i2
SocketCapacities	object
SocketCapacity	array<object>	Socket 維度容量資訊清單。
	object
AvailableMemory	number	剩餘記憶體容量，單位：GiB。	65
AvailableVcpu	integer	剩餘的 vCPU 核心數。	64
SocketId	integer	Socket 序號。	1
TotalMemory	number	記憶體總容量，單位：GiB。	128
TotalVcpu	integer	vCPU 總核心數。	128
TotalLocalStorage	integer	本機磁碟總容量，單位：GiB。	512
TotalMemory	number	記憶體總容量，單位：GiB。	1024
TotalVcpus	integer	vCPU 總核心數。	56
TotalVgpus	integer	總虛擬 GPU 數量。	10
ChargeType	string	專屬宿主機的計費方式。	Prepaid
Cores	integer	單個 CPU 的核心數。	3
CpuOverCommitRatio	number	CPU 超賣比。取值範圍為：1~5。	1
CreationTime	string	專屬宿主機的建立時間。按照ISO 8601標準表示，並需要使用 UTC+0 時間，格式為`yyyy-MM-ddTHH:mmZ`。	2018-01-01T12:00Z
DedicatedHostClusterId	string	專屬宿主機所在的專屬宿主機叢集 ID。	dc-bp12wlf6am0vz9v2****
DedicatedHostId	string	專屬宿主機 ID。	dh-bp165p6xk2tlw61e****
DedicatedHostName	string	專屬宿主機的名稱。	MyDDHTestName
DedicatedHostOwnerId	integer	專屬宿主機擁有者的使用者 ID。	100************7
DedicatedHostType	string	專屬宿主機的規格類型。	ddh.g5
Description	string	專屬宿主機的描述資訊。	this-is-my-DDH
ExpiredTime	string	包年包月專屬宿主機的到期時間。按照ISO 8601標準表示，並需要使用 UTC+0 時間，格式為`yyyy-MM-ddTHH:mmZ`。	2019-01-01T12:00Z
GPUSpec	string	GPU 型號。	gpu
HostDetailInfo	object	該參數即將被棄用，為提高相容性，建議您盡量使用其他參數。
SerialNumber	string	該參數即將被棄用，為提高相容性，建議您盡量使用其他參數。	null
VgpuVersion	string	該參數即將被棄用，為提高相容性，建議您盡量使用其他參數。	null
Instances	object
Instance	array<object>	專屬宿主機上建立的 ECS 執行個體清單。
	object	專屬宿主機上建立的 ECS 執行個體。
InstanceId	string	專屬宿主機上建立的 ECS 執行個體 ID。	i-bp14ot0ykf8w13a1****
InstanceOwnerId	integer	ECS 執行個體擁有者的使用者 ID。	128************0
InstanceType	string	專屬宿主機上建立的 ECS 執行個體規格資訊。	ecs.g5.large
SocketId	string	執行個體所處的 Socket 的序號。	0,1
MachineId	string	專屬宿主機機器碼。	12aaa123456ff19dec12345d3026e****
NetworkAttributes	object	專屬宿主機的網路屬性值。
SlbUdpTimeout	integer	SLB UDP 逾時時間。單位：S。當前僅支援 60S。	60
UdpTimeout	integer	UDP 逾時時間。單位：S。當前僅支援 60S。	60
OperationLocks	object
OperationLock	array<object>	專屬宿主機資源被鎖定原因清單。
	object
LockReason	string	專屬宿主機被鎖定的原因。可能值： financial：因欠費被鎖定。 security：因安全原因被鎖定。	financial
PhysicalGpus	integer	實體 GPU 數量。	10
RegionId	string	專屬宿主機所在地域 ID。	cn-hangzhou
ResourceGroupId	string	專屬宿主機所在資源群組 ID。	rg-aek3b6jzp66****
SaleCycle	string	包年包月單位。可能值： Month。 Year。	Month
SchedulerOptions.ManagedPrivateSpaceId	string	專屬宿主機所屬託管資源池（Managed Private Space）ID。	mps-iq81z6pkbqjx61php46e
Sockets	integer	實體處理器（CPU）數量。	5
Status	string	專屬宿主機的使用狀態。可能值： Available：執行中。專屬宿主機的正常執行狀態。 UnderAssessment：實體機風險，即故障潛伏期，其實體機處於可用狀態，但可能導致專屬宿主機中的 ECS 執行個體出現問題。 PermanentFailure：故障。永久性故障，專屬宿主機無法使用。	Available
SupportedCustomInstanceTypeFamilies	object
SupportedCustomInstanceTypeFamily	array	專屬宿主機支援的自訂執行個體規格族。
	string	專屬宿主機支援的自訂執行個體規格族。	ecs.ddh6s.custom
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	專屬宿主機支援的 ECS 執行個體規格族清單。
	string	專屬宿主機支援的 ECS 執行個體規格族。	ecs.g5
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	專屬宿主機支援的 ECS 執行個體規格清單。
	string	專屬宿主機支援的 ECS 執行個體規格。	ecs.g5.large
Tags	object
Tag	array<object>	專屬宿主機的標籤清單。
	object	標籤配對資訊。
TagKey	string	專屬宿主機的標籤鍵。	TestKey
TagValue	string	專屬宿主機的標籤值。	TestValue
ZoneId	string	可用區 ID。	cn-hangzhou-g
NextToken	string	本次呼叫返回的查詢憑證（Token）。當使用 MaxResults 和 NextToken 方式進行分頁查詢，且該返回值為空時，表示無更多返回的資料資訊。	e71d8a535bd9cc11
PageNumber	integer	專屬宿主機清單的頁碼。	5
PageSize	integer	輸入時設定的每頁列數。	1
RequestId	string	請求 ID。	7654525A-9964-4ABB-8BCD-98F8835E809A
TotalCount	integer	專屬宿主機總數。	3

樣本

正常返回樣本

JSON格式

{
  "DedicatedHosts": {
    "DedicatedHost": [
      {
        "ActionOnMaintenance": "Migrate",
        "AutoPlacement": "on",
        "AutoReleaseTime": "2017-01-01T12:00Z",
        "Capacity": {
          "AvailableInstanceTypes": {
            "AvailableInstanceType": [
              {
                "AvailableInstanceCapacity": 0,
                "InstanceType": ""
              }
            ]
          },
          "AvailableLocalStorage": 65,
          "AvailableMemory": 25,
          "AvailableVcpus": 5,
          "AvailableVgpus": 2,
          "LocalStorageCategory": "i2",
          "SocketCapacities": {
            "SocketCapacity": [
              {
                "AvailableMemory": 65,
                "AvailableVcpu": 64,
                "SocketId": 1,
                "TotalMemory": 128,
                "TotalVcpu": 128
              }
            ]
          },
          "TotalLocalStorage": 512,
          "TotalMemory": 1024,
          "TotalVcpus": 56,
          "TotalVgpus": 10
        },
        "ChargeType": "Prepaid",
        "Cores": 3,
        "CpuOverCommitRatio": 1,
        "CreationTime": "2018-01-01T12:00Z",
        "DedicatedHostClusterId": "dc-bp12wlf6am0vz9v2****",
        "DedicatedHostId": "dh-bp165p6xk2tlw61e****",
        "DedicatedHostName": "MyDDHTestName",
        "DedicatedHostOwnerId": 0,
        "DedicatedHostType": "ddh.g5",
        "Description": "this-is-my-DDH",
        "ExpiredTime": "2019-01-01T12:00Z",
        "GPUSpec": "gpu",
        "HostDetailInfo": {
          "SerialNumber": "null",
          "VgpuVersion": "null"
        },
        "Instances": {
          "Instance": [
            {
              "InstanceId": "i-bp14ot0ykf8w13a1****",
              "InstanceOwnerId": 0,
              "InstanceType": "ecs.g5.large",
              "SocketId": "0,1"
            }
          ]
        },
        "MachineId": "12aaa123456ff19dec12345d3026e****",
        "NetworkAttributes": {
          "SlbUdpTimeout": 60,
          "UdpTimeout": 60
        },
        "OperationLocks": {
          "OperationLock": [
            {
              "LockReason": "financial"
            }
          ]
        },
        "PhysicalGpus": 10,
        "RegionId": "cn-hangzhou",
        "ResourceGroupId": "rg-aek3b6jzp66****",
        "SaleCycle": "Month",
        "SchedulerOptions.ManagedPrivateSpaceId": "mps-iq81z6pkbqjx61php46e",
        "Sockets": 5,
        "Status": "Available",
        "SupportedCustomInstanceTypeFamilies": {
          "SupportedCustomInstanceTypeFamily": [
            "ecs.ddh6s.custom"
          ]
        },
        "SupportedInstanceTypeFamilies": {
          "SupportedInstanceTypeFamily": [
            "ecs.g5"
          ]
        },
        "SupportedInstanceTypesList": {
          "SupportedInstanceTypesList": [
            "ecs.g5.large"
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagKey": "TestKey",
              "TagValue": "TestValue"
            }
          ]
        },
        "ZoneId": "cn-hangzhou-g"
      }
    ]
  },
  "NextToken": "e71d8a535bd9cc11",
  "PageNumber": 5,
  "PageSize": 1,
  "RequestId": "7654525A-9964-4ABB-8BCD-98F8835E809A",
  "TotalCount": 3
}

錯誤碼

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.	指定的鎖定類型不存在。

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

變更歷史

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