Umieść zakres

Operacja Put Range zapisuje w pliku zakres bajtów. Ta operacja jest obsługiwana w wersji 2025-05-05 i nowszych dla udziałów plików z włączonym protokołem NFS.

Dostępność protokołu

Włączony protokół udziału plików	Dostępny
SMB
NFS

Prosić

Żądanie Put Range jest konstruowane w następujący sposób. Zalecamy używanie protokołu HTTPS.

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
KŁAŚĆ	https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range	HTTP/1.1

Zastąp składniki ścieżki wyświetlane we własnym identyfikatorze URI żądania, w następujący sposób:

Składnik ścieżki	Opis
myaccount	Nazwa konta magazynu.
myshare	Nazwa udziału plików.
mydirectorypath	Fakultatywny. Ścieżka do katalogu nadrzędnego.
myfile	Nazwa pliku.

Aby uzyskać informacje o ograniczeniach nazewnictwa ścieżek, zobacz Nazwa i odwołania udziały, katalogi, pliki i metadane.

Parametry identyfikatora URI

Dla identyfikatora URI żądania można określić następujące dodatkowe parametry.

Parametr	Opis
timeout	Fakultatywny. Parametr timeout jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi plików.

Nagłówki żądań

Wymagane i opcjonalne nagłówki żądań są opisane w następujących tabelach:

Typowe nagłówki żądań

Nagłówek żądania	Opis
Authorization	Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Date lub x-ms-date	Wymagane. Określa uniwersalny czas koordynowany (UTC) dla żądania. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version	Wymagane dla wszystkich autoryzowanych żądań. Określa wersję operacji do użycia dla tego żądania. Ta operacja jest obsługiwana w wersji 2025-05-05 i nowszych dla udziałów plików z włączonym protokołem NFS. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
Range lub x-ms-range	Wymagana jest Range lub x-ms-range. Określa zakres bajtów do zapisania. Należy określić zarówno początek, jak i koniec zakresu. Ten nagłówek jest definiowany przez specyfikację protokołu HTTP/1.1 . W przypadku operacji aktualizacji zakres może mieć rozmiar do 4 miB. W przypadku jasnej operacji zakres może być maksymalnie wartością pełnego rozmiaru pliku. Usługa plików akceptuje tylko jeden zakres bajtów dla nagłówków Range i x-ms-range, a zakres bajtów musi być określony w następującym formacie: bytes=startByte-endByte. Jeśli określono zarówno Range, jak i x-ms-range, usługa używa wartości x-ms-range. Aby uzyskać więcej informacji, zobacz Określanie nagłówka zakresu dla operacji usługi plików.
Content-Length	Wymagane. Określa liczbę bajtów przesyłanych w treści żądania. Gdy nagłówek x-ms-write jest ustawiony na clear, wartość tego nagłówka musi być ustawiona na wartość 0.
Content-MD5	Fakultatywny. Skrót MD5 zawartości. Ten skrót służy do weryfikowania integralności danych podczas transportu. Po określeniu nagłówka Content-MD5 usługa Azure Files porównuje skrót zawartości, która dotarła z wartością nagłówka, która została wysłana. Jeśli dwa skróty nie są zgodne, operacja kończy się niepowodzeniem z kodem błędu 400 (Nieprawidłowe żądanie). Nagłówek Content-MD5 nie jest dozwolony, gdy nagłówek x-ms-write jest ustawiony na clear. Jeśli jest on dołączony do żądania, usługa plików zwraca kod stanu 400 (nieprawidłowe żądanie).
x-ms-write: { update ¦ clear }	Wymagane. Należy określić jedną z następujących opcji: update: zapisuje bajty określone przez treść żądania do określonego zakresu. Aby przeprowadzić aktualizację, należy dopasować nagłówki Range i Content-Length. clear: czyści określony zakres i zwalnia miejsce używane w magazynie dla tego zakresu. Aby wyczyścić zakres, ustaw nagłówek Content-Length na 0i ustaw nagłówek Range na wartość wskazującą zakres do wyczyszczenia, maksymalnie maksymalny rozmiar pliku.
x-ms-lease-id:<ID>	Wymagane, jeśli plik ma aktywną dzierżawę. Dostępne dla wersji 2019-02-02 lub nowszej. Ten nagłówek jest ignorowany, jeśli plik znajduje się w udziale plików z włączonym protokołem NFS, który nie obsługuje dzierżaw plików.
x-ms-client-request-id	Fakultatywny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitor Azure Files.
x-ms-file-last-write-time: { now ¦ preserve }	Fakultatywny. Wersja 2021-06-08 lub nowsza. Możesz określić jedną z następujących opcji: now: wartość domyślna. Aktualizuje znacznik czasu ostatniego zapisu do czasu żądania. preserve: zachowuje istniejący znacznik czasu ostatniego zapisu bez zmian.
x-ms-file-request-intent	Wymagane, jeśli nagłówek Authorization określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action należy przyznać, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości autoryzowanej przy użyciu nagłówka Authorization. Dostępne dla wersji 2022-11-02 lub nowszej.
x-ms-allow-trailing-dot: { <Boolean> }	Fakultatywny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna zostać przycięta, czy nie. Ten nagłówek jest ignorowany, jeśli element docelowy znajduje się w udziale plików z włączonym protokołem NFS, który domyślnie obsługuje kropkę końcową. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Tylko nagłówki żądań protokołu SMB

