你当前正在访问 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 的一些示例：
  • https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile
  • https://myaccount.blob.core.windows.net/mycontainer/myblob?sastoken
  • http://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>
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 及更高版本。 确定文件的安全描述符的复制行为：
  • source：从源文件复制目标文件上的安全描述符。
  • override：目标文件上的安全描述符通过 x-ms-file-permission 或 x-ms-file-permission-key 标头确定。
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-Type
  • Content-Encoding
  • Content-Language
  • Content-Length
  • Cache-Control
  • Content-MD5
  • Content-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 位于另一个帐户中时，源帐户会产生事务成本。 此外，如果源帐户和目标帐户位于不同区域 (例如美国北部和美国南部) ，则用于传输请求的带宽将作为出口向源帐户收费。 同一区域中帐户间的传出免费。

请参阅