Buscar blobs por etiquetas

  • Artículo
  • Tiempo de lectura: 5 minutos

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 determinada.

Solicitud

La solicitud Find Blobs by Tags se puede construir como sigue. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

URI de solicitud del método GET Versión HTTP
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

Parámetros de URI

Se pueden especificar los parámetros adicionales siguientes en el URI de solicitud.

Parámetro Descripción
expression Obligatorio. Filtra el conjunto de resultados para incluir solo blobs cuyas etiquetas coincidan con la expresión especificada.

Vea comentarios para obtener más información sobre cómo construir esta expresión.
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 ha completado. 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 devolverán. Si la solicitud no especifica maxresults, o especifica un valor superior a 5.000, el servidor devolverá un máximo de 5.000 elementos.

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. El parámetro timeout se expresa en segundos. Para obtener más información, vea Establecer tiempos de espera para las operaciones de Blob Service.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud requeridos y opcionales.

Encabezado de solicitud Descripción
Authorization Obligatorio. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, vea Autorización de solicitudes para Azure Storage.
Date o x-ms-date Obligatorio. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes para Azure Storage.
x-ms-version Obligatorio para todas las solicitudes autorizadas, 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 Control de versiones para Azure Storage Services.
x-ms-client-request-id Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 KiB que se registra en los registros de análisis cuando se habilita el registro de análisis de almacenamiento. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes recibidas por el servidor. Para más información, consulte Acerca del registro Storage Analytics y registro de Azure: uso de registros para realizar un seguimiento Storage solicitudes.

Cuerpo de la solicitud

Ninguno.

Response

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

Código de estado

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

Para obtener información sobre los códigos de estado, vea Códigos de estado y de 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
Content-Type application/xml
Content-Length Tamaño del documento XML devuelto, en bytes
x-ms-request-id Este encabezado identifica de forma única la solicitud que se realizó y se puede utilizar para solucionar problemas relacionados con esta. Para más información, consulte Solución de problemas de operaciones de API.
x-ms-version Indica la versión del servicio Blob utilizado para ejecutar la solicitud.
Date Valor de fecha y hora UTC generado por el servicio que indica la hora a la que se inició la respuesta.
x-ms-client-request-id Este encabezado se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del encabezado si está presente en la solicitud y el valor tiene como máximo x-ms-client-request-id 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.

Cuerpo de la respuesta

En la versión 2020-04-08 y versiones posteriores, las etiquetas correspondientes del blob se encapsulan dentro de un elemento Tags. 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

El propietario de la cuenta y cualquier persona con una firma de acceso compartido que tenga permiso para buscar blobs por etiquetas (el permiso SAS) pueden llamar a esta f operación.

Además, los usuarios de RBAC con el permiso Microsoft.Storage/storageAccounts/blobServices/containers/blobs/filter/action pueden realizar esta operación.

Comentarios

La Find Blobs by Tags operación se admite en la API rest versión 2019-12-12 y posteriores.

El índice secundario utilizado por Find Blobs by Tags es finalmente coherente. Las actualizaciones de etiquetas de blob Set Blob Tags a través de muchas no son visibles inmediatamente para las Find Blobs by Tags operaciones.

Construir 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 determinada. 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 ansi SQL gramática de cláusula WHERE para el valor del where=<expression> parámetro de consulta. Se admiten los siguientes operadores:

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 parámetro URI debe estar codificado correctamente where como URI (incluidos los espacios y operadores). Los ejemplos anteriores omiten esto para mejorar la legibilidad.

Todos los valores de etiqueta son cadenas y 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, se debe emplear el relleno adecuado y el formato ordenable. Los valores de etiqueta deben incluirse entre comillas simples.

Si los nombres de etiqueta son SQL identificadores 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 no válida).

Vea también

Administración y búsqueda de datos en Azure Blob Storage con el Índice de blobs
Autorización de solicitudes para Azure Storage
Códigos de estado y error
Códigos de error del servicio BLOB