DescribeInstances - ENS - Alibaba Cloud Documentation Center

Queries the details of one or more Edge Node Service (ENS) instances.

Operation description

You can call this operation up to 800 times per second per account.
You can call this operation up to 100 times per second per user.
You can specify multiple request parameters to be queried. Specified parameters are evaluated by using the AND operator. Only the specified parameters are included in the filter conditions. However, if InstanceIds is set to an empty JSON array, it is regarded as a valid filter condition and an empty result is returned.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
ens:DescribeInstances	list	Instance `acs:ens::{#accountId}:instance/{#InstanceId}`	none	none

Request parameters

Parameter	Type	Required	Description	Example
EnsRegionId	string	No	The region ID.	cn-beijing-cmcc
InstanceId	string	No	The ID of the instance.	i-5iqczfxps7csjrxeca****
EnsRegionIds	string	No	The IDs of the regions. The value is a JSON array that consists of up to 100 IDs. Separate multiple IDs with commas (,).	["cn-suzhou-telecom","cn-chengdu-telecom"]
InstanceIds	string	No	The IDs of the instances. The value is a JSON array that consists of up to 100 IDs. Separate IDs with commas (,).	["i-5iqczfxps7csjrxeca07**", "i-5iqczfxps7csjrxeca07**"]]
InstanceName	string	No	The name of the instance.	TestName
ImageId	string	No	The ID of the image.	centos_6_08_64_20G_alibase_****
PageNumber	integer	No	The page number. Pages start from page 1. Default value: 1.	1
PageSize	string	No	The number of entries to return on each page. The maximum value is 100. Default value: 10.	10
Status	string	No	The status of the instance. Valid values: Running Stopped Expired	Running
OrderByParams	string	No	The method that you want to use to sort instances. The value of this parameter is in the JSON format. You can sort instances by name, expiration time, node ID, or creation time. You can specify one or more methods.	{"InstanceNameSort":"asc","ExpireTimeSort":"asc","CreationTimeSort":"desc"}}
EnsServiceId	string	No	The ID of the edge service. You can use the ID to query information about the instances that are created in the edge service.	ens-20190730202316s****
InstanceResourceType	string	No	The condition that you want to use to filter instances by category. Valid values: EnsInstance: ENS instances that you purchase. EnsService: ENS instances that belong to edge services. BuildMachine: ENS instances that are configured with image builders. EnsPostPaidInstance: Pay-as-you-go ENS instances that you purchase.	EnsService
SearchKey	string	No	The keyword that you use to query the logs of the service. You can specify the values of parameters such as ip, InstanceName, and InstanceId as the keyword.	Joshua
NetworkId	string	No	The ID of the network.	n-2zeuphj08tt7q3brd****
VSwitchId	string	No	The ID of the vSwitch.	vsw-2zeh0r1pabwtg6wcs****
SecurityGroupId	string	No	The ID of the security group.	sg-5kyicq2kfcapxrdds6tar7jqb
IntranetIp	string	No	The internal IP address of the instance.	47.100.XX.XX
Tags	array<object>	No	The tags that are added to the resource. This operation does not return tag information. You can call this operation in combination with the tag-related operations.
	object	No	The tags of the instance. This operation does not return tag information. You can call this operation in combination with the tag-related operations.
Key	string	No	The key of the tag that are to add to the instance. Valid values: 1 to 20.	tag
Value	string	No	The tag value of the instance. Valid values: 1 to 20.	2
InstanceType	string	No	The instance type.	ens.se1.tiny

Response parameters

Parameter	Type	Description	Example
	object
