List Blobs

Artículo
03/16/2023

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

Solicitud

Puede construir la List Blobs solicitud como se indica a continuación. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento.

Método	URI de solicitud	Versión de 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 Azure Blob Storage puerto como 127.0.0.1:10000, seguido del nombre de la cuenta de almacenamiento emulada.

Método	URI de solicitud	Versión de 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 del identificador 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 comienzan 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 aparece en medio de la ruta de acceso del prefijo. Por ejemplo, puede intentar buscar blobs con nombre `readmefile.txt` mediante la ruta `folder1/folder2/readme/readmefile.txt`de acceso de prefijo . 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 `BlobPrefix` elemento 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 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 en el cuerpo de respuesta si la lista devuelta no estaba completa. A continuación, puede usar el valor del marcador en una llamada posterior para solicitar el siguiente conjunto de elementos de lista. El valor de 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 `maxresults`o especifica un valor mayor que 5000, el servidor devolverá hasta 5000 elementos. Si hay resultados adicionales para devolver, el servicio devuelve un token de continuación en el `NextMarker` elemento de respuesta. En ciertos casos, el servicio podría devolver menos resultados de los especificados por `maxresults`y también 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).
`include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,` `deletedwithversions,immutabilitypolicy,legalhold,permissions}`	Opcional. Especifica uno o más conjuntos de datos que se deben incluir en la respuesta: - `snapshots`: especifica que las instantáneas deben incluirse en la enumeración . Las instantáneas aparecen ordenadas de más antigua a más reciente en la respuesta. - `metadata`: especifica que los metadatos de 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 se deben incluir en la respuesta los metadatos relacionados con cualquier operación `Copy Blob` actual o previa. -`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 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 para los blobs o directorios enumerados se incluirán en la enumeración. Si desea especificar varias de estas opciones en el URI, debe separarlas mediante una coma codificada para URL ("%82").
`showonly={deleted,files,directories}`	Opcional. Especifica uno de estos conjuntos de datos que se devolverán en la respuesta: -`deleted`:Opcional. Versión 2020-08-04 y posteriores. Solo para las cuentas habilitadas con el 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 de ACL POSIX para enumerar blobs eliminados temporalmente. Si `include=deleted` también se especifica , se produce un error en la solicitud incorrecta (400). -`files`:Opcional. Versión 2020-12-06 y posteriores. Solo para las cuentas habilitadas con el 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 el 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 más información, consulte Configuración de tiempos de espera para las operaciones de Blob Storage.

Encabezados de solicitud

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

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de la 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 y 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. Para obtener más información, vea Supervisar 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`es , los valores de identidad de usuario devueltos en los <campos Propietario>, <Grupo> y <Acl> se transforman de Microsoft Entra identificadores de objeto a nombres principales de usuario. Si `false`es , los valores se devuelven como identificadores de objeto 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 blob para obtener una solicitud de ejemplo.

Response

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

