Compartir a través de


List Containers

La List Containers operación devuelve una lista de los contenedores de la cuenta de almacenamiento especificada.

Solicitud

Puede construir la solicitud de la List Containers siguiente manera. 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/?comp=list HTTP/1.1

Tenga en cuenta que el URI debe incluir siempre la barra diagonal (/) para separar el nombre de host de las partes de la ruta de acceso y de la consulta del URI. En el caso de la operación List Containers, la parte de la ruta de acceso del URI está vacía.

Solicitud 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?comp=list HTTP/1.1

Tenga en cuenta que el almacenamiento emulado solo admite tamaños de blob de hasta 2 GiB.

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

Parámetros del identificador URI

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

Parámetro Descripción
prefix Opcional. Filtra los resultados para devolver solo los contenedores con un nombre que comienza con el prefijo especificado.
marker Opcional. Valor de cadena que identifica la parte de la lista de contenedores que se va a devolver con la siguiente operación de lista. La operación devuelve el NextMarker valor dentro del cuerpo de la respuesta, si la operación de lista no devolvió todos los contenedores restantes para que se muestren con la página actual. Puede usar el NextMarker valor como valor del marker parámetro en una llamada posterior para solicitar la siguiente página de elementos de lista.

El valor de marcador es opaco para el cliente.
maxresults Opcional. Especifica el número máximo de contenedores que se van a devolver. Si la solicitud no especifica maxresultso especifica un valor mayor que 5000, el servidor devolverá hasta 5000 elementos.

Tenga en cuenta que si la operación de lista cruza un límite de partición, el servicio devolverá un token de continuación para recuperar el resto de los resultados. Por este motivo, es posible que el servicio devuelva menos resultados de los especificados por maxresultso que el valor predeterminado sea 5000.

Si el parámetro se establece en un valor menor o igual que cero, el servidor devuelve el código de estado 400 (solicitud incorrecta).
include={metadata,deleted,system} Opcional. Especifica uno o más conjuntos de datos que se deben incluir en la respuesta:

- metadata: 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 los identificadores de C#.
- deleted: versión 2019-12-12 y posteriores. Especifica que los contenedores eliminados temporalmente deben incluirse en la respuesta.
- system: versión 2020-10-02 y posteriores. Especifica si los contenedores del sistema se van a incluir en la respuesta. Al incluir esta opción se enumeran los contenedores del sistema, como $logs y $changefeed. Tenga en cuenta que los contenedores del sistema específicos devueltos variarán en función de las características de servicio habilitadas en la cuenta de almacenamiento.
timeout Opcional. El parámetro timeout se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Storage.

Encabezados de solicitud

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

Encabezado de solicitud Descripción
Authorization Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
Date o x-ms-date Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
x-ms-version Necesario para todas las solicitudes autorizadas. 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, consulte Supervisión de Azure Blob Storage.

Cuerpo de la solicitud

Ninguno.

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, consulte Códigos de estado y error.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también incluye 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 Encabezado HTTP/1.1 estándar. 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 en la versión 2009-09-19 y versiones posteriores.
Date Valor de fecha y hora UTC que indica la hora en 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 del cuerpo de la respuesta es el siguiente.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>  

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

A partir de la versión 2013-08-15, el atributo AccountName para el elemento EnumerationResults ha cambiado de nombre y ahora se llama ServiceEndpoint. El elemento URL también se ha quitado del elemento Container. En el caso de las versiones anteriores a 2013-08-15, la dirección URL del contenedor, tal y como especifica el URL campo, no incluye el restype=container parámetro . Si utiliza este valor para realizar solicitudes posteriores en los contenedores enumerados, asegúrese de agregar este parámetro para indicar que el tipo de recurso es un contenedor.

Los Prefixelementos , Markery MaxResults solo están presentes si los especifica en el URI. El NextMarker elemento solo tiene un valor si los resultados de la lista no están completos.

El Metadata elemento solo está presente si especifica el include=metadata parámetro en el URI. Dentro del elemento Metadata, el valor de cada par nombre-valor aparece en un elemento que corresponde al nombre del par.

Si un par nombre-valor de metadatos infringe las restricciones de nomenclatura aplicadas por la versión 2009-09-19, 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>  
  

A partir de la versión 2016-05-31, los permisos públicos del contenedor se proporcionan en la PublicAccess propiedad . Indica si se puede acceder a los datos del contenedor públicamente y el nivel de acceso. Los valores posibles son:

  • container: indica el acceso de lectura público completo para los datos de contenedor y blob. Los clientes pueden enumerar blobs dentro del contenedor a través de una solicitud anónima, pero no pueden enumerar contenedores dentro de la cuenta de almacenamiento.
  • blob: indica el acceso de lectura público para blobs. Los datos de blobs de este contenedor se pueden leer a través de una solicitud anónima, pero los datos del contenedor no están disponibles. Los clientes no pueden enumerar blobs dentro del contenedor a través de una solicitud anónima.

