共用方式為

建立檔案

  • 發行項

Create File 作業會建立新的檔案或取代檔案。 啟用 NFS 通訊協定的檔案共用版本 2025-05-05 和更新版本支援這項作業。 當您呼叫 Create File時，您只會初始化檔案。 若要將內容新增至檔案，您可以呼叫 Put Range 作業。

通訊協定可用性

已啟用檔案共享通訊協定 可用
SMB 是
NFS 是

請求

Create File 要求建構方式如下。 建議您使用 HTTPS。

方法 要求 URI HTTP 版本
放置 https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile HTTP/1.1

將要求 URI 中顯示的路徑元件取代為您自己的路徑元件，如下表所述：

路徑元件 描述
myaccount 記憶體帳戶的名稱。
myshare 檔案共享的名稱。
mydirectorypath 自選。 要建立檔案之目錄的路徑。 如果省略目錄路徑，則會在指定的共用內建立檔案。

如果指定目錄，則必須先存在於共用內，才能建立檔案。
myfile 要建立的檔名。

如需路徑命名限制的相關信息，請參閱 名稱和參考共用、目錄、檔案和元數據。

URI 參數

您可以在要求 URI 上指定下列其他參數：

參數 描述
timeout 自選。 timeout 參數是以秒為單位來表示。 如需詳細資訊，請參閱 設定檔案服務作業的逾時。

要求標頭

下表說明必要和選擇性的要求標頭：

常見的要求標頭

要求標頭 描述
Authorization 必填。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱 授權對 Azure 記憶體的要求。
Date 或 x-ms-date 必填。 指定要求的國際標準時間 （UTC） 時間。 如需詳細資訊，請參閱 授權對 Azure 記憶體的要求。
x-ms-version 所有已授權要求的必要專案。 指定要用於此要求的作業版本。 啟用 NFS 通訊協定的檔案共用版本 2025-05-05 和更新版本支援這項作業。

如需詳細資訊，請參閱 Azure 記憶體服務的版本設定。
Content-Length 自選。 如果存在，則必須為零。
x-ms-content-length: byte value 必填。 此標頭會指定檔案的大小上限，最多 4 個字節 （TiB）。
Content-Type 或 x-ms-content-type 自選。 檔案的MIME內容類型。 預設類型為 application/octet-stream。
Content-Encoding 或 x-ms-content-encoding 自選。 指定哪些內容編碼已套用至檔案。 當 取得檔案 作業在檔案資源上執行時，這個值會傳回給用戶端，而且您可以使用它來譯碼檔案內容。
Content-Language 或 x-ms-content-language 自選。 指定此資源所使用的自然語言。
Cache-Control 或 x-ms-cache-control 自選。 Azure 檔案記憶體會儲存此值，但不會使用或修改此值。
x-ms-content-md5 自選。 設定檔案的 MD5 哈希。
x-ms-content-disposition 自選。 設定檔案的 Content-Disposition 標頭。
x-ms-type: file 必填。 標頭設定為 file。
x-ms-meta-name:value 自選。 與檔案相關聯的名稱/值組做為元數據。 中繼資料名稱必須遵循 C# 識別子的命名規則，。

附註：無法從伺服器消息塊 （SMB） 用戶端存取透過 Azure 檔案服務指定的檔案元數據。
x-ms-file-creation-time: { now ¦ <DateTime> } 必要：版本 2019-02-02 到 2021-04-10。 選用：版本 2021-06-08 和更新版本。 檔案的國際標準時間 （UTC） 建立時間屬性。 now 的值可用來指出要求的時間。 預設值為 now。
x-ms-file-last-write-time: { now ¦ <DateTime> } 必要：版本 2019-02-02 到 2021-04-10。 選用：版本 2021-06-08 和更新版本。 國際標準時間 （UTC） 檔案的最後寫入屬性。 您可以使用 now 值來指出要求的時間。 預設值為 now。
x-ms-lease-id:<ID> 如果檔案具有使用中租用，則為必要專案。 適用於 2019-02-02 版和更新版本。

