List Containers

Articolo
02/12/2024

L'operazione List Containers restituisce un elenco dei contenitori nell'account di archiviazione specificato.

Richiesta

È possibile costruire la List Containers richiesta come indicato di seguito. È consigliato il protocollo HTTPS. Sostituire myaccount con il nome dell'account di archiviazione.

Metodo	URI richiesta	Versione HTTP
`GET`	`https://myaccount.blob.core.windows.net/?comp=list`	HTTP/1.1

Si noti che l'URI deve sempre includere la barra (/) per separare il nome host dal percorso e dalle parti di una query dell'URI. Nel caso dell'operazione List Containers, la parte del percorso dell'URI è vuota.

Richiesta di servizio di archiviazione emulata

Quando si effettua una richiesta per il servizio di archiviazione emulato, specificare il nome host dell'emulatore e Archiviazione BLOB di Azure porta come 127.0.0.1:10000, seguito dal nome dell'account di archiviazione emulato.

Metodo	URI richiesta	Versione HTTP
`GET`	`http://127.0.0.1:10000/devstoreaccount1?comp=list`	HTTP/1.1

Si noti che l'archiviazione emulata supporta solo le dimensioni dei BLOB fino a 2 GiB.

Per altre informazioni, vedere Usare l'emulatore Azurite per lo sviluppo locale di Archiviazione di Azure e Differenze tra l'emulatore di archiviazione e i servizi di archiviazione di Azure.

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI della richiesta.

Parametro	Descrizione
`prefix`	Facoltativa. Filtra i risultati per restituire solo i contenitori con un nome che inizia con il prefisso specificato.
`marker`	facoltativo. Valore stringa che identifica la parte dell'elenco di contenitori da restituire con l'operazione di presentazione successiva. L'operazione restituisce il `NextMarker` valore all'interno del corpo della risposta, se l'operazione di elenco non ha restituito tutti i contenitori rimanenti da elencare con la pagina corrente. È possibile usare il `NextMarker` valore come valore per il `marker` parametro in una chiamata successiva per richiedere la pagina successiva di elementi dell'elenco. Il valore marcatore risulta opaco al client.
`maxresults`	facoltativo. Specifica il numero massimo di contenitori da restituire. Se la richiesta non specifica `maxresults`o specifica un valore maggiore di 5000, il server restituirà fino a 5000 elementi. Si noti che se l'operazione di elenco supera un limite di partizione, il servizio restituirà un token di continuazione per recuperare il resto dei risultati. Per questo motivo, è possibile che il servizio restituisca un numero inferiore di risultati rispetto a specificato da `maxresults`o rispetto al valore predefinito 5000. Se il parametro è impostato su un valore minore o uguale a zero, il server restituisce il codice di stato 400 (richiesta non valida).
`include={metadata,deleted,system}`	facoltativo. Specifica uno o più set di dati da includere nella risposta: -`metadata`: si noti che i metadati richiesti con questo parametro devono essere archiviati in conformità alle restrizioni di denominazione imposte dalla versione 2009-09-19 dell'archiviazione BLOB. A partire da questa versione, tutti i nomi dei metadati devono rispettare le convenzioni di denominazione per gli identificatori C#. -`deleted`: versione 2019-12-12 e successive. Specifica che i contenitori eliminati soft devono essere inclusi nella risposta. -`system`: versione 2020-10-02 e successive. Specifica se i contenitori di sistema devono essere inclusi nella risposta. L'inclusione di questa opzione elenca i contenitori di sistema, ad esempio `$logs` e `$changefeed`. Si noti che i contenitori di sistema specifici restituiti variano in base alle funzionalità del servizio abilitate nell'account di archiviazione.
`timeout`	facoltativo. Il parametro `timeout` viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di archiviazione BLOB.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Intestazione della richiesta	Descrizione
`Authorization`	Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`Date` o `x-ms-date`	Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`x-ms-version`	Obbligatorio per tutte le richieste autorizzate. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`x-ms-client-request-id`	facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log al momento della configurazione della registrazione. È consigliabile usare questa intestazione per correlare le attività lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare Archiviazione BLOB di Azure.

Testo della richiesta

Nessuno.

Risposta

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni di risposta e il corpo della risposta nel formato XML.

Codice stato

Un'operazione completata correttamente restituisce 200 (OK). Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta include anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione risposta	Descrizione
`Content-Type`	Intestazione HTTP/1.1 standard. Specifica il formato in cui vengono restituiti i risultati. Attualmente, questo valore è `application/xml`.
`x-ms-request-id`	Questa intestazione identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risoluzione dei problemi relativi alle operazioni api.
`x-ms-version`	Indica la versione di Archiviazione BLOB usata per eseguire la richiesta. Questa intestazione viene restituita per le richieste effettuate nella versione 2009-09-19 e successive.
`Date`	Valore di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
`x-ms-client-request-id`	È possibile usare questa intestazione per risolvere i problemi relativi alle richieste e alle risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione `x-ms-client-request-id` , se presente nella richiesta. Il valore è al massimo 1024 caratteri ASCII visibili. Se l'intestazione `x-ms-client-request-id` non è presente nella richiesta, questa intestazione non sarà presente nella risposta.

