Compartir a través de

Enumerar blobs

  • Artículo

La operación List Blobs devuelve una lista de los blobs en el contenedor especificado.

Pedir

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

Método URI de solicitud Versión HTTP
GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list HTTP/1.1

URI del servicio de almacenamiento emulado

Al realizar una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto de Azure Blob Storage como 127.0.0.1:10000, seguido del nombre de la cuenta de almacenamiento emulada.

Método URI de solicitud Versión HTTP
GET http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list HTTP/1.1

Para más información, consulte Uso del emulador de Azurite para el desarrollo local de Azure Storage.

Parámetros de URI

Puede especificar los siguientes parámetros adicionales en el URI.

Parámetro Descripción
prefix Opcional. Filtra los resultados para devolver solo blobs con nombres que comiencen por el prefijo especificado. En las cuentas que tienen un espacio de nombres jerárquico, se producirá un error en los casos en los que el nombre de un archivo aparezca en medio de la ruta de acceso de prefijo. Por ejemplo, puede intentar buscar blobs denominados readmefile.txt mediante la ruta de acceso de prefijo folder1/folder2/readme/readmefile.txt. Aparecerá un error si alguna subcarpeta contiene un archivo denominado readme.
delimiter Opcional. Cuando la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix en el cuerpo de la respuesta. Este elemento actúa como marcador de posición para todos los blobs con nombres que comienzan con la misma subcadena, hasta la apariencia del carácter delimitador. El delimitador puede ser un solo carácter o una cadena.
marker Opcional. Valor de cadena que identifica la parte de la lista que se va a devolver con la siguiente operación de lista. La operación devuelve un valor de marcador dentro del cuerpo de la respuesta si la lista devuelta no se completó. A continuación, puede usar el valor del marcador en una llamada posterior para solicitar el siguiente conjunto de elementos de lista.

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

Establecer maxresults en un valor menor o igual que cero da como resultado el código de respuesta de error 400 (solicitud incorrecta).
include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,
deletedwithversions,immutabilitypolicy,legalhold,permissions}		 Opcional. Especifica uno o varios conjuntos de datos que se van a incluir en la respuesta:

- snapshots: especifica que las instantáneas deben incluirse en la enumeración. Las instantáneas se muestran de más antigua a más reciente en la respuesta.
- metadata: especifica que los metadatos del blob se devuelven en la respuesta.
- uncommittedblobs: especifica que los blobs para los que se han cargado los bloques, pero que no se han confirmado mediante Put Block List, se incluirán en la respuesta.
- copy: versión 2012-02-12 y posteriores. Especifica que los metadatos relacionados con cualquier operación de Copy Blob actual o anterior deben incluirse en la respuesta.
- deleted: versión 2017-07-29 y posteriores. Especifica que los blobs eliminados temporalmente deben incluirse en la respuesta.
- tags: versión 2019-12-12 y posteriores. Especifica que las etiquetas de índice de blobs definidas por el usuario deben incluirse en la respuesta.
- versions: versión 2019-12-12 y posteriores. Especifica que las versiones de blobs deben incluirse en la enumeración.
- deletedwithversions: versión 2020-10-02 y posteriores. Especifica que los blobs eliminados con cualquier versión (activa o eliminada) deben incluirse en la respuesta. Los elementos que ha eliminado permanentemente aparecen en la respuesta hasta que la recolección de elementos no utilizados los procesa. Use la etiqueta \<HasVersionsOnly\>y el valor true.
- immutabilitypolicy: versión 2020-06-12 y posteriores. Especifica que la enumeración debe incluir la directiva de inmutabilidad hasta la fecha y el modo de directiva de inmutabilidad de los blobs.
- legalhold: versión 2020-06-12 y posteriores. Especifica que la enumeración debe incluir la suspensión legal de los blobs.
- permissions: versión 2020-06-12 y posteriores. Solo se admite para las cuentas con un espacio de nombres jerárquico habilitado. Si una solicitud incluye este parámetro, el propietario, el grupo, los permisos y la lista de control de acceso de los blobs o directorios enumerados se incluirán en la enumeración.

Para especificar más de una de estas opciones en el URI, debe separar cada opción con una coma codificada por URL ("%82").
showonly={deleted,files,directories} Opcional. Especifica uno de estos conjuntos de datos que se van a devolver en la respuesta:

