Lista containrar

  • Artikel

Åtgärden List Containers returnerar en lista över containrarna under det angivna lagringskontot.

Förfrågan

Du kan skapa begäran på List Containers följande sätt. HTTPS rekommenderas. Ersätt myaccount med namnet på ditt lagringskonto.

Metod URI för förfrågan HTTP-version
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

Observera att URI:n alltid måste innehålla snedstrecket (/) för att skilja värdnamnet från sökvägen och frågedelarna i URI:n. När det gäller List Containers åtgärden är sökvägsdelen av URI:n tom.

Emulerad lagringstjänstbegäran

När du gör en begäran mot den emulerade lagringstjänsten anger du emulatorns värdnamn och Azure Blob Storage port som 127.0.0.1:10000, följt av namnet på det emulerade lagringskontot.

Metod URI för förfrågan HTTP-version
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

Observera att emulerad lagring endast stöder blobstorlekar på upp till 2 GiB.

Mer information finns i Använda Azurite-emulatorn för lokal Azure Storage-utveckling och Skillnader mellan Storage-emulatorn och Azure Storage-tjänsterna.

URI-parametrar

Du kan ange följande ytterligare parametrar för begärande-URI:n.

Parameter Beskrivning
prefix Valfritt. Filtrerar resultatet så att endast containrar returneras med ett namn som börjar med det angivna prefixet.
marker Valfritt. Ett strängvärde som identifierar den del av listan över containrar som ska returneras med nästa liståtgärd. Åtgärden returnerar NextMarker värdet i svarstexten om liståtgärden inte returnerade alla containrar som återstår att lista med den aktuella sidan. Du kan använda NextMarker värdet som värde för parametern marker i ett efterföljande anrop för att begära nästa sida med listobjekt.

Markörvärdet är täckande för klienten.
maxresults Valfritt. Anger det maximala antalet containrar som ska returneras. Om begäran inte anger maxresultseller anger ett värde som är större än 5 000 returnerar servern upp till 5 000 objekt.

Observera att om listningsåtgärden korsar en partitionsgräns returnerar tjänsten en fortsättningstoken för att hämta resten av resultaten. Därför är det möjligt att tjänsten returnerar färre resultat än vad som anges av maxresults, eller som standard 5000.

Om parametern är inställd på ett värde som är mindre än eller lika med noll returnerar servern statuskod 400 (felaktig begäran).
include={metadata,deleted,system} Valfritt. Anger en eller flera datauppsättningar som ska ingå i svaret:

-metadata: Observera att metadata som begärs med den här parametern måste lagras i enlighet med namngivningsbegränsningarna i 2009-09-19-versionen av Blob Storage. Från och med den här versionen måste alla metadatanamn följa namngivningskonventionerna för C#-identifierare.
-deleted: Version 2019-12-12 och senare. Anger att mjukt borttagna containrar ska ingå i svaret.
-system: Version 2020-10-02 och senare. Anger om systemcontainrar ska tas med i svaret. Om du tar med det här alternativet listas systemcontainrar, till exempel $logs och $changefeed. Observera att de specifika systemcontainrar som returneras varierar beroende på vilka tjänstfunktioner som är aktiverade på lagringskontot.
timeout Valfritt. Parametern timeout uttrycks i sekunder. Mer information finns i Ställa in tidsgränser för Blob Storage-åtgärder.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden.

Begärandehuvud Beskrivning
Authorization Krävs. Anger auktoriseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
Date eller x-ms-date Krävs. Anger Coordinated Universal Time (UTC) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
x-ms-version Krävs för alla auktoriserade begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
x-ms-client-request-id Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggning har konfigurerats. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Blob Storage.

Begärandetext

Inga.

Svarsåtgärder

Svaret innehåller en HTTP-statuskod, en uppsättning svarshuvuden och en svarstext i XML-format.

Statuskod

