# Categorizing your objects using tags Categorizing objects with tags Use object tagging to categorize storage. Each tag is a key-value pair. You can add tags to new objects when you upload them, or you can add them to existing objects. + You can associate up to 10 tags with an object. Tags that are associated with an object must have unique tag keys. + A tag key can be up to 128 Unicode characters in length, and tag values can be up to 256 Unicode characters in length. Amazon S3 object tags are internally represented in UTF-16. Note that in UTF-16, characters consume either 1 or 2 character positions. + The key and values are case sensitive. + For more information about tag restrictions, see [User-defined tag restrictions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html#allocation-tag-restrictions) in the *AWS Billing and Cost Management User Guide*. For basic tag restrictions, see [Tag restrictions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions) in the *Amazon EC2 User Guide*. **Examples** Consider the following tagging examples: **Example PHI information** Suppose that an object contains protected health information (PHI) data. You might tag the object using the following key-value pair. ``` PHI=True ``` or ``` Classification=PHI ``` **Example Project files** Suppose that you store project files in your S3 bucket. You might tag these objects with a key named `Project` and a value, as shown following. ``` Project=Blue ``` **Example Multiple tags** You can add multiple tags to an object, as shown following. ``` Project=x Classification=confidential ``` **Key name prefixes and tags** Object key name prefixes also enable you to categorize storage. However, prefix-based categorization is one-dimensional. Consider the following object key names: ``` photos/photo1.jpg project/projectx/document.pdf project/projecty/document2.pdf ``` These key names have the prefixes `photos/`, `project/projectx/`, and `project/projecty/`. These prefixes enable one-dimensional categorization. That is, everything under a prefix is one category. For example, the prefix `project/projectx` identifies all documents related to project x. With tagging, you now have another dimension. If you want photo1 in project x category, you can tag the object accordingly. **Additional benefits** In addition to data classification, tagging offers benefits such as the following: + Object tags enable fine-grained access control of permissions. For example, you could grant a user permissions to read-only objects with specific tags. + Object tags enable fine-grained object lifecycle management in which you can specify a tag-based filter, in addition to a key name prefix, in a lifecycle rule. + When using Amazon S3 analytics, you can configure filters to group objects together for analysis by object tags, by key name prefix, or by both prefix and tags. + You can also customize Amazon CloudWatch metrics to display information by specific tag filters. The following sections provide details. **Important** It is acceptable to use tags to label objects containing confidential data, such as personally identifiable information (PII) or protected health information (PHI). However, the tags themselves shouldn't contain any confidential information. **Adding object tag sets to multiple Amazon S3 object with a single request** To add object tag sets to more than one Amazon S3 object with a single request, you can use S3 Batch Operations. You provide S3 Batch Operations with a list of objects to operate on. S3 Batch Operations calls the respective API operation to perform the specified operation. A single Batch Operations job can perform the specified operation on billions of objects containing exabytes of data. The S3 Batch Operations feature tracks progress, sends notifications, and stores a detailed completion report of all actions, providing a fully managed, auditable, serverless experience. You can use S3 Batch Operations through the Amazon S3 console, AWS CLI, AWS SDKs, or REST API. For more information, see [S3 Batch Operations basics](batch-ops.md#batch-ops-basics). For more information about object tags, see [Managing object tags](tagging-managing.md). ## API operations related to object tagging Amazon S3 supports the following API operations that are specifically for object tagging: **Object API operations** + [PUT Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUTtagging.html) – Replaces tags on an object. You specify tags in the request body. There are two distinct scenarios of object tag management using this API. + Object has no tags – Using this API you can add a set of tags to an object (the object has no prior tags). + Object has a set of existing tags – To modify the existing tag set, you must first retrieve the existing tag set, modify it on the client side, and then use this API to replace the tag set. **Note** If you send this request with an empty tag set, Amazon S3 deletes the existing tag set on the object. If you use this method, you will be charged for a Tier 1 Request (PUT). For more information, see [Amazon S3 Pricing](https://d0.awsstatic.com/whitepapers/aws_pricing_overview.pdf). The [DELETE Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETEtagging.html) request is preferred because it achieves the same result without incurring charges. + [GET Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETtagging.html) – Returns the tag set associated with an object. Amazon S3 returns object tags in the response body. + [DELETE Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETEtagging.html) – Deletes the tag set associated with an object. **Other API operations that support tagging** + [PUT Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html) and [Initiate Multipart Upload](https://docs.aws.amazon.com/AmazonS3/latest/API/mpUploadInitiate.html)– You can specify tags when you create objects. You specify tags using the `x-amz-tagging` request header. + [GET Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html) – Instead of returning the tag set, Amazon S3 returns the object tag count in the `x-amz-tag-count` header (only if the requester has permissions to read tags) because the header response size is limited to 8 K bytes. If you want to view the tags, you make another request for the [GET Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETtagging.html) API operation. + [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) – You can specify tags in your POST request. As long as the tags in your request don't exceed the 8 K byte HTTP request header size limit, you can use the `PUT Object `API to create objects with tags. If the tags you specify exceed the header size limit, you can use this POST method in which you include the tags in the body. [PUT Object - Copy](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectCOPY.html) – You can specify the `x-amz-tagging-directive` in your request to direct Amazon S3 to either copy (default behavior) the tags or replace tags by a new set of tags provided in the request. Note the following: + S3 Object Tagging is strongly consistent. For more information, see [Amazon S3 data consistency model](Welcome.md#ConsistencyModel). ## Additional configurations This section explains how object tagging relates to other configurations. ### Object tagging and lifecycle management In bucket lifecycle configuration, you can specify a filter to select a subset of objects to which the rule applies. You can specify a filter based on the key name prefixes, object tags, or both. Suppose that you store photos (raw and the finished format) in your Amazon S3 bucket. You might tag these objects as shown following. ``` phototype=raw or phototype=finished ``` You might consider archiving the raw photos to Amazon Glacier sometime after they are created. You can configure a lifecycle rule with a filter that identifies the subset of objects with the key name prefix (`photos/`) that have a specific tag (`phototype=raw`). For more information, see [Managing the lifecycle of objects](object-lifecycle-mgmt.md). ### Object tagging and replication If you configured Replication on your bucket, Amazon S3 replicates tags, provided you grant Amazon S3 permission to read the tags. For more information, see [Setting up live replication overview](replication-how-setup.md). ### Object tagging event notifications You can set up an Amazon S3 event notification to receive notice when an object tag is added or deleted from an object. The `s3:ObjectTagging:Put` event type notifies you when a tag is PUT on an object or when an existing tag is updated. The `s3:ObjectTagging:Delete` event type notifies you when a tag is removed from an object. For more information, see [ Enabling event notifications](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-enable-disable-notification-intro.html). For more information about object tagging, see the following topics: **Topics** + [ ## API operations related to object tagging ](#tagging-apis) + [ ## Additional configurations ](#tagging-other-configs) + [ # Tagging and access control policies ](tagging-and-policies.md) + [ # Managing object tags ](tagging-managing.md) # Tagging and access control policies Controlling access with tags You can also use permissions policies (bucket and user policies) to manage permissions related to object tagging. For policy actions see the following topics: + [Object operations](security_iam_service-with-iam.md#using-with-s3-actions-related-to-objects) + [Bucket operations](security_iam_service-with-iam.md#using-with-s3-actions-related-to-buckets) Object tags enable fine-grained access control for managing permissions. You can grant conditional permissions based on object tags. Amazon S3 supports the following condition keys that you can use to grant conditional permissions based on object tags: + `s3:ExistingObjectTag/` – Use this condition key to verify that an existing object tag has the specific tag key and value. **Note** When granting permissions for the `PUT Object` and `DELETE Object` operations, this condition key is not supported. That is, you cannot create a policy to grant or deny a user permissions to delete or overwrite an object based on its existing tags. + `s3:RequestObjectTagKeys` – Use this condition key to restrict the tag keys that you want to allow on objects. This is useful when adding tags to objects using the PutObjectTagging and PutObject, and POST object requests. + `s3:RequestObjectTag/` – Use this condition key to restrict the tag keys and values that you want to allow on objects. This is useful when adding tags to objects using the PutObjectTagging and PutObject, and POST Bucket requests. For a complete list of Amazon S3 service-specific condition keys, see [Bucket policy examples using condition keys](amazon-s3-policy-keys.md). The following permissions policies illustrate how object tagging enables fine grained access permissions management. **Example 1: Allow a user to read only the objects that have a specific tag and key value** The following permissions policy limits a user to only reading objects that have the `environment: production` tag key and value. This policy uses the `s3:ExistingObjectTag` condition key to specify the tag key and value. **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/JohnDoe" ] }, "Effect": "Allow", "Action": ["s3:GetObject", "s3:GetObjectVersion"], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Condition": { "StringEquals": {"s3:ExistingObjectTag/environment": "production"} } } ] } ``` **Example 2: Restrict which object tag keys that users can add** The following permissions policy grants a user permissions to perform the `s3:PutObjectTagging` action, which allows user to add tags to an existing object. The condition uses the `s3:RequestObjectTagKeys` condition key to specify the allowed tag keys, such as `Owner` or `CreationDate`. For more information, see [Creating a condition that tests multiple key values](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_multi-value-conditions.html) in the *IAM User Guide*. The policy ensures that every tag key specified in the request is an authorized tag key. The `ForAnyValue` qualifier in the condition ensures that at least one of the specified keys must be present in the request. **** ``` { "Version":"2012-10-17", "Statement": [ {"Principal":{"AWS":[ "arn:aws:iam::111122223333:role/JohnDoe" ] }, "Effect": "Allow", "Action": [ "s3:PutObjectTagging" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ], "Condition": {"ForAnyValue:StringEquals": {"s3:RequestObjectTagKeys": [ "Owner", "CreationDate" ] } } } ] } ``` **Example 3: Require a specific tag key and value when allowing users to add object tags** The following example policy grants a user permission to perform the `s3:PutObjectTagging` action, which allows a user to add tags to an existing object. The condition requires the user to include a specific tag key (such as `Project`) with the value set to `X`. **** ``` { "Version":"2012-10-17", "Statement": [ {"Principal":{"AWS":[ "arn:aws:iam::111122223333:user/JohnDoe" ] }, "Effect": "Allow", "Action": [ "s3:PutObjectTagging" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ], "Condition": {"StringEquals": {"s3:RequestObjectTag/Project": "X" } } } ] } ``` # Managing object tags Managing object tags This section explains how you can manage object tags using the AWS SDKs for Java and .NET or the Amazon S3 console. Object tagging gives you a way to categorize storage in general purpose buckets. Each tag is a key-value pair that adheres to the following rules: + You can associate up to 10 tags with an object. Tags that are associated with an object must have unique tag keys. + A tag key can be up to 128 Unicode characters in length, and tag values can be up to 256 Unicode characters in length. Amazon S3 object tags are internally represented in UTF-16. Note that in UTF-16, characters consume either 1 or 2 character positions. + The key and values are case sensitive. For more information about object tags, see [Categorizing your objects using tags](object-tagging.md). For more information about tag restrictions, see [User-Defined Tag Restrictions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html) in the *AWS Billing and Cost Management User Guide*. ## Using the S3 console Editing object tags **To add tags to an object** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **General purpose buckets**. 1. In the bucket list, choose the name of the bucket that contains the object. 1. Select the check box to the left of the names of the objects you want to change. 1. In the **Actions** menu, choose **Edit tags**. 1. Review the objects listed, and choose **Add tags**. 1. Each object tag is a key-value pair. Enter a **Key** and a **Value**. To add another tag, choose **Add Tag**. You can enter up to 10 tags for an object. 1. Choose **Save changes**. Amazon S3 adds the tags to the specified objects. For more information, see also [Viewing object properties in the Amazon S3 console](view-object-properties.md) and [Uploading objects](upload-objects.md) in this guide. ## Using the AWS SDKs ------ #### [ Java ] To manage object tags using the AWS SDK for Java, you can set tags for a new object and retrieve or replace tags for an existing object. For more information about object tagging, see [Categorizing your objects using tags](object-tagging.md). Upload an object to a bucket and set tags using an S3Client. For examples, see [Upload an object to a bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObject_section.html) in the *Amazon S3 API Reference*. ------ #### [ .NET ] The following example shows how to use the AWS SDK for .NET to set the tags for a new object and retrieve or replace the tags for an existing object. For more information about object tagging, see [Categorizing your objects using tags](object-tagging.md). For information about setting up and running the code examples, see [Getting Started with the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-setup.html) in the *AWS SDK for .NET Developer Guide*. ``` using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Collections.Generic; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { public class ObjectTagsTest { private const string bucketName = "*** bucket name ***"; private const string keyName = "*** key name for the new object ***"; private const string filePath = @"*** file path ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); PutObjectWithTagsTestAsync().Wait(); } static async Task PutObjectWithTagsTestAsync() { try { // 1. Put an object with tags. var putRequest = new PutObjectRequest { BucketName = bucketName, Key = keyName, FilePath = filePath, TagSet = new List{ new Tag { Key = "Keyx1", Value = "Value1"}, new Tag { Key = "Keyx2", Value = "Value2" } } }; PutObjectResponse response = await client.PutObjectAsync(putRequest); // 2. Retrieve the object's tags. GetObjectTaggingRequest getTagsRequest = new GetObjectTaggingRequest { BucketName = bucketName, Key = keyName }; GetObjectTaggingResponse objectTags = await client.GetObjectTaggingAsync(getTagsRequest); for (int i = 0; i < objectTags.Tagging.Count; i++) Console.WriteLine("Key: {0}, Value: {1}", objectTags.Tagging[i].Key, objectTags.Tagging[i].Value); // 3. Replace the tagset. Tagging newTagSet = new Tagging(); newTagSet.TagSet = new List{ new Tag { Key = "Key3", Value = "Value3"}, new Tag { Key = "Key4", Value = "Value4" } }; PutObjectTaggingRequest putObjTagsRequest = new PutObjectTaggingRequest() { BucketName = bucketName, Key = keyName, Tagging = newTagSet }; PutObjectTaggingResponse response2 = await client.PutObjectTaggingAsync(putObjTagsRequest); // 4. Retrieve the object's tags. GetObjectTaggingRequest getTagsRequest2 = new GetObjectTaggingRequest(); getTagsRequest2.BucketName = bucketName; getTagsRequest2.Key = keyName; GetObjectTaggingResponse objectTags2 = await client.GetObjectTaggingAsync(getTagsRequest2); for (int i = 0; i < objectTags2.Tagging.Count; i++) Console.WriteLine("Key: {0}, Value: {1}", objectTags2.Tagging[i].Key, objectTags2.Tagging[i].Value); } catch (AmazonS3Exception e) { Console.WriteLine( "Error encountered ***. Message:'{0}' when writing an object" , e.Message); } catch (Exception e) { Console.WriteLine( "Encountered an error. Message:'{0}' when writing an object" , e.Message); } } } } ``` ------