Path - Create

服務:

Storage Services

API 版本:

2023-08-03

建立檔案 |建立目錄 |重新命名檔案 |重新命名目錄
建立或重新命名檔案或目錄。 根據預設，目的地會遭到覆寫，如果目的地已經存在，且租用已中斷。 請注意，除非來源容器也有符合的強制容器加密原則，否則不允許將檔案或目錄重新命名為具有強制容器加密原則的容器。 此作業支援條件式 HTTP 要求。 如需詳細資訊，請參閱 為 Blob 服務作業指定條件式標頭。 如果目的地已經存在，請使用條件式要求搭配 If-None-Match：“*”。

PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}

含選擇性參數:

PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}?resource={resource}&continuation={continuation}&mode={mode}&timeout={timeout}

URI 參數

名稱	位於	必要	類型	Description
accountName	path	True	string	Azure 記憶體帳戶名稱。
dnsSuffix	path	True	string	Azure Data Lake Storage 端點的 DNS 後綴。
filesystem	path	True	string	文件系統標識碼。 Regex 模式: ^[$a-z0-9](?!.*--)[-a-z0-9]{1,61}[a-z0-9]$
path	path	True	string	檔案或目錄路徑。
continuation	query		string	自選。 重新命名目錄時，會限制以每個叫用重新命名的路徑數目。 如果要重新命名的路徑數目超過此限制，則會在此回應標頭中傳回接續令牌。 當回應中傳回接續令牌時，必須在後續重新命名作業的調用中指定它，才能繼續重新命名目錄。
mode	query		PathRenameMode	自選。 只有在啟用命名空間時才有效。 此參數會決定重新命名作業的行為。 此值必須是 “legacy” 或 “posix”，而預設值會是 “posix”。
resource	query		PathResourceType	僅適用於建立檔案和建立目錄。 此值必須是 「file」 或 「directory」。
timeout	query		integer int32	選擇性作業逾時值，以秒為單位。 期間是從服務收到要求時開始的。 如果逾時值在作業完成之前經過，作業就會失敗。

要求標頭

Media Types: "application/octet-stream"

