All Products
Search
Document Center

Elastic Compute Service:Query an ECS instance

Last Updated:Sep 12, 2023

You can manage Elastic Compute Service (ECS) instances by using the ECS console or by calling API operations. Alibaba Cloud provides SDKs in multiple languages to encapsulate APIs. This topic describes how to use an API operation to query ECS instances in Python.

Background information

For information about the sample code that is used to query an ECS instance, see the "Sample code" section of this topic. For information about the explanation of the sample code, see the following sections of this topic:

Create a RAM user and obtain its AccessKey pair

An AccessKey pair that consists of an AccessKey ID and an AccessKey secret is required if you want to use API operations to manage ECS instances. To ensure the security of cloud services, create a Resource Access Management (RAM) user, generate an AccessKey pair for the RAM user, and use the RAM user to manage ECS instances by using API operations.

Perform the following operations to create a RAM user and obtain its AccessKey pair:

  1. Create a RAM user. For more information, see Create a RAM user.

  2. Create an AccessKey pair for the RAM user. For more information, see Create an AccessKey pair.

  3. Grant the RAM user full access to ECS by attaching the AliyunECSFullAccess policy to the user. For more information, see Grant permissions to RAM users.

Install ECS SDK for Python

Make sure that you have prepared the runtime environment for Python. Python 2.7 or later is used in this topic.

Run the following command to install the SDK for Python:

pip install aliyun-python-sdk-ecs

If you are prompted that you do not have the permissions, run the following sudo command to continue the installation:

sudo pip install aliyun-python-sdk-ecs

SDK for Python 2.1.2 is used in this topic.

Sample code

The following code provides an example on how to query an ECS instance. You can modify the code based on your actual needs.

#  coding=utf-8
# if the python sdk is not install using 'sudo pip install aliyun-python-sdk-ecs'
# if the python sdk is install using 'sudo pip install --upgrade aliyun-python-sdk-ecs'
# make sure the sdk version is greater than 2.1.2, you can use command 'pip show aliyun-python-sdk-ecs' to check
import json
import logging
import os
from aliyunsdkcore import client
from aliyunsdkecs.request.v20140526.DescribeInstancesRequest import DescribeInstancesRequest
from aliyunsdkecs.request.v20140526.DescribeRegionsRequest import DescribeRegionsRequest
# configuration the log output formatter, if you want to save the output to file,
# append ",filename='ecs_invoke.log'" after datefmt.

logging.basicConfig(level=logging.INFO, format='%(asctime)s %(filename)s[line:%(lineno)d] %(levelname)s %(message)s', datefmt='%a %d %b %Y %H:%M:%S')

# Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime. 
# If the project code is leaked, the AccessKey pair may be leaked and the security of resources within your account may be compromised. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. The sample code is for reference only. We recommend that you use Security Token Service (STS) tokens, which provide higher security.
# Replace <RegionId> with the actual region ID. You can call the DescribeRegions operation to query the most recent region list. 
clt = client.AcsClient(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], '<RegionId>')

# sample api to list aliyun open api.
def hello_aliyun_regions():
    request = DescribeRegionsRequest()
    response = _send_request(request)
    if response is not None:
        region_list = response.get('Regions').get('Region')
        assert response is not None
        assert region_list is not None
        result = map(_print_region_id, region_list)
        logging.info("region list: %s", list(result))

# output the instance owned in current region.
def list_instances():
    request = DescribeInstancesRequest()
    request.set_accept_format('json')
    # The following code provides an example on how to configure request parameters to perform a paged query. In this example, set_PageNumber is set to 1 and set_PageSize is set to 2. 
    request.set_PageNumber(1)
    request.set_PageSize(2)
    response = _send_request(request)
    if response is not None:
        instance_list = response.get('Instances').get('Instance')
        result = map(_print_instance_id, instance_list)
        logging.info("current region include instance %s", list(result))

def _print_instance_id(item):
    instance_id = item.get('InstanceId')
    return instance_id

def _print_region_id(item):
    region_id = item.get("RegionId")
    return region_id

# send open api request
def _send_request(request):
    request.set_accept_format('json')
    try:
        response_str = clt.do_action_with_exception(request)
        logging.info(response_str)
        response_detail = json.loads(response_str)
        return response_detail
    except Exception as e:
        logging.error(e)