- deleted: opcional. Versión 2020-08-04 y posteriores. Solo para las cuentas habilitadas con espacio de nombres jerárquico. Cuando una solicitud incluye este parámetro, la lista solo contiene blobs eliminados temporalmente. Tenga en cuenta que no se admite la reserva de autorización posIX ACL para enumerar blobs eliminados temporalmente. Si también se especifica include=deleted, se produce un error en la solicitud incorrecta (400).
- files: opcional. Versión 2020-12-06 y posteriores. Solo para las cuentas habilitadas con espacio de nombres jerárquico. Cuando una solicitud incluye este parámetro, la lista solo contiene archivos.
- directories: opcional. Versión 2020-12-06 y posteriores. Solo para las cuentas habilitadas con espacio de nombres jerárquico. Cuando una solicitud incluye este parámetro, la lista solo contiene directorios.
timeout Opcional. El parámetro timeout se expresa en segundos. Para obtener más información, consulte Configuración de tiempos de espera para 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 Obligatorio. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Para más información, consulte Autorizar solicitudes a Azure Storage.
Date o x-ms-date Obligatorio. Especifica la hora universal coordinada (UTC) de la solicitud. Para más información, consulte Autorizar solicitudes a Azure Storage.
x-ms-version Necesario para todas las solicitudes autorizadas y opcional para las solicitudes anónimas. Especifica la versión de la operación que se va a usar para esta solicitud. Para más información, consulte Control de versiones de para 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. Para más información, consulte Monitor Azure Blob Storage.
x-ms-upn Opcional. Válido solo cuando se habilita un espacio de nombres jerárquico para la cuenta y include=permissions se proporciona en la solicitud. Si true, los valores de identidad de usuario devueltos en el>propietario de <, <grupo>y <campos de> Acl se transforman de identificadores de objeto de Microsoft Entra a nombres de entidad de seguridad de usuario. Si false, los valores se devuelven como identificadores de objeto de Microsoft Entra. El valor predeterminado es false. Tenga en cuenta que los identificadores de objeto de grupo y aplicación no se traducen porque no tienen nombres descriptivos únicos.

Cuerpo de la solicitud

Ninguno.

Solicitud de ejemplo

Consulte Enumeración de recursos de blobs para obtener una solicitud de ejemplo.

Respuesta

La respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y un cuerpo de respuesta en formato XML.

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 de esta operación incluye los siguientes encabezados. La respuesta también puede incluir encabezados HTTP adicionales estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1 de .

Encabezado de respuesta Descripción
Content-Type Especifica el formato en el que se devuelven los resultados. Actualmente, este valor es application/xml.
x-ms-request-id Este encabezado identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud. Para obtener más información, consulte Solución de problemas de operaciones de API.
x-ms-version Indica la versión de Blob Storage que se usa para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas mediante la versión 2009-09-19 y posteriores.

Este encabezado también se devuelve para las solicitudes anónimas, sin una versión especificada, si el contenedor se marcó para el acceso público mediante la versión 2009-09-19 de Blob Storage.
Date Valor de fecha y hora UTC que indica la hora a la que se inició la respuesta. El servicio genera este valor.
x-ms-client-request-id Puede usar este encabezado para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del encabezado x-ms-client-request-id, si está presente en la solicitud. El valor tiene como máximo 1024 caracteres ASCII visibles. Si el encabezado x-ms-client-request-id no está presente en la solicitud, este encabezado no estará presente en la respuesta.

Cuerpo de la respuesta

El formato de la respuesta XML es el siguiente.

Tenga en cuenta que los elementos Prefix, Marker, MaxResultsy Delimiter solo están presentes si se especificaron en el URI de solicitud. El elemento NextMarker tiene un valor solo si los resultados de la lista no están completos.

Las instantáneas, los metadatos de blobs y los blobs no confirmados se incluyen en la respuesta solo si se especifican con el parámetro include en el URI de solicitud.

En la versión 2009-09-19 y versiones posteriores, las propiedades del blob se encapsulan dentro de un elemento Properties.

A partir de la versión 2009-09-19, List Blobs devuelve los siguientes elementos cambiados de nombre en el cuerpo de la respuesta:

  • Last-Modified (anteriormente LastModified)

  • Content-Length (anteriormente Size)

  • Content-Type (anteriormente ContentType)

  • Content-Encoding (anteriormente ContentEncoding)

  • Content-Language (anteriormente ContentLanguage)