名稱	必要	類型	Description
Cache-Control		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「快取控制」回應標頭中，以進行「讀取檔案」作業。
Content-Encoding		string	自選。 指定哪些內容編碼已套用至檔案。 執行「讀取檔案」作業時，這個值會傳回給用戶端。
Content-Language		string	自選。 指定檔案目標物件所使用的自然語言。
Content-Disposition		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「內容處置」響應標頭中。
x-ms-cache-control		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「快取控制」回應標頭中。
x-ms-content-type		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「內容類型」回應標頭中。
x-ms-content-encoding		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「內容編碼」回應標頭中。
x-ms-content-language		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「Content-Language」回應標頭中。
x-ms-content-disposition		string	自選。 服務會儲存此值，並將其包含在「讀取檔案」作業的「內容處置」響應標頭中。
x-ms-rename-source		string	要重新命名的選擇性檔案或目錄。 當使用 SAS 令牌時，此值必須具有下列格式：“/{filesystem}/{path}”或 “/{filesystem}/{path}？sastoken”。 如果指定 「x-ms-properties」 ，則屬性會覆寫現有的屬性;否則，將會保留現有的屬性。 此值必須是 URL 百分比編碼字串。 請注意，字串只能包含 ISO-8859-1 字元集中的 ASCII 字元。
x-ms-lease-id		string	自選。 URI 中所指定路徑的租用標識碼。 要覆寫的路徑必須具有作用中的租用，且租用標識碼必須相符。 Regex 模式: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-source-lease-id		string	重新命名作業的選擇性。 來源路徑的租用標識碼。 來源路徑必須具有作用中的租用，且租用標識碼必須相符。 Regex 模式: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-properties		string	自選。 要與檔案或目錄一起儲存的使用者定義屬性，格式為以逗號分隔的名稱和值組清單 “n1=v1， n2=v2， ...”，其中每個值都是 base64 編碼字符串。 請注意，字串只能包含 ISO-8859-1 字元集中的 ASCII 字元。
x-ms-permissions		string	選擇性且只有在帳戶啟用階層命名空間時才有效。 設定檔案擁有者、檔案擁有者群組和其他專案的 POSIX 訪問許可權。 每個類別都可以被授與讀取 （4）、寫入 （2） 或執行 （1） 許可權。 支援符號符號 （rwxrw-rw-） 和 4 位數八進位表示法（例如 0766）。 黏性位也受到支援，而且在符號表示法中，其代表的是字母 t 或 T，取決於其他類別的執行位是分別設定或未設定的（例如，含黏性位的 rwxrw-rw- 會分別表示為 rwxrw-rwT。具有黏性位的 rwxrw-rwx 會以 rwxrw-rwt 表示，沒有 t 或 T 表示未設定黏性位。 在 4 位數八進位表示法中，其以第 1 位數表示法（例如 1766 代表具有黏性位的 rwxrw-rw-，而 0766 代表 rwxrw-rw- 而不黏性位）。 與 x-ms-acl 搭配使用無效。
x-ms-umask		string	選擇性且只有在帳戶啟用階層命名空間時才有效。 建立檔案或目錄且父資料夾沒有預設 ACL 時，umask 會限制要建立的檔案或目錄許可權。 產生的許可權是由 p & ^u 提供，其中 p 是許可權，而您是 umask。 例如，如果 p 是 0777，而您是 0057，則產生的許可權為 0720。 目錄的默認許可權為 0777，檔案的默認許可權為 0666。 預設的 umask 為 0027。 umask 必須以 4 位數八進位表示法指定（例如 0766）。
x-ms-owner		string	選擇性且只有在帳戶啟用階層命名空間時才有效。 設定檔案或目錄的擁有者。
x-ms-group		string	選擇性且只有在帳戶啟用階層命名空間時才有效。 設定檔案或目錄的擁有群組。
x-ms-acl		string	選擇性且只有在帳戶啟用階層命名空間時才有效。 設定檔案和目錄的 POSIX 訪問控制許可權。 每個訪問控制專案 （ACE） 都包含範圍、類型、使用者或群組標識碼，以及格式為 “[scope：][type]：[id]：[permissions]” 的許可權。 範圍必須是 「預設值」，才能指出 ACE 屬於目錄的預設 ACL;否則範圍是隱含的，且 ACE 屬於存取 ACL。 ACE 類型有四種：「user」 會將許可權授與擁有者或具名使用者、「群組」將許可權授與擁有者群組或具名群組、「遮罩」會限制授與給具名使用者和群組成員的許可權，而「其他」會將許可權授與任何其他專案中找不到的所有使用者。 針對類型為 「mask」 和 「other」 的專案，會省略使用者或群組標識碼。 擁有者和擁有者群組也會省略使用者或群組標識符。 許可權欄位是3個字元序列，第一個字元是 『r』 以授與讀取許可權，第二個字元是 『w』 以授與寫入許可權，而第三個字元是 『x』 以授與執行許可權。 如果未授與存取權，則會使用 『-』 字元來表示許可權遭到拒絕。 例如，下列 ACL 會將讀取、寫入和執行許可權授與檔案擁有者和john.doe@contoso、擁有群組的讀取許可權，以及其他人沒有許可權：“user：：rwx，user：john.doe@contoso：rwx，group：：r--,other：：：---,mask=rwx”。 與 x-ms-permissions 搭配使用時無效。
x-ms-proposed-lease-id		string	自選。 如果您想要在建立檔案或目錄期間取得租用，請指定建議的租用標識碼。 如果建立成功，則會使用此租用標識符來取得租用。 Regex 模式: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-expiry-option		string	選擇性且只有在帳戶啟用階層命名空間，且只支援檔案時才有效。 如果您想要在建立檔案時設定到期時間，請指定下列其中一個到期選項。 “RelativeToNow” 設定相對於目前時間的到期時間。 使用者將會傳遞從現在起經過的毫秒數。 RFC 1123 格式的「絕對」絕對時間。 “Neverexpire” 將檔案設定為永不過期，不需要使用此選項來指定到期時間。
x-ms-expiry-time		string	選擇性且只有在帳戶啟用階層命名空間，且只支援檔案時才有效。 指定檔案到期的到期時間。 根據到期選項指定為 RFC 1123 HTTP 時間字串或毫秒數。
If-Match		string	自選。 ETag 值。 只有在資源的 ETag 符合指定的值時，才指定此標頭來執行作業。 ETag 必須以引號指定。
If-None-Match		string	自選。 ETag 值或特殊通配符 （“*”） 值。 只有在資源的 ETag 不符合指定的值時，才指定此標頭來執行作業。 ETag 必須以引號指定。
If-Modified-Since		string	自選。 日期和時間值。 請指定此標頭，只有在資源自指定的日期和時間之後已修改時，才會執行作業。
If-Unmodified-Since		string	自選。 日期和時間值。 只有當資源自指定的日期和時間之後尚未修改時，才指定此標頭來執行作業。
x-ms-source-if-match		string	自選。 ETag 值。 只有在來源的 ETag 符合指定的值時，才指定此標頭來執行重新命名作業。 ETag 必須以引號指定。
x-ms-source-if-none-match		string	自選。 ETag 值或特殊通配符 （“*”） 值。 只有在來源的 ETag 不符合指定的值時，才指定此標頭來執行重新命名作業。 ETag 必須以引號指定。
x-ms-source-if-modified-since		string	自選。 日期和時間值。 只有在來源自指定的日期和時間之後修改過時，才指定此標頭來執行重新命名作業。
x-ms-source-if-unmodified-since		string	自選。 日期和時間值。 只有在來源自指定的日期和時間之後尚未修改時，才指定此標頭來執行重新命名作業。
x-ms-encryption-key		string	自選。 Base64 編碼的 AES-256 加密金鑰。
x-ms-encryption-key-sha256		string	自選。 加密金鑰的Base64編碼SHA256哈希。
x-ms-encryption-algorithm: AES256		string	自選。 指定要用於加密的演算法。 此標頭的值必須是 AES256。
x-ms-encryption-context		string	自選。 預設值為 「Empty」。 如果設定值，則會設定 Blob /檔案系統元數據。 最大長度 - 1024。 只有在帳戶啟用階層命名空間時才有效。
x-ms-client-transaction-id		string	自選。 預設值為 「Empty」。 如果設定值，則會在檔案建立或重新命名時設定 Blob 元數據。 如果用戶端的要求逾時，可以使用取得屬性呼叫來擷取此值，以確認逾時要求是否在服務端成功。 最大長度 - 36。 只有在帳戶啟用階層命名空間時才有效。
x-ms-client-request-id		string	在分析記錄中記錄的 UUID，用於疑難解答和相互關聯。 Regex 模式: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-date		string	指定要求的國際標準時間（UTC）。 使用共用密鑰授權時，這是必要的。
x-ms-version		string	指定用於處理要求的 REST 通訊協定版本。 使用共用密鑰授權時，這是必要的。

