複製檔案
作業 Copy File 會將 Blob 或檔案複製到儲存體帳戶內的目的地檔案。
可在 2015-02-21 版和更新版本中使用。
通訊協定可用性
| 已啟用檔案共用通訊協定 | 可用 |
|---|---|
| SMB |  |
| NFS |  |
要求
您可以建構 Copy File 要求，如下所示。 我們建議使用 HTTPS。
從 2013-08-15 版開始，如果目的地檔案位於與來源檔案相同的帳戶中，您可以指定目的地檔案的共用存取簽章。 從 2015-04-05 版開始，如果目的地檔案位於不同的儲存體帳戶中，您也可以指定目的地檔案的共用存取簽章。
| 方法 | 要求 URI | HTTP 版本 |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
將要求 URI 中的路徑元件取代為您自己的路徑元件，如下所示：
| 路徑元件 | Description |
|---|---|
myaccount |
儲存體帳戶的名稱。 |
myshare |
檔案共用的名稱。 |
mydirectorypath |
選擇性。 上層目錄的路徑。 |
myfile |
檔案的名稱。 |
如需路徑命名限制的詳細資訊，請參閱 命名和參考共用、目錄、檔案和中繼資料。
URI 參數
您可以在要求 URI 上指定下列其他參數：
| 參數 | 描述 |
|---|---|
timeout |
選擇性。 timeout 參數以秒為單位。 如需詳細資訊，請參閱設定Azure 檔案儲存體作業的逾時。 |
要求標頭
下表描述必要和選擇性的要求標頭：
| 要求標頭 | 描述 |
|---|---|
Authorization |
必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。 |
Date 或 x-ms-date |
必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。 |
x-ms-version |
所有已授權要求都需要。 指定用於這個要求的作業版本。 這項作業僅適用于 2015-02-21 版和更新版本。 如需詳細資訊，請參閱 Azure 儲存體服務的版本。 |
x-ms-meta-name:value |
選擇性。 指定與檔案相關聯的名稱/值組做為中繼資料。 如果未指定名稱/值組，作業會將中繼資料從來源 Blob 或檔案複製到目的地檔案。 如果指定了一或多個名稱/值組，則會使用指定的中繼資料建立目的地檔案，而且中繼資料不會從來源 Blob 或檔案複製。 中繼資料名稱必須遵守 C# 識別碼的命名規則。 請注意，無法從 SMB 用戶端存取透過 Azure 檔案儲存體 指定的檔案中繼資料。 |
x-ms-copy-source:name |
必要。 指定來源檔案或 Blob 的 URL，長度最多為 2 kibibytes (KiB) 。 若要將檔案複製到相同儲存體帳戶內的另一個檔案，您可以使用共用金鑰來授權來源檔案。 如果您要從另一個儲存體帳戶複製檔案，或是從相同的儲存體帳戶或其他儲存體帳戶複製 Blob，則必須使用共用存取簽章來授權來源檔案或 Blob。 如果來源是公用 Blob，則不需要授權才能執行複製作業。 您也可以將共用快照集中的檔案指定為複製來源。 以下是來源物件 URL 的一些範例：
|
x-ms-lease-id:<ID> |
如果目的地檔案具有作用中的租用，則為必要專案。 適用于 2019-02-02 版和更新版本。 為此標頭指定的租用識別碼必須符合目的地檔案的租用識別碼。 如果要求不包含租用識別碼或識別碼無效，作業會失敗，狀態碼為 412 (前置條件失敗) 。 如果指定此標頭，且目的地檔案目前沒有使用中租用，作業就會失敗，狀態碼為 412 (前置條件失敗) 。 |
x-ms-file-permission-copy-mode: { source ¦ override } |
選擇性。 適用于 2019-07-07 版和更新版本。 決定檔案之安全性描述項的複製行為：
|
x-ms-file-permission |
如果 x-ms-file-permission-copy-mode 指定為 override 且 x-ms-file-permission-key 未指定 ，則為必要項。 適用于 2019-07-07 版和更新版本。 此許可權是安全性描述元 定義語言 (SDDL) 中所指定檔案的安全性描述元。 如果許可權大小為 8 kibibytes (KiB) 或更少，您可以使用此標頭。 否則，您可以使用 x-ms-file-permission-key 。 如果指定，它必須具有擁有者、群組和 任意存取控制清單， (DACL) 。 請注意，只能指定 或 x-ms-file-permission-key 的 x-ms-file-permission 其中一個。 |
x-ms-file-permission-key |
如果 x-ms-file-permission-copy-mode 指定為 override 且 x-ms-file-permission 未指定 ，則為必要項。 適用于 2019-07-07 版和更新版本。 此標頭會指定要為檔案設定之許可權的索引鍵。 您可以使用 作業來建立此金鑰 Create Permission 。請注意，只能指定 或 x-ms-file-permission-key 的 x-ms-file-permission 其中一個。 |
x-ms-file-copy-ignore-readonly |
選擇性。 適用于 2019-07-07 版和更新版本。 這個布林值會指定是否 ReadOnly 應遵守預先存在的目的地檔案上的 屬性。 true如果是 ，複製作業就會成功。 否則，目的地上具有 ReadOnly 屬性集的上一個檔案會導致複製作業失敗。 |
x-ms-file-attributes |
選擇性。 適用于 2019-07-07 版和更新版本。 此標頭會指定要在目的地檔案上設定的檔案系統屬性。 請參閱 可用屬性的清單。 您可以使用 的值 source ，將屬性從來源檔案複製到目的地檔案。 您可以使用 的值 none 來清除目的地檔案上的所有屬性。 |
x-ms-file-creation-time |
選擇性。 適用于 2019-07-07 版和更新版本。 此標頭會指定在目的地檔案上設定的建立時間屬性，以 UTC 為單位。 您可以使用 的值 source ，將建立時間從來源檔案複製到目的地檔案。 |
x-ms-file-last-write-time |
選擇性。 適用于 2019-07-07 版和更新版本。 此標頭會指定在目的地檔案上設定的上次寫入時間屬性，以 UTC 為單位。 您可以使用 的值 source ，將上次寫入時間從來源檔案複製到目的地檔案。 |
x-ms-file-copy-set-archive |
選擇性。 適用于 2019-07-07 版和更新版本。 這個布林值會指定是否 Archive 應該設定屬性，而不論 x-ms-file-attributes 標頭值為何。 |
x-ms-client-request-id |
選擇性。 提供用戶端產生的不透明值，其中包含設定記錄時記錄在記錄中的 1-KiB 字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊，請參閱監視Azure Blob 儲存體。 |
x-ms-file-change-time: { <DateTime> ¦ source } |
選擇性。 版本 2021-06-08 和更新版本。 檔案的 UTC 變更時間屬性，格式為 ISO 8601 格式。 的值 source 可用來將變更時間從來源檔案複製到目的地檔案。 預設時間戳記是要求的時間。 |
x-ms-file-request-intent |
如果 Authorization 標頭指定 OAuth 權杖，則為必要專案。 可接受的值為 backup 。 此標頭會 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 指定 ，如果在指派給使用 Authorization 標頭授權的身分識別的 RBAC 原則中包含 ，則應該授與 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 。 適用于 2022-11-02 版和更新版本。 |
x-ms-allow-trailing-dot: { <Boolean> } |
選擇性。 版本 2022-11-02 和更新版本。 布林值會指定是否應該修剪要求 URL 中的尾端點。 如需詳細資訊，請參閱 命名和參考共用、目錄、檔案和中繼資料。 |
x-ms-source-allow-trailing-dot: { <Boolean> } |
選擇性。 版本 2022-11-02 和更新版本。 布林值會指定是否應該修剪來源 URL 中的尾端點。 只有當複製來源是 Azure 檔案時，才應該指定此標頭。 任何其他複製來源類型都不支援此標頭。 如需詳細資訊，請參閱 命名和參考共用、目錄、檔案和中繼資料。 |
要求本文
無。
回應
回應包括 HTTP 狀態碼和一組回應標頭。
狀態碼
成功的作業會傳回狀態碼「202 (已接受)」。
如需狀態碼的相關資訊，請參閱 狀態和錯誤碼。
回應標頭
這項作業的回應包括下列標頭。 此回應也包含其他標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格。
| 回應標頭 | 描述 |
|---|---|
ETag |
如果複製作業已完成，則包含 ETag 目的地檔案的值。 如果複製作業未完成，則包含 ETag 作業開始時所建立之空白檔案的值。 |
Last-Modified |
傳回復製作業至目的地檔案完成的日期/時間。 |
x-ms-request-id |
可唯一識別提出的要求。 您可以使用此標頭對要求進行疑難排解。 如需詳細資訊，請參閱 針對 API 作業進行疑難排解。 |
x-ms-version |
指出用來執行要求的Azure 檔案儲存體版本。 |
Date |
UTC 日期/時間值，指出服務傳送回應的時間。 |
x-ms-copy-id: <id> |
提供此複製作業的字串識別碼。 Get File搭配 或 Get File Properties 來檢查此複製作業的狀態，或傳遞 至 Abort Copy File 以解除擱置的複製作業。 |
x-ms-copy-status: <success ¦ pending> |
指出具有下列值的複製作業狀態： - success：複製作業成功完成。- pending：複製作業仍在進行中。 |
x-ms-client-request-id |
可用來針對要求和對應的回應進行疑難排解。 如果此標頭存在於要求中，且值最多為 1，024 個可見的 ASCII 字元，則此標頭的值等於標頭的值 x-ms-client-request-id 。 x-ms-client-request-id如果要求中沒有標頭，此標頭將不會出現在回應中。 |
回應本文
無
範例回應
Response Status:
HTTP/1.1 202 Accepted
Response Headers:
Last-Modified: <date>
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2015-02-21
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>
授權
帳戶擁有者或擁有共用存取簽章的用戶端可以呼叫這項作業，該簽章具有寫入目的地檔案或其共用的許可權。 請注意，要求上指定的共用存取簽章僅適用于目的地檔案。
原始程式檔或 Blob 的存取權會個別獲得授權，如要求標頭 x-ms-copy-source 的詳細資料中所述。
下表描述如何授權作業的 Copy File 目的地和來源物件：
| 檔案 | 使用共用金鑰或共用金鑰 Lite 授權 | 具有共用存取簽章的授權 | 公用物件不需要授權 |
|---|---|---|---|
| 目的地檔案 | Yes | 是 | 不適用 |
| 相同帳戶中的來源檔案 | Yes | 是 | 不適用 |
| 另一個帳戶中的原始程式檔 | No | 是 | 不適用 |
| 相同帳戶或其他帳戶中的來源 Blob | No | Yes | Yes |
檔案系統屬性
| 屬性 | Win32 檔案屬性 | 定義 |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
檔案是唯讀的。 應用程式可以讀取檔案，但無法寫入或刪除檔案。 |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
檔案被隱藏起來。 它不包含在一般目錄清單中。 |
System |
FILE_ATTRIBUTE_SYSTEM |
作業系統會使用檔案的一部分，或以獨佔方式使用檔案。 |
None |
FILE_ATTRIBUTE_NORMAL |
檔案未設定其他屬性。 只有在單獨使用此屬性時才有效。 |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
檔案是封存檔案。 應用程式通常會使用這個屬性來標記要備份或移除的檔案。 |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
檔案正用於暫存儲存體。 |
Offline |
FILE_ATTRIBUTE_OFFLINE |
檔案的資料無法立即使用。 此檔案系統屬性主要提供與 Windows 的相容性。 Azure 檔案儲存體不支援離線儲存體選項。 |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
內容索引服務不會為檔案編制索引。 |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
背景資料完整性掃描器不會讀取使用者資料流程。 此檔案系統屬性主要提供與 Windows 的相容性。 |
備註
作業 Copy File 可以非同步完成。 您可以使用回應標頭傳回的複製識別碼 x-ms-copy-id 來檢查複製作業的狀態，或取消它。 Azure 檔案儲存體最好地複製檔案。
如果目的地檔案存在，將會覆寫它。 複製作業正在進行時，您無法修改目的地檔案。
作業 Copy File 一律會複製整個來源 Blob 或檔案。 不支援複製特定範圍的位元組或一組區塊。
作業的來源 Copy File 可以是位於共用快照集的檔案。 作業的 Copy File 目的地不能是位於共用快照集的檔案。
當複製作業的來源提供 ETag 值時，如果作業進行中時來源有任何變更，則會失敗。 嘗試在進行複製作業時變更目的地檔案將會失敗，狀態碼為 409 (衝突) 。
當 ETag 作業啟動時，目的地檔案的值會變更 Copy File 。 它會在複製作業期間持續變更。
複製屬性和中繼資料
複製 Blob 或檔案時，下列系統屬性會複製到具有相同值的目的地檔案：
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
目的地檔案的大小一律與來源 Blob 或檔案相同。 目的地檔案標頭 Content-Length 的值符合來源 Blob 或檔案的該標頭值。
將租用的 Blob 或檔案複製到檔案
作業 Copy File 只會從來源 Blob 或檔案讀取，因此來源物件的租用不會影響作業。 作業會在 Copy File 作業啟動時儲存 ETag 來源 Blob 或檔案的值。 ETag如果複製作業完成前的值變更，作業就會失敗。 您可以在複製作業期間租用檔案的來源 Blob，以防止變更檔案的來源 Blob。
如果目的地檔案具有作用中的無限租用，您必須在呼叫 Copy File 作業時指定其租用識別碼。 複製作業擱置時，目的地檔案上的任何租用作業都失敗，狀態碼為 409 (Conflict) 。 在複製作業期間，目的地檔案上的無限租用會以這種方式鎖定，無論您是複製到與來源名稱不同的目的地檔案，還是複製到與來源同名的目的地檔案。 如果用戶端在尚未存在的檔案上指定租用識別碼，Azure 檔案儲存體傳回狀態碼 412 (前置條件失敗) 。
使用暫止複製作業
作業 Copy File 可能會以非同步方式完成複製檔案。 使用下表根據傳回的狀態碼 Copy File 來判斷下一個步驟：
| 狀態碼 | 意義 |
|---|---|
| 202 (已接受)，x-ms-copy-status：成功 | 複製作業成功完成。 |
| 202 (已接受)，x-ms-copy-status：暫止 | 複製作業尚未完成。 使用 Get File Properties 輪詢目的地 Blob，直到 x-ms-copy-status 複製作業完成或失敗為止。 |
| 4xx，500 或 503 | 複製作業失敗。 |
在作業期間和之後 Copy File ，目的地檔案的屬性會包含作業的 Copy File 複製識別碼，以及來源 Blob 或檔案的 URL。 當作業完成時，Azure 檔案儲存體會將時間與結果值寫入目的地檔案的屬性 (success 、 failed 或 aborted) 。 如果作業有 failed 結果，標頭 x-ms-copy-status-description 會包含錯誤詳細資料字串。
擱置 Copy File 的作業有兩周逾時。 在兩周後未完成的複製嘗試，並將欄位設定 failed 為 的空白檔案 x-ms-copy-status ，並將 x-ms-status-description 欄位設定為 500 (OperationCancelled) 。 在複製作業期間可能發生的間歇性非嚴重錯誤，可能會阻礙作業的進度，但不會造成失敗。 在此情況下，x-ms-copy-status-description 會描述間歇性的錯誤。
在複製作業期間修改目的地檔案的任何嘗試都會失敗，狀態碼 409 (衝突) 「正在複製檔案」。
如果您呼叫 Abort Copy File 作業，您會看到 x-ms-copy-status:aborted 標頭。 目的地檔案的中繼資料和檔案長度為 0 個位元組。 您可以重複原始呼叫， Copy File 以再次嘗試作業。
計費
作業的 Copy File 目的地帳戶會收取一筆交易來啟動作業的費用。 目的地帳戶也會為每個要求取消或要求複製作業的狀態產生一筆交易。
當來源檔案或 Blob 位於另一個帳戶時，來源帳戶會產生交易成本。 此外，如果來源和目的地帳戶位於不同的區域 (例如美國北部和美國南部) ，則您用來傳送要求的頻寬會以輸出方式向來源帳戶收費。 相同地區的帳戶之間其輸出為免費。