Resource Groups Tagging API

(1)

Resource Groups Tagging API

API Reference

(2)

Resource Groups Tagging API: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

AWS Resource Groups Tagging API Reference

This guide describes the API operations for AWS Resource Groups Tagging.

A tag is a label that you assign to an AWS resource. A tag consists of a key and a value, both of which you deﬁne. For example, if you have two Amazon EC2 instances, you might assign both a tag key of "Stack."

But the value of "Stack" might be "Testing" for one and "Production" for the other.

AWS supports tagging on all core infrastructure resources that incur charges. Most other AWS resources also support tagging. Some resources support tagging only through that service's native tagging operations, and don't yet support this API. See the documentation for an individual service for information about that service's native tagging operations.

Important

Do not store personally identiﬁable information (PII) or other conﬁdential or sensitive

information in tags. We use tags to provide you with billing and administration services. Tags are not intended to be used for private or sensitive data.

Tagging can help you organize your resources and enables you to simplify resource management, access management and cost allocation.

For information about tagging your AWS resources, including strategies and techniques, see Tagging AWS resources in the Amazon Web Services General Reference.

You can use the Resource Groups Tagging API operations to complete the following tasks:

• Tag and untag supported resources located in the speciﬁed Region for the AWS account.

• Use tag-based ﬁlters to search for resources located in the speciﬁed Region for the AWS account.

• List all existing tag keys in the speciﬁed Region for the AWS account.

• List all existing values for the speciﬁed key in the speciﬁed Region for the AWS account.

To use Resource Groups Tagging API operations, you must add the following permissions to your IAM policy:

• tag:GetResources

• tag:TagResources

• tag:UntagResources

• tag:GetTagKeys

• tag:GetTagValues

You'll also need permissions to access the resources of individual services so that you can tag and untag those resources.

For more information on IAM policies, see Managing IAM Policies in the IAM User Guide.

(6)

Services that support the Resource Groups Tagging API

You can use the Resource Groups Tagging API to tag resources for the following AWS services.

NoteThis list includes only those AWS services that work with the Resource Groups Tagging API.

If an AWS service isn't listed below, you might still be able to tag that service's resources by using the service's native tagging operations instead of using the Resource Groups Tagging API operations. See the documentation for an individual service for information about that service's native tagging operations.

This lets you tag resources by using the AWS CLI version of the service's operation. For example, you could tag an IAM user by using a command similar to the following example:

$ aws iam tag-user --user-name kristy --tags Key=CostCenter,Value=1234

For a list of the AWS services that work with Tag Editor, see Supported Resources in the AWS Resource Groups User Guide.

• Alexa for Business

• Amazon API Gateway

• Amazon AppFlow

• Amazon AppStream

• AWS AppSync

• AWS App Mesh

• Amazon Athena

• AWS Audit Manager

• Amazon Aurora

• Auto Scaling

The TagResources and UntagResources operations of AWS Resource Groups Tagging API work as documented with Auto Scaling Groups. However, the GetTagKey, GetTagValues and GetResources operations aren't supported at this time and return an empty response for this service.

• AWS Backup

• AWS Batch

• Amazon Braket

• AWS Certiﬁcate Manager

• AWS Certiﬁcate Manager Private Certiﬁcate Authority

• Amazon Cloud Directory

• AWS Cloud Map

• AWS CloudFormation

• Amazon CloudFront

• AWS CloudHSM

• AWS CloudTrail

• Amazon CloudWatch (alarms only)

• Amazon CloudWatch Events

(7)

• Amazon CloudWatch Logs

• Amazon CloudWatch Synthetics

• AWS CodeArtifact

• AWS CodeBuild

• AWS CodeCommit

• Amazon CodeGuru Proﬁler

• Amazon CodeGuru Reviewer

• AWS CodePipeline

• AWS CodeStar

• AWS CodeStar connections

• Amazon Cognito Identity

• Amazon Cognito user pools

• Amazon Comprehend

• AWS Conﬁg

• Amazon Connect

• AWS Data Exchange

• AWS Data Pipeline

• AWS Database Migration Service

• AWS DataSync

• AWS Device Farm

• AWS Direct Connect

• AWS Directory Service

• Amazon DynamoDB

• Amazon Elastic Block Store (Amazon EBS)

• Amazon Elastic Compute Cloud (Amazon EC2)

• EC2 Image Builder

• Amazon Elastic Container Registry (Amazon ECR)

• Amazon Elastic Container Service (Amazon ECS)

• Amazon Elastic Kubernetes Service (Amazon EKS)

