Containers weergeven

Artikel
02/03/2024

De List Containers bewerking retourneert een lijst met de containers onder het opgegeven opslagaccount.

Aanvraag

U kunt de List Containers aanvraag als volgt samenstellen. HTTPS wordt aanbevolen. Vervang myaccount door de naam van uw opslagaccount.

Methode	Aanvraag-URI	HTTP-versie
`GET`	`https://myaccount.blob.core.windows.net/?comp=list`	HTTP/1.1

Houd er rekening mee dat de URI altijd de slash (/) moet bevatten om de hostnaam te scheiden van het pad en de querygedeelten van de URI. In het geval van de List Containers bewerking is het padgedeelte van de URI leeg.

Aanvraag voor geëmuleerde opslagservice

Wanneer u een aanvraag doet voor de geëmuleerde opslagservice, geeft u de hostnaam van de emulator en Azure Blob Storage poort op als 127.0.0.1:10000, gevolgd door de naam van het geëmuleerde opslagaccount.

Methode	Aanvraag-URI	HTTP-versie
`GET`	`http://127.0.0.1:10000/devstoreaccount1?comp=list`	HTTP/1.1

Houd er rekening mee dat geëmuleerde opslag alleen blobgrootten tot 2 GiB ondersteunt.

Zie Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling en Verschillen tussen de Opslagemulator en Azure Storage-services voor meer informatie.

URI-parameters

U kunt de volgende aanvullende parameters opgeven voor de aanvraag-URI.

Parameter	Beschrijving
`prefix`	Optioneel. Filtert de resultaten om alleen containers te retourneren met een naam die begint met het opgegeven voorvoegsel.
`marker`	Optioneel. Een tekenreekswaarde die het gedeelte van de lijst met containers aangeeft dat moet worden geretourneerd bij de volgende vermeldingsbewerking. De bewerking retourneert de `NextMarker` waarde in de hoofdtekst van het antwoord, als de vermeldingsbewerking niet alle containers retourneert die moeten worden weergegeven met de huidige pagina. U kunt de `NextMarker` waarde gebruiken als de waarde voor de `marker` parameter in een volgende aanroep om de volgende pagina met lijstitems op te vragen. De markeringswaarde is ondoorzichtig voor de client.
`maxresults`	Optioneel. Hiermee geeft u het maximum aantal containers op dat moet worden geretourneerd. Als de aanvraag niet opgeeft `maxresults`of een waarde groter is dan 5000, retourneert de server maximaal 5000 items. Houd er rekening mee dat als de vermeldingsbewerking een partitiegrens overschrijdt, de service een vervolgtoken retourneert voor het ophalen van de rest van de resultaten. Daarom is het mogelijk dat de service minder resultaten retourneert dan is opgegeven door `maxresults`, of de standaardwaarde van 5000. Als de parameter is ingesteld op een waarde kleiner dan of gelijk aan nul, retourneert de server statuscode 400 (Ongeldige aanvraag).
`include={metadata,deleted,system}`	Optioneel. Hiermee geeft u een of meer gegevenssets op die moeten worden opgenomen in het antwoord: - `metadata`: Metagegevens die zijn aangevraagd met deze parameter, moeten worden opgeslagen in overeenstemming met de naamgevingsbeperkingen die zijn opgelegd door de 2009-09-19-versie van Blob Storage. Vanaf deze versie moeten alle metagegevensnamen voldoen aan de naamconventies voor C#-id's. - `deleted`: Versie 2019-12-12 en hoger. Hiermee geeft u op dat voorlopig verwijderde containers moeten worden opgenomen in het antwoord. - `system`: Versie 2020-10-02 en hoger. Hiermee geeft u op of systeemcontainers moeten worden opgenomen in het antwoord. Als u deze optie opneemt, worden systeemcontainers weergegeven, zoals `$logs` en `$changefeed`. Houd er rekening mee dat de specifieke systeemcontainers die worden geretourneerd, variëren, afhankelijk van welke servicefuncties zijn ingeschakeld voor het opslagaccount.
`timeout`	Optioneel. De `timeout` parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Blob Storage-bewerkingen voor meer informatie.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader	Beschrijving
`Authorization`	Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
`Date` of `x-ms-date`	Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
`x-ms-version`	Vereist voor alle geautoriseerde aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
`x-ms-client-request-id`	Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Blob Storage bewaken voor meer informatie.