如果檔案位於已啟用 NFS 通訊協定的檔案共用上，則不支援檔案租用，則會忽略此標頭。
x-ms-client-request-id 自選。 提供客戶端產生的不透明值，其中包含設定記錄時記錄的 1-kibibyte （KiB） 字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊，請參閱 監視 Azure 檔案服務。
x-ms-file-request-intent 如果 Authorization 標頭指定 OAuth 令牌，則為必要項。 可接受的值為 backup。 此標頭指定，如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在指派給使用 Authorization 標頭授權的身分識別中，則應該授與這些 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action。 適用於 2022-11-02 版和更新版本。
x-ms-allow-trailing-dot: { <Boolean> } 自選。 版本 2022-11-02 和更新版本。 布爾值會指定是否應該修剪要求 URL 中的尾端點。

如果目標位於已啟用 NFS 通訊協定的檔案共用上，預設支援尾端點，則會忽略此標頭。

如需詳細資訊，請參閱 命名和參考共用、目錄、檔案和元資料。

僅限SMB要求標頭

要求標頭 描述
x-ms-file-change-time: { now ¦ <DateTime> } 自選。 版本 2021-06-08 和更新版本。 國際標準時間 （UTC） 會以 ISO 8601 格式變更檔案的時間屬性。 您可以使用 now 值來指出要求的時間。 預設值為 now。
x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> } 在 2019-02-02 到 2021-04-10 版中，如果未指定 x-ms-file-permission-key，則需要此標頭。 自 2021-06-08 版起，這兩個標頭都是選擇性的。 此許可權是base64編碼 二進位安全性描述元格式中，安全性描述元定義語言 （SDDL） 中所指定之檔案的安全性描述元 或 （2024-11-04 版或更新版本）。 您可以指定要與 x-ms-file-permission-format 標頭搭配使用的格式。 如果許可權大小是 8 kibibytes （KiB） 或更少，您可以使用此標頭。 否則，您可以使用 x-ms-file-permission-key。 如果您指定標頭，它必須具有擁有者、群組和 選擇性存取控制清單 （DACL）。 您可以傳遞值 inherit，以繼承自父目錄。
x-ms-file-permission-format: { sddl ¦ binary } 自選。 版本 2024-11-04 或更新版本。 指定傳入 x-ms-file-permission 的值是否為 SDDL 或二進位格式。 如果 x-ms-file-permission 設定為 inherit，則不應該設定此標頭。 如果 x-ms-file-permission 設定為 inherit以外的任何其他值，而且如果未設定此標頭，則會使用 sddl 的預設值。
x-ms-file-permission-key: <PermissionKey> 在 2019-02-02 到 2021-04-10 版中，如果未指定 x-ms-file-permission，則需要此標頭。 自 2021-06-08 版起，這兩個標頭都是選擇性的。 如果未指定這兩個標頭，則會針對 inherit 標頭使用 x-ms-file-permission 的預設值。

您可以呼叫 Create Permission API 來建立金鑰。
x-ms-file-attributes 必要：版本 2019-02-02 到 2021-04-10。 選用：版本 2021-06-08 和更新版本。 此標頭包含要設定於檔案上的檔案系統屬性。 如需詳細資訊，請參閱 可用屬性的清單。 預設值為 None。

僅限 NFS 要求標頭

要求標頭 描述
x-ms-mode 自選。 版本 2025-05-05 和更新版本。 要設定於檔案上的模式位。 模式是以12位數值八進位格式或符號 「rwx」 格式表示。 預設值為 0644。 請參閱 POSIX 檔案權限 （mode）。
x-ms-owner 自選。 版本 2025-05-05 和更新版本。 要設定於檔案上之檔案擁有者的用戶標識碼 （UID）。 預設值為 0 （root）。
x-ms-group 自選。 版本 2025-05-05 和更新版本。 要設定於檔案上之檔案擁有者的群組標識碼 （GID）。 預設值為 0 （根群組）。
x-ms-file-file-type 自選。 版本 2025-05-05 和更新版本。 檔的類型。 如果存在，則必須是「一般」。

要求本文

沒有。

範例要求

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=

回應

回應包含 HTTP 狀態代碼和一組響應標頭。

狀態代碼

成功的作業會傳回狀態代碼 201 （已建立）。 如您需狀態代碼的相關資訊，請參閱 狀態和錯誤碼。