Aparece el elemento Content-MD5 para los blobs creados con la versión 2009-09-19 y versiones posteriores. En la versión 2012-02-12 y posteriores, Blob Storage calcula el valor de Content-MD5 al cargar un blob mediante Put Blob. Blob Storage no calcula esto al crear un blob mediante Put Block List. Puede establecer explícitamente el valor de Content-MD5 al crear el blob o llamando a la Put Block List o Set Blob Properties operaciones.

En el caso de las versiones de 2009-09-19 y posteriores, pero antes de la versión 2015-02-21, no se puede llamar a List Blobs en un contenedor que incluya blobs en anexos. El servicio devuelve el código de estado 409 (Conflicto) si el resultado de la lista contiene un blob en anexos.

LeaseState y LeaseDuration solo aparecen en la versión 2012-02-12 y versiones posteriores.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTimey CopyStatusDescription solo aparecen en la versión 2012-02-12 y versiones posteriores, cuando esta operación incluye el parámetro include={copy}. Estos elementos no aparecen si este blob nunca ha sido el destino en una operación de Copy Blob. Los elementos no aparecen si este blob se ha modificado después de una operación de Copy Blob concluida, mediante Set Blob Properties, Put Blobo Put Block List. Estos elementos tampoco aparecen con un blob creado por Copy Blob, antes de la versión 2012-02-12.

En la versión 2013-08-15 y versiones posteriores, el elemento EnumerationResults contiene un atributo ServiceEndpoint que especifica el punto de conexión de blob. Este elemento también contiene un campo ContainerName que especifica el nombre del contenedor. En versiones anteriores, estos dos atributos se combinaron en el campo ContainerName. También en la versión 2013-08-15 y versiones posteriores, se ha quitado el elemento Url en Blob.

Para la versión 2015-02-21 y posteriores, List Blobs devuelve blobs de todos los tipos (blobs en bloques, páginas y anexos).

Para la versión 2015-12-11 y posteriores, List Blobs devuelve el elemento ServerEncrypted. Este elemento se establece en true si los metadatos de blob y aplicación están completamente cifrados y false de lo contrario.

Para la versión 2016-05-31 y posteriores, List Blobs devuelve el elemento IncrementalCopy para las instantáneas y los blobs de copia incremental, con el valor establecido en true.

Para la versión 2017-04-17 y posteriores, List Blobs devuelve el elemento AccessTier si se ha establecido explícitamente un nivel de acceso. Para obtener una lista de los niveles de blob en páginas prémium permitidos, consulte Almacenamiento premium de alto rendimiento y discos administrados para máquinas virtuales. En el caso de las cuentas de Blob Storage o de uso general v2, los valores válidos son Hot, Cooly Archive. Si el blob está en estado de rehidratación pendiente, se devuelve ArchiveStatus elemento con uno de los valores válidos (rehydrate-pending-to-hot, rehydrate-pending-to-coolo rehydrate-pending-to-cold). Para obtener información detallada sobre los niveles de blobs en bloques, consulte niveles de almacenamiento frecuente, esporádico y de archivo.

Para la versión 2017-04-17 y posteriores, List Blobs devuelve el elemento AccessTierInferred en cuentas de Blob Storage o de uso general v2. Si el blob en bloques no tiene establecido el nivel de acceso, la información del nivel se deduce de las propiedades de la cuenta de almacenamiento y este valor se establece en true. Este encabezado solo está presente si el nivel se deduce de la propiedad account.

Para la versión 2017-04-17 y posteriores, List Blobs devuelve el elemento AccessTierChangeTime en cuentas de Blob Storage o de uso general v2. Esto solo se devuelve si se estableció el nivel en el blob en bloques. Para obtener más información, vea Representación de valores de fecha y hora en encabezados.

Para la versión 2017-07-29 y posteriores, Deleted, DeletedTimey RemainingRetentionDays aparecen cuando esta operación incluye el parámetro include={deleted}. Estos elementos no aparecen si este blob no se eliminó. Estos elementos aparecen para blobs o instantáneas que se eliminan con la operación de DELETE, cuando se ha habilitado la característica de eliminación temporal. El elemento Deleted se establece en true para blobs e instantáneas que se eliminan temporalmente. Deleted-Time corresponde a la hora en que se eliminó el blob. RemainingRetentionDays indica el número de días después de los cuales se elimina permanentemente un blob eliminado temporalmente.

