Placera intervall
Åtgärden Put Range skriver ett byteintervall till en fil.
Protokolltillgänglighet
| Aktiverat filresursprotokoll | Tillgängligt |
|---|---|
| SMB |
|
| NFS |
|
Förfrågan
Begäran Put Range kan konstrueras på följande sätt. Vi rekommenderar att du använder HTTPS.
| Metod | URI för förfrågan | HTTP-version |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Ersätt sökvägskomponenterna som visas i begärande-URI:n med dina egna, enligt följande:
| Sökvägskomponent | Beskrivning |
|---|---|
myaccount |
Namnet på ditt lagringskonto. |
myshare |
Namnet på filresursen. |
mydirectorypath |
Valfritt. Sökvägen till den överordnade katalogen. |
myfile |
Namnet på filen. |
Information om namngivningsbegränsningar för sökväg finns i Namn och referensresurser, kataloger, filer och metadata.
URI-parametrar
Följande ytterligare parametrar kan anges i begärande-URI:n.
| Parameter | Beskrivning |
|---|---|
timeout |
Valfritt. Parametern timeout uttrycks i sekunder. Mer information finns i Ange tidsgränser för filtjänståtgärder. |
Begärandehuvuden
De obligatoriska och valfria begäranderubrikerna beskrivs i följande tabell:
| 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 eller x-ms-range |
Antingen Range eller x-ms-range krävs.Anger det byteintervall som ska skrivas. Både början och slutet av intervallet måste anges. Det här huvudet definieras av HTTP/1.1-protokollspecifikationen. För en uppdateringsåtgärd kan intervallet vara upp till 4 MiB i storlek. För en klar åtgärd kan intervallet vara upp till värdet för filens fulla storlek. Filtjänsten accepterar endast ett intervall med en enda byte för Range huvudena och x-ms-range och byteintervallet måste anges i följande format: bytes=startByte-endByte.Om både Range och x-ms-range anges använder tjänsten värdet x-ms-range. Mer information finns i Ange områdesrubriken för Filtjänståtgärder. |
Content-Length |
Krävs. Anger antalet byte som överförs i begärandetexten.
x-ms-write När rubriken är inställd på clearmåste värdet för det här huvudet anges till 0. |
Content-MD5 |
Valfritt. En MD5-hash för innehållet. Denna hash används för att verifiera dataintegriteten under transporten.
Content-MD5 När rubriken har angetts jämför Azure Files hashen för innehållet som har anlänt med det rubrikvärde som skickades. Om de två hashvärdena inte matchar misslyckas åtgärden med felkoden 400 (felaktig begäran).Rubriken Content-MD5 tillåts inte när rubriken är inställd på x-ms-writeclear. Om den ingår i begäran returnerar filtjänsten statuskod 400 (felaktig begäran). |
x-ms-write: { update ¦ clear } |
Krävs. Du måste ange något av följande alternativ:
|
x-ms-lease-id: <ID> |
Krävs om filen har ett aktivt lån. Tillgänglig för version 2019-02-02 och senare. |
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 Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Valfritt. Version 2021-06-08 och senare. Du kan ange något av följande alternativ:
|
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 RBAC-principen som tilldelats den identitet som har behörighet med huvudet Authorization . 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
De data som representerar intervallet som ska laddas upp.
Exempelbegäran: Uppdatera byteintervall
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Exempelbegäran: Rensa byteintervall
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Svarsåtgärder
Svaret innehåller en HTTP-statuskod och en uppsättning svarshuvuden.
Statuskod
En lyckad åtgärd returnerar statuskoden 201 (skapad).
Mer information om statuskoder finns i Status och felkoder.
Svarshuvuden
Svaret för den här åtgärden innehåller följande rubriker. Svaret kan också innehålla ytterligare HTTP-standardhuvuden. Alla standardhuvuden överensstämmer med HTTP/1.1-protokollspecifikationen.
| Svarsrubrik | Beskrivning |
|---|---|
ETag |
ETag innehåller ett värde som representerar filens version. Värdet omges av citattecken. |
Last-Modified |
Returnerar datum och tid då katalogen senast ändrades. Datumformatet följer RFC 1123. Mer information finns i Representera datum/tid-värden i rubriker. Alla åtgärder som ändrar resursen eller dess egenskaper eller metadata uppdaterar den senaste ändrade tiden. Åtgärder på filer påverkar inte resursens senast ändrade tid. |
Content-MD5 |
Det här huvudet returneras så att klienten kan söka efter meddelandeinnehållsintegritet. Värdet för det här huvudet beräknas av filtjänsten. Det är inte nödvändigtvis samma som värdet som anges i begärandehuvudena. |
x-ms-request-id |
Identifierar begäran unikt och kan användas för att felsöka begäran. Mer information finns i Felsöka API-åtgärder. |
x-ms-version |
Anger den filtjänstversion som användes för att köra begäran. |
Date |
Ett UTC-datum/tid-värde som genereras av tjänsten, vilket anger den tid då svaret initierades. |
x-ms-request-server-encrypted: { true ¦ false } |
Version 2017-04-17 och senare. Värdet för det här huvudet anges till true om innehållet i begäran har krypterats med hjälp av den angivna algoritmen. Annars är värdet inställt på false. |
x-ms-client-request-id |
Det här huvudet kan användas för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet x-ms-client-request-id för huvudet om det finns i begäran och värdet inte innehåller fler än 1 024 synliga ASCII-tecken.
x-ms-client-request-id Om rubriken inte finns i begäran finns den inte i svaret. |
x-ms-file-last-write-time |
Version 2021-06-08 och senare. Den senaste skrivtiden för filen, i ISO 8601-format. Exempel: 2017-05-10T17:52:33.9551861Z. |
Själva svaret
Inga.
Exempelsvar
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Auktorisering
Endast kontoägaren kan anropa den här åtgärden.
Kommentarer
Åtgärden Put Range skriver ett byteintervall till en fil. Den här åtgärden kan endast anropas på en befintlig fil. Det går inte att anropa för att skapa en ny fil. Om du anropar Put Range med ett filnamn som för närvarande inte finns returneras statuskoden 404 (hittades inte).
Om du vill skapa en ny fil anropar du Skapa fil. En fil kan vara upp till 4 TiB i storlek.
En Put Range åtgärd tillåts 10 minuter per MiB att slutföras. Om åtgärden tar längre tid än 10 minuter per MiB i genomsnitt överskrider den tidsgränsen.
Om filen har ett aktivt lån måste klienten ange ett giltigt låne-ID för begäran om att skriva ett intervall.
Intervalluppdateringsåtgärder
Anrop Put Range med Update alternativet utför en skrivning på plats på den angivna filen. Allt innehåll i det angivna intervallet skrivs över med uppdateringen. Varje intervall som skickas med Put Range för en uppdateringsåtgärd kan vara upp till 4 MiB i storlek. Om du försöker ladda upp ett intervall som är större än 4 MiB returnerar tjänsten statuskoden 413 (begärandeentiteten är för stor).
Intervallrensningsåtgärder
Om du anropar Put Range med Clear alternativet frigörs utrymmet i lagringen så länge det angivna intervallet är 512 byte justerat. Intervall som har rensats spåras inte längre som en del av filen och returneras inte i listintervallsvaret . Om det angivna intervallet inte är justerat med 512 byte skriver åtgärden nollor till början eller slutet av intervallet som inte är 512 byte justerat och frigör resten av intervallet inom det justerade intervallet med 512 byte.
Alla intervall som inte har rensats returneras i svaret Listintervall . Ett exempel finns i avsnittet "Sample unaligned clear range" som följer.
Fillån
Du kan anropa Lånefil för att få ett exklusivt skrivlås till filen mot andra skrivningar under en oändlig varaktighet.
SMB-klientbyteintervalllås
SMB-protokollet tillåter byteintervalllås för att hantera läs- och skrivåtkomst till regioner i en fil. Det innebär att Put Range misslyckas om en SMB-klient har ett lås som överlappar det intervall som anges av åtgärden med hjälp x-ms-rangeav Put Range . Mer information finns i Hantera fillås.
Meddelanden om ändring av SMB-klientkatalog
SMB-protokollet stöder funktionen FindFirstChangeNotification API som gör att program kan identifiera när ändringar sker i filsystemet. Den kan identifiera när en fil eller katalog läggs till, ändras eller tas bort och när en fils storlek, attribut eller säkerhetsbeskrivningar ändras. SMB-klienter som använder det här API:et får inte meddelanden när en fil- eller katalogändring sker via Azure Files REST API. Ändringar som orsakas av andra SMB-klienter sprider dock meddelanden.
Exempel på avmarkerat intervall
Anta att en fil skapas med Skapa fil och att ett enda intervall skrivs med Put Range, enligt följande:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Om du utför en listintervallåtgärd i filen returneras följande svarstext:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Anta nu att en ojusterad byteintervallåtgärd för rensat intervall utförs:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
En efterföljande listintervallåtgärd i filen returnerar följande svarstext:
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Observera att nollor har skrivits till det ojusterade utrymmet från 768-1024 och 2048-2304.
Put Range stöds inte på en resursögonblicksbild, vilket är en skrivskyddad kopia av en resurs. Ett försök att utföra den här åtgärden på en resursögonblicksbild misslyckas med 400 (InvalidQueryParameterValue).