• AWS Elastic Beanstalk

• Amazon Elastic File System (Amazon EFS)

• Elastic Load Balancing

• Amazon Elastic Inference

• Amazon ElastiCache

• AWS Elemental MediaLive

• AWS Elemental MediaPackage

• AWS Elemental MediaPackage VoD

• AWS Elemental MediaTailor

• Amazon EMR

• Amazon EMR on EKS (EMR containers)

• Amazon EventBridge Schema

• AWS Firewall Manager

• Amazon Forecast

• Amazon Fraud Detector

• Amazon FSx

• Amazon GameLift

(8)

• Amazon S3 Glacier

• AWS Global Accelerator

• AWS Ground Station

• AWS Glue

• Amazon GuardDuty

• AWS Identity and Access Management (IAM) – at this time, you can tag only the following IAM resources using the Resource Groups Tagging API:

• instance-profile

• mfa

• oidc-provider

• policy

• saml-provider

• server-certificate

• Amazon Inspector

• Amazon Interactive Video Service

• AWS IoT Analytics

• AWS IoT Core

• AWS IoT Device Defender

• AWS IoT Device Management

• AWS IoT Events

• AWS IoT Greengrass

• AWS IoT 1-Click – at this time, you can tag only the following AWS IoT 1-Click resources using the Resource Groups Tagging API:

• projects

• devices

• AWS IoT SiteWise IoT Sitewise

• AWS IoT Things Graph

• AWS IoT Wireless

• Amazon Kendra

• AWS Key Management Service (AWS KMS)

• Amazon Kinesis

• Amazon Kinesis Data Analytics

• Amazon Kinesis Data Firehose

• AWS Lambda

• Amazon Lex

• AWS License Manager

• Amazon Lightsail

• Amazon Macie

• Amazon Machine Learning

• Amazon Managed Blockchain

• Amazon MQ

• Amazon Managed Streaming for Apache Kafka (Amazon MSK)

• Amazon Neptune

• AWS Network Manager

• Amazon OpenSearch Service

• AWS OpsWorks

(9)

• AWS OpsWorks CM

• AWS Organizations

• AWS Outposts

• Amazon Pinpoint

• Amazon Quantum Ledger Database (Amazon QLDB)

• Amazon Relational Database Service (Amazon RDS)

• Amazon Redshift

• AWS Resource Access Manager

• AWS Resource Groups

• AWS RoboMaker

• Amazon Route 53

• Amazon Route 53 Resolver

• Amazon Simple Storage Service (Amazon S3) (buckets only)

• Amazon SageMaker

• Savings Plans

• AWS Secrets Manager

• AWS Security Hub

• AWS Service Catalog

• Service Quotas

• Amazon Simple Email Service (Amazon SES)

• Amazon Simple Notiﬁcation Service (Amazon SNS)

• Amazon Simple Queue Service (Amazon SQS)

• Amazon Simple Workﬂow Service

• AWS Step Functions

• AWS Storage Gateway

• AWS Systems Manager

• AWS Transfer for FTP

• Amazon Virtual Private Cloud (Amazon VPC)

• AWS WAF

• AWS WAF Regional

• Amazon WorkLink

• Amazon WorkSpaces

• AWS X-Ray

(10)

Actions

The following actions are supported:

• DescribeReportCreation (p. 7)

• GetComplianceSummary (p. 10)

• GetResources (p. 16)

• GetTagKeys (p. 23)

• GetTagValues (p. 26)

• StartReportCreation (p. 30)

• TagResources (p. 34)

• UntagResources (p. 38)

(11)

DescribeReportCreation

Describes the status of the StartReportCreation operation.

You can call this operation only from the organization's management account and from the us-east-1 Region.

Response Syntax