Corpo della risposta

Il formato del corpo della risposta è quello indicato di seguito.

<?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 e LeaseDuration risultano unicamente nella versione 2012-02-12 e successive.

A partire dalla versione 2013-08-15, l'attributo AccountName per l'elemento EnumerationResults è stato rinominato in ServiceEndpoint. Anche l'elemento URL è stato rimosso dall'elemento Container. Per le versioni precedenti al 2013-08-15, l'URL del contenitore, come specificato dal URL campo, non include il restype=container parametro . Se si utilizza questo valore per effettuare altre richieste nei contenitori enumerati, assicurarsi di aggiungere questo parametro per indicare che il tipo di risorsa è un contenitore.

Gli Prefixelementi , Markere MaxResults sono presenti solo se vengono specificati nell'URI. L'elemento NextMarker ha un valore solo se i risultati dell'elenco non sono completi.

L'elemento Metadata è presente solo se si specifica il include=metadata parametro nell'URI. Nell'elemento Metadata il valore di ogni coppia nome-valore è elencato in un elemento corrispondente al nome della coppia.

Se una coppia nome-valore dei metadati viola le restrizioni di denominazione applicate dalla versione 2009-09-19, il corpo della risposta indica il nome problematico all'interno di un x-ms-invalid-name elemento. Il frammento XML seguente mostra quanto segue:

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

A partire dalla versione 2016-05-31, le autorizzazioni pubbliche del contenitore vengono fornite nella PublicAccess proprietà . Indica se è possibile accedere pubblicamente ai dati nel contenitore e al livello di accesso. I valori possibili sono:

container: indica l'accesso in lettura pubblico completo per i dati del contenitore e del BLOB. I client possono enumerare i BLOB all'interno del contenitore tramite una richiesta anonima, ma non possono enumerare i contenitori all'interno dell'account di archiviazione.
blob: indica l'accesso in lettura pubblico per i BLOB. I dati BLOB all'interno di questo contenitore possono essere letti tramite richiesta anonima, ma i dati del contenitore non sono disponibili. I client non possono enumerare i BLOB all'interno del contenitore tramite una richiesta anonima.

Se questa proprietà non è specificata nella <properties> sezione , il contenitore è privato per il proprietario dell'account.

HasImmutabilityPolicy e HasLegalHold vengono visualizzati solo nella versione 2017-11-09 e successive. HasImmutabilityPolicy è true se nel contenitore sono impostati criteri di immutabilità e false in caso contrario. HasLegalHold è true se il contenitore contiene uno o più blocchi legali e false in caso contrario.

Nota

A partire dalla versione 2009-09-19, il corpo della risposta per List Containers restituisce l'ora dell'ultima modifica del contenitore, in un elemento denominato Last-Modified. Nelle versioni precedenti questo elemento è denominato LastModified.

Gli Versionelementi , Deleted, DeletedTimee RemainingRetentiondays vengono visualizzati solo nella versione 2019-12-12 e successive se si specifica il deleted valore per il parametro includedi query . Questi elementi vengono visualizzati solo se il contenitore viene eliminato soft ed è idoneo per il ripristino. Gli Versionelementi , Deleted, DeletedTimee RemainingRetentiondays vengono visualizzati solo nella versione 2019-12-12 e successive se il valore eliminato viene specificato per il include parametro di query e se il contenitore viene eliminato soft e idoneo per il ripristino.

Autorizzazione

L'autorizzazione è necessaria quando si chiama un'operazione di accesso ai dati in Archiviazione di Azure. È possibile autorizzare l'operazione List Containers come descritto di seguito.

Archiviazione di Azure supporta l'uso di Microsoft Entra ID per autorizzare le richieste ai dati BLOB. Con Microsoft Entra ID è possibile usare il controllo degli accessi in base al ruolo di Azure per concedere le autorizzazioni a un'entità di sicurezza. L'entità di sicurezza può essere un utente, un gruppo, un'entità servizio applicazione o un'identità gestita di Azure. L'entità di sicurezza viene autenticata da Microsoft Entra ID per restituire un token OAuth 2.0. Il token può quindi essere usato per autorizzare una richiesta relativa al servizio BLOB.

Per altre informazioni sull'autorizzazione tramite Microsoft Entra ID, vedere Autorizzare l'accesso ai BLOB usando Microsoft Entra ID.

Autorizzazioni

Di seguito è riportata l'azione controllo degli accessi in base al ruolo necessaria per un utente, un gruppo o un'entità servizio di Microsoft Entra per chiamare l'operazione List Containers e il ruolo controllo degli accessi in base al ruolo di Azure con privilegi minimi che include questa azione:

