Use DescribeRegions
with an Amazon SDK or CLI
The following code examples show how to use DescribeRegions
.
- C++
-
- SDK for C++
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. //! Describe all Amazon Elastic Compute Cloud (Amazon EC2) Regions. /*! \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::EC2::describeRegions( const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::EC2::EC2Client ec2Client(clientConfiguration); Aws::EC2::Model::DescribeRegionsRequest request; Aws::EC2::Model::DescribeRegionsOutcome outcome = ec2Client.DescribeRegions(request); if (outcome.IsSuccess()) { std::cout << std::left << std::setw(32) << "RegionName" << std::setw(64) << "Endpoint" << std::endl; const auto ®ions = outcome.GetResult().GetRegions(); for (const auto ®ion: regions) { std::cout << std::left << std::setw(32) << region.GetRegionName() << std::setw(64) << region.GetEndpoint() << std::endl; } } else { std::cerr << "Failed to describe regions:" << outcome.GetError().GetMessage() << std::endl; } std::cout << std::endl; return outcome.IsSuccess(); }
-
For API details, see DescribeRegions in Amazon SDK for C++ API Reference.
-
- CLI
-
- Amazon CLI
-
Example 1: To describe all of your enabled Regions
The following
describe-regions
example describes all of the Regions that are enabled for your account.aws ec2 describe-regions
Output:
{ "Regions": [ { "Endpoint": "ec2.eu-north-1.amazonaws.com", "RegionName": "eu-north-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-south-1.amazonaws.com", "RegionName": "ap-south-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-3.amazonaws.com", "RegionName": "eu-west-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-2.amazonaws.com", "RegionName": "eu-west-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-1.amazonaws.com", "RegionName": "eu-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-3.amazonaws.com", "RegionName": "ap-northeast-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-2.amazonaws.com", "RegionName": "ap-northeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-1.amazonaws.com", "RegionName": "ap-northeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.sa-east-1.amazonaws.com", "RegionName": "sa-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ca-central-1.amazonaws.com", "RegionName": "ca-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-southeast-1.amazonaws.com", "RegionName": "ap-southeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-southeast-2.amazonaws.com", "RegionName": "ap-southeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-central-1.amazonaws.com", "RegionName": "eu-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-1.amazonaws.com", "RegionName": "us-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-2.amazonaws.com", "RegionName": "us-east-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-1.amazonaws.com", "RegionName": "us-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-2.amazonaws.com", "RegionName": "us-west-2", "OptInStatus": "opt-in-not-required" } ] }
For more information, see Regions and Zones
in the Amazon EC2 User Guide. Example 2: To describe enabled Regions with an endpoint whose name contains a specific string
The following
describe-regions
example describes all Regions that you have enabled that have the string "us" in the endpoint.aws ec2 describe-regions \ --filters
"Name=endpoint,Values=*us*"
Output:
{ "Regions": [ { "Endpoint": "ec2.us-east-1.amazonaws.com", "RegionName": "us-east-1" }, { "Endpoint": "ec2.us-east-2.amazonaws.com", "RegionName": "us-east-2" }, { "Endpoint": "ec2.us-west-1.amazonaws.com", "RegionName": "us-west-1" }, { "Endpoint": "ec2.us-west-2.amazonaws.com", "RegionName": "us-west-2" } ] }
For more information, see Regions and Zones
in the Amazon EC2 User Guide. Example 3: To describe all Regions
The following
describe-regions
example describes all available Regions, including Regions that are disabled.aws ec2 describe-regions \ --all-regions
Output:
{ "Regions": [ { "Endpoint": "ec2.eu-north-1.amazonaws.com", "RegionName": "eu-north-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-south-1.amazonaws.com", "RegionName": "ap-south-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-3.amazonaws.com", "RegionName": "eu-west-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-2.amazonaws.com", "RegionName": "eu-west-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-west-1.amazonaws.com", "RegionName": "eu-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-3.amazonaws.com", "RegionName": "ap-northeast-3", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.me-south-1.amazonaws.com", "RegionName": "me-south-1", "OptInStatus": "not-opted-in" }, { "Endpoint": "ec2.ap-northeast-2.amazonaws.com", "RegionName": "ap-northeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-northeast-1.amazonaws.com", "RegionName": "ap-northeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.sa-east-1.amazonaws.com", "RegionName": "sa-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ca-central-1.amazonaws.com", "RegionName": "ca-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-east-1.amazonaws.com", "RegionName": "ap-east-1", "OptInStatus": "not-opted-in" }, { "Endpoint": "ec2.ap-southeast-1.amazonaws.com", "RegionName": "ap-southeast-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.ap-southeast-2.amazonaws.com", "RegionName": "ap-southeast-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.eu-central-1.amazonaws.com", "RegionName": "eu-central-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-1.amazonaws.com", "RegionName": "us-east-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-east-2.amazonaws.com", "RegionName": "us-east-2", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-1.amazonaws.com", "RegionName": "us-west-1", "OptInStatus": "opt-in-not-required" }, { "Endpoint": "ec2.us-west-2.amazonaws.com", "RegionName": "us-west-2", "OptInStatus": "opt-in-not-required" } ] }
For more information, see Regions and Zones
in the Amazon EC2 User Guide. Example 4: To list the Region names only
The following
describe-regions
example uses the--query
parameter to filter the output and return only the names of the Regions as text.aws ec2 describe-regions \ --all-regions \ --query
"Regions[].{Name:RegionName}"
\ --outputtext
Output:
eu-north-1 ap-south-1 eu-west-3 eu-west-2 eu-west-1 ap-northeast-3 ap-northeast-2 me-south-1 ap-northeast-1 sa-east-1 ca-central-1 ap-east-1 ap-southeast-1 ap-southeast-2 eu-central-1 us-east-1 us-east-2 us-west-1 us-west-2
For more information, see Regions and Zones
in the Amazon EC2 User Guide. -
For API details, see DescribeRegions
in Amazon CLI Command Reference.
-
- JavaScript
-
- SDK for JavaScript (v3)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. import { DescribeRegionsCommand, EC2Client } from "@aws-sdk/client-ec2"; /** * List all available AWS regions. * @param {{ regionNames: string[], includeOptInRegions: boolean }} options */ export const main = async ({ regionNames, includeOptInRegions }) => { const client = new EC2Client({}); const command = new DescribeRegionsCommand({ // By default this command will not show regions that require you to opt-in. // When AllRegions is true, even the regions that require opt-in will be returned. AllRegions: includeOptInRegions, // You can omit the Filters property if you want to get all regions. Filters: regionNames?.length ? [ { Name: "region-name", // You can specify multiple values for a filter. // You can also use '*' as a wildcard. This will return all // of the regions that start with `us-east-`. Values: regionNames, }, ] : undefined, }); try { const { Regions } = await client.send(command); const regionsList = Regions.map((reg) => ` • ${reg.RegionName}`); console.log("Found regions:"); console.log(regionsList.join("\n")); } catch (caught) { if (caught instanceof Error && caught.name === "DryRunOperation") { console.log(`${caught.message}`); } else { throw caught; } } };
-
For API details, see DescribeRegions in Amazon SDK for JavaScript API Reference.
-
- PowerShell
-
- Tools for PowerShell
-
Example 1: This example describes the regions that are available to you.
Get-EC2Region
Output:
Endpoint RegionName -------- ---------- ec2.eu-west-1.amazonaws.com eu-west-1 ec2.ap-southeast-1.amazonaws.com ap-southeast-1 ec2.ap-southeast-2.amazonaws.com ap-southeast-2 ec2.eu-central-1.amazonaws.com eu-central-1 ec2.ap-northeast-1.amazonaws.com ap-northeast-1 ec2.us-east-1.amazonaws.com us-east-1 ec2.sa-east-1.amazonaws.com sa-east-1 ec2.us-west-1.amazonaws.com us-west-1 ec2.us-west-2.amazonaws.com us-west-2
-
For API details, see DescribeRegions
in Amazon Tools for PowerShell Cmdlet Reference.
-
- Ruby
-
- SDK for Ruby
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. require 'aws-sdk-ec2' # @param ec2_client [Aws::EC2::Client] An initialized EC2 client. # @example # list_regions_endpoints(Aws::EC2::Client.new(region: 'us-west-2')) def list_regions_endpoints(ec2_client) result = ec2_client.describe_regions # Enable pretty printing. max_region_string_length = 16 max_endpoint_string_length = 33 # Print header. print 'Region' print ' ' * (max_region_string_length - 'Region'.length) print " Endpoint\n" print '-' * max_region_string_length print ' ' print '-' * max_endpoint_string_length print "\n" # Print Regions and their endpoints. result.regions.each do |region| print region.region_name print ' ' * (max_region_string_length - region.region_name.length) print ' ' print region.endpoint print "\n" end end # Displays a list of Amazon Elastic Compute Cloud (Amazon EC2) # Availability Zones available to you depending on the AWS Region # of the Amazon EC2 client. # # @param ec2_client [Aws::EC2::Client] An initialized EC2 client. # @example # list_availability_zones(Aws::EC2::Client.new(region: 'us-west-2')) def list_availability_zones(ec2_client) result = ec2_client.describe_availability_zones # Enable pretty printing. max_region_string_length = 16 max_zone_string_length = 18 max_state_string_length = 9 # Print header. print 'Region' print ' ' * (max_region_string_length - 'Region'.length) print ' Zone' print ' ' * (max_zone_string_length - 'Zone'.length) print " State\n" print '-' * max_region_string_length print ' ' print '-' * max_zone_string_length print ' ' print '-' * max_state_string_length print "\n" # Print Regions, Availability Zones, and their states. result.availability_zones.each do |zone| print zone.region_name print ' ' * (max_region_string_length - zone.region_name.length) print ' ' print zone.zone_name print ' ' * (max_zone_string_length - zone.zone_name.length) print ' ' print zone.state # Print any messages for this Availability Zone. if zone.messages.count.positive? print "\n" puts ' Messages for this zone:' zone.messages.each do |message| print " #{message.message}\n" end end print "\n" end end # Example usage: def run_me region = '' # Print usage information and then stop. if ARGV[0] == '--help' || ARGV[0] == '-h' puts 'Usage: ruby ec2-ruby-example-regions-availability-zones.rb REGION' # Replace us-west-2 with the AWS Region you're using for Amazon EC2. puts 'Example: ruby ec2-ruby-example-regions-availability-zones.rb us-west-2' exit 1 # If no values are specified at the command prompt, use these default values. # Replace us-west-2 with the AWS Region you're using for Amazon EC2. elsif ARGV.count.zero? region = 'us-west-2' # Otherwise, use the values as specified at the command prompt. else region = ARGV[0] end ec2_client = Aws::EC2::Client.new(region: region) puts 'AWS Regions for Amazon EC2 that are available to you:' list_regions_endpoints(ec2_client) puts "\n\nAmazon EC2 Availability Zones that are available to you for AWS Region '#{region}':" list_availability_zones(ec2_client) end run_me if $PROGRAM_NAME == __FILE__
-
For API details, see DescribeRegions in Amazon SDK for Ruby API Reference.
-
- Rust
-
- SDK for Rust
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. async fn show_regions(client: &Client) -> Result<(), Error> { let rsp = client.describe_regions().send().await?; println!("Regions:"); for region in rsp.regions() { println!(" {}", region.region_name().unwrap()); } Ok(()) }
-
For API details, see DescribeRegions
in Amazon SDK for Rust API reference.
-
- SAP ABAP
-
- SDK for SAP ABAP
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. TRY. oo_result = lo_ec2->describeregions( ) . " oo_result is returned for testing purposes. " DATA(lt_regions) = oo_result->get_regions( ). MESSAGE 'Retrieved information about Regions.' TYPE 'I'. CATCH /aws1/cx_rt_service_generic INTO DATA(lo_exception). DATA(lv_error) = |"{ lo_exception->av_err_code }" - { lo_exception->av_err_msg }|. MESSAGE lv_error TYPE 'E'. ENDTRY.
-
For API details, see DescribeRegions in Amazon SDK for SAP ABAP API reference.
-
For a complete list of Amazon SDK developer guides and code examples, see Create Amazon EC2 resources using an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.