Żaden.

Nagłówki żądań NFS

Żaden.

Treść żądania

Dane reprezentujące zakres do przekazania.

Przykładowe żądanie: Aktualizowanie zakresu bajtów

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  

Przykładowe żądanie: Wyczyść zakres bajtów

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=  

Odpowiedź

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.

Kod stanu

Pomyślna operacja zwraca kod stanu 201 (Utworzono). Aby uzyskać więcej informacji na temat kodów stanu, zobacz Stan i kody błędów.

Nagłówki odpowiedzi

Odpowiedź dla tej operacji zawiera nagłówki w poniższych tabelach. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1 .

Typowe nagłówki odpowiedzi

Nagłówek odpowiedzi	Opis
ETag	Element ETag zawiera wartość reprezentującą wersję pliku. Wartość jest ujęta w cudzysłów.
Last-Modified	Zwraca datę i godzinę ostatniej modyfikacji katalogu. Format daty jest zgodny z RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentowanie wartości daty/godziny w nagłówkach. Każda operacja modyfikując udział lub jego właściwości lub metadane aktualizuje czas ostatniej modyfikacji. Operacje na plikach nie mają wpływu na czas ostatniej modyfikacji udziału.
Content-MD5	Ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę plików. Nie musi być taka sama jak wartość określona w nagłówkach żądania.
x-ms-request-id	Jednoznacznie identyfikuje żądanie, które zostało wykonane, i może służyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
x-ms-version	Wskazuje wersję usługi plików, która została użyta do wykonania żądania.
Date	Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę zainicjowania odpowiedzi.
x-ms-request-server-encrypted: { true ¦ false }	Wersja 2017-04-17 lub nowsza. Wartość tego nagłówka jest ustawiona na true, jeśli zawartość żądania zostanie pomyślnie zaszyfrowana przy użyciu określonego algorytmu. W przeciwnym razie wartość jest ustawiona na wartość false.
x-ms-client-request-id	Ten nagłówek może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id, jeśli znajduje się w żądaniu, a wartość nie zawiera więcej niż 1024 widocznych znaków ASCII. Jeśli nagłówek x-ms-client-request-id nie znajduje się w żądaniu, nie jest obecny w odpowiedzi.
x-ms-file-last-write-time	Wersja 2021-06-08 lub nowsza. Czas ostatniego zapisu dla pliku w formacie ISO 8601. Przykład: 2017-05-10T17:52:33.9551861Z.

Tylko nagłówki odpowiedzi protokołu SMB

Żaden.

Nagłówki odpowiedzi tylko systemu plików NFS

Żaden.

Treść odpowiedzi

Żaden.

Przykładowa odpowiedź

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  

Autoryzacja

Tylko właściciel konta może wywołać tę operację.

Uwagi

Operacja Put Range zapisuje w pliku zakres bajtów. Tę operację można wywołać tylko w istniejącym pliku. Nie można go wywołać, aby utworzyć nowy plik. Wywołanie Put Range z nazwą pliku, która obecnie nie istnieje, zwraca kod stanu 404 (Nie znaleziono).

Aby utworzyć nowy plik, wywołaj metodę Create File. Rozmiar pliku może być maksymalnie 4 TiB.

Operacja Put Range jest dozwolona przez 10 minut na ukończenie programu MiB. Jeśli operacja trwa średnio niż 10 minut na miB, przekracza limit czasu.