Azione controllo degli accessi in base al ruolo di Azure:Microsoft.Storage/storageAccounts/blobServices/containers/read (con ambito all'account di archiviazione o versione successiva)
Ruolo predefinito con privilegi minimi:Collaboratore ai dati del BLOB di archiviazione (con ambito dell'account di archiviazione o versione successiva)

Per altre informazioni sull'assegnazione dei ruoli tramite il controllo degli accessi in base al ruolo di Azure, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

Una firma di accesso condiviso fornisce accesso delegato sicuro alle risorse in un account di archiviazione. Con una firma di accesso condiviso è possibile controllare in modo granulare il modo in cui un client può accedere ai dati. È possibile specificare la risorsa a cui il client può accedere, le autorizzazioni necessarie per tali risorse e il periodo di validità della firma di accesso condiviso.

L'operazione List Containers supporta l'autorizzazione tramite una firma di accesso condiviso dell'account.

Quando l'accesso con chiave condivisa non è consentito per l'account di archiviazione, non sarà consentito un token di firma di accesso condiviso dell'account in una richiesta di archiviazione BLOB. Per altre informazioni, vedere Informazioni su come impedire la chiave condivisa influisce sui token di firma di accesso condiviso.

Firma di accesso condiviso dell'account

Una firma di accesso condiviso dell'account è protetta con la chiave dell'account di archiviazione. Una firma di accesso condiviso dell'account delega l'accesso alle risorse in uno o più servizi di archiviazione. Tutte le operazioni disponibili tramite una firma di accesso condiviso del servizio o di delega utente sono disponibili anche tramite una firma di accesso condiviso dell'account.

La tabella seguente indica il tipo di risorsa firmata e le autorizzazioni firmate per specificare quando si delega l'accesso:

Operazione	Servizio firmato	Tipo di risorsa firmato	Autorizzazione firmata
List Containers	BLOB (b)	Servizio (s)	Elenco (l)

Per altre informazioni sulla firma di accesso condiviso dell'account, vedere Creare una firma di accesso condiviso dell'account.

L'operazione List Containers supporta l'autorizzazione con chiave condivisa. L'autorizzazione con le chiavi dell'account non è consigliata per la maggior parte degli scenari, perché è meno sicura. Microsoft consiglia di non consentire l'autorizzazione di chiave condivisa per l'account di archiviazione quando possibile. Per altre informazioni, vedere Impedire l'autorizzazione con chiave condivisa.

Commenti

Se si specifica un valore per il maxresults parametro e il numero di contenitori da restituire supera questo valore o supera il valore predefinito per maxresults, il corpo della risposta conterrà l'elemento NextMarker . Si tratta anche di un token di continuazione.

NextMarker indica il contenitore successivo da restituire in una richiesta successiva. Per restituire il set successivo di elementi, specificare il valore di NextMarker per il marker parametro nell'URI per la richiesta successiva. Si noti che il valore NextMarker deve essere considerato opaco.

Se l'operazione di elenco supera un limite di partizione, il servizio restituirà un valore per l'elemento NextMarker per recuperare il resto dei risultati dalla partizione successiva. Un'operazione di elenco che si estende su più di una partizione comporta la restituzione di un set di elementi inferiore a quello specificato da maxresultso rispetto all'impostazione predefinita 5000. L'applicazione deve sempre verificare la presenza dell'elemento NextMarker quando si esegue un'operazione di presentazione e gestirla di conseguenza.

I contenitori sono elencati in ordine alfabetico nel corpo della risposta.

L'operazione List Containers scade dopo 30 secondi.

Fatturazione

Le richieste di determinazione dei prezzi possono provenire dai client che usano le API di archiviazione BLOB, direttamente tramite l'API REST di Archiviazione BLOB o da una libreria client di Archiviazione di Azure. Queste richieste accumulano addebiti per transazione. Il tipo di transazione influisce sul modo in cui viene addebitato l'account. Ad esempio, le transazioni di lettura si accumulano in una categoria di fatturazione diversa rispetto alle transazioni di scrittura. La tabella seguente illustra la categoria di fatturazione per List Containers le richieste in base al tipo di account di archiviazione:

Operazione	Tipo di account di archiviazione	Categoria di fatturazione
List Containers	BLOB in blocchi Premium Utilizzo generico v2 Standard Standard per utilizzo generico v1	Elencare e creare operazioni contenitore

Per informazioni sui prezzi per la categoria di fatturazione specificata, vedere prezzi Archiviazione BLOB di Azure.

Richiesta e risposta di esempio

L'URI di esempio seguente richiede l'elenco di contenitori per un account, impostando i risultati massimi da restituire per l'operazione iniziale su tre.

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

La richiesta viene inviata con queste intestazioni:

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

Il codice di stato e le intestazioni della risposta vengono restituiti nel modo seguente:

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

L'XML della risposta per questa richiesta è il seguente. Si noti che l'elemento NextMarker segue il set di contenitori e include il nome del contenitore successivo da restituire.

<?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>

L'operazione elenco successiva specifica il marcatore nell'URI della richiesta, come illustrato di seguito. Viene restituito il set di risultati successivo, a partire dal contenitore specificato dal marcatore.

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

Vedi anche

Autorizzare le richieste ad Archiviazione di Azure
Stato e codici errore
Codici di errore di Archiviazione BLOB
Enumerazione delle risorse BLOB
Uso dell'emulatore di Archiviazione di Azure per lo sviluppo e il test
Impostazione dei timeout per le operazioni di archiviazione BLOB