Rozsah vložení
Operace Put Range zapíše do souboru rozsah bajtů.
Dostupnost protokolu
| Povolený protokol sdílených složek | K dispozici. |
|---|---|
| SMB |
|
| NFS |
|
Žádost
Požadavek Put Range může být vytvořen následujícím způsobem. Doporučujeme použít https.
| Metoda | Identifikátor URI žádosti | Verze PROTOKOLU HTTP |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Následujícím způsobem nahraďte komponenty cesty uvedené v identifikátoru URI požadavku vlastními:
| Komponenta Cesta | Popis |
|---|---|
myaccount |
Název vašeho účtu úložiště. |
myshare |
Název sdílené složky. |
mydirectorypath |
Nepovinný parametr. Cesta k nadřazené adresáři. |
myfile |
Název souboru. |
Informace o omezeních pojmenování cest najdete v tématu Názvy a odkazy na sdílené složky, adresáře, soubory a metadata.
Parametry identifikátoru URI
V identifikátoru URI požadavku je možné zadat následující další parametry.
| Parametr | Popis |
|---|---|
timeout |
Nepovinný parametr. Parametr timeout je vyjádřen v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace souborové služby. |
Hlavičky požadavku
Požadované a volitelné hlavičky požadavků jsou popsané v následující tabulce:
| Hlavička požadavku | Popis |
|---|---|
Authorization |
Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage. |
Date nebo x-ms-date |
Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby Azure Storage. |
x-ms-version |
Povinné pro všechny autorizované žádosti. Určuje verzi operace, která se má použít pro tento požadavek. Další informace najdete v tématu Správa verzí pro služby Azure Storage. |
Range nebo x-ms-range |
Je vyžadováno buď nebo Rangex-ms-range .Určuje rozsah bajtů, které se mají zapsat. Musí být zadán začátek i konec rozsahu. Tato hlavička je definována specifikací protokolu HTTP/1.1. V případě operace aktualizace může mít rozsah velikost až 4 MiB. V případě jasné operace může být rozsah až do hodnoty plné velikosti souboru. Služba File přijímá pouze jeden rozsah bajtů pro Range hlavičky a x-ms-range a oblast bajtů musí být zadána v následujícím formátu: bytes=startByte-endByte.Pokud jsou zadány obě Rangex-ms-range a, služba použije hodnotu x-ms-range. Další informace najdete v tématu Určení hlavičky rozsahu pro operace souborové služby. |
Content-Length |
Povinná hodnota. Určuje počet bajtů přenášených v textu požadavku. Pokud je hlavička x-ms-write nastavená na clear, musí být hodnota této hlavičky nastavena na 0hodnotu . |
Content-MD5 |
Nepovinný parametr. Hodnota hash md5 obsahu. Tato hodnota hash se používá k ověření integrity dat během přenosu. Když je hlavička Content-MD5 zadána, Azure Files porovná hodnotu hash obsahu, který byl doručen, s hodnotou hlavičky, která byla odeslána. Pokud se tyto dvě hodnoty hash neshodnou, operace selže s kódem chyby 400 (Chybný požadavek).Hlavička Content-MD5 není povolená, pokud je hlavička x-ms-write nastavená na clear. Pokud je součástí požadavku, vrátí souborová služba stavový kód 400 (Chybný požadavek). |
x-ms-write: { update ¦ clear } |
Povinná hodnota. Musíte zadat jednu z následujících možností:
|
x-ms-lease-id: <ID> |
Vyžaduje se, pokud má soubor aktivní zapůjčení. K dispozici pro verzi 2019-02-02 a novější. |
x-ms-client-request-id |
Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem počtu znaků 1 kibibajt (KiB), který je zaznamenán v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá. Další informace najdete v tématu Monitorování Azure Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Nepovinný parametr. Verze 2021-06-08 a novější. Můžete zadat jednu z následujících možností:
|
x-ms-file-request-intent |
Vyžaduje se, pokud Authorization hlavička určuje token OAuth. Přijatelná hodnota je backup. Tato hlavička určuje, že Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action by se měly udělit nebo Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action , pokud jsou zahrnuté v zásadách RBAC přiřazených k identitě, která je autorizována pomocí hlavičky Authorization . K dispozici pro verzi 2022-11-02 a novější. |
x-ms-allow-trailing-dot: { <Boolean> } |
Nepovinný parametr. Verze 2022-11-02 a novější. Logická hodnota určuje, jestli se má v adrese URL požadavku oříznout koncová tečka, nebo ne. Další informace najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na nich. |
Text požadavku
Data představující oblast, která se má nahrát.
Ukázkový požadavek: Aktualizace rozsahu bajtů
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
Ukázkový požadavek: Vymazání rozsahu bajtů
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=
Odpověď
Odpověď obsahuje stavový kód HTTP a sadu hlaviček odpovědi.
Stavový kód
Úspěšná operace vrátí stavový kód 201 (Vytvořeno).
Další informace o stavových kódech najdete v tématu Stavové kódy a kódy chyb.
Hlavičky odpovědi
Odpověď na tuto operaci obsahuje následující hlavičky. Odpověď může také obsahovat další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.
| Hlavička odpovědi | Popis |
|---|---|
ETag |
Značka ETag obsahuje hodnotu, která představuje verzi souboru. Hodnota je uzavřena v uvozovkách. |
Last-Modified |
Vrátí datum a čas poslední změny adresáře. Formát data se řídí dokumentem RFC 1123. Další informace najdete v tématu Reprezentace hodnot data a času v záhlavích. Každá operace, která upraví sdílenou složku nebo její vlastnosti či metadata, aktualizuje čas poslední změny. Operace se soubory nemají vliv na čas poslední změny sdílené složky. |
Content-MD5 |
Tato hlavička se vrátí, aby klient mohl zkontrolovat integritu obsahu zprávy. Hodnotu této hlavičky vypočítá služba File. Nemusí být nutně stejná jako hodnota zadaná v hlavičce požadavku. |
x-ms-request-id |
Jednoznačně identifikuje požadavek, který byl proveden, a lze ho použít k řešení potíží s požadavkem. Další informace najdete v tématu Řešení potíží s operacemi rozhraní API. |
x-ms-version |
Označuje verzi souborové služby, která se použila ke spuštění požadavku. |
Date |
Hodnota data a času UTC vygenerovaná službou, která označuje čas, kdy byla odpověď inicializována. |
x-ms-request-server-encrypted: { true ¦ false } |
Verze 2017-04-17 a novější. Hodnota této hlavičky je nastavena na true , pokud je obsah požadavku úspěšně zašifrován pomocí zadaného algoritmu. V opačném případě je hodnota nastavena na falsehodnotu . |
x-ms-client-request-id |
Tato hlavička se dá použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě x-ms-client-request-id hlavičky, pokud je v požadavku, a hodnota neobsahuje více než 1 024 viditelných znaků ASCII. Pokud hlavička x-ms-client-request-id v požadavku není, není v odpovědi. |
x-ms-file-last-write-time |
Verze 2021-06-08 a novější. Čas posledního zápisu souboru ve formátu ISO 8601 Příklad: 2017-05-10T17:52:33.9551861Z. |
Text odpovědi
Žádné
Ukázková odpověď
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
Autorizace
Tuto operaci může volat pouze vlastník účtu.
Poznámky
Operace Put Range zapíše do souboru rozsah bajtů. Tuto operaci lze volat pouze u existujícího souboru. Nelze ho volat a vytvořit tak nový soubor. Volání Put Range s názvem souboru, který aktuálně neexistuje, vrátí stavový kód 404 (Nenalezeno).
Pokud chcete vytvořit nový soubor, zavolejte Vytvořit soubor. Soubor může mít velikost až 4 TiB.
Dokončení Put Range operace je povoleno 10 minut na MiB. Pokud operace trvá v průměru déle než 10 minut na MiB, vyprší časový limit.
Pokud má soubor aktivní zapůjčení, musí klient zadat platné ID zapůjčení v požadavku na zápis rozsahu.
Operace aktualizace rozsahu
Volání Put Range s Update možností provede místní zápis do zadaného souboru. Veškerý obsah v zadaném rozsahu je přepsán aktualizací. Každý rozsah odeslaný pomocí Put Range pro operaci aktualizace může mít velikost až 4 MiB. Pokud se pokusíte nahrát rozsah větší než 4 MiB, vrátí služba stavový kód 413 (příliš velká entita požadavku).
Operace vymazání rozsahu
Volání Put Range s Clear možností uvolní místo v úložišti, pokud je zadaný rozsah zarovnaný na 512 bajtů. Oblasti, které byly vymazány, se už nesledují jako součást souboru a nevrátí se v odpovědi Rozsah seznamu . Pokud zadaná oblast není zarovnaná na 512 bajtů, operace zapíše nuly na začátek nebo konec oblasti, která není zarovnaná na 512 bajtů, a uvolní zbytek vnitřní oblasti, která je zarovnaná na 512 bajtů.
Všechny oblasti, které nebyly vymazány, se vrátí v odpovědi Seznam rozsahů . Příklad najdete v následující části Ukázková nezarovnaná nezarovnaná oblast.
Zapůjčení souboru
Můžete volat soubor zapůjčení a získat výhradní zámek zápisu do souboru proti jiným zápisům po neomezenou dobu.
Zámky rozsahu bajtů klienta SMB
Protokol SMB umožňuje zámkům rozsahu bajtů spravovat přístup ke čtení a zápisu do oblastí souboru. To znamená, že dojde k selhání, Put Range pokud má klient SMB zámek, který se překrývá s rozsahem určeným Put Range operací pomocí x-ms-range. Další informace najdete v tématu Správa zámků souborů.
Oznámení o změnách adresáře klienta SMB
Protokol SMB podporuje funkci rozhraní API FindFirstChangeNotification , která aplikacím umožňuje zjistit, kdy v systému souborů dojde ke změnám. Dokáže zjistit, kdy je soubor nebo adresář přidán, změněn nebo odstraněn a kdy se změní velikost, atributy nebo popisovače zabezpečení souboru. Klienti SMB, kteří používají toto rozhraní API, nebudou dostávat oznámení, když dojde ke změně souboru nebo adresáře prostřednictvím rozhraní REST API Azure Files. Změny způsobené jinými klienty SMB ale šíří oznámení.
Ukázka nezarovnané oblasti
Předpokládejme, že se soubor vytvoří pomocí příkazu Vytvořit soubor a jeden rozsah se zapíše pomocí Put Rangepříkazu , a to následujícím způsobem:
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
Provedení operace Seznam rozsahů v souboru vrátí následující text odpovědi:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Teď předpokládejme, že se provádí operace nezarovnaného rozsahu bajtů:
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=
Následná operace vypsat rozsahy v souboru vrátí následující text odpovědi:
<?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>
Všimněte si, že nuly byly zapsány do nezarovnané mezery z 768-1024 a 2048-2304.
Put Range se nepodporuje u snímku sdílené složky, což je kopie sdílené složky jen pro čtení. Pokus o provedení této operace na snímku sdílené složky selže s hodnotou 400 (InvalidQueryParameterValue).