Umieść zakres
Operacja Put Range zapisuje zakres bajtów w pliku.
Dostępność protokołu
| Włączony protokół udziału plików | Dostępne |
|---|---|
| SMB |
|
| NFS |
|
Żądanie
Żądanie Put Range można skonstruować w następujący sposób. Zalecamy używanie protokołu HTTPS.
| Metoda | Identyfikator URI żądania | Wersja PROTOKOŁU HTTP |
|---|---|---|
| PUT | 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 |
Opcjonalny. Ścieżka do katalogu nadrzędnego. |
myfile |
Nazwa pliku. |
Aby uzyskać informacje na temat ograniczeń nazewnictwa ścieżek, zobacz Nazwy i udziały referencyjne, katalogi, pliki i metadane.
Parametry identyfikatora URI
W identyfikatorze URI żądania można określić następujące dodatkowe parametry.
| Parametr | Opis |
|---|---|
timeout |
Opcjonalny. Parametr jest wyrażony timeout 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ń opisano w poniższej tabeli:
| 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 dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). 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. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage. |
Range lub x-ms-range |
Wymagane Range lub x-ms-range wymagane.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ć do wartości pełnego rozmiaru pliku. Usługa Plików akceptuje tylko jeden zakres bajtów dla Range nagłówków i x-ms-range , a zakres bajtów musi być określony w następującym formacie: bytes=startByte-endByte.Jeśli zostanie określona wartość i Rangex-ms-range zostanie określona, 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.
x-ms-write Gdy nagłówek jest ustawiony na clearwartość , wartość tego nagłówka musi być ustawiona na 0wartość . |
Content-MD5 |
Opcjonalny. 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 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 x-ms-write nagłówek jest ustawiony na clearwartość . 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:
|
x-ms-lease-id: <ID> |
Wymagane, jeśli plik ma aktywną dzierżawę. Dostępne dla wersji 2019-02-02 lub nowszej. |
x-ms-client-request-id |
Opcjonalny. Udostępnia 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 Monitorowanie Azure Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Opcjonalny. Wersja 2021-06-08 lub nowsza. Możesz określić jedną z następujących opcji:
|
x-ms-file-request-intent |
Wymagane, jeśli Authorization nagłówek określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że wartość Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action powinna zostać udzielona, jeśli zostaną one uwzględnione w zasadach RBAC przypisanych do tożsamości, która jest autoryzowana przy użyciu nagłówka Authorization . Dostępne dla wersji 2022-11-02 lub nowszej. |
x-ms-allow-trailing-dot: { <Boolean> } |
Opcjonalny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna być przycinana, czy nie. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych. |
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=
Reakcja
Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.
Kod stanu
Pomyślna operacja zwraca kod stanu 201 (Utworzony).
Aby uzyskać więcej informacji na temat kodów stanu, zobacz Kody stanu i błędów.
Nagłówki odpowiedzi
Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.
| Nagłówek odpowiedzi | Opis |
|---|---|
ETag |
Element ETag zawiera wartość reprezentującą wersję pliku. Wartość jest ujęta w znaki cudzysłowu. |
Last-Modified |
Zwraca datę i godzinę ostatniej modyfikacji katalogu. Format daty jest zgodny z dokumentem RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentacja 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 wiadomości. 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 |
Unikatowo 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 ustawiana na true wartość , jeśli zawartość żądania zostanie pomyślnie zaszyfrowana przy użyciu określonego algorytmu. W przeciwnym razie wartość jest ustawiona na 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 x-ms-client-request-id nagłówka, jeśli jest obecna w żądaniu, a wartość zawiera nie więcej niż 1024 widoczne znaki ASCII.
x-ms-client-request-id Jeśli nagłówek 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 pliku w formacie ISO 8601. Przykład: 2017-05-10T17:52:33.9551861Z. |
Treść odpowiedzi
Brak.
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 zakres bajtów w pliku. 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 przy użyciu nazwy pliku, która obecnie nie istnieje, zwraca kod stanu 404 (Nie znaleziono).
Aby utworzyć nowy plik, wywołaj metodę Create File (Utwórz plik). Rozmiar pliku może wynosić do 4 TiB.
Operacja Put Range jest dozwolona 10 minut na ukończenie miB. Jeśli operacja trwa średnio ponad 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łanie Put Range za Update pomocą opcji wykonuje zapis w miejscu dla określonego pliku. Każda zawartość w określonym zakresie jest zastępowana aktualizacją. Każdy zakres przesłany 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 (Jednostka żądania jest zbyt duża).
Operacje czyszczenia zakresu
Wywołanie Put Range za pomocą Clear opcji 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 zakres 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 512-bajtowy i zwalnia resztę zakresu wewnątrz tego 512-bajtowego wyrównanego.
Wszystkie zakresy, które nie zostały wyczyszczone, są zwracane w odpowiedzi Zakresy listy . Aby zapoznać się z przykładem, zobacz następującą sekcję "Przykładowy nieprzygotowany zakres czyszczenia".
Dzierżawa pliku
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.
Blokady zakresu bajtów klienta SMB
Protokół SMB umożliwia blokadom zakresu bajtów zarządzanie dostępem do odczytu i zapisu w regionach pliku. Oznacza to, że kończy się niepowodzeniem, Put Range jeśli klient SMB ma blokadę, która nakłada się na zakres określony przez operację Put Range przy użyciu polecenia x-ms-range. Aby uzyskać więcej informacji, zobacz Zarządzanie blokadami plików.
Powiadomienia o zmianie katalogu klienta SMB
Protokół SMB obsługuje funkcję interfejsu API FindFirstChangeNotification , która umożliwia aplikacjom wykrywanie, kiedy zmiany występują w systemie plików. Może wykrywać, kiedy plik lub katalog jest dodawany, zmieniany lub usuwany, oraz kiedy zmienia się rozmiar, atrybuty lub deskryptory zabezpieczeń pliku. 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 Azure Files. Jednak zmiany spowodowane przez innych klientów SMB propagują powiadomienia.
Przykład nieprzyznany zakres wyczyszczonego
Załóżmy, że plik jest tworzony za pomocą polecenia Create File ( Utwórz plik ), a pojedynczy zakres jest zapisywany w Put Rangenastę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 Listy zakresów 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 niezrównogodowana operacja zakresu bajtów zakresu 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 Listy zakresów 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 nieprzygotowanej przestrzeni z zakresu od 768 do 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 migawce udziału kończy się niepowodzeniem z błędem 400 (InvalidQueryParameterValue).