Listintervall

Artikel
03/29/2023

Åtgärden List Ranges returnerar listan över giltiga intervall för en fil.

Protokolltillgänglighet

Aktiverat filresursprotokoll	Tillgängligt
SMB
NFS

Förfrågan

Du kan skapa begäran på List Ranges följande sätt. HTTPS rekommenderas.

Metod	URI för förfrågan	HTTP-version
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	HTTP/1.1

Ersätt sökvägskomponenterna som visas i begärande-URI:n med dina egna, enligt följande:

Sökvägskomponent	Description
`myaccount`	Namnet på ditt lagringskonto.
`myshare`	Namnet på filresursen.
`mydirectorypath`	Valfritt. Sökvägen till den överordnade katalogen.
`myfile`	Namnet på filen.

Mer information om namngivningsbegränsningar för sökvägar finns i Namnge och referera till resurser, kataloger, filer och metadata.

URI-parametrar

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

Parameter	Beskrivning
`sharesnapshot`	Valfritt. Version 2017-04-17 och senare. Parametern `sharesnapshot` är ett täckande `DateTime` värde som, när den finns, anger resursögonblicksbilden för att fråga efter filen.
`timeout`	Valfritt. Parametern `timeout` uttrycks i sekunder. Mer information finns i Ställa in tidsgränser för Azure Files åtgärder.
`prevsharesnapshot`	Valfritt i version 2020-02-10 och senare. Parametern `prevsharesnapshot` är ett täckande `DateTime` värde som, när den finns, anger den tidigare ögonblicksbilden. När både den här parametern och `sharesnapshot` finns innehåller svaret endast sidintervall som har ändrats mellan de två ögonblicksbilderna. När endast `prevsharesnapshot` finns innehåller svaret endast sidintervall som har ändrats mellan den här ögonblicksbilden och den aktiva resursen. Ändrade sidor innehåller både uppdaterade och rensade sidor.

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.
`Range`	Valfritt. Anger det intervall med byte som intervall ska listas över, inklusive. Om det utelämnas returneras alla intervall för filen.
`x-ms-range`	Valfritt. Anger det intervall med byte som intervall ska listas över, inklusive. Om både `Range` - och `x-ms-range` -huvudena anges använder tjänsten värdet `x-ms-range`. Mer information finns i Ange områdesrubriken för Azure Files åtgärder.
`x-ms-lease-id:<ID>`	Valfritt. Version 2019-02-02 och senare. Om rubriken anges utförs åtgärden endast om filens lån för närvarande är aktivt och det låne-ID som anges i begäran matchar filens. Annars misslyckas åtgärden med statuskoden 412 (förhandsvillkoret misslyckades).
`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 Files.
`x-ms-file-request-intent`	Krävs om `Authorization` huvudet anger en OAuth-token. Acceptabelt värde är `backup`. Det här huvudet anger att `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` eller `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` ska beviljas om de ingår i DEN RBAC-princip som tilldelats den identitet som har behörighet med hjälp av `Authorization` huvudet. Tillgänglig för version 2022-11-02 och senare.
`x-ms-allow-trailing-dot: { <Boolean> }`	Valfritt. Version 2022-11-02 och senare. Det booleska värdet anger om en avslutande punkt som finns i begärande-URL:en ska trimmas eller inte. Mer information finns i Namnge och referera till resurser, kataloger, filer och metadata.

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 kan även innehålla ytterligare STANDARD HTTP-huvuden. Alla standardhuvuden överensstämmer med http/1.1-protokollspecifikationen.

Svarsrubrik	Description
`Last-Modified`	Datum/tid då filen senast ändrades. Alla åtgärder som ändrar filen, inklusive en uppdatering av filens metadata eller egenskaper, ändrar filens senaste ändringstid.
`ETag`	`ETag` Innehåller ett värde som representerar filens version, inom citattecken.
`x-ms-content-length`	Filens storlek i bitar. När `prevsharesnapshot` är närvarande beskriver värdet storleken på filen i `sharesnapshot` (om `sharesnapshot` frågeparametern finns). Annars beskrivs storleken på livefilen.
`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 Azure Files som används för att köra begäran.
`Date` eller `x-ms-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

Svarstexten innehåller en lista över giltiga intervall som inte överlappar varandra, sorterade efter att adressintervallet har ökat. Formatet för svarstexten är följande.

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

Om hela filens uppsättning intervall har rensats innehåller svarstexten inga intervall.

Om prevsharesnapshot anges innehåller svaret endast de sidor som skiljer sig mellan målögonblicksbilden (eller livefilen) och den tidigare ögonblicksbilden. Intervallen som returneras inkluderar båda intervallen som har uppdaterats eller som har rensats. Formatet för det här svaret är följande:

<?xml version="1.0" encoding="utf-8"?> 
<Ranges> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
  <ClearRange> 
    <Start>Start Byte</Start>
    <End>End Byte</Start> 
  </ClearRange> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
</Ranges>

Om hela filens uppsättning sidor har rensats och parametern prevsharesnapshot inte har angetts innehåller svarstexten inga intervall.

Auktorisering

Endast kontoägaren kan anropa den här åtgärden.

Kommentarer

Förskjutningarna för start- och slutbyte för varje intervall är inkluderande. Se exempel på intervalluppdateringsåtgärder och Intervallrensningsåtgärder för Put Range. De här exemplen visar vilka intervall som returneras om du skriver eller avmarkerar ett intervall på 512 ojusterade byte från filen.

I en mycket fragmenterad fil med ett stort antal skrivningar kan en List Ranges begäran misslyckas på grund av en intern server-timeout. Program som hämtar intervall för en fil med ett stort antal skrivåtgärder bör hämta en delmängd av intervall i taget.

Från och med version 2020-02-10 kan du anropa List Ranges med en prevsharesnapshot parameter. Detta returnerar de intervall som skiljer sig mellan livefilen och en ögonblicksbild, eller mellan två ögonblicksbilder av filen på ögonblicksbilder. Genom att använda dessa intervallskillnader kan du hämta en inkrementell ögonblicksbild av en fil. Inkrementella ögonblicksbilder är ett kostnadseffektivt sätt att säkerhetskopiera filer om du vill implementera en egen säkerhetskopieringslösning.

Vissa åtgärder i en fil orsakar List Ranges fel när den anropas för att hämta en inkrementell ögonblicksbild. Tjänsten returnerar:

404 (hittades inte) om du anropar en fil som inte finns i någon av ögonblicksbilderna (eller live, om sharesnapshot den inte har angetts).
409 (konflikt) om du anropar en fil som var målet för en överskrivningskopiering efter ögonblicksbilden, angiven av prevsharesnapshot.
409 (konflikt) om du anropar en fil som har tagits bort och återskapats med samma namn och plats, efter att ögonblicksbilden som angetts av prevsharesnapshot har tagits.

Se även

Åtgärder för filer