Categorizing your storage using 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, seeUser-defined tag restrictions in theAWS Billing and Cost Management User Guide. For basic tag restrictions, seeTag restrictions in theAmazon EC2 User Guide.
Examples
Consider the following tagging examples:
Example PHI information
Example Project files
Example Multiple tags
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.jpgproject/projectx/document.pdfproject/projecty/document2.pdfThese key names have the prefixesphotos/,project/projectx/, andproject/projecty/. These prefixes enable one-dimensional categorization. That is, everything under a prefix is one category. For example, the prefixproject/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.
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, seeS3 Batch Operations basics.
For more information about object tags, seeManaging object tags.
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 – 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.
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, seeAmazon S3 Pricing.
TheDELETE Object tagging request is preferred because it achieves the same result without incurring charges.
GET Object tagging – Returns the tag set associated with an object. Amazon S3 returns object tags in the response body.
DELETE Object tagging – Deletes the tag set associated with an object.
Other API operations that support tagging
PUT Object andInitiate Multipart Upload– You can specify tags when you create objects. You specify tags using the
x-amz-taggingrequest header.GET Object – Instead of returning the tag set, Amazon S3 returns the object tag count in the
x-amz-tag-countheader (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 theGET Object tagging API operation.POST Object – 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 ObjectAPI 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 – You can specify the
x-amz-tagging-directivein 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, seeAmazon S3 data consistency model.
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=raworphototype=finishedYou might consider archiving the raw photos to S3 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, seeManaging the lifecycle of objects.
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, seeSetting up live replication overview.
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. Thes3:ObjectTagging:Put event type notifies you when a tag is PUT on an object or when an existing tag is updated. Thes3:ObjectTagging:Delete event type notifies you when a tag is removed from an object. For more information, see Enabling event notifications.
For more information about object tagging, see the following topics:
