Mapping Cmdlets to AWS Service APIs

The consistency of the standardized verb and naming scheme used by Windows PowerShell makes learning the basics of the shell relatively easy, but translating knowledge of an existing API to the standard names can be difficult at first. Starting with version 2.3.19, AWS Tools for Windows PowerShell contains a new cmdlet to help with discovery: Get-AWSCmdletName. This cmdlet accepts the name of an AWS service API and emits the names of cmdlets that invoke an API matching that name pattern. It can also accept an AWS CLI command line and give you back the corresponding PowerShell cmdlet—handy if you are converting an AWS CLI sample.

Discovering Service APIs

Running the PowerShell Get-Command cmdlet with verb and/or noun filtering only gets you so far in discovering the cmdlets that are available in a module. You as a user still need to make the mental leap to associate the verb and noun combination to a known service API. Sometimes this is obvious, sometimes not so much. To get the name of a cmdlet that invokes a known AWS service API is now as easy as:

PS C:> Get-AWSCmdletName -ApiOperation describeinstances

CmdletName              ServiceOperation
----------              ----------------
Get-EC2Instance         DescribeInstances
Get-OPSInstances        DescribeInstances

Note that the full name of the service, and the noun prefix, are displayed in additional columns that are not shown in these examples for brevity.

The parameter name -ApiOperation can be omitted to save typing. You can see from the output that the cmdlet has scanned all cmdlets contained in the AWS PowerShell module and output those that invoke a service API DescribeInstances regardless of the service.

If you know the service of interest, you can restrict the search using the optional -Service parameter:

PS C:> Get-AWSCmdletName describeinstances -Service ec2

CmdletName              ServiceOperation
----------              ----------------
Get-EC2Instance         DescribeInstances

The value supplied to the -Service parameter can be either the prefix code that is applied to the noun part of the name of cmdlets belonging to a service, or one or more words from the service name. For example, these two commands return the same output as the example above:

PS C:> Get-AWSCmdletName describeinstances -Service compute
PS C:> Get-AWSCmdletName describeinstances -Service "compute cloud"

Note that all searches are case insensitive.

If you know the exact name of the service API you are interested in, then you are good to go. But what if you want to find all cmdlets that have something to do with, say, security groups (based on the premise that the term ‘securitygroup’ forms part of the API name)? You might try this:

PS C:> Get-AWSCmdletName securitygroup

As you’ll see if you run the example, the cmdlet displays no output because there is no service API matching that name. What we need is a more flexible way to specify the pattern to match. You can do this by adding the -MatchWithRegex switch:

PS C:> Get-AWSCmdletName securitygroup -MatchWithRegex

CmdletName                              ServiceOperation
----------                              ----------------
Approve-ECCacheSecurityGroupIngress     AuthorizeCacheSecurityGroupIngress
Get-ECCacheSecurityGroup                DescribeCacheSecurityGroups
New-ECCacheSecurityGroup                CreateCacheSecurityGroup
Remove-ECCacheSecurityGroup             DeleteCacheSecurityGroup
Revoke-ECCacheSecurityGroupIngress      RevokeCacheSecurityGroupIngress
Get-EC2SecurityGroup                    DescribeSecurityGroups
Grant-EC2SecurityGroupEgress            AuthorizeSecurityGroupEgress
Grant-EC2SecurityGroupIngress           AuthorizeSecurityGroupIngress
New-EC2SecurityGroup                    CreateSecurityGroup
Remove-EC2SecurityGroup                 DeleteSecurityGroup
Revoke-EC2SecurityGroupEgress           RevokeSecurityGroupEgress
Revoke-EC2SecurityGroupIngress          RevokeSecurityGroupIngress
Join-ELBSecurityGroupToLoadBalancer     ApplySecurityGroupsToLoadBalancer
Enable-RDSDBSecurityGroupIngress        AuthorizeDBSecurityGroupIngress
Get-RDSDBSecurityGroup                  DescribeDBSecurityGroups
New-RDSDBSecurityGroup                  CreateDBSecurityGroup
Remove-RDSDBSecurityGroup               DeleteDBSecurityGroup
Revoke-RDSDBSecurityGroupIngress        RevokeDBSecurityGroupIngress
Approve-RSClusterSecurityGroupIngress   AuthorizeClusterSecurityGroupIngress
Get-RSClusterSecurityGroups             DescribeClusterSecurityGroups
New-RSClusterSecurityGroup              CreateClusterSecurityGroup
Remove-RSClusterSecurityGroup           DeleteClusterSecurityGroup
Revoke-RSClusterSecurityGroupIngress    RevokeClusterSecurityGroupIngress

As you can see its now easy to find all cmdlets that have something to do with a particular term, or object, across all services. When the -MatchWithRegex parameter is used the value of the -ApiOperation parameter is interpreted as a regular expression.

If we wanted to restrict the search to a specific service, we would just add the -Service parameter too, as shown earlier. The -Service parameter value always accepts a regular expression and is not affected by the -MatchWithRegex switch. When looking at the name of the owning service for a cmdlet, Get-AWSCmdletName automatically uses the -Service value as a regular expression, and if that does not yield a match, it then attempts to use the value in a simple text comparison on the service prefix that is used in cmdlet names to effectively namespace the cmdlets.

Translating from AWS CLI

The verb-noun naming standard of PowerShell is considered one of its strengths and one that we are pleased to support to give users a consistent experience. The AWS CLI follows more closely the AWS API naming conventions. Get-AWSCmdletName has one further ability and that is to be able to make a “best effort” at translating an AWS CLI command line to yield the corresponding AWS PowerShell cmdlet. This can be useful when translating a sample:

PS C:> Get-AWSCmdletName -AwsCliCommand "aws ec2 authorize-security-group-ingress"

CmdletName                           ServiceOperation
----------                           ----------------
Grant-EC2SecurityGroupIngress        AuthorizeSecurityGroupIngress

The supplied AWS CLI command is parsed to recover the service identifier and the operation name (which is stripped of any hyphens). You only need to specify enough of the command to allow the service and operation to be identified – the “aws” prefix in the parameter value can be omitted. Also, if you’ve pasted the parameter value from a sample and it contains any CLI options—identified by a ‘–‘ prefix— they are skipped.

Hopefully, you’ll find this new cmdlet useful in discovering and navigating the cmdlets available for working with AWS. Do you have an idea for something that would be useful for you and potentially others? Let us know in the comments!