通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

从 URL 复制 Blob

  • 项目

该 Copy Blob From URL 操作将 blob 同步复制到存储帐户中的目标，以便源 blob 大小高达 256 mb (MiB) 。 此 API 从版本 2018-03-28 开始可用。

操作的 Copy Blob From URL 源可以是任何 Azure 存储帐户中已提交的块 Blob，该帐户可以是公共的，也可以是使用共享访问签名授权的。

请求

可以按如下所示构造 Copy Blob From URL 请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称，将 mycontainer 替换为容器的名称，将 myblob 替换为目标 Blob 的名称。

PUT 方法请求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob HTTP/1.1

模拟存储服务的 URI

对模拟存储服务发出请求时，请将仿真器主机名和Azure Blob 存储端口指定为 127.0.0.1:10000，后跟模拟存储帐户的名称：

PUT 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

有关详细信息，请参阅使用 Azurite 模拟器进行本地 Azure 存储开发。

URI 参数

可以在请求 URI 上指定以下附加参数：

参数 说明
timeout 可选。 timeout 参数以秒表示。 有关详细信息，请参阅 为 Blob 存储操作设置超时。

请求标头

下表描述了必需请求标头和可选请求标头：

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。
Date 或 x-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息，请参阅授权对 Azure 存储的请求。
x-ms-version 对于所有已授权的请求是必需的。 有关详细信息，请参阅 Azure 存储服务的版本控制。
x-ms-meta-name:value 可选。 指定与 Blob 关联的用户定义的名称/值对。 如果未指定名称/值对，该操作会将元数据从源 Blob 或文件复制到目标 Blob。 如果指定了一个或多个名称/值对，则会使用指定的元数据创建目标 Blob，并且不会从源 Blob 或文件复制元数据。

从版本 2009-09-19 开始，元数据名称必须遵守 C# 标识符的命名规则。 有关详细信息，请参阅 命名和引用容器、Blob 和元数据。
x-ms-encryption-scope 可选。 指示用于加密请求内容的加密范围。 版本 2020-12-06 及更高版本中支持此标头。
x-ms-tags 可选。 在 Blob 上设置查询字符串编码的标记。 标记不是从复制源复制的。 有关更多信息，请参见备注。 在版本 2019-12-12 及更高版本中受支持。
x-ms-copy-source-tag-option 可选。 可能的值为 REPLACE 和 COPY (区分大小写) 。 默认值为 REPLACE。

如果 COPY 指定了 ，则源 Blob 中的标记将复制到目标 Blob。 源 Blob 必须是专用的，并且请求必须具有对源 Blob 的“获取 Blob 标记 ”操作和对目标 Blob 执行“设置 Blob 标记” 操作的权限。 这会导致对源帐户上的 Get Blob Tags 操作进行额外调用。

REPLACE 将设置标头在 x-ms-tags 目标 Blob 上指定的标记。 如果 x-ms-tags 指定 REPLACE 且没有标记，则不会在目标 Blob 上设置任何标记。 指定 COPY 和 x-ms-tags 将导致 409 (冲突) 错误。

在版本 2021-04-10 及更高版本中受支持。
x-ms-source-if-modified-since 可选。 一个 DateTime 值。 如果指定此条件头，则仅当源 Blob 自指定日期/时间后发生了修改时才复制 Blob。 如果源 Blob 尚未修改，Blob 存储将返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件，则无法指定此标头。
x-ms-source-if-unmodified-since 可选。 一个 DateTime 值。 如果指定此条件头，则仅当源 Blob 自指定日期/时间后未修改时才复制 Blob。 如果已修改源 Blob，Blob 存储将返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件，则无法指定此标头。
x-ms-source-if-match 可选。 一个 ETag 值。 指定此条件标头以仅当源 Blob 的值与指定值匹配时 ETag 复制源 Blob。 如果值不匹配，Blob 存储将返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件，则无法指定此标头。
x-ms-source-if-none-match 可选。 一个 ETag 值。 指定此条件标头以仅当 Blob 值与指定值不匹配时复制 Blob ETag 。 如果值相同，Blob 存储将返回状态代码 412 (前置条件失败) 。 如果源是 Azure 文件，则无法指定此标头。
If-Modified-Since 可选。 一个 DateTime 值。 如果指定此条件头，则仅当目标 Blob 自指定日期/时间后发生了修改时才复制 Blob。 如果未修改目标 Blob，Blob 存储将返回状态代码 412 (前置条件失败) 。
If-Unmodified-Since 可选。 一个 DateTime 值。 如果指定此条件头，则仅当目标 Blob 自指定日期/时间后未修改时才复制 Blob。 如果已修改目标 Blob，Blob 存储将返回状态代码 412 (前置条件失败) 。
If-Match 可选。 一个 ETag 值。 ETag指定此条件标头的值以仅当指定的ETag值与现有目标 Blob 的值匹配ETag时复制 Blob。 如果值不匹配，Blob 存储将返回状态代码 412 (前置条件失败) 。
If-None-Match 可选。 值 ETag 或通配符 (*) 。