Aanvraagbody

Geen.

Antwoord

Het antwoord bevat een HTTP-statuscode, een set antwoordheaders en een antwoordtekst in XML-indeling.

Statuscode

Een geslaagde bewerking retourneert statuscode 200 (OK). Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord bevat ook aanvullende, standaard HTTP-headers. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Antwoordheader	Description
`Content-Type`	Standaard HTTP/1.1-header. Hiermee geeft u de indeling op waarin de resultaten worden geretourneerd. Momenteel is `application/xml`deze waarde .
`x-ms-request-id`	Deze header identificeert op unieke wijze de aanvraag die is gedaan en kan worden gebruikt voor het oplossen van problemen met de aanvraag. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
`x-ms-version`	Geeft de versie van Blob Storage aan die wordt gebruikt om de aanvraag uit te voeren. Deze header wordt geretourneerd voor aanvragen die zijn gedaan op basis van versie 2009-09-19 en hoger.
`Date`	Een UTC-datum/tijd-waarde die de tijd aangeeft waarop het antwoord is gestart. De service genereert deze waarde.
`x-ms-client-request-id`	U kunt deze header gebruiken om problemen met aanvragen en bijbehorende antwoorden op te lossen. De waarde van deze header is gelijk aan de waarde van de `x-ms-client-request-id` header, als deze aanwezig is in de aanvraag. De waarde is maximaal 1024 zichtbare ASCII-tekens. Als de `x-ms-client-request-id` header niet aanwezig is in de aanvraag, is deze header niet aanwezig in het antwoord.

Hoofdtekst van de reactie

De indeling van de hoofdtekst van het antwoord is als volgt.

<?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, LeaseStateen LeaseDuration worden alleen weergegeven in versie 2012-02-12 en hoger.

Vanaf versie 2013-08-15 is de naam van het AccountName kenmerk voor het EnumerationResults element gewijzigd in ServiceEndpoint. Het URL element is ook verwijderd uit het Container element. Voor versies ouder dan 2013-08-15 bevat de URL van de container, zoals opgegeven in het URL veld, de restype=container parameter niet. Als u deze waarde gebruikt om volgende aanvragen uit te voeren voor de opgesomde containers, moet u deze parameter toevoegen om aan te geven dat het resourcetype een container is.

De Prefixelementen , Markeren MaxResults zijn alleen aanwezig als u deze opgeeft in de URI. Het NextMarker element heeft alleen een waarde als de lijstresultaten niet volledig zijn.

Het Metadata element is alleen aanwezig als u de include=metadata parameter opgeeft in de URI. Binnen het Metadata element wordt de waarde van elk naam-waardepaar weergegeven in een element dat overeenkomt met de naam van het paar.

Als een metagegevensnaam-waardepaar in strijd is met de naamgevingsbeperkingen die worden afgedwongen door de versie 2009-09-19, geeft de antwoordtekst de problematische naam in een x-ms-invalid-name element aan. In het volgende XML-fragment ziet u het volgende:

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

Vanaf versie 2016-05-31 worden de openbare containermachtigingen opgegeven in de PublicAccess eigenschap. Het geeft aan of gegevens in de container openbaar toegankelijk zijn en het toegangsniveau. Mogelijke waarden zijn:

container: Geeft volledige, openbare leestoegang voor container- en blobgegevens aan. Clients kunnen blobs in de container opsommen via een anonieme aanvraag, maar kunnen geen containers in het opslagaccount opsommen.
blob: Geeft openbare leestoegang voor blobs aan. Blobgegevens in deze container kunnen worden gelezen via een anonieme aanvraag, maar containergegevens zijn niet beschikbaar. Clients kunnen geen blobs in de container opsommen via een anonieme aanvraag.

