Path - Create

  • 參考
Service:
Storage Services
API Version:
2023-08-03

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

PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}
With optional parameters: 
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 pattern: ^[$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

選擇性。 服務會儲存此值，並將其包含在「讀取檔案」作業的「內容語言」回應標頭中。
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 pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-source-lease-id

string

重新命名作業的選擇性。 來源路徑的租用標識碼。 來源路徑必須具有作用中的租用，且租用標識碼必須相符。

Regex pattern: ^[{(]?[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]” 的許可權。 範圍必須是 「default」，表示 ACE 屬於目錄的預設 ACL;否則範圍為隱含，且 ACE 屬於存取 ACL。 有四種 ACE 類型：「使用者」會將許可權授與擁有者或具名使用者、「群組」將許可權授與擁有者群組或具名群組，「遮罩」會限制授與具名使用者和群組成員的許可權，而「其他」會將許可權授與任何其他專案中找不到的所有使用者。 使用者或群組標識碼會省略 「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 pattern: ^[{(]?[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-request-id

string

分析記錄中記錄的 UUID，用於疑難解答和相互關聯。

Regex pattern: ^[{(]?[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

已建立檔案或目錄。

Headers

  • 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 Conflict， FilesystemBeingDeleted，「正在刪除指定的文件系統」。
  • 409 Conflict、InvalidDestinationPath、「指定的路徑或路徑的專案存在，而且其資源類型對此作業無效」。* 409 Conflict， InvalidFlushOperation，「資源是由 Blob 服務 API 所建立或修改，而且無法由 Data Lake Storage 服務 API 寫入。」
  • 409 Conflict， InvalidRenameSourcePath：「來源目錄不能與目的地目錄相同，也無法目的地是來源目錄的子目錄。」
  • 409 Conflict，InvalidSourceOrDestinationResourceType：「來源和目的地資源類型必須相同」。
  • 409 Conflict， LeaseAlreadyPresent，「已經有租用存在」。
  • 409 Conflict， LeaseIdMismatchWithLeaseOperation：「指定的租用標識符不符合具有指定租用作業之資源的租用標識符」。
  • 409 Conflict， LeaseIsAlreadyBroken：「租用已中斷，無法再中斷」。
  • 409 Conflict， LeaseIsBreakingAndCannotBeAcquired：「租用標識符相符，但租用目前處於中斷狀態，且在中斷之前無法取得」。
  • 409 Conflict， LeaseIsBreakingAndCannotBeChanged：「租用標識符相符，但租用目前處於中斷狀態且無法變更」。
  • 409 Conflict， 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：「伺服器目前無法接收要求。 請重試您的要求。」

Headers

  • 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