Para la versión 2017-11-09 y posteriores, Creation-Time devuelve la hora en la que se creó este blob.

Para la versión 2019-02-02 y posteriores, List Blobs devuelve el elemento CustomerProvidedKeySha256 si el blob está cifrado con una clave proporcionada por el cliente. El valor se establecerá en el hash SHA-256 de la clave que se usa para cifrar el blob. Además, si la operación incluye el parámetro include={metadata} y hay metadatos de aplicación presentes en un blob cifrado con una clave proporcionada por el cliente, el elemento Metadata tendrá un atributo Encrypted="true". Este atributo indica que el blob tiene metadatos que no se pueden descifrar como parte de la operación de List Blobs. Para acceder a los metadatos de estos blobs, llame a Get Blob Properties o Get Blob Metadata con la clave proporcionada por el cliente.

Para la versión 2019-02-02 y posteriores, List Blobs devuelve el elemento EncryptionScope si el blob está cifrado con un ámbito de cifrado. El valor se establecerá en el nombre del ámbito de cifrado que se usa para cifrar el blob. Si la operación incluye el parámetro include={metadata}, los metadatos de la aplicación en el blob se descifran de forma transparente y están disponibles en el elemento Metadata.

Para la versión 2019-12-12 y posteriores, List Blobs devuelve el elemento RehydratePriority en cuentas de Blob Storage o de uso general v2, si el objeto está en estado de rehydrate pending. Los valores válidos son High y Standard.

Para la versión 2019-12-12 y posteriores, List Blobs devuelve el elemento VersionId para blobs y versiones de blobs generadas, cuando el control de versiones está habilitado en la cuenta.

Para la versión 2019-12-12 y posteriores, List Blobs devuelve el elemento IsCurrentVersion para la versión actual del blob. El valor se establece en true. Este elemento permite diferenciar la versión actual de las versiones de solo lectura generadas automáticamente.

Para la versión 2019-12-12 y posteriores, List Blobs devuelve el elemento TagCount para blobs con etiquetas. El elemento Tags solo aparece cuando esta operación incluye el parámetro include={tags}. Estos elementos no aparecen si no hay etiquetas en el blob.

Para la versión 2019-12-12 y posteriores, List Blobs devuelve el elemento Sealed para blobs en anexos. El elemento Sealed solo aparece cuando el blob en anexos se ha sellado. Estos elementos no aparecen si el blob en anexos no está sellado.

Para la versión 2020-02-10 y posteriores, List Blobs devuelve el elemento LastAccessTime. El elemento muestra cuándo se accedió por última vez a los datos del blob, según la directiva de seguimiento de hora de último acceso de la cuenta de almacenamiento. El elemento no se devuelve si la cuenta de almacenamiento no tiene esta directiva o la directiva está deshabilitada. Para obtener información sobre cómo establecer la directiva de seguimiento de la hora de último acceso de la cuenta, consulte API de Blob Service. El elemento LastAccessTime no realiza el seguimiento de la última vez que se accede a los metadatos del blob.

Para la versión 2020-06-12 y posteriores, List Blobs devuelve los elementos ImmutabilityPolicyUntilDate y ImmutabilityPolicyMode, cuando esta operación incluye el parámetro include={immutabilitypolicy}.

Para la versión 2020-06-12 y posteriores, List Blobs devuelve el elemento LegalHold, cuando esta operación incluye el parámetro include={legalhold}.

Para la versión 2020-06-12 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs devuelve los elementos Owner, Group, Permissionsy Acl. La solicitud debe contener el parámetro include={permissions}. Tenga en cuenta que el elemento Acl es una lista combinada de listas de control de acceso y de control de acceso predeterminadas que se establecieron en el archivo o directorio.

Para la versión 2020-06-12 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs con un delimitador devuelve el elemento Properties en el elemento BlobPrefix. Esto corresponde a las propiedades del directorio .

Para la versión 2020-08-04 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs devuelve el elemento DeletionId para los blobs eliminados. DeletionId es un identificador de 64 bits sin signo. El elemento identifica de forma única una ruta de acceso eliminada temporalmente para distinguirlo de otros blobs eliminados con la misma ruta de acceso.

