Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

GetControl

Returns details about a specific control, most notably a list of AWS Regions where this control is supported. Input a value for the ControlArn parameter, in ARN form. GetControl accepts controltower or controlcatalog control ARNs as input. Returns a controlcatalog ARN format.

In the API response, controls that have the value GLOBAL in the Scope field do not show the DeployableRegions field, because it does not apply. Controls that have the value REGIONAL in the Scope field return a value for the DeployableRegions field, as shown in the example.

Request Syntax


POST /get-control HTTP/1.1
Content-type: application/json

{
   "ControlArn": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

ControlArn

The Amazon Resource Name (ARN) of the control. It has one of the following formats:

Global format

arn:{PARTITION}:controlcatalog:::control/{CONTROL_CATALOG_OPAQUE_ID}

Or Regional format

arn:{PARTITION}:controltower:{REGION}::control/{CONTROL_TOWER_OPAQUE_ID}

Here is a more general pattern that covers AWS Control Tower and Control Catalog ARNs:

^arn:(aws(?:[-a-z]*)?):(controlcatalog|controltower):[a-zA-Z0-9-]*::control/[0-9a-zA-Z_\\-]+$

Type: String

Length Constraints: Minimum length of 34. Maximum length of 2048.

Pattern: arn:(aws(?:[-a-z]*)?):(controlcatalog|controltower):[a-zA-Z0-9-]*::control/[0-9a-zA-Z_\-]+

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "Arn": "string",
   "Behavior": "string",
   "Description": "string",
   "Implementation": { 
      "Type": "string"
   },
   "Name": "string",
   "Parameters": [ 
      { 
         "Name": "string"
      }
   ],
   "RegionConfiguration": { 
      "DeployableRegions": [ "string" ],
      "Scope": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Arn

The Amazon Resource Name (ARN) of the control.

Type: String

Length Constraints: Minimum length of 34. Maximum length of 2048.

Pattern: arn:(aws(?:[-a-z]*)?):(controlcatalog|controltower):[a-zA-Z0-9-]*::control/[0-9a-zA-Z_\-]+

Behavior

A term that identifies the control's functional behavior. One of Preventive, Detective, Proactive

Type: String

Valid Values: PREVENTIVE | PROACTIVE | DETECTIVE

Description

A description of what the control does.

Type: String

Implementation

Returns information about the control, as an ImplementationDetails object that shows the underlying implementation type for a control.

Type: ImplementationDetails object

Name

The display name of the control.

Type: String

Parameters

Returns an array of ControlParameter objects that specify the parameters a control supports. An empty list is returned for controls that don’t support parameters.

Type: Array of ControlParameter objects

RegionConfiguration

Returns information about the control, including the scope of the control, if enabled, and the Regions in which the control currently is available for deployment. For more information about scope, see Global services.

If you are applying controls through an AWS Control Tower landing zone environment, remember that the values returned in the RegionConfiguration API operation are not related to the governed Regions in your landing zone. For example, if you are governing Regions A,B,and C while the control is available in Regions A, B, C, and D, you'd see a response with DeployableRegions of A, B, C, and D for a control with REGIONAL scope, even though you may not intend to deploy the control in Region D, because you do not govern it through your landing zone.

Type: RegionConfiguration object

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

InternalServerException

An internal service error occurred during the processing of your request. Try again later.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource does not exist.

HTTP Status Code: 404

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 429

ValidationException

The request has invalid or missing parameters.

HTTP Status Code: 400

Examples

Retrieve information about a control

Use this operation to retrieve information about a control, including a list of Regions in which the control currently is available for deployment.

Sample Request


aws controlcatalog get-control --control-arn arn:aws:controlcatalog:::control/ka8e3pkqefnjsxuyc26ji580 --region us-east-1


##Alternatively

Sample Request


aws controlcatalog get-control --control-arn arn:aws:controltower:us-east-1::control/ZWORVQKMSSVN --region us-east-1

Sample Response


{
    "Arn": "arn:aws:controlcatalog:::control/ka8e3pkqefnjsxuyc26ji580",
    "Name": "Deny access to AWS based on the requested AWS Region; for an organizational unit",
    "Description": "Disallows access to unlisted operations in global and regional services outside of the specified Regions for an organizational unit.",
    "Behavior": "PREVENTIVE",
    "RegionConfiguration": {
        "Scope": "GLOBAL"
    },
    "Implementation": {
        "Type": "AWS::Organizations::Policy::SERVICE_CONTROL_POLICY"
    },
    "Parameters": [
        {
            "Name": "ExemptedPrincipalArns"
        },
        {
            "Name": "AllowedRegions"
        },
        {
            "Name": "ExemptedActions"
        }
    ]
}