ETag指定此条件标头的值以仅当指定ETag值与目标 Blob 的值不匹配ETag时复制 Blob。

指定通配符 (*) ，以仅当目标 blob 不存在时才执行操作。

如果不满足指定的条件，Blob 存储将返回状态代码 412 (前置条件失败) 。
x-ms-copy-source:name 必需。 指定源 Blob 的 URL。 该值可以是长度最多为 2 kib 的 URL， (KiB) 指定 blob。 此值应为 URL 编码，如同它显示在请求 URI 中那样。 源 Blob 必须是公共的，或者必须通过共享访问签名获得授权。 如果源 Blob 是公共的，则无需授权即可执行该操作。 如果源 Blob 的大小大于 256 MiB，则请求将失败，并出现 409 (冲突) 错误。 源 Blob 的 Blob 类型必须是块 Blob。 下面是源对象 URL 的一些示例：

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> 可选。 指定复制源的授权方案和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。
Microsoft Entra仅支持方案持有者。
版本 2020-10-02 及更高版本中支持此标头。
x-ms-requires-sync:true 必需。 指示这是同步 Copy Blob From URL 操作，而不是异步 Copy Blob 操作。
x-ms-source-content-md5 可选。 指定 URI 中 Blob 内容的 MD5 哈希。 此哈希用于在从 URI 传输数据期间验证 Blob 的完整性。 指定此标头后，存储服务会将从复制源到达的内容的哈希值与此标头值进行比较。

MD5 哈希不随 Blob 一起存储。

如果这两个哈希值不匹配，操作会失败，并显示错误代码 400（错误请求）。
x-ms-lease-id:<ID> 如果目标 Blob 有活动租约，则是必需的。 此标头的租约 ID 必须与目标 Blob 的租约 ID 匹配。 如果请求不包含租约 ID 或无效，则操作将失败，状态代码为 412 (先决条件失败) 。

如果指定了此标头，并且目标 blob 当前没有活动租约，则操作将失败，状态代码为 412 (前置条件失败) 。

在版本 2012-02-12 及更高版本中，此值必须为租用的 Blob 指定活动的无限租约。 有限持续时间租约 ID 失败，状态代码为 412 (前置条件失败) 。
x-ms-client-request-id 可选。 提供客户端生成的不透明值，其字符限制为 1-KiB，在配置日志记录时记录在日志中。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。
x-ms-access-tier 可选。 指定要在目标 Blob 上设置的层。 此标头仅适用于版本 2017-04-17 及更高版本的高级帐户上的页 Blob。 有关受支持层的完整列表，请参阅 VM 的高性能高级存储和托管磁盘。 块 Blob 版本 2018-11-09 及更高版本支持此标头。 Blob 存储或常规用途 v2 帐户支持块 Blob 分层。 有效值为 Hot、Cool、Cold 和 Archive。 注意：Cold 版本 2021-12-02 及更高版本支持层。 有关块 Blob 分层的详细信息，请参阅 热存储层、冷存储层和存档存储层。

请求正文

无。

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

成功的操作将返回状态代码 202（已接受）。

有关状态代码的信息，请参阅 状态和错误代码。

响应头

此操作的响应包括以下标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。

响应标头 说明
ETag 如果复制已完成，则 包含 ETag 目标 Blob 的值。 如果复制未完成，则 ETag 包含复制开始时创建的空 Blob 的值。

该值 ETag 用引号引起来。
Last-Modified 返回对目标 Blob 的复制操作完成的日期/时间。
x-ms-request-id 唯一标识发出的请求。 可以使用它来排查请求问题。 有关详细信息，请参阅 API 操作疑难解答。
x-ms-version 指示用于执行请求的 Blob 存储的版本。
Date 一个 UTC 日期/时间值，指示服务发送响应的时间。
x-ms-copy-id: <id> 此复制操作的字符串标识符。
x-ms-copy-status: <success> 指示复制操作的状态。 值为 success 表示操作已成功完成。
x-ms-client-request-id 可用于对请求和相应的响应进行故障排除。 如果请求中存在此标头的值 x-ms-client-request-id 并且该值最多为 1,024 个可见 ASCII 字符，则此标头的值等于标头的值。 x-ms-client-request-id如果请求中不存在标头，则响应中不会显示此标头。
x-ms-request-server-encrypted: true/false true如果通过指定的算法成功加密请求的内容，则设置为 。 否则，此值为 false。
x-ms-encryption-scope 如果请求使用加密范围，则返回 ，因此客户端可以确保通过加密范围成功加密请求的内容。

响应正文

无。

示例响应

下面是 Blob 复制请求的示例响应：

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2018-03-28  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: success  
Date: <date>