Als deze eigenschap niet is opgegeven in de <properties> sectie, is de container privé voor de accounteigenaar.

HasImmutabilityPolicy en HasLegalHold alleen worden weergegeven in versie 2017-11-09 en hoger. HasImmutabilityPolicy is als voor de container een onveranderbaarheidsbeleid is true ingesteld en false anders. HasLegalHold is true als de container een of meer juridische bewaringen heeft, en false anders.

Notitie

Vanaf versie 2009-09-19 retourneert de antwoordtekst voor List Containers de laatste wijzigingstijd van de container in een element met de naam Last-Modified. In eerdere versies heette LastModifieddit element .

De Versionelementen , Deleted, DeletedTimeen RemainingRetentiondays worden alleen weergegeven in versie 2019-12-12 en hoger als u de deleted waarde voor de queryparameter includeopgeeft. Deze elementen worden alleen weergegeven als de container voorlopig is verwijderd en in aanmerking komt voor herstel. De Versionelementen , Deleted, DeletedTimeen RemainingRetentiondays worden alleen weergegeven in versie 2019-12-12 en hoger als de verwijderde waarde is opgegeven voor de include queryparameter en als de container voorlopig is verwijderd en in aanmerking komt voor herstel.

Autorisatie

Autorisatie is vereist bij het aanroepen van een bewerking voor gegevenstoegang in Azure Storage. U kunt de List Containers bewerking autoriseren zoals hieronder wordt beschreven.

Belangrijk

Microsoft raadt aan Microsoft Entra ID met beheerde identiteiten te gebruiken om aanvragen voor Azure Storage te autoriseren. Microsoft Entra ID biedt superieure beveiliging en gebruiksgemak in vergelijking met autorisatie van gedeelde sleutels.

Azure Storage ondersteunt het gebruik van Microsoft Entra ID om aanvragen voor blobgegevens te autoriseren. Met Microsoft Entra ID kunt u op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) gebruiken om machtigingen te verlenen aan een beveiligingsprincipal. De beveiligingsprincipal kan een gebruiker, groep, toepassingsservice-principal of door Azure beheerde identiteit zijn. De beveiligingsprincipal wordt geverifieerd door Microsoft Entra ID om een OAuth 2.0-token te retourneren. Het token kan vervolgens worden gebruikt om een aanvraag voor de Blob-service te autoriseren.

Zie Toegang tot blobs autoriseren met behulp van Microsoft Entra ID voor meer informatie over autorisatie met behulp van Microsoft Entra ID.

Machtigingen

Hieronder vindt u de RBAC-actie die nodig is voor een Microsoft Entra gebruiker, groep, beheerde identiteit of service-principal om de List Containers bewerking aan te roepen, en de ingebouwde Azure RBAC-rol met de minste bevoegdheden die deze actie omvat:

Azure RBAC-actie:Microsoft.Storage/storageAccounts/blobServices/containers/read (binnen het bereik van het opslagaccount of hoger)
Ingebouwde rol met minimale bevoegdheden:Inzender voor opslagblobgegevens (binnen het bereik van het opslagaccount of hoger)

Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie over het toewijzen van rollen met behulp van Azure RBAC.

Een Shared Access Signature (SAS) biedt beveiligde gedelegeerde toegang tot resources in een opslagaccount. Met een SAS hebt u gedetailleerde controle over hoe een client toegang heeft tot gegevens. U kunt opgeven tot welke resource de client toegang heeft, welke machtigingen ze hebben voor deze resources en hoe lang de SAS geldig is.

De List Containers bewerking ondersteunt autorisatie met behulp van een account-SAS.

Wanneer gedeelde sleuteltoegang niet is toegestaan voor het opslagaccount, wordt een SAS-accounttoken niet toegestaan voor een aanvraag voor Blob Storage. Zie Begrijpen hoe het niet toewijzen van gedeelde sleutel van invloed is op SAS-tokens voor meer informatie.

Account-SAS