Para la versión 2020-10-02 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs devuelve el elemento de propiedad ResourceType para la ruta de acceso. Esto puede ser file o directory.

Para la versión 2021-02-12 y posteriores, List Blobs codificará por porcentaje (por RFC 2396) todos los valores de elemento BlobName o BlobPrefixName. En concreto, lo hará para aquellos valores que contengan caracteres que no sean válidos en XML (U+FFFE o U+FFFF). Si se codifica, el elemento Name incluirá un atributo Encoded=true. Tenga en cuenta que esto solo se produce para los valores de elemento Name que contienen los caracteres no válidos en XML, no los elementos Name restantes de la respuesta.

Para la versión 2021-06-08 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs devuelve el elemento de propiedades Placeholder. Devuelve este elemento en el elemento BlobPrefix para los directorios de marcadores de posición, al enumerar blobs eliminados con un delimitador. Estos directorios de marcador de posición existen para facilitar la navegación a blobs eliminados temporalmente.

Para la versión 2021-06-08 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs devuelve el elemento EncryptionContext. Si se establece el valor de la propiedad de contexto de cifrado, devolverá el valor establecido.

Para la versión 2020-02-10 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, List Blobs devuelve el elemento Expiry-Time para los blobs eliminados. Expiry-Time es la hora en que expirará el archivo y se devuelve para el archivo si la expiración está establecida en el mismo.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Delimiter>string-value</Delimiter>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</name>  
      <Snapshot>date-time-value</Snapshot>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <Content-Length>size-in-bytes</Content-Length>  
        <Content-Type>blob-content-type</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>  
        <BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <LeaseStatus>locked|unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration>  
        <CopyId>id</CopyId>  
        <CopyStatus>pending | success | aborted | failed </CopyStatus>  
        <CopySource>source url</CopySource>  
        <CopyProgress>bytes copied/bytes total</CopyProgress>  
        <CopyCompletionTime>datetime</CopyCompletionTime>  
        <CopyStatusDescription>error string</CopyStatusDescription>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context<EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

Respuesta de ejemplo

Consulte Enumeración de recursos de blobs para obtener una respuesta de ejemplo.

Autorización

Se requiere autorización al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la operación de List Blobs como se describe a continuación.

Importante

Microsoft recomienda usar el identificador de Entra de Microsoft con identidades administradas para autorizar solicitudes a Azure Storage. Microsoft Entra ID proporciona seguridad y facilidad de uso superiores en comparación con la autorización de clave compartida.

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. Microsoft Entra ID autentica la entidad de seguridad para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para obtener más información sobre la autorización mediante el identificador de Entra de Microsoft, consulte Autorizar el acceso a blobs mediante el identificador de Microsoft Entra.

Permisos

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

Si especifica include=tags:

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

Observaciones

Propiedades de blob en la respuesta

Si ha solicitado que los blobs no confirmados se incluyan en la enumeración, tenga en cuenta que algunas propiedades no se establecen hasta que se confirme el blob. Es posible que algunas propiedades no se devuelvan en la respuesta.

El elemento x-ms-blob-sequence-number solo se devuelve para blobs en páginas.

El elemento OrMetadata solo se devuelve para blobs en bloques.

Para los blobs en páginas, el valor devuelto en el elemento Content-Length corresponde al valor del encabezado x-ms-blob-content-length del blob.

El elemento Content-MD5 aparece en el cuerpo de la respuesta, solo si se ha establecido en el blob mediante la versión 2009-09-19 o posterior. Puede establecer la propiedad Content-MD5 cuando se crea el blob o llamando a Set Blob Properties. En la versión 2012-02-12 y versiones posteriores, Put Blob establece el valor MD5 de un blob en bloques, incluso cuando la solicitud de Put Blob no incluye un encabezado MD5.

Metadatos en la respuesta

El elemento Metadata solo está presente si se especificó el parámetro include=metadata en el URI. Dentro del elemento Metadata, el valor de cada par nombre-valor aparece dentro de un elemento correspondiente al nombre del par.

