Put Range
Operace Put Range zapíše do souboru rozsah bajtů. Tato operace je podporována ve verzi 2025-05-05 a novější pro sdílené složky s povoleným protokolem NFS.
Dostupnost protokolu
| Povolený protokol sdílené složky | K dispozici |
|---|---|
| SMB |
|
| NFS |
|
Prosba
Požadavek Put Range je vytvořen následujícím způsobem. Doporučujeme používat PROTOKOL HTTPS.
| Metoda | Identifikátor URI požadavku | Verze HTTP |
|---|---|---|
| DÁT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Součásti cesty zobrazené v identifikátoru URI požadavku nahraďte vlastními, a to následujícím způsobem:
| Komponenta Path | Popis |
|---|---|
myaccount |
Název vašeho účtu úložiště. |
myshare |
Název sdílené složky. |
mydirectorypath |
Volitelný. Cesta k nadřazeného adresáři. |
myfile |
Název souboru. |
Informace o omezeních pojmenování cest najdete v tématu Název a referenční sdílené složky, adresáře, soubory a metadata.
Parametry identifikátoru URI
Pro identifikátor URI požadavku je možné zadat následující další parametry.
| Parametr | Popis |
|---|---|
timeout |
Volitelný. Parametr timeout se vyjadřuje v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace souborové služby. |
Hlavičky požadavku
Povinná a volitelná hlavička požadavku jsou popsána v následujících tabulkách:
Běžné hlavičky požadavků
| Hlavička požadavku | Popis |
|---|---|
Authorization |
Požadovaný. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků na službu Azure Storage. |
Date nebo x-ms-date |
Požadovaný. Určuje standard UTC (Coordinated Universal Time) pro požadavek. Další informace najdete v tématu Autorizace požadavků na službu Azure Storage. |
x-ms-version |
Vyžaduje se pro všechny autorizované žádosti. Určuje verzi operace, která se má pro tento požadavek použít. Tato operace je podporována ve verzi 2025-05-05 a novější pro sdílené složky s povoleným protokolem NFS. Další informace najdete v tématu Správa verzí pro služby Azure Storage. |
Range nebo x-ms-range |
Vyžaduje se Range nebo x-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 specifikace protokolu HTTP/1.1. U operace aktualizace může mít velikost až 4 MiB. U jasné operace může být rozsah až do hodnoty plné velikosti souboru. Služba File přijímá pouze jeden rozsah bajtů pro hlavičky Range a x-ms-range a rozsah bajtů musí být zadán v následujícím formátu: bytes=startByte-endByte.Pokud jsou zadány Range i x-ms-range, služba použije hodnotu x-ms-range. Další informace naleznete v tématu Zadejte hlavičku rozsahu pro operace souborové služby. |
Content-Length |
Požadovaný. Určuje počet bajtů přenášených v textu požadavku. Pokud je záhlaví x-ms-write nastaveno na clear, hodnota tohoto záhlaví musí být nastavena na 0. |
Content-MD5 |
Volitelný. Hodnota hash MD5 obsahu. Tato hodnota hash se používá k ověření integrity dat během přenosu. Když je zadaná hlavička Content-MD5, Služba Azure Files porovná hodnotu hash obsahu, který přišel, s hodnotou hlavičky, která byla odeslána. Pokud se dvě hodnoty hash neshoduje, operace selže s kódem chyby 400 (Chybný požadavek).Záhlaví Content-MD5 není povoleno, pokud je záhlaví x-ms-write nastaveno na clear. Pokud je součástí požadavku, vrátí služba File stavový kód 400 (Chybný požadavek). |
x-ms-write: { update ¦ clear } |
Požadovaný. 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ší. Tato hlavička se ignoruje, pokud je soubor umístěný ve sdílené složce s povoleným protokolem NFS, který nepodporuje zapůjčení souborů. |
x-ms-client-request-id |
Volitelný. Poskytuje hodnotu vygenerovanou klientem, neprůshlenou hodnotou s limitem 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í služby Azure Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Volitelný. 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 hlavička Authorization určuje token OAuth. Přijatelná hodnota je backup. Tato hlavička určuje, že Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action nebo Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action by měly být uděleny, pokud jsou zahrnuty do zásad RBAC přiřazené k identitě, která je autorizovaná pomocí hlavičky Authorization. K dispozici pro verzi 2022-11-02 a novější. |
x-ms-allow-trailing-dot: { <Boolean> } |
Volitelný. Verze 2022-11-02 a novější. Logická hodnota určuje, jestli by se měla oříznout koncová tečka v adrese URL požadavku, nebo ne. Tato hlavička se ignoruje, pokud se cíl nachází ve sdílené složce s povoleným protokolem NFS, který ve výchozím nastavení podporuje koncové tečky. Další informace najdete v tématu Pojmenování a odkazování na sdílené složky, adresáře, soubory a metadata. |
Hlavičky požadavků jenom smb
Žádný.
Pouze hlavičky požadavků NFS
Žádný.
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: Vymazat rozsah 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 Stav a kódy chyb.
Hlavičky odpovědi
Odpověď pro tuto operaci zahrnuje hlavičky v následujících tabulkách. Odpověď může obsahovat také další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.
Běžná hlavička odpovědi
| Hlavička odpovědi | Popis |
|---|---|
ETag |
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 naleznete v tématu Reprezentace hodnot data a času v záhlavích. Jakákoli operace, která upraví sdílenou složku nebo její vlastnosti nebo 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. Hodnota této hlavičky se vypočítá službou File. Nemusí se nutně shodovat s hodnotou zadanou v hlavičce požadavku. |
x-ms-request-id |
Jednoznačně identifikuje požadavek, který byl proveden, a dá se 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 k provedení požadavku. |
Date |
Hodnota data a času UTC vygenerovaná službou, která označuje čas zahájení odpovědi. |
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 false. |
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ě hlavičky x-ms-client-request-id, pokud se nachází v požadavku a hodnota neobsahuje více než 1 024 viditelných znaků ASCII. Pokud v požadavku není hlavička x-ms-client-request-id, není v odpovědi k dispozici. |
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. |
Hlavičky odpovědi pouze smb
Žádný.
Pouze hlavičky odpovědi NFS
Žádný.
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
Oprávnění
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 volat, aby se vytvořil nový soubor. Volání Put Range s názvem souboru, který aktuálně neexistuje, vrátí stavový kód 404 (Nenalezena).
Chcete-li vytvořit nový soubor, zavolejte Vytvořit soubor. Soubor může mít velikost až 4 TiB.
Dokončení operace Put Range je povoleno 10 minut na MiB. Pokud operace trvá průměrně déle než 10 minut za MiB, vyprší časový limit.
Pokud má soubor aktivní zapůjčení, musí klient zadat platné ID zapůjčení v požadavku k zápisu rozsahu.
operací aktualizace rozsahu
Volání Put Range s možností Update provede místní zápis do zadaného souboru. Veškerý obsah v zadaném rozsahu se přepíše aktualizací. Každý rozsah odeslaný s 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 (entita požadavku je příliš velká).
vymazat operace rozsahu
Volání Put Range s možností Clear 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 oblasti uvnitř zarovnaného 512 bajtů.
Všechny oblasti, které nebyly vymazány, se vrátí v odpovědi Seznam. Příklad najdete v následující části "Ukázka nezarovnaného nezarovnaného rozsahu".
zapůjčení souboru
Můžete volat zapůjčení souboru 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 pro čtení a zápis do oblastí souboru. To znamená, že Put Range v souboru umístěném ve sdílené složce s povoleným protokolem SMB selže, pokud má klient SMB zámek, který se překrývá s rozsahem určeným operací Put Range pomocí x-ms-range. Další informace naleznete v tématu Správa zámků souborů.
zámky rozsahu bajtů klienta systému souborů NFS
Zámky rozsahu bajtů SYSTÉMU SOUBORŮ NFS jsou povahu poradenství, takže Put Range v souboru umístěném ve sdílené složce s povoleným protokolem NFS se nezdaří ani v případě, že existuje konfliktní zámek rozsahu bajtů uchovávaný klientem NFS.
oznámení o změnách klientského adresáře SMB
Protokol SMB podporuje funkci FindFirstChangeNotification API, která umožňuje aplikacím zjistit, kdy v systému souborů dojde ke změnám. Dokáže zjistit, kdy se soubor nebo adresář přidá, změní nebo odstraní a kdy se změní velikost souboru, atributy nebo popisovače zabezpečení. 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 služby Azure Files. Změny způsobené jinými klienty SMB ale šíří oznámení.
nezarovnaného nezarovnaného rozsahu vzorku
Předpokládejme, že se soubor vytvoří pomocí Vytvořit soubor a že se do Put Rangezapíše jedna oblast 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 Rozsahy seznamů 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 nerovnaného rozsahu bajtů rozsahu bez zarovnání:
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ásledující operace Rozsahy seznamu 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 od 768-1024 a 2048-2304.
Put Range se na snímku sdílené složky nepodporuje, 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 se 400 (InvalidQueryParameterValue).
Viz také
Operace se soubory