Tworzenie pliku
Operacja Create File tworzy nowy plik lub zastępuje plik. Podczas wywoływania 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ępny |
|---|---|
| SMB |
|
| NFS |
|
Prosić
Możesz utworzyć żądanie Create File, 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 |
Fakultatywny. Ś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 Nazwa i dokumentacja udziałów, katalogów, plików i metadanych.
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ń zostały opisane 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 czas uniwersalny 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. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage. |
Content-Length |
Fakultatywny. Wartość musi być równa 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 |
Fakultatywny. Typ zawartości MIME pliku. Domyślnym typem jest application/octet-stream. |
Content-Encoding lub x-ms-content-encoding |
Fakultatywny. Określa, które kodowania zawartości zostały zastosowane do pliku. Ta wartość jest zwracana do klienta, gdy operacja pobierania pliku |
Content-Language lub x-ms-content-language |
Fakultatywny. Określa języki naturalne używane przez ten zasób. |
Cache-Control lub x-ms-cache-control |
Fakultatywny. Usługa Azure Files przechowuje tę wartość, ale nie używa jej ani nie modyfikuje. |
x-ms-content-md5 |
Fakultatywny. Ustawia skrót MD5 pliku. |
x-ms-content-disposition |
Fakultatywny. Ustawia nagłówek Content-Disposition pliku. |
x-ms-type: file |
Wymagane. Ustaw ten nagłówek na file. |
x-ms-meta-name:value |
Fakultatywny. Pary nazwa-wartość, które są skojarzone z plikiem jako metadane. Nazwy metadanych muszą być zgodne z regułami nazewnictwa dla identyfikatorów języka C# . Uwaga: metadane plików określone za pośrednictwem usługi Azure Files nie są dostępne z poziomu klienta bloku komunikatów serwera (SMB). |
x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> } |
W wersji 2019-02-02 do 2021-04-10 ten nagłówek jest wymagany, jeśli nie określono x-ms-file-permission-key. Od wersji 2021-06-08 oba nagłówki są opcjonalne. To uprawnienie jest deskryptorem zabezpieczeń dla pliku określonego w Security Descriptor Definition Language (SDDL) lub (wersja 2024-11-04 lub nowsza) w formacie kodowanego w formacie base64 binarnym deskryptorze zabezpieczeń. Można określić format używany z nagłówkiem x-ms-file-permission-format. Możesz użyć tego nagłówka, jeśli rozmiar uprawnień to 8 kibibajtów (KiB) lub mniej. W przeciwnym razie możesz użyć x-ms-file-permission-key. Jeśli określisz nagłówek, musi on mieć właściciela, grupę i uznaniową listę kontroli dostępu (DACL). Wartość inherit można przekazać do dziedziczenia z katalogu nadrzędnego. |
x-ms-file-permission-format: { sddl ¦ binary } |
Fakultatywny. Wersja 2024-11-04 lub nowsza. Określa, czy wartość przekazywana w x-ms-file-permission jest w formacie SDDL, czy w formacie binarnym. Jeśli x-ms-file-permission-key jest ustawiona na inherit, nie należy ustawiać tego nagłówka. Jeśli x-ms-file-permission-key jest ustawiona na dowolną inną wartość niż inherit, a jeśli ten nagłówek nie jest ustawiony, zostanie użyta wartość domyślna sddl. |
x-ms-file-permission-key: <PermissionKey> |
W wersji 2019-02-02 do 2021-04-10 ten nagłówek jest wymagany, jeśli nie określono x-ms-file-permission. Od wersji 2021-06-08 oba nagłówki są opcjonalne. Jeśli żaden nagłówek nie zostanie określony, domyślna wartość inherit zostanie użyta dla nagłówka x-ms-file-permission.Klucz można utworzyć, wywołując interfejs API Create Permission. |
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ść now może 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 koordynowanego czasu uniwersalnego (UTC) dla pliku. 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 |
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-change-time: { now ¦ <DateTime> } |
Fakultatywny. Wersja 2021-06-08 lub nowsza. Właściwość czasu uniwersalnego koordynowanego (UTC) dla pliku zmienia wartość 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 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. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych. |
Treść żądania
Żaden.
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=
Odpowiedź
Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.
Kod stanu
Pomyślna operacja zwraca kod stanu 201 (Utworzono).
Aby uzyskać informacje o kodach stanu, zobacz Stan i kody błędów.
Nagłówki odpowiedzi
Odpowiedź dla tej operacji zawiera nagłówki opisane w poniższej tabeli. 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 cudzysłów. |
Last-Modified |
Zwraca datę i godzinę ostatniej modyfikacji pliku. 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 katalog lub jego właściwości aktualizuje czas ostatniej modyfikacji. Operacje na plikach nie mają wpływu na czas ostatniej modyfikacji katalogu. |
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 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, jeśli zawartość żądania została pomyślnie zaszyfrowana przy użyciu określonego algorytmu. Jeśli szyfrowanie nie powiedzie się, wartość jest 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ść godzina utworzenia pliku. |
x-ms-file-last-write-time |
Wartość daty/godziny UTC reprezentująca właściwość czas ostatniego zapisu dla pliku. |
x-ms-file-change-time |
Data/godzina UTC reprezentująca właściwość godziny zmiany 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 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. |
Treść odpowiedzi
Żaden.
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, który system operacyjny używa części lub używa wyłącznie. |
| Żaden | 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. |
| Tymczasowy | FILE_ATTRIBUTE_TEMPORARY | Plik używany do przechowywania tymczasowego. |
| 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. Usługa Azure Files nie obsługuje jej 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 Put Range, aby dodać zawartość do pliku lub zmodyfikować go.
Rozmiar pliku można zmienić, wywołując Set File Properties.
Jeśli udział lub katalog nadrzędny nie istnieje, operacja kończy się niepowodzeniem z kodem stanu 412 (Niepowodzenie warunku wstępnego).
Nuta
Właściwości pliku cache-control, content-type, content-md5, content-encodingi content-language są oddzielone od właściwości systemu plików dostępnych 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śli identyfikatora dzierżawy lub określi nieprawidłowy identyfikator dzierżawy, usługa Azure Files zwraca kod stanu 412 (Niepowodzenie warunku wstępnego). Jeśli klient określa identyfikator dzierżawy, ale plik nie ma aktywnej dzierżawy, usługa Azure Files zwraca również kod stanu 412 (Niepowodzenie warunku wstępnego). Jeśli klient określi identyfikator dzierżawy w pliku, który jeszcze nie istnieje, usługa Azure Files zwraca kod stanu 412 (Niepowodzenie warunku wstępnego) dla żądań wysyłanych 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 obowiązywać w zaktualizowanym pliku do momentu jego wydania.
Create File 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 kodem stanu 400 (InvalidQueryParameterValue).
Zobacz też
Operacje w usłudze Azure Files