# Cloud Control API resource operations
Use AWS Cloud Control API to do or other command verb construction create, read, update, remove, and list (-L) operations on resources in your AWS account.
**Topics**
+ [Prerequisites](#resource-operations-prerequisites)
+ [Specifying credentials](#resource-operations-permissions)
+ [Ensuring requests are unique](#resource-operations-idempotency)
+ [Considerations](#resource-operations-considerations)
+ [Creating a resource](resource-operations-create.md)
+ [Updating a resource](resource-operations-update.md)
+ [Deleting a resource](resource-operations-delete.md)
+ [Discovering resources](resource-operations-list.md)
+ [Reading a resource](resource-operations-read.md)
+ [Managing resource requests](resource-operations-manage-requests.md)
+ [
# Identifying resources with AWS Cloud Control API
](resource-identifier.md)
## Prerequisites for using resources with Cloud Control API
To provision a specific resource using Cloud Control API, that resource type must support Cloud Control API and be available for use in your AWS account.
+ **Resources available for use in your AWS account**
To be available for use in your account, public resource types must be activated, and private resource types must be registered. Supported AWS resource types are public and always activated. For more information, see [Using Cloud Control API resource types](resource-types.md).
+ **Resources that support Cloud Control API**
For a list of AWS resource types that support Cloud Control API, see [Resource types that support Cloud Control API](supported-resources.md).
Third-party resource types, both public and private, support Cloud Control API.
For details about how to determine if a specific resource type supports Cloud Control API, see [Determining if a resource type supports Cloud Control API](resource-types.md#resource-types-determine-support).
For information about using resource types, see [Using Cloud Control API resource types](resource-types.md).
## Specifying credentials for Cloud Control API
As part of performing operations on AWS resources on your behalf, Cloud Control API must make calls to the underlying AWS services that actually provision those resources. To do so, Cloud Control API requires the necessary credentials to access those services. There are two ways for you to enable Cloud Control API to acquire those credentials:
+ **User credentials**
By default, Cloud Control API creates a temporary session using your AWS user credentials, and uses that to make any necessary calls to downstream AWS services. This session lasts up to 24 hours, after which any remaining calls to AWS by Cloud Control API will fail.
+ **Service role credentials**
You can also specify a service role for Cloud Control API to assume during a resource operation, when you make the resource request. Among other advantages, specifying a service role enables Cloud Control API to make calls to underlying AWS services for up to 36 hours.
To use a service role, specify the `RoleArn` parameter of the resource operation request.
Because the Cloud Control API actions are part of the CloudFormation service, the service role you specify is assumed by the CloudFormation service (`cloudformation.amazonaws.com`). For more information, see [CloudFormation service role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html) in the *AWS CloudFormation User Guide*.
The permissions required for each resource handler are defined in the `handlers` section of that resource type's schema. For more information about viewing the resource schema, see .[Viewing resource type schemas](resource-types.md#resource-types-schemas) The `handlers` section is defined in the [resource type definition schema](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-handlers).
## Ensuring resource operation requests are unique when using Cloud Control API
As a best practice, we strongly recommend you specify an idempotency token with create, delete, and update resource operation requests. Preferably, specify a token that will be unique for every request, such as an universally unique identifier (UUID). Such a token ensures requests can be disambiguated in cases where a request must be retried.
The `create-resource`, `delete-resource`, and `update-resource` operations all take a `client-token` parameter, which can be set to an idempotency token.
## Considerations when using Cloud Control API
We recommend that you take the following service behavior into account when performing resource operations using Cloud Control API:
+ Cloud Control API performs each resource operation individually and independently of any other resource operations.
+ A single resource operation request to Cloud Control API might actually consist of multiple calls to the underlying service that provisions the resource. Because of this, a resource request might fail when only partially completed, resulting in only some of the requested changes being applied to the resource.
+ If a resource operation fails at any point, Cloud Control API doesn't roll back the resource to its previous state.
+ You can only perform one resource operation at a time on a given resource using Cloud Control API. However, the resource can still be operated on directly, through the underlying service that provisioned it. We strongly recommend against this approach because it may lead to unpredictable behavior.
# Creating a resource with AWS Cloud Control API
Use the `create-resource` command to create a resource.
## Composing the desired state of the resource
For Cloud Control API to create a resource, you must specify the *desired state* of the resource you want to create. The desired state consists of a listing of the resource properties that you want to specify, and their desired values.
The properties of a resource are defined in its resource type schema. This includes whether the property is required, valid values, and other property constraints. For more information about viewing resource property definitions, see [Viewing resource type schemas](resource-types.md#resource-types-schemas).
The desired state that you specify must be valid against the resource type schema.
As an example, suppose you wanted to create an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html) resource with a specific name and a retention policy of 90 days. As a first step, you must compose the desired state of the resource, formatted as JSON text.
```
{
"LogGroupName": "CloudApiLogGroup",
"RetentionInDays": 90
}
```
When you call the `create-resource` command, you can pass the desired state directly inline as a string, or, for more complicated desired state definitions, specify a file location.
The following AWS Command Line Interface (AWS CLI) command creates the resource and specifies in the `desired-state` parameter that the `RetentionInDays` property of the resource is set to `90`, in addition to specifying the log group name.
```
$ aws cloudcontrol create-resource --type-name AWS::Logs::LogGroup \
--desired-state '{"LogGroupName": "CloudApiLogGroup", "RetentionInDays":90}'
```
## Tracking the progress of a create resource request
The `create-resource` command returns a `ProgressEvent` object that you can use to monitor the current status of your resource create request. For more information, see [Tracking the progress of resource operation requests](resource-operations-manage-requests.md#resource-operations-manage-requests-track).
# Updating a resource with AWS Cloud Control API
Use the `update-resource` command to make updates to an existing resource. This includes resources that weren't originally provisioned using Cloud Control API.
**Important**
We strongly advise against using Cloud Control API to update resources that are under active management by other services. Doing so can lead to unexpected results. For example, don't use Cloud Control API to update resources that are currently part of an CloudFormation stack.
To update an existing resource, you must specify the resource's identifier. For more information about determining a resource's identifier, see [Using a resource's primary identifier](resource-identifier.md#resource-identifier-using).
Updating a resource entails changing resource property values. The properties of a resource are defined in its resource type schema. This includes whether the property is required, valid values, and other property constraints. For more information about viewing resource property definitions, see [Viewing resource type schemas](resource-types.md#resource-types-schemas).
## Composing the patch document
To update a resource, you first define the updates as a list of *patch operations* contained in a JSON patch document. This patch document must adhere to the standard defined in [https://datatracker.ietf.org/doc/html/rfc6902](https://datatracker.ietf.org/doc/html/rfc6902).
Each patch operation defines a single update to a specific resource property. The following properties are required:
+ `op`: The operation type. Cloud Control API supports all operations defined in RFC 6902: `add`, `remove`, `replace`, `move`, `copy`, and `test`.
+ `path`: The path to the resource property, relative to the `properties` section of the resource schema.
Depending on the operation, additional properties may be required. Refer to RFC 6902 for specifics.
When using the `update-resource` command, you can specify the patch document inline as a string, or specify a file location.
The following example updates the retention policy of an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html) resource named `CloudControlApiLogGroup` to 90 days.
```
$ aws cloudcontrol update-resource --type-name AWS::Logs::LogGroup \
--identifier CloudControlApiLogGroup \
--patch-document '[{"op":"replace","path":"RetentionInDays","value":90}]'
```
## How Cloud Control API updates resources
To update a resource, Cloud Control API first retrieves the current state of the resource and then updates the resource in a two-step process:
+ Cloud Control API combines the patch operations specified in the update request with the current state of the resource, to generate the desired state of the resource after it's updated. Operations are applied sequentially in the order that they appear in the patch document. Each operation in the sequence is applied to the resource's current state; the resulting resource state becomes the target of the next operation.
At this point, the entire update request fails if:
+ A patch operation included in the request is invalid.
+ A patch operation of `op` type `test` fails.
In such cases, the entire update request fails and Cloud Control API makes no updates to the resource.
+ Cloud Control API then calls the update handler of the resource type to update the resource.
If the update handler fails at any point, *Cloud Control API does not roll back the resource to its previous state.*
For example, consider the following patch document that is defined to update an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html) resource. The document contains two patch operations. The first operation is of type `test` and checks to see if the resource's retention policy is set to 3653 days. If that is the case, the resource passes the test and Cloud Control API proceeds to the next operation. This operation replaces the current retention policy value with 180 days. If the resource's retention policy is set to a value of other than 3653 days, the first `test` operation fails and Cloud Control API never runs the second `replace` operation.
```
[
{
"op": "test",
"path": "/RetentionInDays",
"value":3653
},
{
"op": "replace",
"path": "/RetentionInDays",
"value":180
}
]
```
## Tracking the progress of an update resource request
The `update-resource` command returns a `ProgressEvent` object that you can use to track the current status of your resource operation request. For more information, see [Tracking the progress of resource operation requests](resource-operations-manage-requests.md#resource-operations-manage-requests-track).
# Deleting a resource with AWS Cloud Control API
Use the `delete-resource` command to delete an existing resource. You can delete the resource whether or not the resource was originally provisioned using Cloud Control API.
**Important**
We strongly advise against using Cloud Control API to delete resources that are under active management by other services. Doing so can lead to unexpected results. For example, don't use Cloud Control API to delete resources that are currently part of an CloudFormation stack.
To update an existing resource, you must specify the resource's identifier. For more information about finding a resource's identifier, see [Using a resource's primary identifier](resource-identifier.md#resource-identifier-using).
The follow example deletes an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html) resource with the name of `CloudControlApiLogGroup`.
```
$ aws cloudcontrol delete-resource \
--type-name AWS::Logs::LogGroup --identifier CloudControlApiLogGroup
```
## Tracking the progress of a delete resource request
The `delete-resource` command returns a `ProgressEvent` object that you can use to track the current status of your resource operation request. For more information, see [Tracking the progress of resource operation requests](resource-operations-manage-requests.md#resource-operations-manage-requests-track).
# Discovering resources with AWS Cloud Control API
Use the `list-resources` command to discover the resources currently provisioned in your AWS account and AWS Region. This includes all resources of the specified resource type, regardless of whether they were provisioned through Cloud Control API, directly through the underlying service, or other mechanism (such as being part of an AWS CloudFormation stack).
The information returned for each resource includes:
+ The resource's primary identifier.
+ Optionally, it may include the *part or all* resource's properties, detailing the current state of the resource. For more information, see [Viewing resource type schemas](resource-types.md#resource-types-schemas).
The follow example returns a list of `AWS::Logs::LogGroup` resources.
```
$ aws cloudcontrol list-resources --type-name AWS::Logs::LogGroup
```
Cloud Control API returns a list of the resources in your account of the specified resource type. For the example , `list-resources` returns the primary identifier and resource properties of all `AWS::Logs::LogGroup` resources in your account, regardless of whether they were provisioned by Cloud Control API. The returned information resembles the following, depending on the resources in your account.
```
{
"TypeName": "AWS::Logs::LogGroup",
"ResourceDescriptions":
[
{
"Identifier": "CloudControlExample",
"Properties": '{"RetentionInDays":180, "LogGroupName": "CloudControlExample", "Arn": "arn:aws:logs:us-west-2:123456789012:log-group:CloudControlExample:*"}'
},
{
"Identifier": "AnotherLogGroupResourceExample",
"Properties": '{"RetentionInDays":90, "LogGroupName": "AnotherLogGroupResourceExample", "Arn": "arn:aws:logs:us-west-2:123456789012:log-group:AnotherLogGroupResourceExample:*"}'
}
]
}
```
The follow example requests a list of `AWS::Kinesis::Stream` resources.
```
$ aws cloudcontrol list-resources --type-name AWS::Kinesis::Stream
```
For Kinesis streams, Cloud Control API returns the primary identifier of each stream, along with a *subset* of the resource properties. In this case, just a single property, `Name`. You could then use a stream's primary identifier with `get-resource` to request the resource's full current state.
```
{
"TypeName": "AWS::Kinesis::Stream",
"ResourceDescriptions": [
{
"Identifier": "MyKinesisStream",
"Properties": '{"Name": "MyKinesisStream"}'
},
{
"Identifier": "AnotherStream",
"Properties": '{"Name": "AnotherStream"}'
}
]
}
```
## Resources that require additional information
Certain resources require that you provide additional information about the resources that you want to list as part of your request. In these cases, you must use the `ResourceModel` parameter to specify these properties.
The table below lists these resources, and the properties you to specify in the `ResourceModel` parameter during list requests.
| Resources | Required properties |
| --- | --- |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-documentationversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-documentationversion.html) | `RestApiId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html) | `RestApiId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-resourceversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-resourceversion.html) | `TypeArn` or `TypeName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-integration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-integration.html) | `DomainName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-objecttype.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-objecttype.html) | `DomainName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupmember.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupmember.html) | `TransitGatewayMulticastDomainId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupsource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupsource.html) | `TransitGatewayMulticastDomainId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskset.html) | `Cluster`, `Service`, and `ID` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-addon.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-addon.html) | `ClusterName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-fargateprofile.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-fargateprofile.html) | `ClusterName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listener.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listener.html) | `LoadBalancerArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listenerrule.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listenerrule.html) | `ListenerArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversion.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/resource-operations-list.html) |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversionmetadata.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversionmetadata.html) | `SchemaVersionId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-accesspolicy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-accesspolicy.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/resource-operations-list.html) |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-dashboard.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-dashboard.html) | `ProjectId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-project.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-project.html) | `PortalId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-datasource.html) | `IndexId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-faq.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-faq.html) | `IndexId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowentitlement.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowentitlement.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowoutput.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowoutput.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowsource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowsource.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowvpcinterface.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowvpcinterface.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-asset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-asset.html) | `PackagingGroupId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-packagingconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-packagingconfiguration.html) | `PackagingGroupId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-networkfirewall-loggingconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-networkfirewall-loggingconfiguration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/resource-operations-list.html) |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-analysis.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-analysis.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dashboard.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dashboard.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dataset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dataset.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-datasource.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-template.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-template.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-theme.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-theme.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxytargetgroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxytargetgroup.html) | `DBProxyName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-accesspoint.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-accesspoint.html) | `Bucket` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-bucket.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-bucket.html) | `OutpostId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-assignment.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-assignment.html) | `InstanceArn`, `PermissionSetArn`, `PrincipalId`, `PrincipalType`, `TargetId`, and `TargetType` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-instanceaccesscontrolattributeconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-instanceaccesscontrolattributeconfiguration.html) | `InstanceArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-permissionset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-permissionset.html) | `InstanceArn` and `PermissionSetArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html) | `Scope` |
# Reading a resource with AWS Cloud Control API
Using a resource's primary identifier, you can call the `get-resource` command to retrieve detailed information about the resource. For information about retrieving a resource's primary identifier, see [Identifying resources with AWS Cloud Control API](resource-identifier.md).
The information returned by `get-resource` includes the resource's schema, which details the current state of the resource, including property values, supported events, and necessary permissions. For more information, see [Viewing resource type schemas](resource-types.md#resource-types-schemas).
The following example returns the current state of an `AWS::Logs::LogGroup` resource named `LogGroupResourceExample`. For `AWS::Logs::LogGroup` resources, the name of a log group is its primary identifier.
```
$ aws cloudcontrol get-resource --type-name AWS::Logs::LogGroup --identifier LogGroupResourceExample
```
# Managing resource operation requests with AWS Cloud Control API
Because resource operations are asynchronous, resource requests such as `create-resource` and `update-resource` return a `ProgressEvent` object that contains information about the current state of your resource create or update request.
For example, a resource create request might initially return the following `ProgressEvent` object.
```
{
"ProgressEvent": {
"EventTime": "2021-08-09T18:17:15.219Z",
"TypeName": "AWS::Logs::LogGroup",
"OperationStatus": "IN_PROGRESS",
"Operation": "CREATE",
"Identifier": "LogGroupResourceExample",
"RequestToken": "5f40c577-3534-4b20-9599-0b0123456789"
}
}
```
The information returned in the `ProgressEvent` object includes a request token that you can then use to track or cancel a resource operation request.
**Note**
Resource operation requests expire after seven days.
## Listing active resource operation requests
Use the `list-resource-requests` command to return a list of active resource operation requests for an AWS account and AWS Region. You can filter the list by request type and status.
Resource operation requests expire after seven days.
The following example returns active resource operation requests, but it filters out any resource create requests that are still in progress.
```
$ aws cloudcontrol list-resource-requests --resource-request-status-filter \
Operations=CREATE,OperationStatuses=IN_PROGRESS
```
The information returned for each resource operation includes a request token that you can then use to track or cancel a resource operation request.
```
{
"ResourceRequestStatusSummaries": [
{
"EventTime": "2021-08-09T18:17:16.591Z",
"TypeName": "AWS::Logs::LogGroup",
"OperationStatus": "SUCCESS",
"Operation": "CREATE",
"Identifier": "LogGroupResourceExample",
"RequestToken": "5f40c577-3534-4b20-9599-0b0123456789"
}
]
}
```
## Tracking the progress of resource operation requests
Use the `get-resource-request-status` command to track the progress of your resource operation request. This command takes the request token included in the `ProgressEvent` object generated during the initial resource operation request. (You can also retrieve the request token for a resource operation request using the `list-resource-requests` command.) The `get-resource-request-status` command returns an updated `ProgressEvent` object containing information on the current state of the request.
See the following example.
```
$ aws cloudcontrol get-resource-request-status \
--request-token 5f40c577-3534-4b20-9599-0b0123456789
```
## Canceling resource operation requests
Use the `cancel-resource-request` command to cancel a resource operation request that is currently in progress. Because you can only perform a single operation on a given resource at a time, there might be cases where you need to cancel the current resource operation to make the resource available so that another operation may be performed on it.
Canceling a resource request does not guarantee that Cloud Control API can immediately cancel all resource operations. Rather, Cloud Control API will stop making further calls to the resource event handler. A single resource operation request to Cloud Control API might actually consist of multiple calls to the underlying service that provisions the resource. Because of this, canceling a resource operation request might leave the request partially completed, resulting in only some of the requested changes being applied to the resource. Cloud Control API doesn't roll back the resource to its previous state.
Only resource operations requests with a status of `PENDING` or `IN_PROGRESS` can be canceled.
**Note**
Although calling `CancelResourceRequest` cancels operations performed by Cloud Control API, it doesn't terminate any asynchronous operations that may have already started on downstream services.
# Identifying resources with AWS Cloud Control API
Every resource type has a property that is defined as its *primary identifier*. The value of this property must be unique for each resource of that type in a given AWS account and AWS Region. For example, many resource types include a `Name` property that must be unique for each resource of that type. In some cases, the primary identifier is defined as a combination of multiple properties that together form a unique identifier. By using this primary identifier, combined with the resource type, you can specify exactly which resource on which you want to perform resource operations such as `update-resource` or `delete-resource`.
In addition, some resource types define *secondary identifiers* that can also be used to uniquely identify resources of that type.
To determine which resource property (or combination of properties) is the primary identifier for a resource type, refer to the `primaryIdentifier` attribute of the resource type schema. The schema includes secondary identifiers defined, as well. For more information, see [Viewing resource type schemas](resource-types.md#resource-types-schemas).
## Getting a resource's primary identifier
You can find the identifier *value* for a specific resource by using Cloud Control API commands. Each of the following commands returns a `ProgressEvent` object that contains the primary identifier of the specified resources:
+
```
cancel-resource-request
```
+
```
create-resource
```
+
```
get-resource-request-status
```
+
```
list-resource-requests
```
## Using a resource's primary identifier
When using Cloud Control API commands, you can specify the primary identifier or any secondary identifier defined for the resource type in its resource schema. You can only specify one identifier. Primary identifiers can be specified as a string or JSON; secondary identifiers must be specified as JSON.
For compound primary identifiers (that is, one that consists of multiple resource properties strung together), to specify the primary identifier as a string, list the property values *in the order that they are specified* in the primary identifier definition, separated by `|`.
For example, the primary identifier for the resource is defined as:
`"primaryIdentifier": [ "/properties/DatabaseName", "/properties/TableName" ]`
So, to specify the primary identifier of a resource as a string, you use the following format.
`DatabaseName|TableName`
For example, given a database with a database name of `MyDatabase` and table name of `MyTable`, you specify `MyDatabase|MyTable`.
For compound identifiers specified as JSON, property order is not required, as shown in the following example.
```
{
"TableName": "MyTable",
"DatabaseName": "MyDatabase"
}
```
For more information about resource identifiers, see [primaryidentifier](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-primaryidentifier) in the *CloudFormation Command Line Interface User Move for Extension Development*.