{ "ErrorMessage": "string", "S3Location": "string", "Status": "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.

ErrorMessage (p. 7)

Details of the common errors that all operations return.

Type: String S3Location (p. 7)

The path to the Amazon S3 bucket where the report was stored on creation.

Type: String Status (p. 7)

Reports the status of the operation.

The operation status can be one of the following:

• RUNNING - Report creation is in progress.

• SUCCEEDED - Report creation is complete. You can open the report from the Amazon S3 bucket that you speciﬁed when you ran StartReportCreation.

• FAILED - Report creation timed out or the Amazon S3 bucket is not accessible.

• NO REPORT - No report was generated in the last 90 days.

Type: String

Errors

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

ConstraintViolationException

The request was denied because performing this operation violates a constraint.

Some of the reasons in the following list might not apply to this speciﬁc operation.

• You must meet the prerequisites for using tag policies. For information, see Prerequisites and Permissions for Using Tag Policies in the AWS Organizations User Guide.

(12)

Examples

• You must enable the tag policies service principal (tagpolicies.tag.amazonaws.com) to integrate with AWS Organizations For information, see EnableAWSServiceAccess.

• You must have a tag policy attached to the organization root, an OU, or an account.

HTTP Status Code: 400 InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the request.

HTTP Status Code: 500 InvalidParameterException

This error indicates one of the following:

• A parameter is missing.

• A malformed string was supplied for the request parameter.

• An out-of-range value was supplied for the request parameter.

• The target ID is invalid, unsupported, or doesn't exist.

• You can't access the Amazon S3 bucket for report storage. For more information, see Additional Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User Guide.

HTTP Status Code: 400 ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Examples

Example

This example illustrates one usage of DescribeReportCreation.

Sample Request

POST / HTTP/1.1

Host: tagging.us-east-1.amazonaws.com Accept-Encoding: identity

Content-Length: 20

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.DescribeReportCreation X-Amz-Date: 20191201T214524Z

User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42 Content-Type: application/x-amz-json-1.1

Authorization: AUTHPARAMS {}

Sample Response

HTTP/1.1 200 OK

(13)

See Also

x-amzn-RequestID: d3cf21f0-26db-11e7-a532-75e05382c8b1 Content-Type: application/x-amz-json-1.1

Date: Sun, 1 Dec 2019 21:45:25 GMT { "ErrorMessage":null,

"S3Location":"s3://awsexamplebucket/AwsTagPolicies/o-exampleorgid/2019-12-01- T21:45:24Z/report.csv",

"Status":"SUCCEEDED"

}

GetComplianceSummary

Returns a table that shows counts of resources that are noncompliant with their tag policies.

For more information on tag policies, see Tag Policies in the AWS Organizations User Guide.

This operation supports pagination, where the response can be sent in multiple pages. You should check the PaginationToken response parameter to determine if there are additional results available to return. Repeat the query, passing the PaginationToken response parameter value as an input to the next request until you recieve a null value. A null value for PaginationToken indicates that there are no more results waiting to be returned.

Request Syntax

{ "GroupBy": [ "string" ], "MaxResults": number, "PaginationToken": "string", "RegionFilters": [ "string" ], "ResourceTypeFilters": [ "string" ], "TagKeyFilters": [ "string" ], "TargetIdFilters": [ "string" ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 51).

The request accepts the following data in JSON format.

GroupBy (p. 10)

Speciﬁes a list of attributes to group the counts of noncompliant resources by. If supplied, the counts are sorted by those attributes.

Type: Array of strings

Valid Values: TARGET_ID | REGION | RESOURCE_TYPE Required: No

MaxResults (p. 10)

Speciﬁes the maximum number of results to be returned in each page. A query can return fewer than this maximum, even if there are more results still to return. You should always check the PaginationToken response value to see if there are more results. You can specify a minimum of 1 and a maximum value of 100.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: No

(15)

Request Parameters

PaginationToken (p. 10)

Speciﬁes a PaginationToken response value from a previous request to indicate that you want the next page of results. Leave this parameter empty in your initial request.

Type: String

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

Pattern: [\s\S]*

Required: No RegionFilters (p. 10)

Speciﬁes a list of AWS Regions to limit the output to. If you use this parameter, the count of returned noncompliant resources includes only resources in the speciﬁed Regions.

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Pattern: [\s\S]*

Required: No

ResourceTypeFilters (p. 10)

Speciﬁes that you want the response to include information for only resources of the speciﬁed types.

The format of each resource type is service[:resourceType]. For example, specifying a resource type of ec2 returns all Amazon EC2 resources (which includes EC2 instances). Specifying a resource type of ec2:instance returns only EC2 instances.

The string for each service name and resource type is the same as that embedded in a resource's Amazon Resource Name (ARN). Consult the AWS General Reference for the following:

• For a list of service name strings, see AWS Service Namespaces.

• For resource type strings, see Example ARNs.

• For more information about ARNs, see Amazon Resource Names (ARNs) and AWS Service Namespaces.

You can specify multiple resource types by using a comma separated array. The array can include up to 100 items. Note that the length constraint requirement applies to each resource type ﬁlter.

Pattern: [\s\S]*

Required: No TagKeyFilters (p. 10)

Specifies that you want the response to include information for only resources that have tags with the specified tag keys. If you use this parameter, the count of returned noncompliant resources includes only resources that have the specified tag keys.

(16)

Response Syntax

Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Required: No TargetIdFilters (p. 10)

Specifies target identifiers (usually, specific account IDs) to limit the output by. If you use this parameter, the count of returned noncompliant resources includes only resources with the specified target IDs.

Pattern: [a-zA-Z0-9-]*

Required: No

Response Syntax

{ "PaginationToken": "string", "SummaryList": [

{

"LastUpdated": "string",

"NonCompliantResources": number, "Region": "string",

"ResourceType": "string", "TargetId": "string", "TargetIdType": "string"

} ] }

Response Elements

A string that indicates that there is more data available than this response contains. To receive the next part of the response, specify this response value as the PaginationToken value in the request for the next page.

Type: String

Pattern: [\s\S]*

SummaryList (p. 12)

A table that shows counts of noncompliant resources.

Type: Array of Summary (p. 47) objects

(17)

Errors

ConstraintViolationException

Examples

Example

This example illustrates one usage of GetComplianceSummary.

Sample Request

HTTP/1.1

Content-Length: 663

(18)

See Also

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetComplianceSummary X-Amz-Date: 20191201T214524Z

Authorization: AUTHPARAMS {

"GroupBy": [ "TARGET_ID", "REGION", "RESOURCE_TYPE"

] }

Sample Response

HTTP/1.1 200 OK

Date: Sun, 1 Dec 2019 21:45:25 GMT { "SummaryList": [

{

"LastUpdated":"2019-10-28T21:53:16Z", "NonCompliantResources":1,

"Region":"us-east-1",

"ResourceType":"ec2:instance", "TargetId":"333333333333", "TargetIdType":"ACCOUNT"

}, {

"ResourceType":"ec2:snapshot", "TargetId":"222222222222", "TargetIdType":"ACCOUNT"

}, {

"ResourceType":"ec2:volume", "TargetId":"111111111111", "TargetIdType":"ACCOUNT"

} ]

}

GetResources

Returns all the tagged or previously tagged resources that are located in the speciﬁed AWS Region for the account.

Depending on what information you want returned, you can also specify the following:

• Filters that specify what tags and resource types you want returned. The response includes all tags that are associated with the requested resources.

• Information about compliance with the account's eﬀective tag policy. For more information on tag policies, see Tag Policies in the AWS Organizations User Guide.

NoteThis operation has a rate limit that speciﬁes the maximum number of times you can call it per second. For the current value of this limit, see Service Quotas for Resource Groups Tagging API in the Tag Editor Users Guide.

Request Syntax

{

"ExcludeCompliantResources": boolean, "IncludeComplianceDetails": boolean, "PaginationToken": "string",

"ResourceARNList": [ "string" ], "ResourcesPerPage": number,

"ResourceTypeFilters": [ "string" ], "TagFilters": [

{

"Key": "string", "Values": [ "string" ] }

],

"TagsPerPage": number }

Request Parameters

ExcludeCompliantResources (p. 16)

Speciﬁes whether to exclude resources that are compliant with the tag policy. Set this to true if you are interested in retrieving information on noncompliant resources only.

You can use this parameter only if the IncludeComplianceDetails parameter is also set to true.

Type: Boolean

(21)

Request Parameters

Required: No

IncludeComplianceDetails (p. 16)

Speciﬁes whether to include details regarding the compliance with the eﬀective tag policy. Set this to true to determine whether resources are compliant with the tag policy and to get details.

Type: Boolean Required: No PaginationToken (p. 16)

Type: String

Pattern: [\s\S]*

Required: No ResourceARNList (p. 16)

Speciﬁes a list of ARNs of resources for which you want to retrieve tag data.

You can't specify both this parameter and the ResourceTypeFilters parameter in the same request. If you do, you get an Invalid Parameter exception.

You can't specify both this parameter and the TagFilters parameter in the same request. If you do, you get an Invalid Parameter exception.

You can't specify both this parameter and any of the pagination parameters (ResourcesPerPage, TagsPerPage, PaginationToken) in the same request. If you do, you get an Invalid

Parameter exception.

If a resource speciﬁed by this parameter doesn't exist, it doesn't generate an error; it simply isn't included in the response.

An ARN (Amazon Resource Name) uniquely identiﬁes a resource. For more information, see Amazon Resource Names (ARNs) and AWS Service Namespaces in the AWS General Reference.

Pattern: [\s\S]*

Required: No

ResourcesPerPage (p. 16)

Speciﬁes the maximum number of results to be returned in each page. A query can return fewer than this maximum, even if there are more results still to return. You should always check the PaginationToken response value to see if there are more results. You can specify a minimum of 1 and a maximum value of 100.

Type: Integer

(22)

Request Parameters

Required: No

ResourceTypeFilters (p. 16)

Speciﬁes the resource types that you want included in the response. The format of each resource type is service[:resourceType]. For example, specifying a resource type of ec2 returns all Amazon EC2 resources (which includes EC2 instances). Specifying a resource type of ec2:instance returns only EC2 instances.

You can't specify both this parameter and the ResourceArnList parameter in the same request. If you do, you get an Invalid Parameter exception.

The string for each service name and resource type is the same as that embedded in a resource's Amazon Resource Name (ARN). For the list of services whose resources you can use in this parameter, see Services that support the Resource Groups Tagging API.

You can specify multiple resource types by using an array. The array can include up to 100 items.

Note that the length constraint requirement applies to each resource type ﬁlter. For example, the following string would limit the response to only Amazon EC2 instances, Amazon S3 buckets, or any AWS Audit Manager resource:

ec2:instance,s3:bucket,auditmanager Type: Array of strings

Pattern: [\s\S]*

Required: No TagFilters (p. 16)

Specifies a list of TagFilters (keys and values) to restrict the output to only those resources that have tags with the specified keys and, if included, the specified values. Each TagFilter must contain a key with values optional. A request can include up to 50 keys, and each key can include up to 20 values.

You can't specify both this parameter and the ResourceArnList parameter in the same request. If you do, you get an Invalid Parameter exception.

Note the following when deciding how to use TagFilters:

• If you don't specify a TagFilter, the response includes all resources that are currently tagged or ever had a tag. Resources that currently don't have tags are shown with an empty tag set, like this:

"Tags": [].

• If you specify more than one ﬁlter in a single request, the response returns only those resources that satisfy all ﬁlters.

• If you specify a ﬁlter that contains more than one value for a key, the response returns resources that match any of the speciﬁed values for that key.

• If you don't specify a value for a key, the response returns all resources that are tagged with that key, with any or no value.

For example, for the following ﬁlters: filter1= {keyA,{value1}}, filter2={keyB, {value2,value3,value4}}, filter3= {keyC}:

• GetResources({filter1}) returns resources tagged with key1=value1

• GetResources({filter2}) returns resources tagged with key2=value2 or key2=value3 or key2=value4

• GetResources({filter3}) returns resources tagged with any tag with the key key3, and with any or no value

(23)

Response Syntax

• GetResources({filter1,filter2,filter3}) returns resources tagged with

(key1=value1) and (key2=value2 or key2=value3 or key2=value4) and (key3, any or no value)

Type: Array of TagFilter (p. 50) objects

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: No TagsPerPage (p. 16)

AWS recommends using ResourcesPerPage instead of this parameter.

A limit that restricts the number of tags (key and value pairs) returned by GetResources in paginated output. A resource with no tags is counted as having one tag (one key and value pair).

GetResources does not split a resource and its associated tags across pages. If the specified TagsPerPage would cause such a break, a PaginationToken is returned in place of the affected resource and its tags. Use that token in another request to get the remaining data. For example, if you specify a TagsPerPage of 100 and the account has 22 resources with 10 tags each (meaning that each resource has 10 key and value pairs), the output will consist of three pages. The first page displays the first 10 resources, each with its 10 tags. The second page displays the next 10 resources, each with its 10 tags. The third page displays the remaining 2 resources, each with its 10 tags.

You can set TagsPerPage to a minimum of 100 items up to a maximum of 500 items.

Type: Integer Required: No

Response Syntax

{ "PaginationToken": "string", "ResourceTagMappingList": [ {

"ComplianceDetails": {

"ComplianceStatus": boolean,

"KeysWithNoncompliantValues": [ "string" ], "NoncompliantKeys": [ "string" ]

},

"ResourceARN": "string", "Tags": [

{

"Key": "string", "Value": "string"

} ] } ]}

Response Elements

(24)

Errors

Type: String

Pattern: [\s\S]*

ResourceTagMappingList (p. 19)

A list of resource ARNs and the tags (keys and values) associated with each.

Type: Array of ResourceTagMapping (p. 46) objects

Errors

InternalServiceException

PaginationTokenExpiredException

A PaginationToken is valid for a maximum of 15 minutes. Your request was denied because the speciﬁed PaginationToken has expired.

Examples

Example

This example illustrates one usage of GetResources.

(25)

See Also

Sample Request

POST / HTTP/1.1

Host: tagging.us-west-2.amazonaws.com Accept-Encoding: identity

Content-Length: 80

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetResources X-Amz-Date: 20191201T214524Z

"ExcludeCompliantResources": null, "IncludeComplianceDetails": true, "PaginationToken":" 1

}

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 14bc735b-26da-11e7-a933-67e2d2f3ef37 Content-Type: application/x-amz-json-1.1

Content-Length: 4060

Date: Sun, 1 Dec 2019 21:45:25 GMT {

"PaginationToken": "", "ResourceTagMappingList": [ {

"ComplianceDetails": { "ComplianceStatus":true,

"KeysWithNoncompliantValues":[], "NoncompliantKeys":[]

},

"ResourceARN": "arn:aws:inspector:us-west-2:123456789012:target/0-nvgVhaxX/

template/0-7sbz2Kz0", "Tags": []

} ]

}

GetTagKeys

Returns all tag keys currently in use in the speciﬁed AWS Region for the calling account.

Request Syntax

{

"PaginationToken": "string"

}

Request Parameters

Type: String

Pattern: [\s\S]*

Required: No

Response Syntax

{

"PaginationToken": "string", "TagKeys": [ "string" ] }

Response Elements

(28)

Errors

Type: String

Pattern: [\s\S]*

TagKeys (p. 23)

A list of all tag keys in the AWS account.

Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Errors

Examples

Example

This example illustrates one usage of GetTagKeys.

(29)

See Also

Sample Request

POST / HTTP/1.1

Content-Length: 2

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetTagKeys X-Amz-Date: 20170421T214126Z

Authorization: AUTHPARAMS {}

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 462f0799-26db-11e7-a88c-a74e0c5622c9 Content-Type: application/x-amz-json-1.1

Content-Length: 79

Date: Fri, 21 Apr 2017 21:41:27 GMT {

"PaginationToken": "", "TagKeys": [

"Example", "Example1", "Example2"

] }

GetTagValues

Returns all tag values for the speciﬁed key that are used in the speciﬁed AWS Region for the calling account.

Request Syntax

{ "Key": "string",

"PaginationToken": "string"

}

Request Parameters

Key (p. 26)

Speciﬁes the tag key for which you want to list all existing values that are currently used in the speciﬁed AWS Region for the calling account.

Type: String

Pattern: [\s\S]*

Required: Yes PaginationToken (p. 26)

Type: String

Pattern: [\s\S]*

Required: No

Response Syntax

{

"PaginationToken": "string", "TagValues": [ "string" ]

(31)

Response Elements

}

Response Elements

Type: String

Pattern: [\s\S]*

TagValues (p. 26)

A list of all tag values for the speciﬁed key currently used in the speciﬁed AWS Region for the calling account.

Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Errors

(32)

Examples

Example

This example illustrates one usage of GetTagValues.

Sample Request

POST / HTTP/1.1

Content-Length: 18

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetTagValues X-Amz-Date: 20170421T214524Z

"Key": "Example_key"

}

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: d3cf21f0-26db-11e7-a532-75e05382c8b1 Content-Type: application/x-amz-json-1.1