Tenga en cuenta que los metadatos solicitados con este parámetro deben almacenarse de acuerdo con las restricciones de nomenclatura impuestas por la versión 2009-09-19 de Blob Storage. A partir de esta versión, todos los nombres de metadatos deben cumplir las convenciones de nomenclatura para identificadores de C#.

Si un par nombre-valor de metadatos infringe estas restricciones de nomenclatura, el cuerpo de la respuesta indica el nombre problemático dentro de un elemento x-ms-invalid-name. El siguiente fragmento XML muestra esto:

  
…  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>  
…

Etiquetas en la respuesta

El elemento Tags solo está presente si el parámetro include=tags se especificó en el URI y si hay etiquetas en el blob. Dentro del elemento TagSet, se devuelven hasta 10 elementos Tag, cada uno que contiene el key y value de las etiquetas de índice de blobs definidas por el usuario. No se garantiza el orden de las etiquetas en la respuesta.

Los elementos Tags y TagCount no se devuelven si no hay ninguna etiqueta en el blob.

El servicio de almacenamiento mantiene una coherencia fuerte entre un blob y sus etiquetas, pero el índice secundario es finalmente coherente. Las etiquetas pueden ser visibles en una respuesta a List Blobs antes de que sean visibles para Find Blobs by Tags operaciones.

Instantáneas en la respuesta

Las instantáneas se muestran en la respuesta solo si se especificó el parámetro include=snapshots en el URI. Las instantáneas enumeradas en la respuesta no incluyen el elemento LeaseStatus, ya que las instantáneas no pueden tener concesiones activas.

Con la versión del servicio 2021-06-08 y versiones posteriores, puede llamar a List Blobs con un delimitador e incluir instantáneas en la enumeración. En el caso de las versiones de servicio anteriores a 2021-06-08, una solicitud que incluye ambos devuelve un error InvalidQueryParameter (código de estado HTTP 400 : solicitud incorrecta).

Blobs no confirmados en la respuesta

Los blobs no confirmados se muestran en la respuesta solo si el parámetro include=uncommittedblobs se especificó en el URI. Los blobs no confirmados enumerados en la respuesta no incluyen ninguno de los siguientes elementos:

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

Blobs eliminados en la respuesta

Los blobs eliminados se muestran en la respuesta solo si se especificó el parámetro include=deleted en el URI. Los blobs eliminados enumerados en la respuesta no incluyen los elementos de concesión de , ya que los blobs eliminados no pueden tener concesiones activas.

Las instantáneas eliminadas se incluyen en la respuesta de lista si include=deleted,snapshot se especificó en el URI.

Metadatos de replicación de objetos en la respuesta

El elemento OrMetadata está presente cuando se ha evaluado una directiva de replicación de objetos en un blob y la llamada List Blobs se realizó mediante la versión 2019-12-12 o posterior. Dentro del elemento OrMetadata, el valor de cada par nombre-valor aparece dentro de un elemento correspondiente al nombre del par. El formato del nombre es or-{policy-id}_{rule-id}, donde {policy-id} es un GUID que representa el identificador de directiva de replicación de objetos en la cuenta de almacenamiento. {rule-id} es un GUID que representa el identificador de regla en el contenedor de almacenamiento. Los valores válidos son complete o failed.

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…

Directiva de inmutabilidad en la respuesta

Los elementos ImmutabilityPolicyUntilDate y ImmutabilityPolicyMode solo están presentes si el parámetro include=immutabilitypolicy se especificó en el URI.

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties>

El elemento LegalHold solo está presente si se especificó el parámetro include=legalhold en el URI.

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties>

Devolver conjuntos de resultados mediante un valor de marcador

Si especifica un valor para el parámetro maxresults y el número de blobs que se van a devolver supera este valor, o supera el valor predeterminado de maxresults, el cuerpo de la respuesta contiene un elemento NextMarker. Este elemento indica el siguiente blob que se va a devolver en una solicitud posterior. En determinados casos, el servicio puede devolver el elemento NextMarker aunque el número de resultados devueltos sea menor que el valor de maxresults.

Para devolver el siguiente conjunto de elementos, especifique el valor de NextMarker como parámetro de marcador en el URI para la solicitud posterior. Tenga en cuenta que el valor de NextMarker debe tratarse como opaco.

Uso de un delimitador para recorrer el espacio de nombres de blob