Een account-SAS wordt beveiligd met de sleutel van het opslagaccount. Een account-SAS delegeert toegang tot resources in een of meer van de opslagservices. Alle bewerkingen die beschikbaar zijn via een service- of gebruikersdelegatie-SAS zijn ook beschikbaar via een account-SAS.

In de volgende tabel ziet u het ondertekende resourcetype en de ondertekende machtigingen die moeten worden opgegeven bij het delegeren van toegang:

Bewerking	Ondertekende service	Ondertekend resourcetype	Ondertekende machtiging
Containers weergeven	Blob (b)	Service(s)	Lijst (l)

Zie een account-SAS Creatie voor meer informatie over de account-SAS.

Opmerkingen

Als u een waarde opgeeft voor de maxresults parameter en het aantal te retourneren containers deze waarde overschrijdt of de standaardwaarde voor maxresultsoverschrijdt, bevat de hoofdtekst van het antwoord het NextMarker -element. (Dit wordt ook wel een vervolgtoken genoemd).

NextMarker geeft de volgende container aan die moet worden geretourneerd op een volgende aanvraag. Als u de volgende set items wilt retourneren, geeft u de waarde van NextMarker op voor de marker parameter op de URI voor de volgende aanvraag. Houd er rekening mee dat de waarde van NextMarker moet worden behandeld als ondoorzichtig.

Als de vermeldingsbewerking een partitiegrens overschrijdt, retourneert de service een waarde voor het NextMarker element voor het ophalen van de rest van de resultaten van de volgende partitie. Een vermeldingsbewerking die meer dan één partitie omvat, resulteert in een kleinere set items die wordt geretourneerd dan is opgegeven door maxresults, of dan de standaardwaarde 5000. Uw toepassing moet altijd controleren op de aanwezigheid van het NextMarker element wanneer u een vermeldingsbewerking uitvoert en deze dienovereenkomstig afhandelen.

Containers worden in alfabetische volgorde weergegeven in de hoofdtekst van het antwoord.

De List Containers bewerking treedt na 30 seconden op.

Billing

Prijsaanvragen kunnen afkomstig zijn van clients die gebruikmaken van Blob Storage-API's, rechtstreeks via de Blob Storage REST API of vanuit een Azure Storage-clientbibliotheek. Met deze aanvragen worden kosten per transactie in rekening gebracht. Het type transactie is van invloed op de manier waarop de rekening in rekening wordt gebracht. Leestransacties worden bijvoorbeeld toegevoegd aan een andere factureringscategorie dan schrijftransacties. In de volgende tabel ziet u de factureringscategorie voor List Containers aanvragen op basis van het type opslagaccount:

Bewerking	Type opslagaccount	Factureringscategorie
Containers weergeven	Premium-blok-blob Standard v2 voor algemeen gebruik Standard v1 voor algemeen gebruik	Containerbewerkingen weergeven en Creatie

Zie prijzen voor Azure Blob Storage voor meer informatie over prijzen voor de opgegeven factureringscategorie.

Voorbeeld van aanvraag en antwoord

Met de volgende voorbeeld-URI wordt de lijst met containers voor een account aangevraagd, waarbij het maximum aantal geretourneerde resultaten voor de eerste bewerking wordt ingesteld op drie.

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

De aanvraag wordt verzonden met deze headers:

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

De statuscode en antwoordheaders worden als volgt geretourneerd:

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

De antwoord-XML voor deze aanvraag is als volgt. Houd er rekening mee dat het NextMarker element de set containers volgt en de naam bevat van de volgende container die moet worden geretourneerd.

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

De volgende lijstbewerking geeft de markering op de aanvraag-URI op, als volgt. De volgende set resultaten wordt geretourneerd, te beginnen met de container die is opgegeven door de markering.

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

Zie ook

Aanvragen autoriseren voor Azure Storage
Status en foutcodes
Blob Storage-foutcodes
Blob-resources opsommen
De Azure Storage-emulator gebruiken voor ontwikkeling en testen
Time-outs instellen voor Blob Storage-bewerkingen

Delen via