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 lagringsemulatorn 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 listningsåtgärd. Åtgärden returnerar NextMarker värdet i svarstexten, om listningsåtgärden inte returnerade alla containrar som återstår för att visas med den aktuella sidan. Du kan använda värdet NextMarker 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 ogenomskinlig 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 än standardvärdet 5 000.

Om parametern är inställd på ett värde som är mindre än eller lika med noll returnerar servern statuskoden 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 inkluderas i svaret.
-system: Version 2020-10-02 och senare. Anger om systemcontainrar ska inkluderas i svaret. Om du inkluderar det här alternativet visas 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 Ange 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 loggningen 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 statuskoden 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 Beskrivning
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 mot version 2009-09-19 och senare.
Date Ett UTC-datum/tid-värde 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. x-ms-client-request-id Om rubriken inte finns i begäran visas inte det här huvudet i svaret.

Själva svaret

Formatet för 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 slutfört.

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

Om ett namn/värde-par för metadata bryter mot namngivningsbegränsningarna som framtvingas 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 versionen 2016-05-31 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änderlighetsprincip inställd på den och false annars. HasLegalHold är true om containern har ett eller flera bevarande av juridiska skäl på sig och false på annat sätt.

Anteckning

Från och med version 2009-09-19 returnerar svarstexten för List Containers containerns senaste ändringstid 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 De här elementen visas bara om containern tas bort mjukt och kan återställas. Elementen Version, Deleted, DeletedTimeoch RemainingRetentiondays visas bara i version 2019-12-12 och senare om det borttagna värdet har angetts för include frågeparametern och om containern är mjukt borttagen 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 Azure Active Directory (Azure AD) för att auktorisera begäranden till blobdata. Med Azure AD 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 Azure AD 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 hjälp av Azure AD finns i Auktorisera åtkomst till blobar med Hjälp av Azure Active Directory.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Azure AD användare, grupp eller tjänstens huvudnamn ska 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 hjälp av 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 listå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 5000. Programmet bör alltid söka efter förekomsten av elementet NextMarker när du utför en liståtgärd och hantera det därefter.

Containrar visas i alfabetisk ordning i svarstexten.

Tidsgränsen List Containers uppnås efter 30 sekunder.

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 huvuden:

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:en 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