if __name__ == '__main__':
    logging.info("Hello Aliyun OpenApi!")
    hello_aliyun_regions()
    list_instances()

Query the list of regions supported by the current account

Create a file named hello_ecs_api.py. Before you use the SDK for Python, use the Alibaba Cloud AccessKey ID and AccessKey secret of the RAM user to instantiate an AcsClient object.

Note

The AccessKey ID and AccessKey secret allow the RAM user to access ECS API of Alibaba Cloud with full permissions. You must keep the AccessKey pair confidential.

import json
import logging
import os
from aliyunsdkcore import client
from aliyunsdkecs.request.v20140526.DescribeInstancesRequest import DescribeInstancesRequest
from aliyunsdkecs.request.v20140526.DescribeRegionsRequest import DescribeRegionsRequest
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(filename)s[line:%(lineno)d] %(levelname)s %(message)s', datefmt='%a %d %b %Y %H:%M:%S')
# Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime. 
# If the project code is leaked, the AccessKey pair may be leaked and the security of resources within your account may be compromised. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. The sample code is for reference only. We recommend that you use STS tokens, which provide higher security.
# Replace <RegionId> with the actual region ID. You can call the DescribeRegions operation to query the most recent region list. 
clt = client.AcsClient(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], '<RegionId>')

After the AcsClient object is instantiated, query the list of regions that are supported by the current account. For more information, see DescribeRegions.

def hello_aliyun_regions():
    request = DescribeRegionsRequest()
    response = _send_request(request)
    region_list = response.get('Regions').get('Region')
    assert response is not None
    assert region_list is not None
    result = map(_print_region_id, region_list)
    logging.info("region list: %s", list(result))
def _print_region_id(item):
    region_id = item.get("RegionId")
    return region_id
def _send_request(request):
    request.set_accept_format('json')
    try:
        response_str = clt.do_action_with_exception(request)
        logging.info(response_str)
        response_detail = json.loads(response_str)
        return response_detail
    except Exception as e:
        logging.error(e)
hello_aliyun_regions()

Run the python hello_ecs_api.py command on the command line to obtain the list of regions that are supported by the current account. Sample response:

region list: ['cn-qingdao', 'cn-beijing', 'cn-zhangjiakou', 'cn-huhehaote', 'cn-wulanchabu', 'cn-hangzhou', 'cn-shanghai', 'cn-shenzhen', 'cn-heyuan', 'cn-guangzhou', 'cn-chengdu', 'cn-hongkong', 'ap-northeast-1', 'ap-southeast-1', 'ap-southeast-2', 'ap-southeast-3', 'ap-southeast-5', 'ap-south-1', 'us-east-1', 'us-west-1', 'eu-west-1']

Query ECS instances in a specific region

The process of querying the instance list is similar to that of querying the region list. Replace the input parameter with DescribeInstancesRequest and re-configure relevant parameters. For more information, see DescribeInstances.

def list_instances():
    request = DescribeInstancesRequest()
    request.set_accept_format('json')
    # The following code provides an example on how to configure request parameters to perform a paged query. In this example, set_PageNumber is set to 1 and set_PageSize is set to 2. 
    request.set_PageNumber(1)
    request.set_PageSize(2)
    response = _send_request(request)
    if response is not None:
        instance_list = response.get('Instances').get('Instance')
        result = map(_print_instance_id, instance_list)
        logging.info("current region include instance %s", list(result))
def _print_instance_id(item):
    instance_id = item.get('InstanceId')
    return instance_id
def _send_request(request):
    request.set_accept_format('json')
    try:
        response_str = clt.do_action_with_exception(request)
        logging.info(response_str)
        response_detail = json.loads(response_str)
        return response_detail
    except Exception as e:
        logging.error(e)
list_instances()

Sample response:

current region include instance ['i-bp165p6xk2tmdhj0****', 'i-bp1a01zbqmsun5odo****'']

For more information about API operations for resource query, see List of API operations by function. For example, to query the list of disks, you can call the DescribeDisks operation by replacing the input parameter with DescribeDisksRequest and re-configure relevant parameters.