En lyckad åtgärd returnerar statuskod 200 (OK). Information om statuskoder finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller följande rubriker. Svaret innehåller även ytterligare STANDARD HTTP-huvuden. Alla standardhuvuden överensstämmer med http/1.1-protokollspecifikationen.

Svarsrubrik Description
Content-Type Standard-HTTP/1.1-rubrik. Anger i vilket format resultaten returneras. För närvarande är application/xmldet här värdet .
x-ms-request-id Det här huvudet identifierar unikt den begäran som har gjorts och kan användas för att felsöka begäran. Mer information finns i Felsöka API-åtgärder.
x-ms-version Anger vilken version av Blob Storage som används för att köra begäran. Det här huvudet returneras för begäranden som görs mot version 2009-09-19 och senare.
Date Ett datum-/tidsvärde för UTC som anger den tid då svaret initierades. Tjänsten genererar det här värdet.
x-ms-client-request-id Du kan använda det här huvudet för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet för x-ms-client-request-id huvudet, om det finns i begäran. Värdet är högst 1 024 synliga ASCII-tecken. Om rubriken x-ms-client-request-id inte finns i begäran kommer det här huvudet inte att finnas i svaret.

Själva svaret

Formatet på svarstexten är följande.

<?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, LeaseStateoch LeaseDuration visas endast i version 2012-02-12 och senare.

Från och med version 2013-08-15 AccountName har attributet för elementet EnumerationResults bytt namn till ServiceEndpoint. Elementet URL har också tagits bort från -elementet Container . För versioner före 2013-08-15 innehåller containerns URL, som anges i URL fältet, inte parametern restype=container . Om du använder det här värdet för att göra efterföljande begäranden mot de uppräknade containrarna måste du lägga till den här parametern för att ange att resurstypen är en container.

Elementen Prefix, Markeroch MaxResults finns bara om du anger dem på URI:n. Elementet NextMarker har bara ett värde om listresultatet inte är klart.

Elementet Metadata finns bara om du anger parametern include=metadata för URI:n. I elementet Metadata visas värdet för varje namn/värde-par i ett element som motsvarar parets namn.

Om ett namnvärdepar för metadata bryter mot namngivningsbegränsningarna som tillämpas av versionen 2009-09-19 anger svarstexten det problematiska namnet i ett x-ms-invalid-name element. Följande XML-fragment visar detta:

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

Från och med 2016-05-31-versionen tillhandahålls de offentliga containerbehörigheterna i PublicAccess egenskapen. Den anger om data i containern kan nås offentligt och åtkomstnivån. Möjliga värden är:

  • container: Anger fullständig, offentlig läsåtkomst för container- och blobdata. Klienter kan räkna upp blobar i containern via anonym begäran, men kan inte räkna upp containrar i lagringskontot.
  • blob: Anger offentlig läsåtkomst för blobar. Blobdata i den här containern kan läsas via anonym begäran, men containerdata är inte tillgängliga. Klienter kan inte räkna upp blobar i containern via anonym begäran.

Om den här egenskapen inte anges i <properties> avsnittet är containern privat för kontoägaren.

HasImmutabilityPolicy och HasLegalHold visas endast i version 2017-11-09 och senare. HasImmutabilityPolicy är true om containern har en oföränderlig princip inställd på den, och false annars. HasLegalHold är true om containern har ett eller flera juridiska undantag på den, och false annars.

Anteckning

Från och med version 2009-09-19 returnerar svarstexten för List Containers containerns senast ändrade tid, i ett element med namnet Last-Modified. I tidigare versioner hette LastModifieddet här elementet .

Elementen , , och RemainingRetentiondays visas bara i version 2019-12-12 och senare om du anger deleted värdet för frågeparametern include. DeletedTimeDeletedVersion Dessa element visas bara om containern är mjuk borttagen och kan återställas. Elementen Version, Deleted, DeletedTimeoch RemainingRetentiondays visas endast i version 2019-12-12 och senare om det borttagna värdet anges för include frågeparametern och om containern är mjuk och berättigad att återställas.

Auktorisering