Content-Length: 42

Date: Fri, 21 Apr 2017 21:45:25 GMT { "PaginationToken": "",

"TagValues": [ "Example_value"

] }

StartReportCreation

Generates a report that lists all tagged resources in the accounts across your organization and tells whether each resource is compliant with the eﬀective tag policy. Compliance data is refreshed daily. The report is generated asynchronously.

The generated report is saved to the following location:

s3://example-bucket/AwsTagPolicies/o-exampleorgid/YYYY-MM-ddTHH:mm:ssZ/

report.csv

Request Syntax

{ "S3Bucket": "string"

}

Request Parameters

S3Bucket (p. 30)

The name of the Amazon S3 bucket where the report will be stored; for example:

awsexamplebucket

For more information on S3 bucket requirements, including an example bucket policy, see the example S3 bucket policy on this page.

Type: String

Pattern: [a-z0-9.-]*

Required: Yes

Response Elements

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

Errors

ConcurrentModiﬁcationException

The target of the operation is currently being modiﬁed by a diﬀerent request. Try again later.

(35)

Examples

HTTP Status Code: 400 ConstraintViolationException

Examples

Sample Amazon S3 policy

Before creating the report, you must grant access for the tag policies service principal to an Amazon S3 bucket for report storage. Attach the following bucket policy to the bucket. The statements in the Condition element ensure that the operations can be performed only by the management account of the speciﬁed organization. If you don't know your organization ID or your management account's ID, you can call DescribeOrganization to ﬁnd it.

