Establecer etiquetas de blobs

  • Artículo

La Set Blob Tags operación establece etiquetas definidas por el usuario para el blob especificado como uno o varios pares clave-valor.

Solicitud

La solicitud Set Blob Tags se puede construir como sigue. Se recomienda usar HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

URI de solicitud de método PUT Versión de HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=tags

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=tags&versionid=<DateTime>		 HTTP/1.1

Parámetros del identificador URI

Puedes especificar los siguientes parámetros adicionales en el URI de la solicitud:

Parámetro Descripción
versionid Opcional para la versión 2019-12-12 y posteriores. El versionid parámetro es un valor opaco DateTime que, cuando está presente, especifica la versión del blob que se va a recuperar.
timeout Opcional. El parámetro timeout se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Storage.

Encabezados de solicitud

Los encabezados de solicitud obligatorios y opcionales se describen en la tabla siguiente:

Encabezado de solicitud Descripción
Authorization Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
Date o x-ms-date Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
x-ms-version Necesario para todas las solicitudes autorizadas. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Versiones de los servicios de Azure Storage.
Content-Length Necesario. La longitud del contenido de la solicitud, en bytes. Este encabezado hace referencia a la longitud de contenido del documento de etiquetas, no al propio blob.
Content-Type Necesario. El valor de este encabezado debe ser application/xml; charset=UTF-8.
Content-MD5 Opcional. Hash MD5 del contenido de la solicitud. Este hash se utiliza para comprobar la integridad del contenido de la solicitud durante el transporte. Si ambos valores de hash no coinciden, la operación produce un error con el código de estado 400 (solicitud incorrecta).

Este encabezado está asociado al contenido de la solicitud y no al contenido del propio blob.
x-ms-content-crc64 Opcional. Hash CRC64 del contenido de la solicitud. Este hash se utiliza para comprobar la integridad del contenido de la solicitud durante el transporte. Si ambos valores de hash no coinciden, la operación produce un error con el código de estado 400 (solicitud incorrecta).

Este encabezado está asociado al contenido de la solicitud y no al contenido del propio blob.

Si hay encabezados y x-ms-content-crc64 , Content-MD5 se produce un error en la solicitud con el código de error 400 (solicitud incorrecta).
x-ms-lease-id:<ID> Obligatorio si el blob tiene una concesión activa.

Para realizar esta operación en un blob con una concesión activa, especifique el identificador de concesión válido de este encabezado. Si no se especifica un identificador de concesión válido en la solicitud, se produce un error en la operación con el código de estado 403 (Prohibido).
x-ms-client-request-id Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor. Para obtener más información, consulte Supervisión de Azure Blob Storage.

Esta operación admite el x-ms-if-tags encabezado condicional para establecer etiquetas de blob solo si se cumple una condición especificada. Para más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage.

Cuerpo de la solicitud

El formato del cuerpo de la solicitud es el siguiente:

<?xml version="1.0" encoding="utf-8"?>  
<Tags>  
    <TagSet>  
        <Tag>  
            <Key>tag-name-1</Key>  
            <Value>tag-value-1</Value>  
        </Tag>  
        <Tag>  
            <Key>tag-name-2</Key>  
            <Value>tag-value-2</Value>  
        </Tag>  
    </TagSet>  
</Tags>

El cuerpo de la solicitud debe ser un documento XML UTF-8 con formato correcto y contener un conjunto de etiquetas que represente las etiquetas del blob.

El conjunto de etiquetas puede contener no más de 10 etiquetas. Las claves y los valores de etiqueta distinguen mayúsculas de minúsculas. Las claves de etiqueta deben tener entre 1 y 128 caracteres y los valores de etiqueta deben tener entre 0 y 256 caracteres. Entre los caracteres de clave y valor válidos se incluyen:

  • Letras minúsculas y mayúsculas (a-z, A-Z)
  • Dígitos (0-9)
  • Un espacio ( )
  • Más (+), menos (-), punto (.), barra diagonal (/), dos puntos (:), iguales (=) y subrayado (_)