Code	integer	The returned service code. 0 indicates that the request was successful.	0
PageSize	integer	The number of entries per page.	60
PageNumber	integer	The page number.	1
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCount	integer	The total number of entries returned.	2
Instances	array<object>	The returned instance information. It is an array that consists of InstanceAttributesType data.
Instance	object	Schema of Response
CreationTime	string	The time when the instance was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.	2019-07-26T06:40:43Z
Status	string	The status of the instance. Valid values: Running Expired Stopped	Running
SpecName	string	The instance type.	ens.sn1.stiny
InstanceTypeFamily	string	The instance family. Valid values: x86_vm: x86-based computing instance. x86_pm: x86-based physical machine. x86_bmi: x86-based bare metal instance. x86_bm: bare metal instance with the SmartNIC. pc_bmi: heterogeneous bare metal instance. pc_vm: heterogeneous virtual machine. arm_bmi: Arm-based computing instance.	x86_vm
InstanceResourceType	string	The category of the instance. Valid values: EnsInstance: ENS instances that you purchase. EnsService: ENS instances that belong to edge services. BuildMachine: ENS instances that are configured with image builders. EnsPostPaidInstance: pay-as-you-go ENS instances that you purchase.	EnsService
HostName	string	The hostname of the instance. The hostname cannot start or end with a period (.) or hyphen (-). It cannot contain consecutive periods (.) or hyphens (-). For a Windows instance, the hostname must be 2 to 15 characters in length and can contain letters, digits, and hyphens (-). The hostname cannot contain periods (.) or contain only digits. For an instance that runs another operating system such as Linux, the hostname must be 2 to 64 characters in length. You can use periods (.) to separate the hostname into multiple segments. Each segment can contain letters, digits, and hyphens (-).	testHostName
InstanceId	string	The ID of the instance.	i-instanc****
InternetMaxBandwidthIn	integer	The maximum outbound bandwidth. Unit: Mbit/s.	40
InternetMaxBandwidthOut	integer	The minimum inbound bandwidth. Unit: Mbit/s.	100
EnsRegionId	string	The region ID of the instance.	cn-hangzhou-telecom
Cpu	string	The number of vCPUs.	2
ExpiredTime	string	The expiration time. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.	2119-07-13T02:38:57Z
InstanceName	string	The name of the instance.	i-5itef0f28t17bcdw9deu6meub
Disk	integer	The total size of the disk. Unit: MiB.	71680
OSName	string	The name of the image.	centos 6.8 x86_64
Memory	integer	The memory size. Unit: MB.	2048
ImageId	string	The ID of the image.	m-****
DataDisk	array<object>	Details of the data disk.
DataDisk	object	Schema of Response
device_type	string	The extended field of the disk category. Valid values: file: local disk. pangu: ultra disk. local_hdd: local HDD.	pangu
disk_type	string	The type of the cloud disk or local disk. Valid values: system: system disk. data: data disk.	system
Size	integer	The size of the disk. Unit: MiB.	51200
DiskName	string	The name of the disk.	DiskName
uuid	string	The UUID of the disk.	d-5itef1wtxj961mbff8xe9****
storage	integer	The size of the disk. Unit: MiB.	20480
DiskId	string	The ID of the disk.	d-5ip4c2dhmas0vjd5u1r****
Category	string	The category of the cloud disk or local disk. Valid values: file: local disk. pangu: ultra disk. local_hdd: local HDD.	file
name	string	The name of the disk.	name
DiskSize	integer	The size of the disk. Unit: GiB.	100
PublicIpAddresses	array<object>	Details of the public IP addresses.
PublicIpAddress	object	Schema of Response
Ip	string	The IP address.	119.147.xx.xx
GateWay	string	The gateway.	119.147.xx.xx
Isp	string	The Internet service provider (ISP).	unicom
PrivateIpAddresses	array<object>	Details of the private IP addresses.
PrivateIpAddress	object	Schema of Response
Ip	string	The IP address.	119.147.xx.xx
GateWay	string	The gateway.	119.147.xx.xx
Isp	string	The ISP.	cmcc
SecurityGroupIds	array	The IDs of the security groups.
SecurityGroupId	string	The ID of the security group.	sg-5kyicq2kfcapxrdds6ta****
InnerIpAddress	array	The private IP addresses of the instances.
IpAddress	string	The private IP address of the instance.	10.170.xx.xx
PublicIpAddress	array	The public IP addresses of the instances.
IpAddress	string	The public IP address of the instance.	119.147.xx.xx
SystemDisk	object	Details of the system disk.
device_type	string	The extended field of the disk category. Valid values: file: local disk. pangu: ultra disk. local_hdd: local HDD.	pangu
disk_type	string	The type of the cloud disk or local disk. Valid values: system: system disk. data: data disk.	system
Size	integer	The size of the disk. Unit: MiB.	51200
DiskName	string	The name of the disk.	DiskName
uuid	string	The UUID of the disk.	d-5ip4c2dhmas0rn7rt0p96****
storage	integer	The size of the disk. Unit: MiB.	20480
DiskId	string	The ID of the disk.	d-5ip4c2dhmas0rn7rt0p9****
Category	string	The category of the cloud disk or local disk. Valid values: file: local disk. pangu: ultra disk. local_hdd: local HDD.	file
name	string	The name of the disk.	DiskName
NetworkAttributes	object	Details of the network.
NetworkId	string	The ID of the network.	n-2zeuphj08tt7q3brd****
VSwitchId	string	The vSwitch ID.	vsw-2zeh0r1pabwtg6wcs****
PrivateIpAddress	array	Details of the private IP addresses.
IpAddress	string	The private IP address of the instance. If a private IP address is specified, the number of private IP addresses must be 1. The private IP address must be an available IP address in the CIDR block of the vSwitch.	172.17..
Tags	array<object>	The tags of the instance. Note This operation does not return tag information. You can call this operation in combination with the tag-related operations.
Tags	object	The tag. Note This operation does not return tag information. You can call this operation in combination with the tag-related operations.
TagValue	string	The tag value.	value1
TagKey	string	The tag key.	key1
AutoReleaseTime	string	The automatic release time of the instance.	2023-06-28T14:38:52Z
SpotStrategy	string	The bidding policy of the preemptible instance.	NoSpot