{ "Version": "2012-10-17", "Statement": [

{

"Sid": "TagPolicyACL", "Effect": "Allow", "Principal": {

(36)

Examples

"Service": [

"tagpolicies.tag.amazonaws.com"

] },

"Action": "s3:GetBucketAcl",

"Resource": "arn:aws:s3:::your-bucket-name", "Condition": {

"StringEquals": {

"aws:SourceAccount": "your-org-management-account-id",

"aws:SourceArn": "arn:aws:tag:us-east-1:your-org-management-account- id:*"

} } }, {

"Sid": "TagPolicyBucketDelivery", "Effect": "Allow",

"Principal": { "Service": [

"tagpolicies.tag.amazonaws.com"

] },

"Action": [

"s3:PutObject", "s3:PutObjectAcl"

],

"Resource": "arn:aws:s3:::<your-bucket-name>/AwsTagPolicies/<your-org-id>/*", "Condition": {

"StringEquals": {

"aws:SourceAccount": "<your-org-management-account-id>",

"aws:SourceArn": "arn:aws:tag:us-east-1:<your-org-management-account- id>:*"

} } } ] }

Sample KMS Key Policy

If you choose to use a customer managed KMS key, you must grant access for the tag policies service principal before creating the report. Add the following Statement to your current KMS key policy.