Auktorisering krävs när du anropar en dataåtkomståtgärd i Azure Storage. Du kan auktorisera åtgärden enligt beskrivningen List Containers nedan.

Azure Storage stöder användning av Microsoft Entra ID för att auktorisera begäranden till blobdata. Med Microsoft Entra ID kan du använda rollbaserad åtkomstkontroll i Azure (Azure RBAC) för att bevilja behörigheter till ett säkerhetsobjekt. Säkerhetsobjektet kan vara en användare, grupp, programtjänstens huvudnamn eller en hanterad Azure-identitet. Säkerhetsobjektet autentiseras av Microsoft Entra ID för att returnera en OAuth 2.0-token. Token kan sedan användas för att auktorisera en begäran mot Blob-tjänsten.

Mer information om auktorisering med Microsoft Entra ID finns i Auktorisera åtkomst till blobar med Microsoft Entra ID.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Microsoft Entra användare, grupp eller tjänstens huvudnamn ska kunna anropa List Containers åtgärden och den minst privilegierade inbyggda Azure RBAC-rollen som innehåller den här åtgärden:

Mer information om hur du tilldelar roller med Azure RBAC finns i Tilldela en Azure-roll för åtkomst till blobdata.

Kommentarer

Om du anger ett värde för parametern maxresults och antalet containrar som ska returneras överskrider det här värdet, eller överskrider standardvärdet för maxresults, innehåller svarstexten elementet NextMarker . (Detta kallas även för en fortsättningstoken).

NextMarker anger nästa container som ska returneras för en efterföljande begäran. Om du vill returnera nästa uppsättning objekt anger du värdet NextMarker för för parametern marker på URI:n för den efterföljande begäran. Observera att värdet NextMarker för ska behandlas som ogenomskinlig.

Om listningsåtgärden korsar en partitionsgräns returnerar tjänsten ett värde för elementet NextMarker för att hämta resten av resultaten från nästa partition. En listningsåtgärd som sträcker sig över mer än en partition resulterar i att en mindre uppsättning objekt returneras än vad som anges av maxresults, eller än standardvärdet 5 000. Programmet bör alltid söka efter förekomsten av elementet NextMarker när du utför en listningsåtgärd och hantera det därefter.

Containrar visas i alfabetisk ordning i svarstexten.

Åtgärden överskrider tidsgränsen List Containers efter 30 sekunder.

Fakturering

Prisbegäranden kan komma från klienter som använder Blob Storage-API:er, antingen direkt via REST-API:et för Blob Storage eller från ett Azure Storage-klientbibliotek. Dessa begäranden ackumulerar avgifter per transaktion. Typen av transaktion påverkar hur kontot debiteras. Lästransaktioner till exempel tillfaller en annan faktureringskategori än skrivtransaktioner. I följande tabell visas faktureringskategorin för List Containers begäranden baserat på lagringskontotypen:

Åtgärd Typ av lagringskonto Faktureringskategori
Lista containrar Premium-blockblob
Standard generell användning v2
Standard generell användning v1		 Lista och skapa containeråtgärder

Mer information om priser för den angivna faktureringskategorin finns i Azure Blob Storage Prissättning.

Exempel på begäran och svar

Följande exempel-URI begär listan över containrar för ett konto och anger det maximala resultatet som ska returneras för den första åtgärden till tre.

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

Begäran skickas med följande rubriker:

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

Statuskoden och svarshuvudena returneras på följande sätt:

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

Svars-XML för den här begäran är följande. Observera att elementet NextMarker följer uppsättningen containrar och innehåller namnet på nästa container som ska returneras.

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

Den efterföljande liståtgärden anger markören på begärande-URI:n enligt följande. Nästa resultatuppsättning returneras, med början i containern som anges av markören.

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

Se även

Auktorisera begäranden till Azure Storage
Status- och felkoder
Felkoder för Blob Storage
Räkna upp blobresurser
Använda Azure Storage-emulatorn för utveckling och testning
Ange tidsgränser för Blob Storage-åtgärder