你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
复制文件
该 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 中所示的路径组件替换为你自己的组件，如下所示：
| 路径组件 | 说明 |
|---|---|
myaccount |
存储帐户的名称。 |
myshare |
文件共享的名称。 |
mydirectorypath |
可选。 父目录的路径。 |
myfile |
文件的名称。 |
有关路径命名限制的详细信息，请参阅 命名和引用共享、目录、文件和元数据。
URI 参数
可以在请求 URI 上指定以下附加参数：
| 参数 | 说明 |
|---|---|
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 kiB () 。 若要将文件复制到同一存储帐户中的另一个文件，可以使用共享密钥来授权源文件。 如果要从另一个存储帐户复制文件，或者从同一存储帐户或另一个存储帐户复制 Blob，则必须使用共享访问签名授权源文件或 Blob。 如果源是公共 Blob，则无需授权即可执行复制操作。 还可以将共享快照中的文件指定为复制源。 下面是源对象 URL 的一些示例：
|
x-ms-lease-id:<ID> |
如果目标文件具有活动租约，则为必需。 适用于版本 2019-02-02 及更高版本。 为此标头指定的租约 ID 必须与目标文件的租约 ID 匹配。 如果请求不包含租约 ID 或 ID 无效，则操作将失败，状态代码为 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 kiB () 或更小，则可以使用此标头。 否则，可以使用 x-ms-file-permission-key。 如果指定，它必须具有所有者、组和 可自由访问控制列表 (DACL) 。 请注意，只能指定 或 中的 x-ms-file-permissionx-ms-file-permission-key一个。 |
x-ms-file-permission-key |
如果 x-ms-file-permission-copy-mode 指定为 override 且 x-ms-file-permission 未指定，则为 必需。 适用于版本 2019-07-07 及更高版本。 此标头指定要为文件设置的权限的键。 可以使用 操作创建此密钥 Create Permission 。请注意，只能指定 或 中的 x-ms-file-permissionx-ms-file-permission-key一个。 |
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/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action，如果 或 包含在分配给使用 标头授权的标识的 RBAC 策略中，则应授予 或Authorization。 适用于版本 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 Properties起使用 Get File 以检查此复制操作的状态，或将 传递给 Abort Copy File 以取消挂起的复制操作。 |
x-ms-copy-status: <success ¦ pending> |
使用以下值指示复制操作的状态： - success：复制操作已成功完成。- pending：复制操作仍在进行中。 |
x-ms-client-request-id |
可用于对请求和相应响应进行故障排除。 如果请求中存在此标头的值 x-ms-client-request-id ，并且该值最多为 1，024 个可见 ASCII 字符，则此标头的值等于该标头的值。
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 ：
| 文件 | 使用共享密钥或共享密钥精简版进行授权 | 使用共享访问签名进行授权 | 不需要授权的公共对象 |
|---|---|---|---|
| 目标文件 | 是 | 是 | 不适用 |
| 同一帐户中的源文件 | 是 | 是 | 不适用 |
| 另一个帐户中的源文件 | 否 | 是 | 不适用 |
| 同一帐户或其他帐户中的源 blob | 否 | 是 | 是 |
文件系统属性
| Attribute | 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 可以异步完成。 可以使用响应标头返回的复制 ID 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 进行更改。
如果目标文件具有活动的无限租约，则必须在对操作的调用 Copy File 中指定其租约 ID。 复制操作处于挂起状态时，目标文件上的任何租用操作都失败，状态代码为 409 (冲突) 。 无论是复制到与源名称不同的目标文件，还是复制到与源文件同名的目标文件，目标文件上的无限租约都以这种方式锁定。 如果客户端在尚不存在的文件上指定租约 ID，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 ，目标文件的属性包含操作的副本 ID Copy File 和源 Blob 或文件的 URL。 操作完成后，Azure 文件存储将时间和结果值 (success、 failed或 aborted) 写入目标文件的属性。 如果操作具有 failed 结果，则 x-ms-copy-status-description 标头包含错误详细信息字符串。
挂起 Copy File 的操作超时为两周。 两周后尚未完成的复制尝试超时，并留下一个空文件， x-ms-copy-status 其中字段设置为 failed ， x-ms-status-description 字段设置为 500 (OperationCancelled) 。 复制操作期间可能发生的间歇性非致命错误可能会阻碍操作的进度，但不会导致操作失败。 这种情况下，x-ms-copy-status-description 说明间发错误。
在复制操作期间修改目标文件的任何尝试都将失败，状态代码为 409 (Conflict) ，“正在复制文件”。
如果调用操作 Abort Copy File ，将看到标头 x-ms-copy-status:aborted 。 目标文件将具有完整的元数据和 0 字节的文件长度。 可以重复对 Copy File 的原始调用以再次尝试该操作。
计费
操作的目标帐户针对一个 Copy File 启动操作的事务收费。 对于取消复制操作或请求复制操作状态的每个请求，目标帐户也会产生一个事务。
当源文件或 Blob 位于另一个帐户中时，源帐户会产生事务成本。 此外，如果源帐户和目标帐户位于不同区域 (例如美国北部和美国南部) ，则用于传输请求的带宽将作为出口向源帐户收费。 同一区域中帐户间的传出免费。