回應標頭

此作業的回應包含下表中的標頭。 回應也可能包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格，。

常見的響應標頭

回應標頭 描述
ETag ETag 包含值，表示檔案的版本。 值會以引弧括住。
Last-Modified 傳回上次修改檔案的日期和時間。 日期格式遵循 RFC 1123。 如需詳細資訊，請參閱 代表標頭中的日期/時間值。

修改目錄或其屬性的任何作業會更新上次修改的時間。 檔案上的作業不會影響目錄的上次修改時間。
x-ms-request-id 可唯一識別已提出並可用於對要求進行疑難解答的要求。 如需詳細資訊，請參閱針對 API 作業進行疑難解答
x-ms-version 指出用來執行要求的 Azure 檔案服務版本。
Date 服務所產生的 UTC 日期/時間值，表示起始響應的時間。
x-ms-request-server-encrypted: true/false 版本 2017-04-17 和更新版本。 如果您已使用指定的演算法成功加密要求的內容，此標頭的值會設定為 true。 如果加密失敗，則值會 false。
x-ms-file-creation-time UTC 日期/時間值，表示檔案的建立時間屬性。
x-ms-file-last-write-time UTC 日期/時間值，表示檔案的最後一個寫入時間屬性。
x-ms-file-change-time 代表檔案變更時間屬性的UTC日期/時間。
x-ms-file-file-id 檔案的檔案識別碼。
x-ms-file-parent-id 檔案的父檔案標識碼。
x-ms-client-request-id 用來針對要求及其對應的回應進行疑難解答。 如果此標頭存在於要求中，則這個標頭的值等於 x-ms-client-request-id 標頭的值，而且值包含不超過 1,024 個可見的 ASCII 字元。 如果要求中沒有 x-ms-client-request-id 標頭，它就不會出現在回應中。

僅限SMB回應標頭

回應標頭 描述
x-ms-file-permission-key 版本 2019-02-02 和更新版本。 檔案許可權的索引鍵。
x-ms-file-attributes 版本 2019-02-02 和更新版本。 檔案的檔案系統屬性。 如需詳細資訊，請參閱 的可用屬性清單。

僅限 NFS 回應標頭

回應標頭 描述
x-ms-mode 版本 2025-05-05 和更新版本。 檔案的模式。 請參閱 POSIX 檔案權限 （mode）。
x-ms-owner 版本 2025-05-05 和更新版本。 檔案擁有者的使用者識別碼 （UID）。
x-ms-group 版本 2025-05-05 和更新版本。 檔案擁有者的群組標識碼 （GID）。
x-ms-file-file-type 版本 2025-05-05 和更新版本。 檔案的類型，可能的值為：『Regular』。

回應本文

沒有。

範例回應

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

授權

只有帳戶擁有者可以呼叫這項作業。

檔案系統屬性

屬性 Win32 檔案屬性 定義
ReadOnly FILE_ATTRIBUTE_READONLY 唯讀的檔案。 應用程式可以讀取檔案，但無法寫入或刪除檔案。
隱藏 FILE_ATTRIBUTE_HIDDEN 檔案已隱藏。 它不包含在一般目錄清單中。
系統 FILE_ATTRIBUTE_SYSTEM 操作系統使用 部分或獨佔使用的檔案。
沒有 FILE_ATTRIBUTE_NORMAL 未設定其他屬性的檔案。 此屬性只有在單獨使用時才有效。
檔案 FILE_ATTRIBUTE_ARCHIVE 檔案是封存盤案。 應用程式通常會使用這個屬性來標記檔案以進行備份或移除。
臨時 FILE_ATTRIBUTE_TEMPORARY 用於暫存記憶體的檔案。
離線 FILE_ATTRIBUTE_OFFLINE 檔案的數據無法立即取得。 此文件系統屬性主要是為了提供與 Windows 的相容性。 Azure 檔案服務不支援離線記憶體選項。
NotContentIndexed FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 檔案不會由內容索引服務編製索引。
NoScrubData FILE_ATTRIBUTE_NO_SCRUB_DATA 背景數據完整性掃描器不會 讀取 的用戶數據流。 此文件系統屬性主要是為了提供與 Windows 的相容性。