Response

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta.

status code

Una operación correcta devuelve el código de estado 204 (Sin contenido).

Para obtener más información sobre los códigos de estado, consulte Códigos de estado y error.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también puede incluir otros encabezados HTTP estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Encabezado de respuesta Descripción
x-ms-request-id Identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
x-ms-version Versión de Blob Storage que se usó para ejecutar la solicitud.
Date Valor de fecha y hora UTC generado por el servicio, que indica la hora en que se inició la respuesta.
x-ms-client-request-id Se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del x-ms-client-request-id encabezado si está presente en la solicitud y el valor no contiene más de 1024 caracteres ASCII visibles. Si el x-ms-client-request-id encabezado no está presente en la solicitud, no estará presente en la respuesta.

Response body

Ninguno.

Authorization

La autorización es necesaria al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Set Blob Tags operación como se describe a continuación.

Azure Storage admite el uso de Microsoft Entra ID para autorizar solicitudes a datos de blobs. Con Microsoft Entra ID, puede usar el control de acceso basado en rol de Azure (RBAC de Azure) para conceder permisos a una entidad de seguridad. La entidad de seguridad puede ser un usuario, un grupo, una entidad de servicio de aplicación o una identidad administrada de Azure. La entidad de seguridad se autentica mediante Microsoft Entra ID para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para más información sobre la autorización mediante Microsoft Entra ID, consulte Autorización del acceso a blobs mediante Microsoft Entra ID.

Permisos

A continuación se enumeran las acciones de RBAC necesarias para un usuario, grupo o entidad de servicio de Microsoft Entra para llamar a la Set Blob Tags operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Para más información sobre la asignación de roles mediante RBAC de Azure, consulte Asignación de un rol de Azure para el acceso a datos de blobs.

Comentarios

La Set Blob Tags operación se admite en la API REST versión 2019-12-12 y posteriores.

En el caso de las cuentas con espacio de nombres jerárquico habilitado, la Set Blob Tags operación no se admite porque las etiquetas de blob no se admiten para las cuentas de espacio de nombres jerárquicos.

La Set Blob Tags operación sobrescribe todas las etiquetas existentes en el blob. Para quitar todas las etiquetas de un blob, envíe una Set Blob Tags solicitud con un vacío <TagSet>.

Esta operación no actualiza la ETag ni la hora de la última modificación del blob. Es posible establecer etiquetas en un blob archivado.

El servicio de almacenamiento mantiene una coherencia fuerte entre un blob y sus etiquetas. Los cambios en las etiquetas de blob son visibles inmediatamente para las operaciones posteriores Get Blob Tags en el blob. Sin embargo, el índice secundario es coherente con el tiempo. Es posible que los cambios en las etiquetas de un blob no sean visibles inmediatamente para Find Blobs by Tags las operaciones.

Si una solicitud proporciona etiquetas no válidas, Blob Storage devuelve el código de estado 400 (solicitud incorrecta).

Facturación

Las solicitudes de precios se pueden originar en clientes que usan las API de Blob Storage, ya sea directamente a través de la API rest de Blob Storage o de una biblioteca cliente de Azure Storage. Estas solicitudes acumulan cargos por transacción. El tipo de transacción afecta a cómo se cobra la cuenta. Por ejemplo, las transacciones de lectura se acumulan en una categoría de facturación diferente que las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de Set Blob Tags las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
Establecer etiquetas de blobs Blobs en bloques Premium
De uso general, estándar, v2		 Otras operaciones
Establecer etiquetas de blobs De uso general, estándar, v1 Operaciones de escritura

Para obtener información sobre los precios de la categoría de facturación especificada, consulte precios Azure Blob Storage.

Consulte también

Administración y búsqueda de datos de Blob Storage con etiquetas de índice de blobs
Autorización de solicitudes a Azure Storage
Estado y códigos de error
Códigos de error de Blob Storage