The statements in the Condition element ensure that the operations can be performed only by the management account of the speciﬁed organization. If you don't know your organization ID or your organization admin account ID, you can call the DescribeOrganization operation to ﬁnd it.

...{

"Sid": "AllowBucketAccessKMSPolicy", "Effect": "Allow",

"Principal": {

"Service": "tagpolicies.tag.amazonaws.com"

},

"Action": [ "kms:Decrypt",

"kms:GenerateDataKey*"

],

"Resource": "arn:aws:kms:<region>:<your-kms-key-arn>", "Condition": {

"StringEquals": {

"aws:SourceAccount": "<org-admin-account-id>",

"aws:SourceArn": "arn:aws:tag:us-east-1:<org-admin-account-id>:*"

}

(37)

See Also

} }

Example

This example illustrates one usage of StartReportCreation.

Sample Request

POST / HTTP/1.1

Content-Length: 20

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.StartReportCreation X-Amz-Date: 20191201T214524Z

"S3Bucket": "awsexamplebucket"

}

Sample Response

HTTP/1.1 200 OK

Date: Sun, 1 Dec 2019 21:45:25 GMT {}

TagResources

Applies one or more tags to the speciﬁed resources. Note the following:

• Not all resources can have tags. For a list of services with resources that support tagging using this operation, see Services that support the Resource Groups Tagging API. If the resource doesn't yet support this operation, the resource's service might support tagging using its own API operations. For more information, refer to the documentation for that service.

