List Blobs
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
(anteriormenteLastModified
)Content-Length
(anteriormenteSize
)Content-Type
(anteriormenteContentType
)Content-Encoding
(anteriormenteContentEncoding
)Content-Language
(anteriormenteContentLanguage
)
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 Blob
o 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
, Cool
y 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-cool
o 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 true
en . 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
, DeletedTime
y 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 Owner
elementos , Permissions
Group
, 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 losName
Blob
valores de elemento o BlobPrefix
Name
. 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.
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 establecepending
en si Blob Storage sigue reintentando la operación. En el texto seCopyStatusDescription
describe el error que podría haberse producido durante el último intento de copia.Si
CopyStatus
se establece enfailed
, el texto deCopyStatusDescription
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.