Tworzenie pliku
Operacja Create File tworzy nowy plik lub zastępuje plik. Podczas wywoływania metody Create Filenależy zainicjować tylko plik. Aby dodać zawartość do pliku, należy wywołać operację Put Range .
Dostępność protokołu
| Włączony protokół udziału plików | Dostępne |
|---|---|
| SMB |  |
| NFS |  |
Żądanie
Możesz utworzyć Create File żądanie, wykonując następujące czynności. Zalecamy używanie protokołu HTTPS.
| Metoda | Identyfikator URI żądania | Wersja PROTOKOŁU HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Zastąp składniki ścieżki wyświetlane we własnym identyfikatorze URI żądania, zgodnie z opisem w poniższej tabeli:
| Składnik ścieżki | Opis |
|---|---|
myaccount |
Nazwa konta magazynu. |
myshare |
Nazwa udziału plików. |
mydirectorypath |
Opcjonalny. Ścieżka do katalogu, w którym ma zostać utworzony plik. Jeśli ścieżka katalogu zostanie pominięta, plik zostanie utworzony w określonym udziale. Jeśli katalog jest określony, musi już istnieć w udziale, zanim będzie można utworzyć plik. |
myfile |
Nazwa pliku do utworzenia. |
Aby uzyskać informacje o ograniczeniach 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 godzinę uniwersalnego czasu koordynowanego (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. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage. |
Content-Length |
Opcjonalny. Musi być zero, jeśli istnieje. |
x-ms-content-length: byte value |
Wymagane. Ten nagłówek określa maksymalny rozmiar pliku, do 4 tebibajtów (TiB). |
Content-Type lub x-ms-content-type |
Opcjonalny. Typ zawartości MIME pliku. Domyślnym typem jest application/octet-stream. |
Content-Encoding lub x-ms-content-encoding |
Opcjonalny. Określa, które kodowania zawartości zostały zastosowane do pliku. Ta wartość jest zwracana do klienta po wykonaniu operacji Pobierz plik w zasobie pliku i można jej użyć do dekodowania zawartości pliku. |
Content-Language lub x-ms-content-language |
Opcjonalny. Określa języki naturalne używane przez ten zasób. |
Cache-Control lub x-ms-cache-control |
Opcjonalny. Azure Files przechowuje tę wartość, ale nie używa jej ani nie modyfikuje. |
x-ms-content-md5 |
Opcjonalny. Ustawia skrót MD5 pliku. |
x-ms-content-disposition |
Opcjonalny. Ustawia nagłówek pliku Content-Disposition . |
x-ms-type: file |
Wymagane. Ustaw ten nagłówek na file. |
x-ms-meta-name:value |
Opcjonalny. Pary nazwa-wartość skojarzone z plikiem jako metadane. Nazwy metadanych muszą być zgodne z regułami nazewnictwa identyfikatorów języka C#. Uwaga: metadane plików określone za pośrednictwem Azure Files nie są dostępne z klienta bloku komunikatów serwera (SMB). |
x-ms-file-permission: { inherit ¦ <SDDL> } |
W wersji 2019-02-02 do 2021-04-10 ten nagłówek jest wymagany, jeśli x-ms-file-permission-key nie zostanie określony. Od wersji 2021-06-08 oba nagłówki są opcjonalne. To uprawnienie jest deskryptorem zabezpieczeń dla pliku określonego w języku SDDL (Security Descriptor Definition Language). Możesz użyć tego nagłówka, jeśli rozmiar uprawnień to 8 kibibajtów (KiB) lub mniej. W przeciwnym razie można użyć polecenia x-ms-file-permission-key. Jeśli określisz nagłówek, musi on mieć listę właściciela, grupy i uznaniowej listy kontroli dostępu (DACL). Możesz przekazać wartość do inherit dziedziczenia z katalogu nadrzędnego. |
x-ms-file-permission-key: <PermissionKey> |
W wersji 2019-02-02 do 2021-04-10 ten nagłówek jest wymagany, jeśli x-ms-file-permission nie zostanie określony. Od wersji 2021-06-08 oba nagłówki są opcjonalne. Jeśli żaden nagłówek nie zostanie określony, zostanie użyta wartość inherit domyślna nagłówka x-ms-file-permission .Klucz można utworzyć, wywołując Create Permission interfejs API. |
x-ms-file-attributes |
Wymagane: wersja 2019-02-02 do 2021-04-10. Opcjonalnie: wersja 2021-06-08 lub nowsza. Ten nagłówek zawiera atrybuty systemu plików, które mają być ustawione w pliku. Aby uzyskać więcej informacji, zobacz listę dostępnych atrybutów. Wartość domyślna to None. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Wymagane: wersja 2019-02-02 do 2021-04-10. Opcjonalnie: wersja 2021-06-08 lub nowsza. Właściwość czasu utworzenia uniwersalnego czasu koordynowanego (UTC) dla pliku. Wartość może now służyć do wskazania czasu żądania. Wartość domyślna to now. |
x-ms-file-last-write-time: { now ¦ <DateTime> } |
Wymagane: wersja 2019-02-02 do 2021-04-10. Opcjonalnie: wersja 2021-06-08 lub nowsza. Właściwość ostatniego zapisu dla pliku to koordynowany czas uniwersalny (UTC). Możesz użyć wartości , now aby wskazać czas żądania. Wartość domyślna to now. |
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-change-time: { now ¦ <DateTime> } |
Opcjonalny. Wersja 2021-06-08 lub nowsza. Właściwość czasu uniwersalnego koordynowanego (UTC) dla pliku zmienia się w formacie ISO 8601. Możesz użyć wartości , now aby wskazać czas żądania. Wartość domyślna to now. |
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
Brak.
Przykładowe żądanie
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1
Request Headers:
x-ms-version: 2020-02-10
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT
Content-Type: text/plain; charset=UTF-8
x-ms-content-length: 1024
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Reakcja
Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.
Kod stanu
Operacja zakończona powodzeniem zwraca kod stanu 201 (utworzono).
Aby uzyskać informacje o kodach stanu, zobacz Stan i kody błędów.
Nagłówki odpowiedzi
Odpowiedź na tę operację zawiera nagłówki opisane w poniższej tabeli. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie nagłówki standardowe 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 cudzysłów. |
Last-Modified |
Zwraca datę i godzinę ostatniej modyfikacji pliku. Format daty jest zgodny z RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty/godziny w nagłówkach. Każda operacja modyfikując katalog lub jego właściwości aktualizuje czas ostatniej modyfikacji. Operacje na plikach nie wpływają na czas ostatniej modyfikacji katalogu. |
x-ms-request-id |
Jednoznacznie identyfikuje żądanie, które zostało wykonane i może być używane 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ę Azure Files używaną 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 wartość , jeśli zawartość żądania została pomyślnie zaszyfrowana przy użyciu określonego algorytmu. Jeśli szyfrowanie nie powiedzie się, wartość to false. |
x-ms-file-permission-key |
Klucz uprawnienia do pliku. |
x-ms-file-attributes |
Atrybuty systemu plików w pliku. Aby uzyskać więcej informacji, zobacz listę dostępnych atrybutów. |
x-ms-file-creation-time |
Wartość daty/godziny UTC reprezentująca właściwość godziny utworzenia pliku. |
x-ms-file-last-write-time |
Wartość daty/godziny UTC reprezentująca właściwość czasu ostatniego zapisu dla pliku. |
x-ms-file-change-time |
Data/godzina UTC, która reprezentuje właściwość zmiany godziny dla pliku. |
x-ms-file-file-id |
Identyfikator pliku. |
x-ms-file-parent-id |
Identyfikator pliku nadrzędnego. |
x-ms-client-request-id |
Służy do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli znajduje się w żądaniu, a wartość nie zawiera więcej niż 1024 widocznych znaków ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, nie jest obecny w odpowiedzi. |
Treść odpowiedzi
Brak.
Przykładowa odpowiedź
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Date: Mon, 27 Jan 2014 23:00:12 GMT
ETag: "0x8CB14C3E29B7E82"
Last-Modified: Mon, 27 Jan 2014 23:00:06 GMT
x-ms-version: 2014-02-14
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Autoryzacja
Tylko właściciel konta może wywołać tę operację.
Atrybuty systemu plików
| Atrybut | Atrybut pliku Win32 | Definicja |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | Plik, który jest tylko do odczytu. Aplikacje mogą odczytywać plik, ale nie mogą go zapisywać ani usuwać. |
| Ukryty | FILE_ATTRIBUTE_HIDDEN | Plik jest ukryty. Nie jest on uwzględniony w zwykłej liście katalogów. |
| System | FILE_ATTRIBUTE_SYSTEM | Plik używany przez system operacyjny lub używany wyłącznie przez system operacyjny. |
| Brak | FILE_ATTRIBUTE_NORMAL | Plik, który nie ma innych atrybutów ustawionych. Ten atrybut jest prawidłowy tylko wtedy, gdy jest używany sam. |
| Archiwum | FILE_ATTRIBUTE_ARCHIVE | Plik, który jest plikiem archiwum. Aplikacje zwykle używają tego atrybutu do oznaczania plików do tworzenia kopii zapasowej lub usuwania. |
| Tymczasowe | FILE_ATTRIBUTE_TEMPORARY | Plik używany do przechowywania tymczasowego. |
| Tryb offline | FILE_ATTRIBUTE_OFFLINE | Dane pliku nie są natychmiast dostępne. Ten atrybut systemu plików jest przedstawiany głównie w celu zapewnienia zgodności z systemem Windows. Azure Files nie obsługuje go z opcjami magazynu w trybie offline. |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | Plik nie jest indeksowany przez usługę indeksowania zawartości. |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | Strumień danych użytkownika, który nie jest odczytywany przez skaner integralności danych w tle. Ten atrybut systemu plików jest przedstawiany głównie w celu zapewnienia zgodności z systemem Windows. |
Uwagi
Aby utworzyć nowy plik, najpierw zainicjuj go, wywołując Create File i określając maksymalny rozmiar, do 4 TiB. Podczas wykonywania tej operacji nie dołączaj zawartości do treści żądania. Po utworzeniu pliku wywołaj metodę Put Range , aby dodać zawartość do pliku lub zmodyfikować go.
Rozmiar pliku można zmienić, wywołując polecenie Set File Properties.
Jeśli udział lub katalog nadrzędny nie istnieje, operacja kończy się niepowodzeniem z kodem stanu 412 (Warunek wstępny nie powiodło się).
Uwaga
Właściwości cache-controlpliku , , content-typecontent-md5, content-encodingi content-language są oddzielone od właściwości systemu plików, które są dostępne dla klientów SMB. Klienci SMB nie mogą odczytywać, zapisywać ani modyfikować tych wartości właściwości.
Aby utworzyć plik, jeśli istniejący plik ma aktywną dzierżawę, klient musi określić prawidłowy identyfikator dzierżawy w żądaniu. Jeśli klient nie określa identyfikatora dzierżawy lub określa nieprawidłowy identyfikator dzierżawy, Azure Files zwraca kod stanu 412 (Warunek wstępny nie powiodło się). Jeśli klient określa identyfikator dzierżawy, ale plik nie ma aktywnej dzierżawy, Azure Files zwraca również kod stanu 412 (Niepowodzenie warunku wstępnego). Jeśli klient określa identyfikator dzierżawy w pliku, który jeszcze nie istnieje, Azure Files zwraca kod stanu 412 (Warunek wstępny niepowodzenie) dla żądań, które są wysyłane w wersji 2019-02-02 i nowszych.
Jeśli istniejący plik z aktywną dzierżawą zostanie zastąpiony przez operację Create File , dzierżawa będzie nadal istnieć w zaktualizowanym pliku do momentu jego wydania.
Create File nie jest obsługiwana w migawki 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 kodem stanu 400 (InvalidQueryParameterValue).