你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
该 Copy Blob From URL 作将 blob 同步复制到存储帐户中的目标，源 blob 大小最大为 256 兆字节 （MiB）。 此 API 从版本 2018-03-28 开始提供。
作的 Copy Blob From URL 源可以是任何 Azure 存储帐户中任何已提交的块 blob，该块 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 上指定以下附加参数：
| 参数 | DESCRIPTION |
|---|---|
timeout |
可选。
timeout 参数以秒为单位表示。 有关详细信息，请参阅 为 Blob 存储作设置超时。 |
请求标头
下表描述了必需请求标头和可选请求标头：
| 请求标头 | DESCRIPTION |
|---|---|
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 and COPY （区分大小写）。 默认值是 REPLACE。如果 COPY 指定，则源 blob 中的标记将复制到目标 blob。 源 blob 必须是专用的，并且请求必须具有对源 blob 执行 “获取 Blob 标记 ”作和对目标 blob 执行“ 设置 Blob 标记 ”作的权限。 这会导致对 Get Blob Tags 源账户上的作进行额外调用。REPLACE 将设置标头在目标 blob 上指定的标记 x-ms-tags 。 如果 x-ms-tags 指定 REPLACE 且没有标记，则不会在目标 blob 上设置任何标记。 指定 COPY and x-ms-tags 将导致 409 （Conflict） 错误。在版本 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 的值与指定值不匹配时 ETag 复制 blob。 如果值相同，则 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 值与 ETag 现有目标 blob 的值匹配时复制 blob。 如果值不匹配，Blob 存储将返回状态代码 412（不满足前提条件）。 |
If-None-Match |
可选。 值 ETag 或通配符 （*）。为此条件标头指定 ETag 一个值，以便仅在指定的 ETag 值与 ETag 目标 blob 的值不匹配时复制 blob。指定通配符 （*） 以仅在目标 blob 不存在时执行该作。 如果未满足指定的条件，则 Blob 存储将返回状态代码 412 （Precondition Failed）。 |
x-ms-copy-source:name |
必填。 指定源 blob 的 URL。 该值可以是长度最大为 2 KiB 的 URL，用于指定 blob。 该值应采用 URL 编码，因为它将显示在请求 URI 中。 源 blob 必须是公共的，或者通过共享访问签名进行授权。 如果源 blob 是公共的，则无需授权即可执行该作。 如果源 blob 的大小大于 256 MiB，则请求将失败，并出现 409 （Conflict） 错误。 源 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 （Bad Request）。 |
x-ms-lease-id:<ID> |
如果目标 blob 具有活动租约，则为必需。 为此标头指定的租约 ID 必须与目标 Blob 的租约 ID 匹配。 如果请求不包含租约 ID 或租约 ID 无效，则作将失败，状态代码为 412 （Precondition Failed）。 如果指定了此标头，并且目标 blob 当前没有活动租约，则作将失败，状态代码为 412 （Precondition Failed）。 在版本 2012-02-12 及更高版本中，此值必须为租用的 blob 指定活动的无限租约。 有限持续时间租约 ID 失败，状态代码为 412 （Precondition Failed）。 |
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。
注意：版本 2021-12-02 及更高版本支持Cold 层。 有关块 blob 分层的详细信息，请参阅 热存储层、冷存储层和存档存储层。 |
x-ms-file-request-intent |
如果 x-ms-copy-source header 是 Azure 文件 URL，则 x-ms-copy-source-authorization 为 Required，并且 header 指定 OAuth 令牌。 可接受的值为 backup。 此标头指定，如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在分配给使用 x-ms-copy-source-authorization 标头授权的标识的 RBAC 策略中，则应授予 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action。 适用于版本 2025-07-05 及更高版本。 |
请求主体
没有。
响应
响应包括 HTTP 状态代码和一组响应标头。
状态代码
成功的作返回状态代码 202（已接受）。
有关状态代码的信息，请参阅 状态和错误代码。
响应标头
此操作的响应包括以下标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。
| 响应头 | DESCRIPTION |
|---|---|
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> |
指示复制作的状态。 值 of 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） 授权 | 共享密钥授权（或共享密钥 Lite） |
|---|---|---|---|
| 目标块 blob | 是的 | 是的 | 是的 |
| 同一存储帐户中的源块 blob | 是的 | 是的 | 是的 |
| 另一个存储帐户中的源块 blob | 否 | 是的 | 否 |
如果请求在请求标头中 x-ms-tags 指定了 tags，则调用方必须满足 Set Blob Tags 作的授权要求。
可以按如下所述授权 Copy Blob From URL 操作。 请注意，必须通过具有 读取 （r） 权限的 SAS 令牌单独授权不同存储帐户中的源 blob。 有关源 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
- Azure RBAC作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write （用于写入现有 Blob）或 Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action （用于将新 Blob 写入目标）
- 最低特权内置角色：存储 Blob 数据参与者
同一存储帐户中的源 blob
- Azure RBAC作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- 最低特权内置角色：存储 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块 blob 的值在作开始时和作结束时会发生变化Copy Blob From URL。
复制 blob 属性和元数据
复制块 blob 时，以下系统属性将复制到具有相同值的目标 blob：
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
源 blob 的已提交块列表也会复制到目标 blob。 不会复制任何未提交的块。
目标 blob 的大小始终与源 blob 相同，因此目标 blob 的标头值 Content-Length 与源 blob 的标头值匹配。
x-ms-tags如果标头为目标 blob 提供标记，则必须对它们进行查询字符串编码。 标签键和值必须符合 Set Blob Tags 作中指定的命名和长度要求。
x-ms-tags标头最多可以包含 2 KB 的标签。 如果您需要更多标签，请使用该 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 复制 Blob（目标帐户1） | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
写入操作 |
| 从 URL 复制 Blob（源帐户2） | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
读取操作 |
1目标账户需要为启动写入的 1 个事务付费。
阿拉伯数字源账户对源对象的每个读取请求都会产生一个事务。
若要了解指定计费类别的定价，请参阅 Azure Blob 存储定价。
此外，如果源账户和目标账户位于不同的区域（例如，美国北部和美国南部），则用于传输请求的带宽将作为出口向源存储帐户收费。 同一区域中的帐户之间的出口是免费的。
将源 blob 复制到同一帐户中具有不同名称的目标 blob 时，会为新 blob 使用额外的存储资源。 然后，复制作将对存储帐户的容量使用量收取这些额外资源的费用。