AWS Developer Tools Blog
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:
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:
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:
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:
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:
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:
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!