Udostępnij za pośrednictwem


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 Tak
NFS Nie

Żą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:
  • update: zapisuje bajty określone przez treść żądania do określonego zakresu. Nagłówki Range i Content-Length muszą być zgodne, aby przeprowadzić aktualizację.
  • clear: czyści określony zakres i zwalnia miejsce używane w magazynie dla tego zakresu. Aby wyczyścić zakres, ustaw Content-Length nagłówek na 0, a następnie ustaw Range nagłówek na wartość wskazującą zakres na wyczyszczenie, 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.
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:
  • now: wartość domyślna. Aktualizacje znacznik czasu ostatniego zapisu do godziny żądania.
  • preserve: zachowuje istniejący znacznik czasu ostatniego zapisu bez zmian.
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).

Zobacz też