Si esta propiedad no se especifica en la <properties> sección , el contenedor es privado para el propietario de la cuenta.

HasImmutabilityPolicy y HasLegalHold solo aparecen en la versión 2017-11-09 y posteriores. HasImmutabilityPolicy es true si el contenedor tiene una directiva de inmutabilidad establecida en él y false , de lo contrario, . HasLegalHold es true si el contenedor tiene una o varias suspensiones legales en él y false , de lo contrario, .

Nota

A partir de la versión 2009-09-19, el cuerpo de respuesta de List Containers devuelve la hora de la última modificación del contenedor, en un elemento denominado Last-Modified. En versiones anteriores, este elemento se denominaba LastModified.

Los Versionelementos , Deleted, DeletedTimey RemainingRetentiondays solo aparecen en la versión 2019-12-12 y posteriores si especifica el deleted valor para el parámetro includede consulta . Estos elementos solo aparecen si el contenedor se elimina temporalmente y es apto para restaurarse. Los Versionelementos , Deleted, DeletedTimey RemainingRetentiondays solo aparecen en la versión 2019-12-12 y posteriores si se especifica el valor eliminado para el include parámetro de consulta y si el contenedor se elimina temporalmente y es apto para restaurarse.

Authorization

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

Importante

Microsoft recomienda usar Microsoft Entra ID con identidades administradas para autorizar solicitudes a Azure Storage. Microsoft Entra ID proporciona una mayor seguridad y facilidad de uso 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. 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 un usuario, grupo, identidad administrada o entidad de servicio de Microsoft Entra para llamar a la List Containers operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

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

Comentarios

Si especifica un valor para el maxresults parámetro y el número de contenedores que se van a devolver supera este valor o supera el valor predeterminado para maxresults, el cuerpo de la respuesta contendrá el NextMarker elemento . (Esto también se conoce como token de continuación).

NextMarker indica el siguiente contenedor que se va a devolver en una solicitud posterior. Para devolver el siguiente conjunto de elementos, especifique el valor de NextMarker para el marker parámetro en el URI de la solicitud posterior. Tenga en cuenta que el valor de NextMarker se debe tratar como opaco.

Si la operación de enumeración cruza un límite de partición, el servicio devolverá un valor para el NextMarker elemento para recuperar el resto de los resultados de la siguiente partición. Una operación de enumeración que abarca más de una partición da como resultado un conjunto más pequeño de elementos que se especifica en maxresults, o que el valor predeterminado de 5000. La aplicación siempre debe comprobar la presencia del NextMarker elemento al realizar una operación de enumeración y controlarla en consecuencia.

Los contenedores aparecen en orden alfabético en el cuerpo de respuesta.

La operación List Containers agota el tiempo de espera al cabo de 30 segundos.

Facturación

Las solicitudes de precios se pueden originar en clientes que usan las API de Blob Storage, ya sea directamente a través de la API rest de Blob Storage o de una biblioteca cliente de Azure Storage. Estas solicitudes acumulan cargos por transacción. El tipo de transacción afecta a cómo se cobra la cuenta. Por ejemplo, las transacciones de lectura se acumulan en una categoría de facturación diferente que las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de List Containers las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
List Containers Blobs en bloques Premium
De uso general, estándar, v2
De uso general, estándar, v1
Enumerar y Create operaciones de contenedor

Para obtener información sobre los precios de la categoría de facturación especificada, consulte precios Azure Blob Storage.

Solicitud y respuesta de ejemplo

El siguiente URI de ejemplo solicita la lista de contenedores de una cuenta, estableciendo los resultados máximos que se devolverán para la operación inicial en tres.

GET https://myaccount.blob.core.windows.net/?comp=list&maxresults=3 HTTP/1.1  

La solicitud se envía con estos encabezados:

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=  

El código de estado y los encabezados de respuesta se devuelven de la forma siguiente:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

El código XML de respuesta para esta solicitud es el siguiente. Tenga en cuenta que el NextMarker elemento sigue el conjunto de contenedores e incluye el nombre del siguiente contenedor que se va a devolver.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>  

La subsiguiente operación de lista especifica el marcador en el URI de la solicitud, de la forma siguiente. Se devuelve el siguiente conjunto de resultados, empezando por el contenedor especificado por el marcador.

https://myaccount.blob.core.windows.net/?comp=list&maxresults=3&marker=video  

Consulte también

Autorización de solicitudes a Azure Storage
Estado y códigos de error
Códigos de error de Blob Storage
Enumeración de recursos de blobs
Uso del emulador de Azure Storage para desarrollo y pruebas
Establecimiento de tiempos de espera para las operaciones de Blob Storage