# Categorización de los objetos mediante etiquetas
Utilice el etiquetado de objetos para categorizar el almacenamiento. Cada etiqueta es un par clave-valor.
Puede agregar etiquetas a nuevos objetos al cargarlos o agregarlas a objetos existentes.
+ Puede asociar hasta 10 etiquetas a un objeto. Las etiquetas que están asociadas con un objeto deben tener claves de etiquetas exclusivas.
+ Una clave de etiqueta puede tener una longitud de hasta 128 caracteres Unicode y los valores de etiqueta pueden tener una longitud de hasta 256 caracteres Unicode. Las etiquetas de objetos de Amazon S3 se representan internamente en UTF-16. Tenga en cuenta que en UTF-16, los caracteres ocupan 1 o 2 posiciones de caracteres.
+ La clave y los valores distinguen entre mayúsculas y minúsculas.
+ Para obtener más información sobre las restricciones en las etiquetas, consulte [Restricciones de las etiquetas definidas por el usuario](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html#allocation-tag-restrictions) en la *Guía del usuario de Administración de facturación y costos de AWS*. Para obtener información sobre las restricciones básicas de las etiquetas, consulte [Restricciones de etiquetas](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions) en la *Guía del usuario de Amazon EC2*.
**Ejemplos**
Considere los siguientes ejemplos de etiquetado:
**Example Información sanitaria protegida (PHI)**
Suponga que un objeto contiene datos de información sanitaria protegida (PHI). Podría etiquetar el objeto con el siguiente par clave-valor.
```
PHI=True
```
o
```
Classification=PHI
```
**Example Archivos de proyecto**
Supongamos que almacena archivos de proyecto en su bucket de S3. Podría etiquetar estos objetos con una clave llamada `Project` y un valor, como se muestra a continuación:
```
Project=Blue
```
**Example Múltiples etiquetas**
Puede agregar varias etiquetas a un objeto, como se muestra a continuación.
```
Project=x
Classification=confidential
```
**Prefijos y etiquetas de nombre de clave**
Los prefijos de nombre de clave de objeto también le permiten clasificar el almacenamiento. Sin embargo, la categorización basada en prefijos es unidimensional. Considere los siguientes nombres de claves de objeto:
```
photos/photo1.jpg
project/projectx/document.pdf
project/projecty/document2.pdf
```
Estos nombres de claves tienen los prefijos `photos/`, `project/projectx/` y `project/projecty/`. Estos prefijos habilitan la categorización monodimensional. Es decir, todo lo que tenga un mismo prefijo es una categoría. Por ejemplo, el prefijo `project/projectx` identifica a todos los documentos relacionados con project x.
Con el etiquetado, ahora tendrá otra dimensión. Si quiere que la foto 1 esté en la categoría project x, puede etiquetar el objeto correspondientemente.
**Beneficios adicionales**
Además de la clasificación de datos, el etiquetado ofrece los siguientes beneficios:
+ Las etiquetas de objetos permiten el control de acceso pormenorizado para otorgar permisos. Por ejemplo, podría conceder a un usuario permisos para leer solo objetos con determinadas etiquetas.
+ Las etiquetas de objetos permiten una administración precisa del ciclo de vida de un objeto, en la que podrá especificar filtros basados en etiquetas, además de prefijos de nombres de clave, en una regla de ciclo de vida.
+ Cuando utilice los análisis de Amazon S3 puede configurar filtros para agrupar los objetos de modo que se analicen por etiquetas de objetos, por prefijos de nombre de clave o por prefijos y etiquetas.
+ También puede personalizar métricas de Amazon CloudWatch para mostrar información especificando filtros de etiquetas. En las siguientes secciones presentamos más detalles.
**importante**
Es aceptable usar etiquetas para etiquetar objetos que contengan información confidencial (como información personalmente identificable o información sanitaria protegida). No obstante, las etiquetas en sí no deberían contener información confidencial.
**Agregar conjuntos de etiquetas de objetos a varios objetos de Amazon S3 con una sola solicitud.**
Para añadir conjuntos de etiquetas de objetos á más de un objeto de Amazon S3 con una sola solicitud, puede utilizar Operaciones por lotes de S3. Proporcione a Operaciones por lotes de S3 una lista de objetos en los que operar. Operaciones por lotes de S3 llama a la operación de la API respectiva para realizar la operación especificada. Un solo trabajo de operaciones por lotes puede realizar la operación especificada en miles de millones de objetos con exabytes de datos.
Operaciones por lotes de S3 realiza un seguimiento del avance, envía notificaciones y guarda un informe de finalización de todas las acciones, por lo que proporciona una experiencia sin servidor, auditable, completamente administrada. Puede emplear Operaciones por lotes de S3 a través de la consola de Amazon S3, AWS CLI, los SDK de AWS o la API de REST. Para obtener más información, consulte [Conceptos básicos de Operaciones por lotes de S3](batch-ops.md#batch-ops-basics).
Para obtener más información acerca de las etiquetas de objeto, consulte [Administrar etiquetas de objetos](tagging-managing.md).
## Operaciones de la API relacionadas con el etiquetado de objetos
Amazon S3 admite las siguientes operaciones de la API específicas al etiquetado de objetos:
**Operaciones de la API para objetos**
+ [PUT Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUTtagging.html): sustituye las etiquetas en un objeto. Las etiquetas se especifican en el cuerpo de la solicitud. Hay dos escenarios diferentes de administración de etiquetas de objetos con esta API.
+ Si el objeto no tiene etiquetas: con esta API puede agregar un conjunto de etiquetas a un objeto (el objeto no tiene etiquetas anteriores).
+ Si el objeto tiene un conjunto de etiquetas existente: para modificar el conjunto de etiquetas existente, en primer lugar debe recuperar el conjunto de etiquetas existente, modificarlo en el cliente y usar esta API para sustituir el conjunto de etiquetas.
**nota**
Si envía esta solicitud con un conjunto de etiquetas vacío, Amazon S3 elimina el conjunto de etiquetas existente en el objeto. Si utiliza este método, se le cobrará por una solicitud de nivel 1 (PUT). Para obtener más información, consulte [Precios de Amazon S3](https://d0.awsstatic.com/whitepapers/aws_pricing_overview.pdf).
La solicitud [DELETE Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETEtagging.html) es la preferida porque consigue el mismo resultado sin incurrir en cargos.
+ [GET Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETtagging.html): devuelve el conjunto de etiquetas asociado con un objeto. Amazon S3 devuelve las etiquetas de objeto en el cuerpo de la respuesta.
+ [DELETE Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectDELETEtagging.html): elimina el conjunto de etiquetas asociadas con un objeto.
**Otras operaciones de la API que admiten etiquetado**
+ [PUT Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html) e [Initiate Multipart Upload](https://docs.aws.amazon.com/AmazonS3/latest/API/mpUploadInitiate.html): puede especificar etiquetas al crear los objetos. Las etiquetas se especifican con el encabezado de solicitud `x-amz-tagging`.
+ [GET Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html): en lugar de devolver el conjunto de etiquetas, Amazon S3 devuelve el recuento de etiquetas de objeto en el encabezado `x-amz-tag-count` (solo si el solicitante tiene permiso para leer las etiquetas) dado que el tamaño del encabezado de respuesta está limitado a 8 Kb. Si quiere ver las etiquetas, realice otra solicitud para la operación de la API [GET Object tagging](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETtagging.html).
+ [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html): puede especificar las etiquetas en su solicitud POST.
Siempre que las etiquetas de su solicitud no excedan el límite de tamaño de 8 Kb para los encabezados de solicitud, puede usar la API `PUT Object `para crear objetos con etiquetas. Si las etiquetas que especifique superan el límite de tamaño del encabezado, puede usar este método POST, en el que incluiría las etiquetas en el cuerpo.
[PUT Object - Copy](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectCOPY.html): puede especificar el `x-amz-tagging-directive` en su solicitud para dar la instrucción a Amazon S3 de que copie (comportamiento predeterminado) las etiquetas o sustituya por un nuevo conjunto de etiquetas facilitadas en la solicitud.
Tenga en cuenta lo siguiente:
+ El etiquetado de objetos S3 es muy consistente. Para obtener más información, consulte [Modelo de consistencia de datos de Amazon S3](Welcome.md#ConsistencyModel).
## Configuraciones adicionales
En esta sección, se explica cómo el etiquetado de objetos se relaciona con otras configuraciones.
### Etiquetar objetos y administrar el ciclo de vida
En la configuración del ciclo de vida del bucket, puede especificar un filtro para seleccionar un subconjunto de objetos al que se aplica la regla. Puede especificar un filtro en función de los prefijos de nombres de clave, etiquetas de objetos o ambos.
Supongamos que almacena fotos (en formato bruto y terminado) en su bucket de Amazon S3. Puede etiquetar estos objetos como se muestra a continuación.
```
phototype=raw
or
phototype=finished
```
Podría plantearse archivar las fotos en bruto en Amazon Glacier tiempo después de que se creen. Puede configurar una regla de ciclo de vida con un filtro que identifique el subconjunto de objetos con el prefijo de nombre de clave (`photos/`) que tiene una etiqueta específica (`phototype=raw`).
Para obtener más información, consulte [Administración del ciclo de vida de los objetos](object-lifecycle-mgmt.md).
### Etiquetar y replicar objetos
Si configura la replicación en un bucket, Amazon S3 replica las etiquetas, siempre que conceda permisos a Amazon S3 para leer las etiquetas. Para obtener más información, consulte [Descripción general de la configuración de la replicación en directo](replication-how-setup.md).
### Notificaciones de eventos de etiquetado de objetos
Puede configurar una notificación de evento de Amazon S3 para recibir un aviso cuando se agrega o elimina una etiqueta de un objeto. El tipo de evento `s3:ObjectTagging:Put` le notifica cuando una etiqueta es PUT en un objeto o cuando se actualiza una etiqueta existente. El tipo de evento `s3:ObjectTagging:Delete` le notifica cuando se quita una etiqueta de un objeto. Para obtener más información, consulte [Habilitación de notificaciones de eventos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-enable-disable-notification-intro.html).
Para obtener más información sobre el etiquetado de objetos, vea los siguientes temas:
**Topics**
+ [Operaciones de la API relacionadas con el etiquetado de objetos](#tagging-apis)
+ [Configuraciones adicionales](#tagging-other-configs)
+ [Etiquetado y políticas de control de acceso](tagging-and-policies.md)
+ [Administrar etiquetas de objetos](tagging-managing.md)
# Etiquetado y políticas de control de acceso
También puede usar políticas de permisos (políticas de bucket y usuario) para administrar los permisos relacionados con el etiquetado de objetos. Para ver acciones de políticas, consulte los siguientes temas:
+ [Operaciones con objetos](security_iam_service-with-iam.md#using-with-s3-actions-related-to-objects)
+ [Operaciones con buckets](security_iam_service-with-iam.md#using-with-s3-actions-related-to-buckets)
Las etiquetas de objetos permiten un control de acceso pormenorizado para administrar permisos. Puede otorgar permisos condicionales en función de las etiquetas de objetos. Amazon S3 admite las siguientes claves de condiciones que puede usar para conceder permisos condicionales basados en etiquetas de objetos.
+ `s3:ExistingObjectTag/`: use esta clave condicional para verificar una etiqueta de objeto existente tiene una clave y un valor específicos para la etiqueta.
**nota**
Al conceder permisos para las operaciones `PUT Object` y `DELETE Object`, esta clave condicional no se admite. Es decir, no puede crear una política para conceder o denegar permisos a un usuario para eliminar o sobrescribir un objeto en función de sus etiquetas existentes.
+ `s3:RequestObjectTagKeys`: use esta clave condicional para restringir las claves de etiqueta que quiera permitir en objetos. Esto resulta útil al agregar etiquetas a objetos con PutObjectTagging y PutObject y con las solicitudes POST para objetos.
+ `s3:RequestObjectTag/`: use esta clave condicional para restringir las claves y valores de etiqueta que quiera permitir en objetos. Esto resulta útil al agregar etiquetas a objetos con PutObjectTagging y PutObject y con las solicitudes POST para buckets.
Para obtener una lista completa de las claves condicionales específicas de servicio de Amazon S3, consulte [Ejemplos de políticas de bucket que utilizan claves de condición](amazon-s3-policy-keys.md). Las siguientes políticas de permisos ilustran cómo el etiquetado de objetos facilita una administración de permisos de acceso pormenorizada.
**Example 1: Permitir a un usuario leer solo los objetos que tienen una clave y valor de etiqueta específicos**
La siguiente política de permisos limita al usuario a leer solo los objetos que tengan la clave y el valor de la etiqueta `environment: production`. Esta política usa la clave de condición `s3:ExistingObjectTag` para especificar la clave y el valor de etiqueta.
****
```
{
"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: Restringir las claves de etiqueta de objetos que los usuarios pueden agregar**
La siguiente política de permisos concede permisos a un usuario para realizar la acción `s3:PutObjectTagging`, lo que permite al usuario agregar etiquetas a un objeto existente. La condición usa la clave de condición `s3:RequestObjectTagKeys` para especificar las claves de etiqueta permitidas, como `Owner` o `CreationDate`. Para obtener más información, consulte [Creación de una condición que pruebe valores de varias claves](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_multi-value-conditions.html) en la *Guía para usuarios de IAM*.
La política garantiza que cada clave de etiqueta especificada en la solicitud sea una clave de etiqueta autorizada. El calificador `ForAnyValue` de la condición garantiza que al menos una de las claves especificadas estará presente en la solicitud.
****
```
{
"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: Requerir una clave y un valor de etiqueta específica al permitir a los usuarios agregar etiquetas de objetos**
La política de ejemplo siguiente concede un permiso de usuario para realizar la acción `s3:PutObjectTagging`, lo que permite al usuario agregar etiquetas a un objeto existente. La condición requiere que el usuario incluya una clave de etiqueta específica (como `Project`) con el valor establecido en `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"
}
}
}
]
}
```
# Administrar etiquetas de objetos
En esta sección, se explica cómo puede administrar etiquetas de objetos con los SDK de AWS para Java y .NET, o la consola de Amazon S3.
El etiquetado de objetos le permite categorizar el almacenamiento en los buckets de uso general. Cada etiqueta es un par clave-valor que se ajusta a las reglas siguientes:
+ Puede asociar hasta 10 etiquetas a un objeto. Las etiquetas que están asociadas con un objeto deben tener claves de etiquetas exclusivas.
+ Una clave de etiqueta puede tener una longitud de hasta 128 caracteres Unicode y los valores de etiqueta pueden tener una longitud de hasta 256 caracteres Unicode. Las etiquetas de objetos de Amazon S3 se representan internamente en UTF-16. Tenga en cuenta que en UTF-16, los caracteres ocupan 1 o 2 posiciones de caracteres.
+ La clave y los valores distinguen entre mayúsculas y minúsculas.
Para obtener más información acerca de las etiquetas de objeto, consulte [Categorización de los objetos mediante etiquetas](object-tagging.md). Para obtener más información sobre las restricciones de las etiquetas, consulte [Restricciones de las etiquetas definidas por el usuario](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html) en la *Guía del usuario de Administración de facturación y costos de AWS*.
## Uso de la consola de S3
**Para añadir etiquetas a un objeto**
1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon S3 en [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. En el panel de navegación izquierdo, elija **Buckets de uso general**.
1. En la lista de buckets, seleccione el nombre del bucket que contiene el objeto.
1. Seleccione la casilla de verificación situada a la izquierda de los nombres de los objetos que desea cambiar.
1. En el menú **Actions (Acciones)**, elija **Edit (Editar)**.
1. Revise los objetos mencionados y elija **Add tags (Agregar etiquetas)**.
1. Cada etiqueta de objeto es un par clave-valor. Introduzca la información pertinente en **Key (Clave)** y **Value (Valor)**. Para agregar otra etiqueta, elija **Add Tag (Añadir etiqueta)**.
Puede introducir hasta 10 etiquetas para un objeto.
1. Elija **Save changes**.
Amazon S3 agrega las etiquetas a los objetos especificados.
Para obtener más información, consulte [Visualización de propiedades de objeto en la consola de Amazon S3](view-object-properties.md) y [Carga de objetos](upload-objects.md) en esta guía.
## Uso de la SDKs AWS
------
#### [ Java ]
Para administrar etiquetas de objetos mediante el AWS SDK para Java, puede establecer etiquetas para un nuevo objeto y recuperar o reemplazar etiquetas de un objeto ya existente. Para obtener más información acerca de cómo etiquetar objetos, consulte [Categorización de los objetos mediante etiquetas](object-tagging.md).
Cargue un objeto en un bucket y configure las etiquetas con un S3Client. Para ver ejemplos, consulte [Cargar un objeto en un bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObject_section.html) en la *Referencia de la API de Amazon S3*.
------
#### [ .NET ]
En la siguiente muestra se indica cómo utilizar el AWS SDK para .NET para establecer las etiquetas para un nuevo objeto y recuperar o reemplazar las etiquetas de un objeto ya existente. Para obtener más información acerca de cómo etiquetar objetos, consulte [Categorización de los objetos mediante etiquetas](object-tagging.md).
Para obtener información acerca de cómo configurar y ejecutar ejemplos de código, consulte [Introducción al SDK de AWS para .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-setup.html) en la *Guía para desarrolladores del SDK de AWS para .NET*.
```
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);
}
}
}
}
```
------