Jeśli plik ma aktywną dzierżawę, klient musi określić prawidłowy identyfikator dzierżawy w żądaniu, aby zapisać zakres.

operacje aktualizacji zakresu

Wywoływanie Put Range za pomocą opcji Update wykonuje zapis w miejscu w określonym pliku. Każda zawartość w określonym zakresie jest zastępowana aktualizacją. Każdy zakres przesłany z Put Range dla operacji aktualizacji może mieć rozmiar do 4 MiB. Jeśli spróbujesz przekazać zakres większy niż 4 miB, usługa zwróci kod stanu 413 (Żądanie jednostki za duży).

zakres operacji czyszczenia

Wywołanie Put Range z opcją Clear zwalnia miejsce w magazynie, o ile określony zakres jest wyrównany do 512 bajtów. Zakresy, które zostały wyczyszczone, nie są już śledzone w ramach pliku i nie są zwracane w odpowiedzi zakresu listy. Jeśli określony zakres nie jest wyrównany do 512 bajtów, operacja zapisuje zera na początku lub na końcu zakresu, który nie jest wyrównany do 512 bajtów i zwalnia resztę zakresu wewnątrz tego 512-bajtowego wyrównanego.

Wszystkie zakresy, które nie zostały wyczyszczone, są zwracane w odpowiedzi listy. Aby zapoznać się z przykładem, zobacz sekcję "Przykładowy nieprzygotowany zakres wyczyszczonego", który następuje poniżej.

dzierżawy plików

Możesz wywołać plik dzierżawy, aby uzyskać wyłączną blokadę zapisu w pliku względem innych zapisów przez nieskończony czas trwania.

zakres bajtów klienta SMB blokuje

Protokół SMB umożliwia blokowanie zakresu bajtów w celu zarządzania dostępem do odczytu i zapisu w regionach pliku. Oznacza to, że Put Range w pliku znajdującym się w udziale plików z włączonym protokołem SMB kończy się niepowodzeniem, jeśli klient SMB ma blokadę nakładającą się na zakres określony przez operację Put Range przy użyciu x-ms-range. Aby uzyskać więcej informacji, zobacz Zarządzanie blokadami plików.

zakres bajtów klienta systemu plików NFS blokuje

Blokady zakresu bajtów protokołu POSIX protokołu NFS mają charakter doradczy, dlatego Put Range w pliku znajdującym się w udziale plików z włączonym protokołem NFS nie zakończy się niepowodzeniem, nawet jeśli występuje konflikt blokada zakresu bajtów przechowywana przez klienta systemu plików NFS.

powiadomienia o zmianie katalogu klienta SMB

Protokół SMB obsługuje funkcję interfejsu API FindFirstChangeNotification, która umożliwia aplikacjom wykrywanie zmian w systemie plików. Może wykrywać, kiedy plik lub katalog jest dodawany, zmieniany lub usuwany, oraz gdy rozmiar, atrybuty lub deskryptory zabezpieczeń pliku się zmieniają. Klienci SMB korzystający z tego interfejsu API nie będą otrzymywać powiadomień, gdy nastąpi zmiana pliku lub katalogu za pośrednictwem interfejsu API REST usługi Azure Files. Jednak zmiany spowodowane przez innych klientów SMB propagują powiadomienia.

Przykład nieprzygotowany zakres czyszczenia

Załóżmy, że plik jest tworzony za pomocą Create File, a pojedynczy zakres jest zapisywany przy użyciu Put Rangew następujący sposób:

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  

Wykonanie operacji zakresów listy w pliku zwraca następującą treść odpowiedzi:

<?xml version="1.0" ecoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>65536</End>  
</Range>  
</Ranges>  

Teraz załóżmy, że wykonywana jest operacja nieprzygotowanego zakresu bajtów wyczyszczonego zakresu:

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=  

Kolejna operacja Zakresy listy w pliku zwraca następującą treść odpowiedzi:

<?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>  

Należy pamiętać, że zera zostały zapisane w nieprzypisanym miejscu z 768-1024 i 2048-2304.

Put Range nie jest obsługiwana w migawce udziału, która jest kopią udziału tylko do odczytu. Próba wykonania tej operacji na migawki udziału kończy się niepowodzeniem z wartością 400 (InvalidQueryParameterValue).

Zobacz też

Operacje na plikach