• Each resource can have up to 50 tags. For other limits, see Tag Naming and Usage Conventions in the AWS General Reference.

• You can only tag resources that are located in the speciﬁed AWS Region for the AWS account.

• To add tags to a resource, you need the necessary permissions for the service that the resource belongs to as well as permissions for adding tags. For more information, see the documentation for each service.

Important

Do not store personally identiﬁable information (PII) or other conﬁdential or sensitive

information in tags. We use tags to provide you with billing and administration services. Tags are not intended to be used for private or sensitive data.

Minimum permissions

In addition to the tag:TagResources permission required by this operation, you must also have the tagging permission deﬁned by the service that created the resource. For example, to tag an Amazon EC2 instance using the TagResources operation, you must have both of the following permissions:

• tag:TagResource

• ec2:CreateTags

Note

In addition, some services might have speciﬁc requirements for tagging some resources. For example, to tag an Amazon S3 bucket, you must also have the s3:GetBucketTagging permission. If the expected minimum permissions don't work, check the documentation for that service's tagging APIs for more information.

Request Syntax

{ "ResourceARNList": [ "string" ], "Tags": {

"string" : "string"

} }

Request Parameters

ResourceARNList (p. 34)

Speciﬁes the list of ARNs of the resources that you want to apply tags to.

(39)

Response Syntax

Pattern: [\s\S]*

Required: Yes Tags (p. 34)

Specifies a list of tags that you want to add to the specified resources. A tag consists of a key and a value that you define.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Required: Yes

Response Syntax