授权

在 Azure 存储中调用任何数据访问操作时，都需要授权。 下表介绍了如何授权操作的目标对象和源对象 Copy Blob From URL ：

对象类型 Microsoft Entra ID授权 共享访问签名 (SAS) 授权 共享密钥授权 (或共享密钥精简版)
目标块 Blob 是 是 是
同一存储帐户中的源块 Blob 是 是 是
另一个存储帐户中的源块 Blob 否 是 否

如果请求在请求标头中 x-ms-tags 指定标记，则调用方必须满足 “设置 Blob 标记” 操作的授权要求。

可以授权操作， Copy Blob From URL 如下所述。 请注意，必须通过 SAS 令牌单独对不同存储帐户中的源 blob 进行授权，该令牌具有 读取 (r) 权限。 有关源 Blob 授权的详细信息，请参阅请求标头 x-ms-copy-source的详细信息。

重要

Microsoft 建议将 Microsoft Entra ID 与托管标识结合使用来授权对 Azure 存储的请求。 与共享密钥授权相比，Microsoft Entra ID提供更高的安全性和易用性。

Azure 存储支持使用 Microsoft Entra ID 来授权对 Blob 数据的请求。 使用 Microsoft Entra ID，可以使用 Azure 基于角色的访问控制 (Azure RBAC) 向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证，以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。

若要详细了解如何使用 Microsoft Entra ID 授权，请参阅使用 Microsoft Entra ID 授权访问 blob。

权限

下面列出了Microsoft Entra用户、组、托管标识或服务主体调用操作Copy Blob From URL所需的 RBAC 操作，以及包含此操作的最低特权内置 Azure RBAC 角色：

目标 Blob

同一存储帐户中的源 Blob

若要详细了解如何使用 Azure RBAC 分配角色，请参阅 分配 Azure 角色以访问 Blob 数据。

注解

操作的 Copy Blob From URL 源 Blob 和目标 Blob 必须是块 Blob。

在版本 2020-10-02 及更高版本中，复制操作的源支持Microsoft Entra授权。

Copy Blob From URL 操作会始终复制整个源 blob。 不支持复制字节范围或块集。

可以将源 Blob 复制到具有不同名称的目标 Blob。 目标 Blob 可以是现有的块 Blob，也可以是复制操作创建的新 Blob。

从块 Blob 复制时，将复制所有提交的块及其块 ID。 不会复制未提交的块。 复制操作结束时，目标 Blob 将具有与源相同的已提交块计数。

当 ETag 操作启动和操作完成时 Copy Blob From URL ，块 Blob 的值将更改。

复制 Blob 属性和元数据

复制块 Blob 时，以下系统属性将复制到具有相同值的目标 Blob：

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-Length

  • Cache-Control

  • Content-MD5

  • Content-Disposition

源 blob 的已提交块列表也会复制到目标 Blob。 不会复制任何未提交的块。

目标 Blob 的大小始终与源 Blob 相同，因此目标 Blob 的 Content-Length 标头值与源 blob 的标头值匹配。

x-ms-tags如果标头提供目标 Blob 的标记，则它们必须经过查询字符串编码。 标记键和值必须符合 “设置 Blob 标记” 操作中指定的命名和长度要求。

标头 x-ms-tags 最多可以包含 2 千位标记。 如果需要更多标记，请使用 Set Blob Tags 操作。

x-ms-tags如果标头不提供标记，则不会从源 Blob 复制标记。

复制租用的 Blob

该 Copy Blob From URL 操作仅从源 Blob 读取，因此源 blob 的租用状态并不重要。

计费

定价请求可以源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的计费方式。 例如，读取事务应计为与写入事务不同的计费类别。 下表显示了基于存储帐户类型的请求的计费类别 Copy Blob From URL ：

操作 存储帐户类型 计费类别
从 URL (目标帐户1 复制 Blob) 高级块 blob
标准常规用途 v2
标准常规用途 v1		 写入操作
从 URL (源帐户2 复制 Blob) 高级块 blob
标准常规用途 v2
标准常规用途 v1		 读取操作

1目标帐户针对一个事务收费以启动写入。
2源帐户对源对象的每个读取请求都会产生一个事务。

若要了解指定计费类别的定价，请参阅Azure Blob 存储定价。

此外，如果源帐户和目标帐户位于不同区域 (例如，美国北部和美国南部) ，则用于传输请求的带宽将作为出口向源存储帐户收取费用。 同一区域中帐户间的传出免费。

将源 Blob 复制到同一帐户中具有不同名称的目标 Blob 时，会为新 Blob 使用其他存储资源。 然后，复制操作会导致存储帐户对这些额外资源的容量使用量产生费用。

另请参阅

授权对 Azure 存储的请求
状态和错误代码
Blob 存储错误代码
了解快照如何产生费用