Buscar blobs por etiquetas

  • Artículo

La Find Blobs by Tags operación busca todos los blobs de la cuenta de almacenamiento cuyas etiquetas coinciden con una expresión de búsqueda.

Solicitud

Puede construir la solicitud de la Find Blobs by Tags siguiente manera. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento.

URI de solicitud de método GET Versión de HTTP
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> 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
expression Necesario. Filtra el conjunto de resultados para incluir solo blobs cuyas etiquetas coincidan con la expresión especificada.

Para obtener más información sobre cómo construir esta expresión, vea Comentarios.
marker Opcional. Valor de cadena que identifica la parte del conjunto de resultados que se va a devolver con la siguiente operación. La operación devuelve un valor de marcador dentro del cuerpo de la respuesta si el conjunto de resultados devuelto no se completó. A continuación, el valor del marcador se puede usar en una llamada posterior para solicitar el siguiente conjunto de elementos.

El valor de marcador es opaco para el cliente.
maxresults Opcional. Especifica el número máximo de blobs que se van a devolver. Si la solicitud no especifica maxresults o especifica un valor mayor que 5000, el servidor devuelve hasta 5000 elementos. Si hay resultados adicionales que devolver, el servicio devuelve un token de continuación en el NextMarker elemento de respuesta. En determinados casos, el servicio podría devolver menos resultados que maxresults los especificados. El servicio también puede devolver un token de continuación.

Si se establece maxresults en un valor menor o igual que cero, se devolverá el código de respuesta de error 400 (Solicitud incorrecta).
timeout Opcional. Expresado en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Storage.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud obligatorios y opcionales:

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 Se requiere para todas las solicitudes autorizadas, pero opcional para las solicitudes anónimas. 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.
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.

Cuerpo de la solicitud

Ninguno.

Response

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

status code

Una operación correcta devuelve el código de estado 200 Correcto.

Para obtener 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 encabezados HTTP estándar adicionales. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Encabezado de respuesta Descripción
Content-Type Especifica application/xml como tipo de contenido.
Content-Length Especifica el tamaño del documento XML devuelto, en bytes.
x-ms-request-id Identifica de forma única la solicitud que se realizó. Puede usarlo para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
x-ms-version Indica la versión de Azure Blob Storage que se usó para ejecutar la solicitud.
Date Valor de fecha y hora UTC que indica la hora en la que el servicio envió 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 es como máximo de 1024 caracteres ASCII visibles. Si el x-ms-client-request-id encabezado no está presente en la solicitud, este encabezado no estará presente en la respuesta.

Response body

En la versión 2020-04-08 y posteriores, las etiquetas coincidentes del blob se encapsulan dentro de un Tags elemento . El formato del cuerpo de respuesta es el siguiente:

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=http://myaccount.blob.core.windows.net/>  
  <Where>string-value</Where>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</Name>  
      <ContainerName>container-name</ContainerName>  
      <Tags>
        <TagSet>
          <Tag>
            <Key>matching-tag-name1</Key>
            <Value>matching-tag-value1</Value>
          </Tag>
          <Tag>
            <Key>matching-tag-name2</Key>
            <Value>matching-tag-value2</Value>
          </Tag>
        </TagSet>
      </Tags> 
    </Blob>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

El cuerpo de la respuesta es un documento XML UTF-8 bien formado.

Authorization

La autorización es necesaria al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Find Blobs by 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 que un usuario, grupo o entidad de servicio de Microsoft Entra llame a la Find Blobs by Tags operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

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

Comentarios

La Find Blobs by 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 Find Blobs by Tags operación no se admite porque las etiquetas de blob no se admiten para las cuentas de espacio de nombres jerárquicos.

El índice secundario que Find Blobs by Tags usa es finalmente coherente. Novedades a las etiquetas de blob a través Set Blob Tags de es posible que no sean visibles inmediatamente para Find Blobs by Tags las operaciones.

Construcción de una expresión de búsqueda

El where parámetro URI busca blobs en la cuenta de almacenamiento cuyas etiquetas coinciden con una expresión. La expresión debe evaluarse como true para que se devuelva un blob en el conjunto de resultados.

El servicio de almacenamiento admite un subconjunto de la gramática de la cláusula SQL WHERE ANSI para el valor del where=<expression> parámetro de consulta. El servicio de almacenamiento admite los operadores siguientes:

Operador Descripción Ejemplo
= Igual &where=Status = 'In Progress'
> Mayor que &where=LastModified > '2018-06-18 20:51:26Z'
>= Mayor o igual que &where=Priority >= '05'
< Menor que &where=Age < '032'
<= Menor o igual que &where=Reviewer <= 'Smith'
AND Y lógico &where=Name > 'C' AND Name < 'D'
&where=Age > '032' AND Age < '100'
@container Especificación de un contenedor &where=@container='mycontainer' AND Name = 'C'

Nota

El valor del where parámetro URI debe estar codificado correctamente con URI (incluidos los espacios y operadores). Los ejemplos anteriores omiten esto para mejorar la legibilidad.

Todos los valores de etiqueta son cadenas. Los operadores relacionales binarios admitidos usan una ordenación lexicográfica de los valores de etiqueta. Para admitir tipos de datos que no son de cadena, incluidos números y fechas, debe usar el relleno adecuado y el formato ordenable. Los valores de etiqueta deben ir entre comillas simples.

Si los nombres de etiqueta son identificadores sql normales, pueden estar presentes sin escape. Si contienen caracteres especiales, deben delimitarse con comillas dobles (por ejemplo, "TagName" = TagValue). Se recomienda incluir siempre los nombres de etiqueta entre comillas dobles.

El servicio de almacenamiento rechazará cualquier solicitud que contenga una expresión no válida con el código de error 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 Find Blobs by Tags las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
Buscar blobs por etiquetas Blobs en bloques Premium
De uso general, estándar, v2
De uso general, estándar, v1		 Enumerar y crear operaciones de contenedor

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 en Azure 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