回應

名稱	類型	Description
201 Created		已建立檔案或目錄。 標題 Date: string ETag: string Last-Modified: string x-ms-request-id: string x-ms-version: string x-ms-continuation: string Content-Length: integer x-ms-request-server-encrypted: true/false: boolean x-ms-encryption-key-sha256: string x-ms-encryption-scope: string
Other Status Codes	DataLakeStorageError	發生錯誤。 可能的 HTTP 狀態、程式代碼和訊息字串如下所列： 400 不正確的要求 ContentLengthMustBeZero：「Content-Length 要求標頭必須是零」。 400 不正確的要求，InvalidAuthenticationInfo，「驗證資訊未以正確的格式提供。 檢查 Authorization 標頭的值。」 400 不正確的要求，InvalidFlushPosition：「上傳的數據不是連續的，或位置查詢參數值不等於附加上傳的數據之後檔案的長度。 400 不正確的要求，InvalidHeaderValue，“其中一個 HTTP 標頭的值不是正確的格式。 400 不正確的要求，Invalid HttpVerb，“指定的 HTTP 動詞無效 - 伺服器無法辨識它。 400 不正確的要求，InvalidInput，「其中一個要求輸入無效」。 400 不正確的要求，InvalidPropertyName，“屬性名稱不能空白。 400 不正確的要求，InvalidPropertyName，“屬性名稱包含無效的字元。 400 不正確的要求，InvalidQueryParameterValue，「要求 URI 中指定的其中一個查詢參數的值無效」。 400 不正確的要求，InvalidResourceName，“指定的資源名稱包含無效的字元。 400 不正確的要求，InvalidSourceUri，「來源 URI 無效」。 400 不正確的要求 InvalidUri：「要求 URI 無效」。 400 不正確的要求，MissingRequiredHeader，「未指定此要求的必要 HTTP 標頭」。 400 不正確的要求，MissingRequiredQueryParameter，「未指定此要求的必要查詢參數」。 400 不正確的要求、MultipleConditionHeadersNotSupported、「不支援多個條件標頭」。 400 不正確的要求，OutOfRangeInput，“其中一個要求輸入超出範圍。 400 不正確的要求，OutOfRangeQueryParameterValue，“要求 URI 中指定的其中一個查詢參數超出允許的範圍。 400 不正確的要求，UnsupportedHeader，「不支援要求中指定的其中一個標頭」。 400 不正確的要求、UnsupportedQueryParameter：「不支援在要求 URI 中指定的其中一個查詢參數」。 400 不正確的要求，UnsupportedRestVersion，「不支援指定的 Rest 版本」。 403 禁止，AccountIsDisabled，「指定的帳戶已停用」。 403 禁止，AuthorizationFailure，「此要求未獲授權執行這項作業」。 403 禁止，InsufficientAccountPermissions：「正在存取的帳戶沒有足夠的許可權可執行這項作業。」 404 找不到，FilesystemNotFound，「指定的文件系統不存在」。 404 找不到，PathNotFound，「指定的路徑不存在」。 404 找不到，RenameDestinationParentPathNotFound，「目的地路徑的父目錄不存在」。 404 找不到 ResourceNotFound：「指定的資源不存在」。 404 找不到 SourcePathNotFound：「重新命名作業的來源路徑不存在」。 405 方法不允許、不支援的 HttpVerb：「資源不支援指定的 HTTP 動詞命令」。 409 Conflict，DestinationPathIsBeingDeleted：「指定的目的地路徑標示為要刪除」。 409 Conflict，DirectoryNotEmpty：「遞歸查詢參數值必須為 true，才能刪除非空白目錄。 409 Conflict， FilesystemAlreadyExists， “指定的文件系統已經存在。 409 衝突，FilesystemBeingDeleted，「正在刪除指定的文件系統」。 409 Conflict， InvalidDestinationPath， “指定的路徑或路徑的專案存在，而且其資源類型對這項作業無效。* 409 衝突，InvalidFlushOperation，「資源是由 Blob 服務 API 所建立或修改，無法由 Data Lake Storage Service API 寫入。 409 Conflict， InvalidRenameSourcePath， “來源目錄不能與目的地目錄相同，目的地也不能是來源目錄的子目錄。 409 Conflict，InvalidSourceOrDestinationResourceType，「來源和目的地資源類型必須相同」。 409 衝突，LeaseAlreadyPresent，“已經有租用存在。 409 Conflict，LeaseIdMismatchWithLeaseOperation：「指定的租用標識符與指定租用作業的資源租用標識符不符」。 409 衝突，LeaseIsAlreadyBroken，“租用已經中斷，不能再中斷。 409 Conflict， LeaseIsBreakingAndCannotBeAcquired， “租用標識符相符，但租用目前處於中斷狀態，而且在中斷之前無法取得。 409 Conflict， LeaseIsBreakingAndCannotBeChanged：「租用標識符相符，但租用目前處於中斷狀態且無法變更」。 409 衝突，LeaseIsBrokenAndCannotBeRenewed：「租用標識符相符，但租用已明確中斷，無法更新。 409 Conflict， LeaseNameMismatch， 「指定的租用名稱不符合現有的租用名稱」。 409 Conflict，LeaseNotPresentWithLeaseOperation：「租用標識符不存在於指定的租用作業中。」 409 Conflict， PathAlreadyExists， “指定的路徑已經存在。 409 Conflict、PathConflict、“指定的路徑或路徑的專案存在，而且其資源類型對這項作業無效。 409 Conflict，SourcePathIsBeingDeleted：「指定的來源路徑標示為要刪除」。 409 Conflict，ResourceTypeMismatch，「要求中指定的資源類型不符合資源的類型」。 412 前置條件失敗，ConditionNotMet：「不符合使用 HTTP 條件標頭指定的條件」。 412 前置條件失敗，LeaseIdMismatch：「指定的租用標識碼不符合資源的租用標識符」。 412 前置條件失敗，LeaseIdMissing：「資源目前有租用，且要求中未指定租用標識符」。 412 前置條件失敗，LeaseNotPresent：「資源目前沒有租用」。 412 前置條件失敗，LeaseLost：「已指定租用標識碼，但資源的租用已過期」。 412 前置條件失敗，SourceConditionNotMet：「不符合使用 HTTP 條件標頭所指定的來源條件。」 413 要求實體太大，RequestBodyTooLarge：「要求主體太大，超過允許上限。」 416 要求的範圍無法滿足，InvalidRange，「指定的範圍對目前資源的大小無效」。 500 內部伺服器錯誤 InternalError：「伺服器發生內部錯誤。 請重試要求。」 500 內部伺服器錯誤 OperationTimedOut：「作業無法在允許的時間內完成」。 503 服務無法使用，ServerBusy，「輸出超過帳戶限制」。 503 服務無法使用，ServerBusy，「輸入超過帳戶限制」。 503 服務無法使用，ServerBusy，「每秒的作業超過帳戶限制」。 503 服務無法使用 ServerBusy：「伺服器目前無法接收要求。 請重試您的要求。 標題 x-ms-request-id: string x-ms-version: string

定義

名稱	Description
DataLakeStorageError
Error	服務錯誤回應物件。
PathRenameMode	自選。 只有在啟用命名空間時才有效。 此參數會決定重新命名作業的行為。 此值必須是 “legacy” 或 “posix”，而預設值會是 “posix”。
PathResourceType	僅適用於建立檔案和建立目錄。 此值必須是 「file」 或 「directory」。

DataLakeStorageError

名稱	類型	Description
error	Error	服務錯誤回應物件。

Error

服務錯誤回應物件。

名稱	類型	Description
code	string	服務錯誤碼。
message	string	服務錯誤訊息。

PathRenameMode

自選。 只有在啟用命名空間時才有效。 此參數會決定重新命名作業的行為。 此值必須是 “legacy” 或 “posix”，而預設值會是 “posix”。

名稱	類型	Description
legacy	string
posix	string

PathResourceType

僅適用於建立檔案和建立目錄。 此值必須是 「file」 或 「directory」。

名稱	類型	Description
directory	string
file	string