{ "FailedResourcesMap": { "string" : {

"ErrorCode": "string", "ErrorMessage": "string", "StatusCode": number }

}}

Response Elements

FailedResourcesMap (p. 35)

A map containing a key-value pair for each failed item that couldn't be tagged. The key is the ARN of the failed resource. The value is a FailureInfo object that contains an error code, a status code, and an error message. If there are no errors, the FailedResourcesMap is empty.

Type: String to FailureInfo (p. 44) object map

(40)

Errors

Key Pattern: [\s\S]*

Errors

Examples

Example

This example illustrates one usage of TagResources.

Sample Request

POST / HTTP/1.1

Content-Length: 82

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.TagResources X-Amz-Date: 20170421T214834Z

Authorization: AUTHPARAMS { "ResourceARNList": [

"arn:aws:s3:::example_bucket"

], "Tags": {

"key": "Example_key"

}

(41)

See Also

}

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 45352206-26dc-11e7-8812-6fb02084e31d Content-Type: application/x-amz-json-1.1

Content-Length: 0

Date: Fri, 21 Apr 2017 21:48:35 GMT

UntagResources

Removes the speciﬁed tags from the speciﬁed resources. When you specify a tag key, the action removes both that key and its associated value. The operation succeeds even if you attempt to remove tags from a resource that were already removed. Note the following:

• To remove tags from a resource, you need the necessary permissions for the service that the resource belongs to as well as permissions for removing tags. For more information, see the documentation for the service whose resource you want to untag.

• You can only tag resources that are located in the speciﬁed AWS Region for the calling AWS account.

Minimum permissions

In addition to the tag:UntagResources permission required by this operation, you must also have the remove tags permission deﬁned by the service that created the resource. For example, to remove the tags from an Amazon EC2 instance using the UntagResources operation, you must have both of the following permissions:

• tag:UntagResource

• ec2:DeleteTags

Request Syntax

{ "ResourceARNList": [ "string" ], "TagKeys": [ "string" ]

}

Request Parameters

ResourceARNList (p. 38)

Speciﬁes a list of ARNs of the resources that you want to remove tags from.

Pattern: [\s\S]*

Required: Yes TagKeys (p. 38)

Speciﬁes a list of tag keys that you want to remove from the speciﬁed resources.

(43)

Response Syntax

Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Required: Yes

Response Syntax

{

"FailedResourcesMap": { "string" : {

"ErrorCode": "string", "ErrorMessage": "string", "StatusCode": number }

} }

Response Elements

FailedResourcesMap (p. 39)

A map containing a key-value pair for each failed item that couldn't be untagged. The key is the ARN of the failed resource. The value is a FailureInfo object that contains an error code, a status code, and an error message. If there are no errors, the FailedResourcesMap is empty.

Type: String to FailureInfo (p. 44) object map

Key Pattern: [\s\S]*

Errors

(44)

Examples

Example

This example illustrates one usage of UntagResources.

Sample Request

POST / HTTP/1.1

Content-Length: 74

X-Amz-Target: ResourceGroupsTaggingAPI_20170126.UntagResources X-Amz-Date: 20170421T215122Z

"TagKeys": [ "key"

],

"ResourceARNList": [

"arn:aws:s3:::examplebucket"

]

}

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: a923ddd9-26dc-11e7-bf86-49f2fe9ee8df Content-Type: application/x-amz-json-1.1

Content-Length: 25

Date: Fri, 21 Apr 2017 21:51:23 GMT { "FailedResourcesMap": {}

}

Data Types

The Resource Groups Tagging API API contains several data types that various actions use. This section describes each data type in detail.

Note

The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.

The following data types are supported:

• ComplianceDetails (p. 43)

• FailureInfo (p. 44)

• ResourceTagMapping (p. 46)

• Summary (p. 47)

• Tag (p. 49)

• TagFilter (p. 50)

(47)

ComplianceDetails

Information that shows whether a resource is compliant with the eﬀective tag policy, including details on any noncompliant tag keys.

Resource Groups Tagging API

Resource Groups Tagging API

API Reference

Resource Groups Tagging API: API Reference

Table of Contents

AWS Resource Groups Tagging API Reference

Services that support the Resource Groups Tagging API

Actions

DescribeReportCreation

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

GetComplianceSummary

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

GetResources

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

GetTagKeys

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

GetTagValues

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

StartReportCreation

Request Syntax

Request Parameters

Response Elements

Errors

Examples

Sample Amazon S3 policy

Sample KMS Key Policy

Example

Sample Request

Sample Response

See Also

TagResources

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples