Copy File作将 blob 或文件复制到存储帐户中的目标文件。 在版本 2015-02-21 及更高版本中，启用了 SMB 协议的文件共享支持此作，在版本 2025-05-05 及更高版本中支持启用 NFS 协议的文件共享。
协议可用性
| 已启用文件共享协议 | 可用 |
|---|---|
| SMB |
|
| NFS |
|
请求
Copy File 请求构造如下。 建议使用 HTTPS。
从版本 2013-08-15 开始，如果目标文件与源文件位于同一帐户中，则可以指定目标文件的共享访问签名。 从版本 2015-04-05 开始，如果目标文件位于其他存储帐户中，则还可以为目标文件指定共享访问签名。
| 方法 | 请求 URI | HTTP 版本 |
|---|---|---|
| 放 | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
将请求 URI 中显示的路径组件替换为你自己的路径组件，如下所示：
| 路径组件 | 描述 |
|---|---|
myaccount |
存储帐户的名称。 |
myshare |
文件共享的名称。 |
mydirectorypath |
自选。 父目录的路径。 |
myfile |
文件的名称。 |
有关路径命名限制的详细信息，请参阅 命名和引用共享、目录、文件和元数据。
URI 参数
可以在请求 URI 上指定以下附加参数：
| 参数 | 描述 |
|---|---|
timeout |
自选。
timeout 参数以秒为单位表示。 有关详细信息，请参阅 设置 Azure 文件存储作的超时。 |
请求标头
下表描述了必需和可选的请求标头：
常见请求标头
| 请求标头 | 描述 |
|---|---|
Authorization |
必填。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅 授权对 Azure 存储的请求。 |
Date 或 x-ms-date |
必填。 指定请求的协调世界时（UTC）。 有关详细信息，请参阅 授权对 Azure 存储的请求。 |
x-ms-version |
所有授权请求都是必需的。 指定要用于此请求的作的版本。 在版本 2015-02-21 及更高版本中，启用了 SMB 协议的文件共享支持此作，在版本 2025-05-05 及更高版本中支持启用 NFS 协议的文件共享。 有关详细信息，请参阅 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（前置条件失败）。 如果目标文件位于启用了 NFS 协议的文件共享上，则忽略此标头，而不支持文件租用。 |
x-ms-file-creation-time |
自选。 适用于版本 2019-07-07 及更高版本。 此标头指定要在目标文件上设置的创建时间的属性（以 UTC 为单位）。 可以使用 source 值将创建时间从源文件复制到目标文件。 |
x-ms-file-last-write-time |
自选。 适用于版本 2019-07-07 及更高版本。 此标头指定要在目标文件上设置的最后一次写入时间的属性（以 UTC 为单位）。 可以使用 source 值将源文件中的上次写入时间复制到目标文件。 |
x-ms-client-request-id |
自选。 提供客户端生成的不透明值，该值具有配置日志记录时日志中记录的 1 KiB 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息，请参阅 监视 Azure Blob 存储。 |
x-ms-file-request-intent |
如果需要 Authorization 标头指定 OAuth 令牌。 可接受的值为 backup。 此标头指定，如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在分配给使用 Authorization 标头授权的标识的 RBAC 策略中，则应授予 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action。 适用于版本 2022-11-02 及更高版本。 |
x-ms-allow-trailing-dot: { <Boolean> } |
自选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁请求 URL 中存在的尾随点。 如果目标位于启用了 NFS 协议的文件共享上，则默认支持尾随点，则忽略此标头。 有关详细信息，请参阅 命名和引用共享、目录、文件和元数据。 |
x-ms-source-allow-trailing-dot: { <Boolean> } |
自选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁源 URL 中存在的尾随点。 仅当复制源位于 Azure 文件共享上时，才应指定此标头。 任何其他复制源类型都不支持此标头。 如果复制源位于启用了 NFS 协议的文件共享上，则默认支持尾随点，则忽略此标头。 有关详细信息，请参阅 命名和引用共享、目录、文件和元数据。 |
仅 SMB 请求标头
| 请求标头 | 描述 |
|---|---|
x-ms-file-change-time: { <DateTime> ¦ source } |
自选。 版本 2021-06-08 及更高版本。 文件的 UTC 更改时间属性，格式为 ISO 8601 格式。
source 值可用于将更改时间从源文件复制到目标文件。 默认时间戳是请求的时间。 |
x-ms-file-permission-copy-mode: { source ¦ override } |
自选。 适用于版本 2019-07-07 及更高版本。 确定文件的安全描述符的复制行为：
|
x-ms-file-permission: { <SDDL> ¦ <binary> } |
如果 x-ms-file-permission-copy-mode 指定为 override 且未指定 x-ms-file-permission-key，则为必需。 适用于版本 2019-07-07 及更高版本。 此权限是 base64 编码 二进制安全描述符格式中 安全描述符定义语言（SDDL） 或版本（版本 2025-01-05 或更高版本）中指定的文件的安全描述符。 可以指定要用于 x-ms-file-permission-format 标头的格式。 如果权限大小为 8 kibibytes（KiB）或更少，则可以使用此标头。 否则，可以使用 x-ms-file-permission-key。 如果指定，它必须具有所有者、组和 自由访问控制列表（DACL）。 只能指定 x-ms-file-permission 或 x-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-permission 或 x-ms-file-permission-key 之一。 |
x-ms-file-permission-format: { sddl ¦ binary } |
自选。 版本 2025-01-05 或更高版本。 指定传入 x-ms-file-permission 的值是采用 SDDL 还是二进制格式。 如果未设置此标头，则使用 sddl 的默认值。 |
x-ms-file-attributes |
自选。 适用于版本 2019-07-07 及更高版本。 此标头指定要在目标文件上设置的文件系统属性。 请参阅 可用属性的列表。 可以使用 source 值将属性从源文件复制到目标文件。 可以使用 none 值清除目标文件上的所有属性。 |
x-ms-file-copy-ignore-readonly |
自选。 适用于版本 2019-07-07 及更高版本。 此布尔值指定是否应尊重预先存在的目标文件上的 ReadOnly 属性。 如果 true，复制作会成功。 否则，目标中具有 ReadOnly 属性集的上一个文件会导致复制作失败。 |
x-ms-file-copy-set-archive |
自选。 适用于版本 2019-07-07 及更高版本。 此布尔值指定是否应设置 Archive 属性，而不考虑 x-ms-file-attributes 标头值。 |
仅 NFS 请求标头
| 请求标头 | 描述 |
|---|---|
x-ms-file-mode-copy-mode: { source ¦ override } |
自选。 版本 2025-05-05 及更高版本。 仅当复制源是启用了 NFS 协议的文件共享上的文件时适用。 确定文件的模式位的复制行为：
|
x-ms-mode |
版本 2025-05-05 及更高版本。 如果 x-ms-file-mode-copy-mode 指定为 override，则为必需 。 要对文件设置的模式位。 模式以 12 位数字八进制格式或符号“rwx”格式表示。 请参阅 POSIX 文件权限（模式）。 |
x-ms-file-owner-copy-mode: { source ¦ override } |
自选。 版本 2025-05-05 及更高版本。 仅当复制源是启用了 NFS 协议的文件共享上的文件时适用。 确定文件的所有者用户标识符（UID）和组标识符（GID）的复制行为：
|
x-ms-owner |
版本 2025-05-05 及更高版本。 要对文件设置的文件所有者的用户标识符（UID）。 如果 x-ms-file-owner-copy-mode 指定为 override，则为必需 。 |
x-ms-group |
版本 2025-05-05 及更高版本。 要对文件设置的文件所有者的组标识符（GID）。 如果 x-ms-file-owner-copy-mode 指定为 override，则为必需 。 |
请求正文
没有。
响应
响应包括 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 标头，则响应中不会显示此标头。 |
仅 SMB 响应标头
没有。
仅 NFS 响应标头
没有。
响应正文
没有
示例响应
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 进行授权 | 使用共享访问签名进行授权 | 不需要授权的公共对象 |
|---|---|---|---|
| 目标文件 | 是的 | 是的 | 不適用 |
| 同一帐户中的源文件 | 是的 | 是的 | 不適用 |
| 另一帐户中的源文件 | 不 | 是的 | 不適用 |
| 同一帐户或其他帐户中的源 Blob | 不 | 是的 | 是的 |
文件系统属性
| 属性 | 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 的兼容性。 |
POSIX 文件权限（模式）
POSIX 文件权限可以用 12 位数字八进制格式或符号“rwx”格式进行数字指定。 例子：
- “0644”或“rw-r--r--”：用户（文件所有者）具有读取、写入权限。 组具有读取权限。 其他人具有读取权限。
- “0755”或“rwxr-xr-x”：用户（文件所有者）具有读取、写入和执行权限。 组具有读取和执行权限。 其他人具有读取和执行权限。
数字八进制格式
三个最低顺序八进制数表示所有者/用户、组和其他用户的权限，并使用八进制数（0-7）表示使用按位组合“4”（读取）、“2”（写入）、“1”（执行）。 最高阶八进制数（0-7）用于指示“4”（SetUID）、“2”（SetGID）、“1”（StickyBit）权限的组合。
| 格式 | 许可 |
|---|---|
| 0700 | 用户（文件所有者）具有读取、写入和执行权限。 |
| 0400 | 用户具有读取权限。 |
| 0200 | 用户具有写入权限。 |
| 0100 | 用户具有执行权限。 |
| 0070 | 组具有读取、写入和执行权限。 |
| 0040 | 组具有读取权限。 |
| 0020 | 组具有写入权限。 |
| 0010 | 组具有执行权限。 |
| 0007 | 其他人具有读取、写入和执行权限。 |
| 0004 | 其他人具有读取权限。 |
| 0002 | 其他人具有写入权限。 |
| 0001 | 其他人具有执行权限。 |
| 4000 | 在文件上设置有效的用户 ID。 |
| 2000 | 在文件上设置有效组 ID。 |
| 1000 | 设置为指示文件只能由文件所有者、目录所有者或根用户删除或重命名文件。 |
符号“rwx”格式
所有者/用户、组和其他用户的权限使用“r”（读取）、“w”（写入）和“x”（执行）字符的组合来指示。
| 格式 | 许可 |
|---|---|
| rwx------ | 用户（文件所有者）具有读取、写入和执行权限。 |
| r-------- | 用户具有读取权限。 |
| -w------- | 用户具有写入权限。 |
| --x------ | 用户具有执行权限。 |
| ---rwx--- | 组具有读取、写入和执行权限。 |
| ---r----- | 组具有读取权限。 |
| ----w---- | 组具有写入权限。 |
| -----x--- | 组具有执行权限。 |
| ------rwx | 其他人具有读取、写入和执行权限。 |
| ------r-- | 其他人具有读取权限。 |
| -------w- | 其他人具有写入权限。 |
| --------x | 其他人具有执行权限。 |
言论
Copy File作可以异步完成。 可以使用 x-ms-copy-id 响应标头返回的副本 ID 来检查复制作的状态或取消它。 Azure 文件存储会尽力复制文件。
如果目标文件存在，则会覆盖该文件。 复制作正在进行时，无法修改目标文件。
Copy File作始终复制整个源 blob 或文件。 不支持复制一系列字节或一组块。
Copy File作的源可以是驻留在共享快照中的文件。
Copy File作的目标不能是驻留在共享快照中的文件。
当复制作的源提供 ETag 值时，如果作正在进行时对源进行任何更改，它将失败。 复制作正在进行时尝试更改目标文件失败，状态代码为 409（冲突）。
Copy File作启动时，目标文件的 ETag 值会更改。 在复制作期间，它将继续频繁更改。
复制属性和元数据
复制 Blob 或文件时，以下系统属性将复制到具有相同值的目标文件中：
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
目标文件的大小始终与源 Blob 或文件相同。 目标文件的 Content-Length 标头的值与源 blob 或文件标头的值匹配。
将租用的 Blob 或文件复制到文件
Copy File作仅从源 blob 或文件读取，因此源对象的租约不会影响作。
Copy File作在作启动时保存源 blob 或文件的 ETag 值。 如果在复制作完成之前 ETag 值发生更改，则作将失败。 可以通过在复制作期间租用文件源 blob 来阻止对文件的源 blob 进行更改。
如果目标文件具有活动的无限租约，则必须在调用 Copy File作时指定其租约 ID。 复制作挂起时，目标文件上的任何租约作都失败，状态代码为 409（冲突）。 在复制作期间，目标文件的无限租约会以这种方式锁定，无论是复制到与源名称不同的目标文件，还是复制到与源同名的目标文件。 如果客户端在尚不存在的文件上指定租约 ID，Azure 文件会返回状态代码 412（前置条件失败）。
使用挂起的复制作
Copy File作可能会异步复制文件。 使用下表根据 Copy File 返回的状态代码确定下一步：
| 状态代码 | 意义 |
|---|---|
| 202 （已接受），x-ms-copy-status： success | 复制作成功完成。 |
| 202 （已接受），x-ms-copy-status： pending | 复制作尚未完成。 使用 Get File Properties 检查目标 blob，直到复制作完成或失败为止检查 x-ms-copy-status。 |
| 4xx、500 或 503 | 复制作失败。 |
在 Copy File作期间和之后，目标文件的属性包含 Copy File作的副本 ID 和源 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（冲突），“正在复制文件”。
如果调用 Abort Copy File作，你将看到 x-ms-copy-status:aborted 标头。 目标文件将具有完好无损的元数据和 0 字节的文件长度。 可以重复对 Copy File 进行原始调用，以便再次尝试该作。
计费
Copy File作的目标帐户由一个事务收取启动作的费用。 目标帐户还会导致每个请求取消或请求复制作的状态发生一个事务。
当源文件或 Blob 位于另一个帐户中时，源帐户会产生事务费用。 此外，如果源帐户和目标帐户位于不同的区域（例如美国北部和美国南部），则用于传输请求的带宽将作为出口向源帐户收费。 同一区域中的帐户之间的出口是免费的。
另请参阅
- 对文件 作
- 授权对 Azure 存储 的请求
- 状态和错误代码
- Azure 文件存储错误代码
- 中止复制文件