You need to enable JavaScript to run this app.
导航

DescribeInstances

最近更新时间2024.03.25 19:47:40

首次发布时间2021.07.31 07:48:16

调用 DescribeInstances 接口查询实例信息。

说明

调用该接口时,使用TagFilters.N.KeyTagFilters.N.Values.N查询到的实例数量不能超过1000个。若超过1000个,请使用DesribeTags接口进行查询。

调试

请求参数

名称类型是否必填
示例值
描述
ActionStringDescribeInstances要执行的操作,取值:DescribeInstances。
VersionString2020-04-01API的版本,取值:2020-04-01。
InstanceIds.NString
InstanceIds.1=i-3ti9101aju3vj0******&InstanceIds.2= i-3tiegs1y963vj0******
实例ID,最多支持100个ID。
  • 参数 - N:表示实例的序号。
  • 多个Instance ID之间用&分隔。
  • InstanceNameStringinstance-test实例的名称,支持关键字模糊查询。
    ZoneIdStringcn-beijing-a实例所属可用区ID。您可以调用DescribeZones查询一个地域下的可用区信息。
    VpcIdStringvpc-3thbinq64t4bwb******私有网络ID。您可以调用DescribeVpcs查询满足条件的私有网络。
    StatusStringRUNNING实例的状态,取值:
  • CREATING:创建中
  • RUNNING:运行中
  • STOPPING:停止中
  • STOPPED:已停止
  • REBOOTING: 重启中
  • STARTING:启动中
  • REBUILDING:重装中
  • RESIZING:更配中
  • ERROR:错误
  • DELETING:删除中
  • PrimaryIpAddressString172.16.XX.XX实例的私网IP地址,例如主网卡或辅助网卡IP地址。
    NextTokenString-分页查询凭证,用于标记分页的位置,初次调用该接口时无需设置。下次查询时,取值为上一次API调用返回的NextToken参数值。
    MaxResultsInteger10分页查询时设置的每页行数。
  • 最大值:100
  • 默认值:10
  • HpcClusterIdStringhpcCluster-3tean8ni5m3vj0******当查询高性能计算GPU型实例时,可以指定高性能计算集群ID。
    KeyPairNameStringkp-test-123密钥对的名称。
    InstanceChargeTypeStringPostPaid实例的计费方式,取值:
  • PostPaid:按量计费
  • PrePaid:包年包月
  • InstanceTypeIds.N

    String

    InstanceTypeIds.1=ecs.g2i.2xlarge&InstanceTypeIds.2=ecs.c2i.2xlarge

    根据规格过滤实例,最多支持100个实例规格。

    • 参数 - N:表示实例的序号。
    • 多个实例规格之间用&分隔。

    InstanceTypeFamilies.N

    String

    InstanceTypeFamilies.1=ecs.g2i&InstanceTypeFamilies.2=ecs.c2i

    根据规格族过滤实例,最多支持100个实例规格族。

    • 参数 - N:表示实例的序号。
    • 多个实例规格族之间用&分隔。

    ProjectName

    String

    project_a

    资源所属项目,一个资源只能归属于一个项目。

    • 只能包含字母、数字、下划线“_”、点“.”和中划线“-”。
    • 长度限制在64个字符以内。

    TagFilters.N.Key

    String

    TagFilters.1.Key=k1

    根据标签查询资源时指定的标签键。

    • 参数 - N:表示标签键的序号,取值范围:1~10。
    • 多个标签键之间用&分隔。
    • 不允许重复。

    TagFilters.N.Values.N

    String

    TagFilters.1.Values.1=v1&TagFilters.1.Values.2=v2

    根据标签查询资源时指定的标签值。

    • 第一个N:表示标签键的序号,取值范围:1~10。
    • 第二个N:表示标签值的序号,取值范围:1~3,即同一标签键最多支持同时查询3个标签值。
    • 多个标签值之间用&分隔。

    说明

    • 如果传入该参数,则必须先传入TagFilters.N.Key
    • 不传则表示查询同一标签键下的所有标签值。
    • 传入空字符串时,表示查询标签值为空的标签。

    DeploymentSetIds.N

    String

    DeploymentSetIds.1=dps-yc1o9aahks5m57nk****&DeploymentSetIds.2=dps-ybr1vulgy87grbt6****

    使用部署集ID,查询对应部署集内的实例。

    • 参数 - N:表示部署集的序号,取值范围:1~100。

    • 多个 DeploymentSetId之间用&分隔。

    DeploymentSetGroupNumbers.N

    String

    DeploymentSetGroupNumbers.1=1&DeploymentSetGroupNumbers.2=2

    使用部署集组号,查询对应部署集组内的实例。

    • 参数 - N:表示部署集组的序号,取值范围:1~3。

    • 多个DeploymentSetGroupNumber之间用&分隔。

    说明

    部署集组高可用策略正在邀测中,如需试用,请提交工单或联系客户经理申请。

    DedicatedHostIdStringdh-3tigy72q3u3vj0x2****专有宿主机ID。您可以调用DescribeDedicatedHosts接口查询专有宿主机列表。
    DedicatedHostClusterIdStringdc-ycle6b76kgv2wrsm****专有宿主机集群ID。您可以调用DescribeDedicatedHostClusters接口查询宿主机集群ID。

    ScheduledInstanceId

    String

    esi-ycmfqs85zrm0tqlp****

    弹性预约单ID。您可以调用DescribeScheduledInstances接口查询弹性预约单ID。

    说明

    弹性预约实例正在邀测中,如需试用,请提交工单或联系客户经理申请。

    EipAddresses.N

    String

    EipAddresses.1=12.XX.XX.89&EipAddresses.2=12.XX.XX.35

    公网IP地址,最多支持100个。您可以调用DescribeEipAddresses接口查询公网IP地址。

    • 参数 - N:表示公网IP地址的序号。

    • 多个公网IP的IP地址之间用&分隔。

    返回数据

    名称类型示例值
    描述
    InstancesArray of Struct-符合条件的实例信息。具体请参见下表 “ Instances 结构 ”。
    NextTokenStringbHpwdXJja2RxemU1eG5sb3NzdGcW1-RCEq******本次调用返回的查询凭证值,返回为空表示没有下一页。

    Instances 结构

    名称类型示例值
    描述
    CreatedAtString2021-06-28T18:29:38+08:00创建时间。
    UpdatedAtString2021-06-29T18:11:46+08:00更新时间。
    InstanceIdStringi-3ti9101aju3vj0******实例ID。
    ZoneIdStringcn-beijing-a可用区ID。
    ImageIdStringimage-3tefr6wgx63vj0******镜像ID。
    StatusStringRUNNING实例的状态。
    InstanceNameStringinstance-test实例名称。
    DescriptionString用于测试的云服务器实例实例描述。
    HostnameStringinstance-host-name实例主机名。
    VpcIdStringvpc-3thbinq64t4bwb******私有网络ID。
    InstanceTypeIdStringecs.c2i.xlarge实例规格ID。
    CpusInteger4CPU数量。
    MemorySizeInteger32768内存大小,单位:MiB。
    OsNameStringCentOS 7.6 64位镜像操作系统的名称。

    OsType

    String

    Linux

    操作系统类型,取值:

    • Linux
    • Windows
    NetworkInterfacesArray of Struct-实例挂载的网卡信息。具体请参见下表“ NetworkInterfaces 结构 ”。
    RdmaIpAddressesList["198.18.xx.xx","198.18.xx.xx"]当查询高性能计算GPU型实例时,列表形式返回各网卡的RDMA IP地址。
    KeyPairNameStringkp-test-123密钥对名称。
    KeyPairIdStringkp-3tgh3ifp8j44kd******密钥对ID。

    SpotStrategy

    String

    NoSpot

    按量计费的抢占式策略,取值:

    • NoSpot(默认):正常按量计费实例。

    • SpotAsPriceGo:系统自动出价,跟随当前市场实际价格的抢占式实例。

    • SpotWithPriceLimit:设置出价上限的抢占式实例。

    SpotPriceLimit

    Float32

    0.78

    抢占式实例的每小时最高价格,支持最大3位小数。

    说明

    仅当SpotStrategy=SpotWithPriceLimit时,返回该参数。

    DeploymentSetIdStringdps-yc1o9aahks5m57nk****实例所属部署集ID。
    DeploymentSetGroupNumberInteger2部署集组序号。

    StoppedMode

    String

    KeepCharging

    实例是否启用了节省停机功能,取值:

    • KeepCharging:普通停机模式,停机后继续收费,且为您保留相关资源。

    • StopCharging:节省停机模式。

      • 节省停机功能正在邀测中,如需试用,请提交工单或联系客户经理申请。

      • 仅部分实例支持节省停机模式,详情请参见节省停机模式说明

      • 停机后,将释放vCPU、内存等计算资源;所挂载的云盘、公网IP和带宽(固定带宽模式)将被保留并继续计费。

      • 停机后再次启动实例,将重新创建vCPU、内存等资源,如果实例所在地域库存不足,将启动失败。

      • 私网IP地址及实例停机前已绑定的公网IP地址,在实例重启后仍保持不变。

    • NotApplicable:表示本实例不支持节省停机功能。

    InstanceChargeTypeStringPostPaid实例的计费方式,取值:
  • PostPaid:按量计费
  • PrePaid:包年包月
  • ExpiredAtString2200-01-01T00:00:00+08:00实例的过期时间,仅InstanceChargeType=PrePaid时返回。
    UuidString4f35e8f7-f549-5c55-9531-5f43ca78****实例的唯一标识符,该信息不随实例状态而改变。
    EipAddressStruct-实例绑定的公网IP地址列表,具体请参见下表“ EipAddress 结构
    LocalVolumesArray of Struct-实例对应的本地盘配置信息,具体请参见下表“ LocalVolumes 结构 ”。
    ProjectNameStringproject_a资源所属项目。
    CpuOptionsStruct-CPU配置详情,具体请参见下表“ CpuOptions 结构 ”。
    TagsArray of Struct-资源的标签信息,具体请参见下表“ Tags 结构 ”。
    PlacementStruct-专有宿主机实例信息,具体请参见下表“ Placement 结构 ”。

    ElasticScheduledInstanceType

    String

    NoEsi

    弹性预约实例类型,取值:

    • NoEsi:非弹性预约实例。

    • Esi:弹性预约实例。

    • Segmented:弹性预约实例-时段型。

    ScheduledInstanceIdStringesi-ycmfqs85zrm0tqlp****弹性预约单ID。

    NetworkInterfaces 结构

    名称类型示例值
    描述
    NetworkInterfaceIdStringeni-3tiu4lmhwq4e8i******网卡ID。
    VpcIdStringvpc-3thbinq64t4bwb******私有网络ID。
    SubnetIdStringsubnet-3tisodmzai4e8i******子网ID。
    PrimaryIpAddressString172.16.xx.xx私网IP地址。
    TypeStringprimary网卡属性,取值:
  • primary:主网卡
  • secondary:辅助网卡
  • MacAddressString00:16:3e:5b:** :**MAC地址。

    EipAddress 结构

    名称类型示例值描述
    AllocationIdStringeip-2749d8a20h4hs7fap8taa****公网IP的ID。
    IpAddressString101.126.XX.XX公网IP地址。

    LocalVolumes 结构

    名称类型示例值描述

    VolumeType

    String

    LOCAL_SSD

    本地盘类型,取值:

    • LOCAL_SSD:SSD本地盘
    • LOCAL_HDD:HDD本地盘
    SizeInteger200实例挂载的本地盘的单盘容量,单位GiB。
    CountInteger4实例挂载的本地盘数量。

    CpuOptions 结构

    名称类型示例值描述
    CoreCountInteger4CPU物理核心数。

    ThreadsPerCore

    Integer

    2

    CPU每核线程数,表示CPU是否开启超线程。
    取值:

    • 1:关闭超线程
    • 2:打开超线程

    vCPU数量=CPU物理核心数*每核线程数

    Tags 结构

    名称类型示例值描述
    KeyStringk1实例的标签键。
    ValueStringv1实例的标签值。

    Placement 结构

    名称类型示例值描述

    Affinity

    String

    Default

    专有宿主机实例是否与专有宿主机关联,取值:

    • Default(默认):不关联专有宿主机。启用节省停机模式的实例重新启动时,若原专有宿主机资源不足,可迁移至自动部署资源池中的其它专有宿主机上。

    • Host:关联专有宿主机。启用节省停机模式的实例重新启动时,仍会部署在原宿主机上。

    DedicatedHostId

    String

    dh-bp67acfmxazb4p****

    实例所在的专有宿主机ID。

    Tenancy

    String

    Default

    是否在专有宿主机上创建实例,取值:

    • Default(默认):创建普通云服务器实例。

    • Host:创建专有宿主机实例。若您不指定DedicatedHostId,则由系统自动选择专有宿主机放置实例。

    DedicatedHostClusterIdStringdc-ycle6b76kgv2wrsm****实例所在的专有宿主机集群ID。

    请求示例

    GET /?Action=DescribeInstances&Version=2020-04-01&InstanceIds.1=i-3ti9101aju3vj0****** HTTP/1.1
    Host: open.volcengineapi.com
    Region: cn-beijing
    Service: ecs
    

    返回示例

    {
        "ResponseMetadata": {
            "RequestId": "2021110417394001022514606307D7****",
            "Action": "DescribeInstances",
            "Version": "2020-04-01",
            "Service": "ecs",
            "Region": "cn-beijing"
        },
        "Result": {
            "Instances": [{
                "CreatedAt": "2021-06-28T18:29:38+08:00",
                "UpdatedAt": "2021-06-29T18:11:46+08:00",
                "InstanceId": "i-3tiegs1y963vj0x0****",
                "ZoneId": "cn-beijing-a",
                "ImageId": "image-3ti94y52ui3vj0wt****",
                "Status": "RUNNING",
                "InstanceName": "sh-testh",
                "Description": "API-create",
                "Hostname": "sh",
                "VpcId": "vpc-3thwbkvycq3vj0x2****",
                "InstanceTypeId": "ecs.c2i.xlarge",
                "Cpus": 4,
                "MemorySize": 8192,
                "OsName": "Windows Server 2012 R2 Datacenter Edition 64-bit Chinese",
                "OsType": "Windows",
                "NetworkInterfaces": [{
                        "NetworkInterfaceId": "eni-3tirof3ove3vj0x1****",
                        "VpcId": "vpc-3thwbkvycq3vj0x2****",
                        "SubnetId": "subnet-3thwbl2z6y3vj0x2****",
                        "PrimaryIpAddress": "192.168.**.**",
                        "Type": "primary",
                        "MacAddress": "00:16:3e:79:**:**"
                    },
                    {
                        "NetworkInterfaceId": "eni-3ti7147rmy3vj0wt****",
                        "VpcId": "vpc-3thwbkvycq3vj0x2****",
                        "SubnetId": "subnet-3thwbl2z6y3vj0x2****",
                        "PrimaryIpAddress": "192.168.**.**",
                        "Type": "secondary",
                        "MacAddress": "00:16:3e:22:**:**"
                    }
                ],
                "RdmaIpAddresses": [],
                "KeyPairName": "",
                "KeyPairId": "kp-ybqcopwrdwl8j1******",
                "InstanceChargeType": "PostPaid",
                "StoppedMode": "KeepCharging",
                "SpotStrategy": "NoSpot",
                "DeploymentSetId": "dps-yc1o9aahks5m57nk****",           
                "EipAddress": {
                    "AllocationId": "eip-2749d8a20h4hs7fap8taa****",
                    "IpAddress": "101.126.XX.XX"
                    },
                "ExpiredAt": "",
                "Uuid": "4f35e8f7-f549-5c55-9531-5f43ca78****",
                "LocalVolumes": [], 
                "ElasticScheduledInstanceType": "NoEsi",            
                "Tags": [ 
                    {
                        "Key": "k1",
                        "Value": "v1"
                    }
                ],
                "CpuOptions": {
                    "CoreCount": "2",
                    "ThreadsPerCore": "2"
                }
            ],    
            "NextToken": ""
        }
    }
    

    错误码

    HttpCode错误码错误信息描述
    400InvalidArgumentThe specified argument is invalid.指定的参数不合法。
    400LimitExceeded.MaximumInstanceIdsYou've reached the limit on the number of InstanceIds that you can set.指定的InstanceIds数量超过最大限制。
    400
    LimitExceeded.MaximumInstanceTypeFamilies
    You've reached the limit on the number of InstanceTypeFamilies that you can set.指定的InstanceTypeFamilies数量超过最大限制。

    400

    LimitExceeded.MaximumInstanceTypeIds

    You've reached the limit on the number of InstanceTypeIds that you can set.

    指定的InstanceTypeIds数量超过最大限制。

    400

    LimitExceeded.MaximumTagFilterKeys

    You've reached the limit on the number of TagFilterKeys that you can set.

    指定的标签键超过最大限制。

    400

    LimitExceeded.MaximumTagFilterValues

    You've reached the limit on the number of TagFilterValues that you can set.

    指定的标签值超过最大限制。

    400InvalidTagFilterKey.MalformedThe specified TagFilterKey is malformed.指定的标签键不合法。
    400InvalidTagFilterValue.MalformedThe specified TagFilterValue is malformed.指定的标签值不合法。

    400

    LimitExceeded.MaximumTagFilterResults

    You've reached the limit on the number of resources that you can describe by TagFilters.

    通过标签过滤出的资源数量超过上限。

    400LimitExceeded.MaximumDeploymentSetIdsYou've reached the limit on the number of DeploymentSetIds that you can set.指定的部署集数量超过最大限制。

    400

    LimitExceeded.MaximumDeploymentSetGroupNumbers

    You've reached the limit on the number of DeploymentSetGroupNumbers that you can set.

    指定的部署集组数量超过最大限制。

    400LimitExceeded.MaximumEipAddressesThe number of specified EipAddresses exceeds the maximum limit.指定的EipAddresses超过最大限制。

    400

    LimitExceeded.PrimaryIpAddresses

    You've reached the limit on the number of PrimaryIpAddresses that you can set.

    指定的私网IP地址超过最大限制。

    409

    InvalidTagFilterKey.Conflict

    The specified TagFilterKey already exists.

    指定的标签键已存在。

    429

    FlowLimitExceeded

    You've reach the limit on request rate of resources.

    您已超过资源请求限速。

    500InternalErrorAn internal error has occurred.内部错误,请重试。如果多次尝试失败,请提交工单。