Examples

Sample success responses

JSONformat

{
  "Code": 0,
  "PageSize": 60,
  "PageNumber": 1,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount": 2,
  "Instances": {
    "Instance": [
      {
        "CreationTime": "2019-07-26T06:40:43Z",
        "Status": "Running",
        "SpecName": "ens.sn1.stiny",
        "InstanceTypeFamily": "x86_vm",
        "InstanceResourceType": "EnsService",
        "HostName": "testHostName",
        "InstanceId": "i-instanc****",
        "InternetMaxBandwidthIn": 40,
        "InternetMaxBandwidthOut": 100,
        "EnsRegionId": "cn-hangzhou-telecom",
        "Cpu": "2",
        "ExpiredTime": "2119-07-13T02:38:57Z",
        "InstanceName": "i-5itef0f28t17bcdw9deu6meub",
        "Disk": 71680,
        "OSName": "centos 6.8 x86_64",
        "Memory": 2048,
        "ImageId": "m-****",
        "DataDisk": {
          "DataDisk": [
            {
              "device_type": "pangu",
              "disk_type": "system",
              "Size": 51200,
              "DiskName": "DiskName",
              "uuid": "d-5itef1wtxj961mbff8xe9****",
              "storage": 20480,
              "DiskId": "d-5ip4c2dhmas0vjd5u1r****",
              "Category": "file",
              "name": "name",
              "DiskSize": 100,
              "EncryptKeyId": "",
              "Encrypted": true
            }
          ]
        },
        "PublicIpAddresses": {
          "PublicIpAddress": [
            {
              "Ip": "119.147.xx.xx",
              "GateWay": "119.147.xx.xx",
              "Isp": "unicom"
            }
          ]
        },
        "PrivateIpAddresses": {
          "PrivateIpAddress": [
            {
              "Ip": "119.147.xx.xx",
              "GateWay": "119.147.xx.xx",
              "Isp": "cmcc"
            }
          ]
        },
        "SecurityGroupIds": {
          "SecurityGroupId": [
            "sg-5kyicq2kfcapxrdds6ta****"
          ]
        },
        "InnerIpAddress": {
          "IpAddress": [
            "10.170.xx.xx"
          ]
        },
        "PublicIpAddress": {
          "IpAddress": [
            "119.147.xx.xx"
          ]
        },
        "SystemDisk": {
          "device_type": "pangu",
          "disk_type": "system",
          "Size": 51200,
          "DiskName": "DiskName",
          "uuid": "d-5ip4c2dhmas0rn7rt0p96****",
          "storage": 20480,
          "DiskId": "d-5ip4c2dhmas0rn7rt0p9****",
          "Category": "file",
          "name": "DiskName"
        },
        "NetworkAttributes": {
          "NetworkId": "n-2zeuphj08tt7q3brd****",
          "VSwitchId": "vsw-2zeh0r1pabwtg6wcs****",
          "PrivateIpAddress": {
            "IpAddress": [
              "172.17.**.**"
            ]
          }
        },
        "Tags": {
          "Tags": [
            {
              "TagValue": "value1",
              "TagKey": "key1"
            }
          ]
        },
        "AutoReleaseTime": "2023-06-28T14:38:52Z",
        "SpotStrategy": "NoSpot",
        "KeyPairName": ""
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	MissingParameter	The input parameter domainName that is mandatory for processing this request is not supplied.	-
400	InstanceIdNotFound	The input parameter instancdId that is not found.	The specified instance ID does not exist.
400	NoPermission	Permission denied.	-
400	CallInterface	Call Interface Happen Error.	An error occurred when you call the operation.
400	InvalidParameter.%s	The specified field %s invalid. Please check it again.	-

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-11-29	The Error code has changed. The request parameters of the API has changed. The response structure of the API has changed	View Change Details
2024-10-17	The Error code has changed. The response structure of the API has changed	View Change Details
2024-08-27	The Error code has changed. The response structure of the API has changed	View Change Details
2024-08-22	The Error code has changed. The response structure of the API has changed	View Change Details
2024-05-23	The Error code has changed. The request parameters of the API has changed	View Change Details
2024-04-09	The Error code has changed. The response structure of the API has changed	View Change Details
2024-01-25	The Error code has changed. The request parameters of the API has changed. The response structure of the API has changed	View Change Details
2024-01-04	The Error code has changed. The response structure of the API has changed	View Change Details