POSIX 檔案權限 （模式）

POSIX 檔案許可權可以用 12 位數值八進位格式或符號 “rwx” 格式來指定。 例子：

  • “0644” 或 “rw-r--r--”： 使用者 （檔案擁有者） 具有讀取、寫入許可權。 群組具有讀取許可權。 其他人具有讀取許可權。
  • “0755” 或 “rwxr-xr-x”：使用者（檔案擁有者）具有讀取、寫入和執行許可權。 群組具有讀取和執行許可權。 其他人具有讀取和執行許可權。

數值八進位格式

三個最低順序八進位數位代表擁有者/使用者、群組和其他使用者的許可權，並使用八進位數位（0-7）來表示，其格式為 '4' （Read）、'2' （Write）、'1' （Execute）。 最高順序八進位數 （0-7） 用來表示 '4' （SetUID）、'2' （SetGID）、'1' （StickyBit） 許可權的組合。

格式 許可
0700 使用者 （檔案擁有者） 具有讀取、寫入和執行許可權。
0400 使用者具有讀取許可權。
0200 使用者具有寫入許可權。
0100 使用者具有執行許可權。
0070 群組具有讀取、寫入和執行許可權。
0040 群組具有讀取許可權。
0020 群組具有寫入許可權。
0010 群組具有執行許可權。
0007 其他人具有讀取、寫入和執行許可權。
0004 其他人具有讀取許可權。
0002 其他人具有寫入許可權。
0001 其他人有執行許可權。
4000 在檔案上設定有效的使用者標識碼。
2000 在檔案上設定有效的群組標識碼。
1000 設定為 ，表示檔案只能由檔案擁有者、目錄擁有者或根使用者刪除或重新命名。

符號 “rwx” 格式

擁有者/使用者、群組和其他使用者的許可權會使用 'r' （Read）、'w' 和 'x' （Execute） 字元的組合來表示。

格式 許可
rwx------ 使用者 （檔案擁有者） 具有讀取、寫入和執行許可權。
r-------- 使用者具有讀取許可權。
-w------- 使用者具有寫入許可權。
--x------ 使用者具有執行許可權。
---rwx--- 群組具有讀取、寫入和執行許可權。
---r----- 群組具有讀取許可權。
----w---- 群組具有寫入許可權。
-----x--- 群組具有執行許可權。
------rwx 其他人具有讀取、寫入和執行許可權。
------r-- 其他人具有讀取許可權。
-------w- 其他人具有寫入許可權。
--------x 其他人有執行許可權。

言論

若要建立新的檔案，請先呼叫 Create File 並指定其大小上限，最多 4 TiB 來初始化它。 當您執行這項作業時，請勿在要求本文中包含內容。 建立檔案之後，請呼叫 Put Range，將內容新增至檔案或修改它。

您可以呼叫 Set File Properties來變更檔案的大小。

如果共用或父目錄不存在，則作業會失敗，狀態代碼為 412（前置條件失敗）。

注意

cache-control、content-type、content-md5、content-encoding和 content-language 的檔案屬性與 SMB 用戶端可用的檔案系統屬性不同。 SMB 用戶端無法讀取、寫入或修改這些屬性值。

若要建立檔案，如果現有的檔案具有作用中的租用，客戶端必須在要求上指定有效的租用標識符。 如果用戶端未指定租用標識碼或指定無效的租用標識符，Azure 檔案服務會傳回狀態代碼 412 （前置條件失敗）。 如果用戶端指定租用標識碼，但檔案沒有使用中租用，則 Azure 檔案服務也會在此實例中傳回狀態代碼 412 （前置條件失敗）。 如果用戶端在尚未存在的檔案上指定租用標識符，Azure 檔案會針對針對 2019-02-02 版和更新版本提出的要求傳回狀態代碼 412 （前置條件失敗）。

如果具有使用中租用的現有檔案被 Create File 作業覆寫，租用會保存在更新的檔案上，直到發行為止。

共用快照集不支援 Create File，這是共用的唯讀複本。 嘗試在共用快照集上執行這項作業失敗，狀態代碼為 400 （InvalidQueryParameterValue）。

另請參閱

檔案 上的 作業