# 获取主机信息 - DescribeUHostInstance

## 简介

获取主机或主机列表信息，并可根据数据中心，主机ID等参数进行过滤。





## 定义

### 公共参数

| 参数名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **Action**     | string  | 对应的 API 指令名称，当前 API 为 `DescribeUHostInstance`                        | **Yes** |
| **PublicKey**  | string  | 用户公钥，可从 [控制台](https://console.sigcalcloud.com/uaccount/api_manage) 获取                                             | **Yes** |
| **Signature**  | string  | 根据公钥及 API 指令生成的用户签名，参见 [签名算法](/docs/api/summary/signature.md)  | **Yes** |

### 请求参数

| 参数名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **Region** | string | 地域。 参见 [地域和可用区列表](/docs/api/summary/regionlist) |**Yes**|
| **Zone** | string | 可用区。参见 [可用区列表](/docs/api/summary/regionlist) |No|
| **ProjectId** | string | 项目ID。不填写为默认项目，子帐号必须填写。 请参考[GetProjectList接口](/docs/api/summary/get_project_list) |No|
| **UHostIds.N** | string | 【数组】UHost主机的资源ID，例如UHostIds.0代表希望获取信息 的主机1，UHostIds.1代表主机2。 如果不传入，则返回当前Region 所有符合条件的UHost实例。 |No|
| **Tag** | string | 要查询的业务组名称 |No|
| **Offset** | int | 列表起始位置偏移量，默认为0 |No|
| **Limit** | int | 返回数据长度，默认为20，最大100 |No|
| **IsolationGroup** | string | 硬件隔离组id。通过硬件隔离组筛选主机。 |No|
| **VPCId** | string | vpc id。通过VPC筛选主机。北京一地域无效。 |No|
| **SubnetId** | string | 子网id。通过子网筛选主机。北京一地域无效。 |No|
| **UDiskIdForAttachment** | string | 要挂载的云盘id，过滤返回能被UDiskId挂载的云主机。目前主要针对rssd云盘使用 |No|

### 响应字段

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **RetCode** | int | 返回状态码，为 0 则为成功返回，非 0 为失败 |**Yes**|
| **Action** | string | 操作指令名称 |**Yes**|
| **Message** | string | 返回错误消息，当 `RetCode` 非 0 时提供详细的描述信息 |No|
| **TotalCount** | int | UHostInstance总数 |**Yes**|
| **UHostSet** | array[[*UHostInstanceSet*](#UHostInstanceSet)] | 云主机实例列表，每项参数可见下面 UHostInstanceSet |**Yes**|

#### 数据模型


#### UHostInstanceSet

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **Zone** | string | 可用区。参见 [可用区列表](api/summary/regionlist) |No|
| **UHostId** | string | UHost实例ID |No|
| **UHostType** | string | 【建议不再使用】云主机机型（旧）。参考[云主机机型说明](api/uhost-api/uhost_type)。 |No|
| **MachineType** | string | 云主机机型（新）。参考[云主机机型说明](api/uhost-api/uhost_type#主机概念20版本)。 |No|
| **CpuPlatform** | string | 云主机CPU平台。参考[云主机机型说明](api/uhost-api/uhost_type#主机概念20版本)。 |No|
| **UHostFamily** | string | 规格族。 由机型代号和 CPU 平台组成，用于指定云主机的硬件类型与处理器平台。 当 MachineType 为 "O"（快杰型）时，支持以下取值： - o1i：快杰型 O1 代，Intel 平台 - o1a：快杰型 O1 代，AMD 平台 - o1r：快杰型 O1 代，ARM 平台 - o2i：快杰型 O2 代，Intel 平台 默认值：o1i 或 o1a或o1r（系统将根据资源情况自动选择） 当 MachineType 为 "OM"（快杰共享型）时，支持以下取值： - om1i：快杰内存增强型 OM1 代，Intel 平台 - om2i：快杰内存增强型 OM2 代，Intel 平台  |No|
| **StorageType** | string | 【建议不再使用】主机磁盘类型。 枚举值为：<br /><br /> > LocalDisk，本地磁盘; <br /><br /> > UDisk 云盘。<br /><br />只要有一块磁盘为本地盘，即返回LocalDisk。 |No|
| **ImageId** | string | 【建议不再使用】主机的系统盘ID。 |No|
| **BasicImageId** | string | 基础镜像ID（指当前自定义镜像的来源镜像） |No|
| **BasicImageName** | string | 基础镜像名称（指当前自定义镜像的来源镜像） |No|
| **Tag** | string | 业务组名称 |No|
| **Remark** | string | 备注 |No|
| **Name** | string | UHost实例名称 |No|
| **State** | string | 实例状态，枚举值：<br /><br /> >初始化: Initializing; <br /><br /> >启动中: Starting; <br /><br />> 运行中: Running; <br /><br />> 关机中: Stopping; <br /><br /> >关机: Stopped <br /><br /> >安装失败: Install Fail; <br /><br /> >重启中: Rebooting; <br /><br /> > 未知(空字符串，获取状态超时或出错)："" |No|
| **CreateTime** | int | 创建时间，格式为Unix时间戳 |No|
| **ChargeType** | string | 计费模式，枚举值为： Year，按年付费； Month，按月付费； Dynamic，按需付费（需开启权限）；Preemptive 为抢占式实例； |No|
| **ExpireTime** | int | 到期时间，格式为Unix时间戳 |No|
| **CPU** | int | 虚拟CPU核数，单位: 个 |No|
| **Memory** | int | 内存大小，单位: MB |No|
| **AutoRenew** | string | 是否自动续费，自动续费：“Yes”，不自动续费：“No” |No|
| **DiskSet** | array[[*UHostDiskSet*](#UHostDiskSet)] | 磁盘信息见 UHostDiskSet |No|
| **IPSet** | array[[*UHostIPSet*](#UHostIPSet)] | 详细信息见 UHostIPSet |No|
| **NetCapability** | string | 网络增强。Normal: 无；Super： 网络增强1.0； Ultra: 网络增强2.0 |No|
| **NetworkState** | string | 【建议不再使用】网络状态。 连接：Connected， 断开：NotConnected |No|
| **TimemachineFeature** | string | 【建议不再使用】数据方舟模式。枚举值：<br /><br /> > Yes: 开启方舟； <br /><br /> > no，未开启方舟 |No|
| **SubnetType** | string | 【建议不再使用】仅北京A的云主机会返回此字段。基础网络模式：Default；子网模式：Private |No|
| **OsName** | string | 创建主机的最初来源镜像的操作系统名称（若直接通过基础镜像创建，此处返回和BasicImageName一致） |No|
| **OsType** | string | 操作系统类别。返回"Linux"或者"Windows" |No|
| **HostType** | string | 【建议不再使用】主机系列：N2，表示系列2；N1，表示系列1 |No|
| **LifeCycle** | string | 主机的生命周期类型。目前仅支持Normal：普通； |No|
| **GPU** | int | GPU个数 |No|
| **GpuType** | string | GPU类型;枚举值["K80", "P40", "V100", "T4","T4A", "T4S","2080Ti","2080Ti-4C","1080Ti", "T4/4", "MI100", "V100S",2080","2080TiS","2080TiPro","3090","4090","4090Pro","A100","A800","H20"] |No|
| **HotPlugMaxCpu** | int | 热升级支持的最大CPU个数 |No|
| **BootDiskState** | string | 系统盘状态 Normal表示初始化完成；Initializing表示在初始化。仍在初始化的系统盘无法制作镜像。 |No|
| **TotalDiskSpace** | int | 总的数据盘存储空间。 |No|
| **IsolationGroup** | string | 隔离组id，不在隔离组则返回"" |No|
| **RdmaClusterId** | string | RDMA集群id，仅快杰云主机返回该值；其他类型云主机返回""。当云主机的此值与RSSD云盘的RdmaClusterId相同时，RSSD可以挂载到这台云主机。 |No|
| **RestrictMode** | string | 仅抢占式实例返回，LowSpeed为低速模式，PowerOff为关机模式 |No|
| **HotplugFeature** | boolean | true: 开启热升级； false，未开启热升级 |No|
| **CloudInitFeature** | boolean | true: 支持cloutinit方式初始化；false: 不支持 |No|
| **IPv6Feature** | boolean | true: 有ipv6特性；false，没有ipv6特性 |No|
| **HpcFeature** | boolean | true: 开启 hpc 系列功能；false: 未开启 |No|
| **EpcInstance** | boolean | true: 高性能计算主机；false: 不是 |No|
| **SecGroupInstance** | boolean | 【待废弃】true: 绑定了安全组的主机；false: 不是 |No|
| **NetFeatureTag** | string | Firewall:防火墙,SecGroup:安全组,Acl:acl |No|
| **HiddenKvm** | boolean | true: 开启 hidden kvm 功能；false: 不是 |No|
| **KeyPair** | [*UHostKeyPair*](#UHostKeyPair) | 密钥信息见 UHostKeyPair |No|
| **UDHostAttribute** | [*UDSetUDHostAttribute*](#UDSetUDHostAttribute) | 私有专区宿主机属性 |No|
| **SpotAttribute** | [*SpotAttribute*](#SpotAttribute) | 竞价实例信息 |No|

#### UHostDiskSet

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **DiskType** | string | 磁盘类型。请参考[磁盘类型](api/uhost-api/disk_type)。 |**Yes**|
| **IsBoot** | string | 是否是系统盘。枚举值：<br /><br /> > True，是系统盘 <br /><br /> > False，是数据盘（默认）。Disks数组中有且只能有一块盘是系统盘。 |**Yes**|
| **Encrypted** | string | "true": 加密盘 "false"：非加密盘 |No|
| **Type** | string | 【建议不再使用】磁盘类型。系统盘: Boot，数据盘: Data,网络盘：Udisk |No|
| **DiskId** | string | 磁盘ID |No|
| **Name** | string | UDisk名字（仅当磁盘是UDisk时返回） |No|
| **Drive** | string | 磁盘盘符 |No|
| **Size** | int | 磁盘大小，单位: GB |No|
| **BackupType** | string | 备份方案。若开通了数据方舟，则为DATAARK |No|

#### UHostIPSet

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **IPMode** | string | IPv4/IPv6； |**Yes**|
| **Default** | string | 内网 Private 类型下，表示是否为默认网卡。true: 是默认网卡；其他值：不是。 |No|
| **Mac** | string | 内网 Private 类型下，当前网卡的Mac。 |No|
| **Weight** | int | 当前EIP的权重。权重最大的为当前的出口IP。 |No|
| **Type** | string | 国际: Internation，BGP: Bgp，内网: Private |No|
| **IPId** | string | 外网IP资源ID 。(内网IP无对应的资源ID) |No|
| **IP** | string | IP地址 |No|
| **Bandwidth** | int | IP对应的带宽, 单位: Mb  (内网IP不显示带宽信息) |No|
| **VPCId** | string | IP地址对应的VPC ID。（北京一不支持，字段返回为空） |No|
| **SubnetId** | string | IP地址对应的子网 ID。（北京一不支持，字段返回为空） |No|
| **NetworkInterfaceId** | string | 弹性网卡为默认网卡时，返回对应的 ID 值 |No|

#### UHostKeyPair

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **KeyPairId** | string | 密钥对ID |No|
| **KeyPairState** | string | 主机密钥对状态，Normal 正常，Deleted 删除 |No|

#### UDSetUDHostAttribute

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **UDHostId** | string | 私有专区宿主机 |No|
| **UDSetId** | string | 私有专区 |No|
| **HostBinding** | boolean | 是否绑定私有专区宿主机 |No|

#### SpotAttribute

| 字段名 | 类型 | 描述信息 | 必填 |
|:---|:---|:---|:---|
| **RecycleTime** | int | 回收时间 |No|

## 示例

### 请求示例
    
```
https://api.sigcalcloud.com/?Action=DescribeUHostInstance
&Region=cn-zj
&Zone=cn-zj-01
&ProjectId=jrdYPkBQ
&UHostIds.N=AUNsCFMm
&Tag=DorQZLay
&LifeCycle=6
&Offset=6
&Limit=3
&IsolationGroup=nSNImHzi
&VPCId=FPnJyAyj
&SubnetId=HLhfwaFY
&NoEIP=false
&ResourceType=ghgUBbcV
&UDiskIdForAttachment=UQmrMUGU
&EpcInstance=true
```

### 响应示例
    
```json
{
  "Action": "DescribeUHostInstanceResponse",
  "RetCode": 0,
  "TotalCount": 2,
  "UHostSet": [
    {
      "AutoRenew": "qSWETQza",
      "BasicImageId": "GCiPFJNV",
      "BasicImageName": "AilAICpK",
      "BootDiskState": "wvOqKxrL",
      "CPU": 1,
      "ChargeType": "eeXICSgb",
      "CloudInitFeature": true,
      "CpuPlatform": "aZLBvEiZ",
      "CreateTime": 2,
      "DiskSet": [
        {
          "BackupType": "wThaZMBG",
          "DiskId": "HGkYYGPC",
          "DiskType": "thFULWJN",
          "Drive": "eFKaOPGI",
          "Encrypted": "TTUcGitp",
          "IsBoot": "uYTOToOh",
          "Name": "AIFttSSZ",
          "Size": 9,
          "Type": "JJZViwCZ"
        }
      ],
      "EpcInstance": true,
      "ExpireTime": 4,
      "GPU": 4,
      "GpuType": "pJdSxKkv",
      "HiddenKvm": false,
      "HostType": "dQanjRcq",
      "HotplugFeature": true,
      "HpcFeature": false,
      "IPSet": [
        {
          "Bandwidth": 2,
          "Default": "PemrNWxq",
          "IP": "hGoWLqyN",
          "IPId": "qBthvXCJ",
          "SubnetId": "owZpgAju",
          "Type": "TBHMANhj",
          "VPCId": "KRvUYRsX"
        }
      ],
      "IPv6Feature": true,
      "ImageId": "laKdatME",
      "IsolationGroup": "uUbVSIFS",
      "KeyPair": {},
      "LifeCycle": "wtcCMMQT",
      "MachineType": "PyCWLFIG",
      "Memory": 9,
      "Name": "gsILwqks",
      "NetCapability": "txhhItss",
      "NetworkState": "jquNUNJz",
      "OsName": "QHGtNxIw",
      "OsType": "CnavCvrW",
      "RdmaClusterId": "TqrHYSXc",
      "Remark": "MxEcJQhA",
      "RestrictMode": "EeJHESCx",
      "SecGroupInstance": false,
      "State": "UtnhXfCa",
      "StorageType": "tEDwzsXb",
      "SubnetType": "ZSfByswJ",
      "Tag": "GbFHtrBQ",
      "TimemachineFeature": "tZqkqfws",
      "TotalDiskSpace": 3,
      "UHostId": "qPzuUUCE",
      "UHostType": "QaByhkja",
      "Zone": "CiMUTSzW"
    }
  ]
}
```