El parámetro delimiter permite al autor de la llamada atravesar el espacio de nombres del blob mediante un delimitador configurado por el usuario. De este modo, puede atravesar una jerarquía virtual de blobs como si fuera un sistema de archivos. El delimitador puede ser un solo carácter o una cadena.

Cuando la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix. El elemento BlobPrefix se devuelve en lugar de todos los blobs con nombres que comienzan con la misma subcadena, hasta la apariencia del carácter delimitador. El valor del elemento BlobPrefix es subcadena+delimitador, donde subcadena es la subcadena común que comienza uno o varios nombres de blobs y delimitador es el valor del parámetro delimiter.

Puede usar el valor de BlobPrefix para realizar una llamada posterior para enumerar los blobs que comienzan por este prefijo. Para ello, especifique el valor de BlobPrefix para el parámetro prefix en el URI de solicitud.

Tenga en cuenta que cada elemento BlobPrefix devuelve recuentos hacia el resultado máximo, al igual que lo hace cada elemento Blob.

Los blobs se enumeran en orden alfabético en el cuerpo de la respuesta, con letras mayúsculas enumeradas primero.

Errores de copia en la descripción del estado de copia

CopyStatusDescription contiene más información sobre el error de Copy Blob.

  • Cuando se produce un error en un intento de copia, CopyStatus se establece en pending si Blob Storage sigue reintentando la operación. El texto CopyStatusDescription describe el error que podría haberse producido durante el último intento de copia.

  • Cuando CopyStatus se establece en failed, el texto del CopyStatusDescription describe el error que provocó un error en la operación de copia.

En la tabla siguiente se describen los campos de cada valor de CopyStatusDescription.

Componente Descripción
Código de estado HTTP Entero de tres dígitos estándar que especifica el error.
Código de error Palabra clave que describe el error. Azure lo proporciona en el elemento <ErrorCode>. Si no aparece ningún <elemento ErrorCode>, el servicio devuelve una palabra clave que contiene texto de error estándar asociado al código de estado HTTP de tres dígitos en la especificación HTTP. Para obtener más información, consulte códigos de error comunes de la API REST.
Información Descripción detallada del error, entre comillas.

En la tabla siguiente se describen los valores CopyStatus y CopyStatusDescription de escenarios de error comunes.

Importante

El texto de descripción que se muestra aquí puede cambiar sin advertencia, incluso sin un cambio de versión. No confíe en que coincida con este texto exacto.

Escenario Copiar valor de estado Copiar valor de descripción del estado
La operación de copia se completó correctamente. éxito vacío
El usuario anuló la operación de copia antes de completarla. abortado vacío
Error al leer desde el blob de origen durante una operación de copia. Se reintentará la operación. pendiente 502 BadGateway "Se encontró un error que se puede reintentar al leer el origen. Volverá a intentarlo. Hora de error: <tiempo>"
Error al escribir en el blob de destino de una operación de copia. Se reintentará la operación. pendiente 500 InternalServerError "Se encontró un error que se puede reintentar. Volverá a intentarlo. Hora de error: <tiempo>"
Se produjo un error irrecuperable al leer desde el blob de origen de una operación de copia. fracasado 404 ResourceNotFound "Error de copia al leer el origen". Cuando el servicio notifica este error subyacente, devuelve ResourceNotFound en el elemento <ErrorCode>. Si no <elemento ErrorCode> aparece en la respuesta, aparece una representación de cadena estándar del estado HTTP, como NotFound, .
El período de tiempo de espera que limita todas las operaciones de copia transcurridos. (Actualmente, el período de tiempo de espera es de dos semanas). fracasado 500 OperationCancelled "La copia superó el tiempo máximo permitido".
Error en la operación de copia con demasiada frecuencia al leer desde el origen y no cumplan una proporción mínima de intentos de éxito. (Este tiempo de espera impide volver a intentar un origen muy deficiente durante dos semanas antes de que se produzca un error). fracasado 500 OperationCancelled "Error de copia al leer el origen".

Facturación

Las solicitudes de precios pueden originarse en clientes que usan api de Blob Storage, ya sea directamente a través de la API REST de Blob Storage o desde 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 a las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de las solicitudes de List Blobs en función del tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
Enumerar blobs Blob en bloques Premium
Uso general estándar v2
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 de Azure Blob Storage.

Consulte también

códigos de error y estado
códigos de error de Blob Storage