共用方式為

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

minLength: 3
maxLength: 63
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)

minimum: 1

選擇性作業逾時值，以秒為單位。 期間是從服務收到要求時開始的。 如果逾時值在作業完成之前經過，作業就會失敗。

要求標頭

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

pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$

自選。 URI 中所指定路徑的租用標識碼。 要覆寫的路徑必須具有作用中的租用，且租用標識碼必須相符。
x-ms-source-lease-id

string

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]” 的許可權。 範圍必須是 「預設值」，才能指出 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

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-transaction-id

string

自選。 預設值為 「Empty」。 如果設定值，則會在檔案建立或重新命名時設定 Blob 元數據。 如果用戶端的要求逾時，可以使用取得屬性呼叫來擷取此值，以確認逾時要求是否在服務端成功。 最大長度 - 36。 只有在帳戶啟用階層命名空間時才有效。
x-ms-client-request-id

string

pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$

在分析記錄中記錄的 UUID，用於疑難解答和相互關聯。
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

Object
名稱 類型 Description
error

Error

服務錯誤回應物件。

Error

Object

服務錯誤回應物件。

名稱 類型 Description
code

string

服務錯誤碼。
message

string

服務錯誤訊息。

PathRenameMode

列舉型別

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

值 Description
legacy
posix

PathResourceType

列舉型別

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

值 Description
directory
file