status code

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 encabezados HTTP adicionales y 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`	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 más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Indica la versión de Blob Storage usada 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 `x-ms-client-request-id` encabezado, si está presente en la solicitud. El valor es como máximo 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

El formato de la respuesta XML es el siguiente.

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

Las instantáneas, los metadatos del blob y los blobs sin confirmar se incluyen en la respuesta solo si se especifican mediante el parámetro include en el URI de solicitud.

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

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

Last-Modified (anteriormente LastModified)
Content-Length (anteriormente Size)
Content-Type (anteriormente ContentType)
Content-Encoding (anteriormente ContentEncoding)
Content-Language (anteriormente ContentLanguage)

El Content-MD5 elemento aparece para los blobs creados con la versión 2009-09-19 y posteriores. En la versión 2012-02-12 y posteriores, Blob Storage calcula el Content-MD5 valor 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 Content-MD5 valor al crear el blob o llamando a las operaciones Put Block List o Set Blob Properties .

En el caso de las versiones 2009-09-19 y posteriores, pero antes de la versión 2015-02-21, no se puede llamar List Blobs a 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 posteriores.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTime y 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 Copy Blob operación. Los elementos no aparecen si este blob se ha modificado después de una operación concluida Copy Blob , 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 posteriores, el EnumerationResults elemento contiene un ServiceEndpoint atributo que especifica el punto de conexión del blob. Este elemento también contiene un ContainerName campo que especifica el nombre del contenedor. En versiones anteriores, estos dos atributos se combinaron en el ContainerName campo . También en la versión 2013-08-15 y posteriores, se ha quitado el Url elemento 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 ServerEncrypted elemento . Este elemento se establece true en 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 IncrementalCopy elemento 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 AccessTier elemento si se ha establecido explícitamente un nivel de acceso. Para obtener una lista de los niveles de blob en páginas Premium 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, el ArchiveStatus elemento se devuelve 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 de acceso frecuente , esporádico y de archivo.

Para la versión 2017-04-17 y posteriores, List Blobs devuelve el AccessTierInferred elemento 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 trueen . 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 AccessTierChangeTime elemento 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 include={deleted} parámetro . Estos elementos no aparecen si este blob no se eliminó. Estos elementos aparecen para blobs o instantáneas que se eliminan con la DELETE operación, cuando se habilitó la característica de eliminación temporal. El Deleted elemento se establece true en 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 CustomerProvidedKeySha256 elemento si el blob está cifrado con una clave proporcionada por el cliente. El valor se establecerá en el hash SHA-256 de la clave utilizada para cifrar el blob. Además, si la operación incluye el include={metadata} parámetro y hay metadatos de aplicación presentes en un blob cifrado con una clave proporcionada por el cliente, el Metadata elemento tendrá un Encrypted="true" atributo . Este atributo indica que el blob tiene metadatos que no se pueden descifrar como parte de la List Blobs operación. 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 EncryptionScope elemento si el blob está cifrado con un ámbito de cifrado. El valor se establecerá en el nombre del ámbito de cifrado usado para cifrar el blob. Si la operación incluye el include={metadata} parámetro , los metadatos de la aplicación en el blob se descifran de forma transparente y están disponibles en el Metadata elemento .

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

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

Para la versión 2019-12-12 y posteriores, List Blobs devuelve el Sealed elemento para los blobs en anexos. El Sealed elemento 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 LastAccessTime elemento . El elemento muestra cuándo se accedió por última vez a los datos del blob, según la directiva de seguimiento de hora de acceso de la última 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 hora de último acceso de la cuenta, consulte La API de Blob Service. El LastAccessTime elemento 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 ImmutabilityPolicyUntilDate elementos y ImmutabilityPolicyMode , cuando esta operación incluye el include={immutabilitypolicy} parámetro .

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

Para la versión 2020-06-12 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, devuelve los Ownerelementos , PermissionsGroup, y Acl . List Blobs La solicitud debe contener el include={permissions} parámetro . Tenga en cuenta que el Acl elemento 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 Properties elemento en el BlobPrefix elemento . 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 DeletionId elemento 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 distinguirla 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 ResourceType elemento de propiedad de la ruta de acceso. Puede ser file o directory.

Para la versión 2021-02-12 y posteriores, List Blobs codificará por porcentaje (por RFC 2396) todos losNameBlobvalores de elemento 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 está codificado, el Name elemento incluirá un Encoded=true atributo . Tenga en cuenta que esto solo se produce para los Name valores de elemento que contienen los caracteres no válidos en XML, no para los elementos restantes Name 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 Placeholder elemento properties. Devuelve este elemento en el BlobPrefix elemento para los directorios de marcador 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 EncryptionContext elemento . Si el valor de la propiedad de contexto de cifrado se establece, 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 Expiry-Time elemento 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 muestra

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

Authorization

La autorización es necesaria al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la List Blobs 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 List Blobs operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Acción RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rol integrado con privilegios mínimos:Lector de datos de Blob de Storage

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.

Una firma de acceso compartido (SAS) proporciona acceso delegado seguro a los recursos de una cuenta de almacenamiento. Con una SAS, tiene un control pormenorizado sobre cómo un cliente puede acceder a los datos. Puede especificar a qué recurso puede acceder el cliente, qué permisos tienen para esos recursos y cuánto tiempo es válido la SAS.

La List Blobs operación admite tres tipos de firmas de acceso compartido: SAS de delegación de usuarios, SAS de servicio y SAS de cuenta.

Como procedimiento recomendado de seguridad, se recomienda usar Microsoft Entra credenciales en lugar de la clave de la cuenta de almacenamiento, que se puede poner en peligro más fácilmente. Si el diseño de la aplicación requiere firmas de acceso compartido, use Microsoft Entra credenciales para crear una SAS de delegación de usuarios, siempre que sea posible.

Cuando no se permite el acceso a la clave compartida para la cuenta de almacenamiento, no se permitirá un token de SAS de servicio o un token de SAS de cuenta en una solicitud a Blob Storage. Para más información, consulte Descripción de cómo no permitir la clave compartida afecta a los tokens de SAS.

SAS de delegación de usuarios

Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra y también por los permisos especificados para la SAS.

La llamada a la List Blobs operación mediante un token de SAS delegado en un recurso de contenedor requiere el permiso List (l) como parte del token de SAS de delegación de usuarios.

Para más información sobre la SAS de delegación de usuarios, consulte Creación de una SAS de delegación de usuarios.

SAS de servicio

Una SAS de servicio está protegida con la clave de cuenta de almacenamiento. Una SAS de servicio delega el acceso a un recurso en un único servicio de Azure Storage, como Blob Storage.

La llamada a la List Blobs operación mediante un token de SAS delegado en un recurso de contenedor requiere el permiso List (l) como parte del token de SAS de servicio.

Para más información sobre la SAS de servicio, consulte Creación de una SAS de servicio.

SAS de cuenta

Una SAS de cuenta está protegida con la clave de cuenta de almacenamiento. SAS de cuenta delega el acceso a los recursos en uno o varios de los servicios de almacenamiento. Todas las operaciones disponibles con una SAS de servicio o delegación de usuarios están también disponibles con una SAS de cuenta.

En la tabla siguiente se indica el tipo de recurso firmado y los permisos firmados que se especificarán al delegar el acceso:

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
List Blobs	Blob (b)	Contenedor (c)	Lista (l)

Para más información sobre la SAS de cuenta, consulte Creación de una SAS de cuenta.

Comentarios

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 los blobs en páginas.

El OrMetadata elemento solo se devuelve para blobs en bloques.

En 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 Content-MD5 elemento 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 Content-MD5 propiedad cuando se crea el blob o llamando a Establecer propiedades de blob. En la versión 2012-02-12 y posteriores, Put Blob establece el valor MD5 de un blob en bloques, incluso cuando la Put Blob solicitud no incluye un encabezado MD5.

Metadatos en la respuesta

El elemento Metadata está presente solo si se especificó el parámetro include=metadata en el URI. Dentro del elemento Metadata, el valor de cada par nombre-valor aparece en un elemento que corresponde 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 de los 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 x-ms-invalid-name elemento. El siguiente fragmento XML muestra lo siguiente:

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

Los Tags elementos y TagCount no se devuelven si no hay etiquetas 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 las operaciones.

Instantáneas en la respuesta

Las instantáneas aparecen 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 LeaseStatus elemento , porque 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. Para 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 sin confirmar aparecen en la respuesta solo si se especificó el parámetro include=uncommittedblobs 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 include=deleted parámetro en el URI. Los blobs eliminados enumerados en la respuesta no incluyen los elementos Lease , 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 OrMetadata elemento está presente cuando se ha evaluado una directiva de replicación de objetos en un blob y la llamada se realizó mediante la List Blobs versión 2019-12-12 o posterior. Dentro del elemento OrMetadata, el valor de cada par nombre-valor aparece en un elemento que corresponde 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 la 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 y 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 ImmutabilityPolicyUntilDate elementos y ImmutabilityPolicyMode solo están presentes si el include=immutabilitypolicy parámetro se especificó en el URI.

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

Suspensión legal en la respuesta

El elemento LegalHold está presente solo 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 maxresults parámetro y el número de blobs que se van a devolver supera este valor o supera el valor predeterminado para maxresults, el cuerpo de la respuesta contiene un NextMarker elemento . Este elemento indica el siguiente blob que se va a devolver en una solicitud posterior. En ciertos casos, el servicio podría devolver el NextMarker elemento 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 el parámetro de marcador en el URI para la solicitud siguiente. Tenga en cuenta que el valor de NextMarker se debe tratar como opaco.

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

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

Si la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix. El BlobPrefix elemento 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 BlobPrefix elemento es subcadena+delimitador, donde subcadena es la subcadena común que comienza uno o varios nombres de blobs y delimitador es el valor del delimiter parámetro.

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 para el prefix parámetro en el URI de BlobPrefix solicitud.

Tenga en cuenta que cada elemento BlobPrefix devuelto se tiene en cuenta para calcular el número máximo de resultados, de la misma manera que los elementos Blob.

Los blobs se muestran en el cuerpo de respuesta en orden alfabético, con las letras mayúsculas en primer lugar.

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 pending en si Blob Storage sigue reintentando la operación. En el texto se CopyStatusDescription describe el error que podría haberse producido durante el último intento de copia.
Si CopyStatus se establece en failed, el texto de CopyStatusDescription describe el error que provocó la operación de copia incorrecta.

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

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 más información, consulte Códigos de error comunes de la API de REST.
Information	Descripción detallada del error, entre comillas.

En la tabla siguiente se describen los valores de CopyStatus y CopyStatusDescription en 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 se base en que coincida con este texto exacto.

Escenario	Valor de estado de copia	Valor de descripción de estado de copia
Operación de copia completada correctamente.	success	empty
El usuario anuló la operación de copia antes de completarla.	aborted	empty
Error al leer desde el blob de origen durante una operación de copia. Se reintentará la operación.	pending	502 BadGateway "Al leer el origen se encontró un error que se puede reintentar. Se volverá a intentar. Hora de error: <hora>"
Error al escribir en el blob de destino de una operación de copia. Se reintentará la operación.	pending	500 InternalServerError "Se encontró un error que se puede volver a intentar. Se volverá a intentar. Hora de error: <hora>"
Se produjo un error irrecuperable al leer el blob de origen durante una operación de copia.	con errores	404 ResourceNotFound "Error de copia al leer el origen". Cuando el servicio notifica este error subyacente, se devuelve `ResourceNotFound` en el <elemento ErrorCode> . Si no aparece ningún <elemento ErrorCode> en la respuesta, aparece una representación de cadena estándar del estado HTTP, como `NotFound`, .
El tiempo de espera que limita todas las operaciones de copia realizadas. (Actualmente, el período de tiempo de espera es de dos semanas).	con errores	500 OperationCancelled "La copia superó el tiempo máximo permitido."
La operación de copia produjo errores muy frecuentes al leer del origen y no alcanzó la relación mínima entre intentos y operaciones correctas. (Este tiempo de espera impide volver a intentar un origen muy deficiente durante dos semanas antes de que se produzca un error).	con errores	500 OperationCancelled "Error en la 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 List Blobs las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación	Tipo de cuenta de almacenamiento	Categoría de facturación
List Blobs	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

Estado y códigos de error
Códigos de error de Blob Storage