List Containers

Artículo
02/03/2024

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 `maxresults`o 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 `maxresults`o 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:

Acción de RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/read (con ámbito en la cuenta de almacenamiento o superior)
Rol integrado con privilegios mínimos:Colaborador de datos de Storage Blob (con ámbito en la cuenta de almacenamiento o superior)

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.

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

La List Containers operación admite la autorización mediante una SAS de cuenta.

Cuando no se permite el acceso a la clave compartida para la cuenta de almacenamiento, no se permitirá 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 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 deben especificar al delegar el acceso:

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
List Containers	Blob (b)	Servicio (s)	Lista (l)

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

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

Compartir a través de